#
# Copyright (c) 1992 Sun Microsystems, Inc.  All rights reserved.
#
:panel
Select which items you want highlighted
with an arrow.

Display
----------
When a message arrives for your process, a file
descriptor becomes active. Depending on the
particular structure of your tool, you can either
arrange for the window system toolkit to call a
callback when the file descriptor becomes active,
or include the file descriptor in a select(3)
call that blocks on a number of file
descriptors.  In either case, after the file
descriptor becomes active, you call
tt_message_receive() to get a handle for a
message containing the incoming message.
You can use the tt_message_*() calls to examine
the attributes of the message to determine the
action you should take. You can recognize replies
to messages you sent by comparing the handles, by
placing information meaningful to your
application in the message with the
tt_message_user_set() call, or by placing
specific callbacks on messages and patterns with
the tt_message_callback_add and
tt_pattern_callback_add calls.

# 
:display_setting
Select which items you want highlighted
with an arrow.

Address:
Because there are many types of tools and
different users will use different sets of tools
at different times, it's often impossible for the
sender of a message to identify the precise
recipient of a message.  Instead, the sender
gives an operation name which specifies the
meaning of the message.

	TT_PROCEDURE: Op and Args supplied.

	TT_OBJECT: Object, Op, and Args
	supplied.

	TT_HANDLER: Op, and Args supplied.

	TT_OTYPE: Otype, Op, and Args supplied.

Handler:
If you know the exact procid of the handler, you
can address messages to it directly. The usual
way this would happen would be for one process to
make a general request and then pick the Handler
attribute out of the reply, directing further
messages to the same handler; this allows two
processes to rendezvous through broadcast message
passing and then go into a dialogue.

Handler_Ptype:
If you know the ptype of the process that will
handle the message, fill it in. You would know
the ptype if you consulted the ptype definition
to find the details of the protocol.

Object:
The objid of the object to which the
message is to be sent.

OType:
Type of the object.

Op:
Fill in the operation that describes the
notification or request being made. 

Opnum:
Operation number. This is used to distinguish
between overloaded operations (operations with
the same name but different argument types), and
to simplify a client's "internal" dispatch
(invoking the proper internal procedure for a
given message.)

Scope:
Use scope session if messages from other
processes in the same session as your process are
desired; use scope file if messages about a file
is desired.

	TT_SESSION: Receive messages from other
	processes in your session.

	TT_FILE: Receive messages about the file
	joined.

	TT_BOTH: Receive messages about a file
	and the session.

	TT_FILE_IN_SESSION:  Receive messages for
	the file joined while in this session.

Session:
For scope session, specify the session
(tt_default_session() by default).

File:
For file scope, specify the name of the file.

Category:
Use category observe if you just want to look at
the messages; use category handle to volunteer to
be the unique handler of the message.

	TT_OBSERVE: Observing processes just get
	copies of the message for their own
	information. Any number of processes can
	observe a message. Even if the message is
	a request, observers cannot return values
	to the sender. Often, the action taken by
	observers just affects the interactive
	display of the underlying tool data.

	TT_HANDLE: Handling processes actually
	perform an action based on the message.
	Only one process will handle any given
	message.  If the message is a request,
	the handling process is the process that
	returns any values. Generally, the action
	taken by a handler affects the
	persistently-stored representation of the
	tool's data.

Class:
Use class request for messages that return
values, or for which you want feedback telling
you when the message is handled or queued, or
when a process is started to handle the request.
Use class notification for messages that just
notify other processes of events.

	TT_NOTICE: Notice are messages that
	inform other tools that some event has
	happened. Tools sending notices don't
	expect replies back; the sender is just
	letting the other tools know what's
	happening.

	TT_REQUEST: Requests are messages that
	ask another tool to perform an action.
	Often, but not always, the requesting
	tool expects some value returned. This
	value is returned as a reply to the
	request. Even if no value is returned,
	the tool processing the request sends a
	reply indicating success or failure.


Disposition:
Specifies the action to take if the message
cannot be handled by any running process. Queue
if the message should be queued until a process
of the Handler_Ptype registers. Start if a
process of the Handler_Ptype should be started.
	TT_QUEUE: Queue the message until a
	process of the proper ptype receives the
	message.

	TT_START: Attempt to start a process of
	the proper ptype if none is running.

Note that Tt_disposition values can be added
together, so that TT_QUEUE+TT_START means both to
queue the message and to try to start a process.
This can be useful if the start can fail (or be
vetoed by the user), to ensure the message is
processed as soon as an eligible process does
start.

State:  Values for the State attribute of a
message.  Possible values and their meanings
are:

	TT_CREATED: Message has been created but
	not yet sent. Only the sender of a
	message will see a message in this
	state.

	TT_SENT: Message has been sent but not
	yet handled.

	TT_HANDLED: Message has been handled,
	return values are valid.

	TT_FAILED: Message could not be delivered
	to a handler.

	TT_QUEUED: Message has been queued for
	later delivery.

	TT_STARTED: Attempting to start a process
	to handle the message.

	TT_REJECTED: Message has been rejected by
	a possible handler.  This state is seen
	only by the rejecting process; ToolTalk
	changes the state back to TT_SENT before
	delivering the message to another
	possible handler.

Status:
A unique number indicating the results of the
message returned by the replier. This number must
be larger than TT_ERR_LAST (defined in tt_c.h).

Status string:
A text description of the Status of the message.

Sender:	
Identifies the process that sent the message.


Sender ptype:
The ptype of the process that sent the message.

Uid:
The effective user identifier of the process that
sent the message.


Gid:
The effective group identifier of the process
that sent the message.

Args:
Fill in any arguments specific to the operation.
Use tt_message_arg_add to add each argument in
turn. For each argument, you must specify: mode
(in, out, or inout), type, and if the mode is in
or inout, the value.

Mode:
Specifies the mode of a message argument.
Possible values and meanings are:
	TT_IN: The argument is written by the
	sender and read by the handler and any
	observers.


	TT_OUT: The argument is written by the
	handler and read by the sender and any
	reply observers.


	TT_INOUT: The argument is written and
	read by the sender and the handler and
	any observers.

VType:
String indicating the type. Common values are
"string" and "int" although developers can create
their own.  This is really for 'application'
specific typespaces, and has nothing to do
with the 'C' typespace.

Value:
Actual data of the value dependent on the type.



# 
:apply_button
When the apply button is pressed, the values of
the specified settings will be highlighted with 
an arrow for each message received.

# 
:reset_button
When pressed, the display values are reset to the
state of the last apply or the initial value,
whichever is last.

