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.

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:

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.

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:


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 is 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. In some cases, Value contains the identifier of the property that changed.
SENSITIVE UNSENSITIVE	The SENSITIVE property of a component has changed. Value contains an empty string.

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:

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.