Creating Callback Routines

User interface panel callback routines are executed when an iTool component, for which the panel has created an observer, generates a notification message. The callback routine then uses the value of the notification message to determine what action to take. Observers are created as described in Adding Observers.

Callback Routine Signature

A user interface panel widget callback routine has the following signature:

PRO PanelName_callback, wPanel, IdOriginator, IdMessage, Value

where:

PanelName_callback is the name of the callback routine,

wPanel is the widget ID of the panel widget (see About the Panel Widget),

IdOriginator is a string identifying the source of the message (usually the object identifier of an iTool component object, but it can be any string value),

IdMessage is a string that uniquely identifies the message being sent, and

Value is a value that is associated with the message being sent.

See iTool Messaging System for more information on the IdMessage and Value arguments.

Registration of Callback Routines

Callback routines are registered along with the user interface panel itself, in the call to the RegisterWidget method of the IDLitUI object. See Registering the Panel with the User Interface Object for details.

Retrieving Widget State Information

The wPanel argument to the callback routine contains the widget ID of the panel widget. This widget ID provides a way for the callback routine to retrieve state information about the widgets that make up the panel.

For example, if you have saved a state structure containing widget information in the user value of the first child widget of the panel widget, code similar to the following would allow you to retrieve that state structure:

; Make sure we have a valid widget ID. 
IF ~ WIDGET_INFO(wPanel, /VALID) THEN RETURN 
 
; Retrieve the widget ID of the first child widget of 
; the UI panel. 
wChild = WIDGET_INFO(wPanel, /CHILD) 
 
; Retrieve the state structure from the user value of 
; the first child widget. 
WIDGET_CONTROL, wChild, GET_UVALUE = state

This technique is used in the example user interface panel described in Example: A Simple UI Panel.