Handling Callbacks

User interface callback routines are executed when an iTool component, for which the user interface 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 User Interface Registration. The iTool messaging system itself is discussed in iTool Messaging System.

Callback Routine Signature

A user interface widget callback routine has the following signature:

PRO WidgetName_callback, Widget, IdOriginator, IdMessage, Value

where:

WidgetName_callback is the name of the callback routine.

Widget is the widget ID of the widget registered as an observer.

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.

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 itself, in the call to the RegisterWidget method of the IDLitUI object. See User Interface Registration for details.

Example Callback Routine

The following code segment illustrates a simple callback routine used in both the idlitwdtool.pro interface and in the example custom interface developed later in this chapter. This callback handles only one message, FILENAME, which is generated when the user saves the current iTool with a new file name. When the callback is executed, the title bar of the iTool interface is updated to reflect the new file name.

PRO example2_wdtool_callback, wBase, strID, messageIn, userdata 
 
; Retrieve a pointer to the state structure. 
wChild = WIDGET_INFO(wBase, /CHILD) 
WIDGET_CONTROL, wChild, GET_UVALUE = pState 
 
; Handle the message that was passed in. 
CASE STRUPCASE(messageIn) OF 
 
   'FILENAME': BEGIN 
      filename = FILE_BASENAME(userdata) 
      newTitle = (*pState).title + ' [' + filename + ']' 
      WIDGET_CONTROL, wBase, TLB_SET_TITLE = newTitle 
      END 
 
   ELSE:  ; Do nothing 
 
ENDCASE

Your callback routine may be more complex, handling any number of messages sent to the user interface. In practice, the callback routine for a user interface is often quite simple — the standard user interface used by the iTools in IDL 6.2 handles only three messages.

Note
Your callback routine is also free to quietly ignore any messages. For example, you may choose to do nothing when the FILENAME message is received.