iTool Messaging System

Notifications are messages sent from one iTool component to one or more observer components. The iTool messaging system provides a unified way for components to notify each other of important changes; it is quite general, and can be used to send messages related to any type of change. Some examples:

Visualizations send notifications when components of the visualization are selected or unselected.

Notifications are issued when the user changes the value of a property. All visualizations or operations that depend on the value of that property are automatically notified.

Note
Messaging functionality is provided mainly by the IDLitTool and IDLitUI objects, using the interface defined by the IDLitIMessaging object.

In many cases, the iTool messaging system is transparent to you as an iTool developer; you may never need to create code that uses the messaging system. The main exception to this rule is the creation of user interface panels (discussed in Creating a User Interface Panel), but there may be other instances in which the notifications sent by the iTool framework itself do not meet your needs and must be augmented by your own message generation and handling code.

Sending Notifications

To send a notification, an iTool component calls the IDLitIMessaging::DoOnNotify method, providing the object identifier of the component that is sending the notification, a string that uniquely identifies the message being sent, and any value associated with the message. The method call looks like:

Obj->DoOnNotify, IdOriginator, IdMessage, Value

where Obj is the object calling the DoOnNotify method, IdOriginator is the iTool component object identifier string of the component that changed, IdMessage is a string that uniquely identifies the change, and Value is the value associated with IdMessage.

The DoOnNotify method is available to most iTool components, since all components subclass from the IDLitIMessaging class either directly or indirectly.

See "IDLitIMessaging::DoOnNotify" (IDL Reference Guide) for details.

The IdOriginator argument is generally the object identifier of an iTool component object, but it can be any string value.

Notification Messages

The value of the IdMessage argument to the DoOnNotify method is a string value that must uniquely identify the message being sent. iTool components and callback routines that process notification messages use the value of the IdMessage string to determine what action to take when a message arrives from an observed component.

When you call the DoOnNotify method yourself, use caution in choosing the value of the IdMessage string. If the string you choose conflicts with a message being sent by another iTool component, the message-handling routines may be activated at the wrong time.

Standard iTool Messages

The following is a list of notification messages sent by components that are part of the standard iTool distribution:

Table 2-1: Standard iTool Messages
Message String	Meaning
SELECTED UNSELECTED	The selection state of an item being watched has changed. Value contains the object identifier of the component whose selection changed.
SELECTIONCHANGED	The selected item within the current iTool changed. Value contains an empty string.
ADDITEMS MOVEITEMS REMOVEITEMS	A call to the Add, Move, or Remove method of an IDLitContainer that supports the IDLitIMessaging interface was made. Value contains the object identifier of the item that was added, moved, or removed.
SETPROPERTY	The value of a property has been changed on a component. If a single property was changed, Value contains the identifier of the property that changed. If multiple properties were changed, Value contains a null string.
SENSITIVE UNSENSITIVE	The SENSITIVE property of a component has changed. Value contains an empty string.
VIEW_PAN	The currently selected view has been panned. Value is a two-element integer vector [x, y] specifying the location of the lower left corner of the visible portion of the view relative to the lower left corner of the entire view.
VIEW_ZOOM	The currently selected view has been zoomed. Value is a floating-point integer representing the new zoom factor for the view.

Observers

To watch for notifications from an iTool component, an iTool component calls the IDLitIMessaging::AddOnNotifyObserver method, providing the object identifier of the component that is watching and the object identifier of the object being watched as arguments. The method call looks like:

Obj->AddOnNotifyObserver, IdObserver, IdSubject

where Obj is the object calling the AddOnNotifyObserver method, IdObserver is the iTool component object identifier string of the component that is watching for notification messages, and IdSubject is a string value identifying the item that IdObserver is interested in. This is normally the object identifier of an iTool component object, but it can be any string value.

Note
When writing a user interface panel, the IdObserver argument contains the object identifier of a user interface adaptor created by a call to the RegisterWidget method of the IDLitUI class. See Creating a UI Panel Interface for details.