Programmer's Reference

Callbacks

Actions performed on widgets by the user must be communicated back to the application. One mechanism used for this communication is a callback. A callback method defines actions to perform in response to some occurrence in a widget. Callbacks are normally registered just after widgets are created. For example, when a push-button widget is created, the application usually registers an activate callback that is run when the button is activated by the user clicking on it. Although it is not necessary for the application to register callbacks, without them the application is unable to take action based on the user's interaction with the widgets.

Callbacks are registered using the addCallback:receiver:selector:clientData: method.

Tip:The argBlock argument of a widget creation message can only be used to set widget resources. The addCallback: message cannot be used within the create argBlock. Callbacks are usually registered immediately after the widget has been created, and before it is realized.

The addCallback:receiver:selector:clientData: method takes four parameters:

callbackName
A constant specifying which callback is being registered, for example, XmNactivateCallback

receiver
The object that will receive the callback message

selector
The 3-parameter callback message selector

clientData
Optional data that will be passed to the callback when it is run

When a callback method is run, it is passed three arguments:

The following example illustrates how to register a callback. First a button is created, in this case, as the child of a shell, and then an XmNactivateCallback is added to the button.

| shell button |
 
shell := CwTopLevelShell
   createApplicationShell: 'shell'
   argBlock: nil.
button := shell
   createPushButton: 'OK'
   argBlock: nil.
button
"Name of the callback to add"
   addCallback: XmNactivateCallback
"Receiver of the callback message, usually self"
   receiver:self
"Name of method to execute"
   selector: #pressed:clientData:callData:
"Data to be passed unmodified to the callback method"
   clientData: 'Test data'.
button manageChild.
 
shell realizeWidget.

When an activate callback occurs due to the button being pressed, the pressed:clientData:callData: method, shown below, is run. The method prints the string 'Test data' on the Transcript Window. The widget issuing the callback is passed as the widget parameter. In this case, this is the push-button widget. The string 'Test data,' specified as the client data when the callback was added, is passed as the clientData parameter. Callback-specific data is passed as the callData parameter. For the activate callback of push-button widgets, however, the call data provides no new information.

pressed: widget clientData: clientData callData: callData
"The push button has been pressed."
   Transcript cr; show: clientData

The following table describes the class hierarchy and data accessor method names for call data objects. All classes are concrete classes. A description of each accessor method can be found in the source or comment for each method.

Table 32. Call data class hierarchy

Class hierarchy Responsibility Data accessor methods
CwAnyCallbackData Provides call data for most callbacks. reason (a constant, prefixed by 'XmCR')
  CwComboBoxCallbackData Provides call data for combo box singleSelectionCallback.
item
itemPosition

  CwConfirmationCallbackData Provides call data for callbacks such as the shell windowCloseCallback. This callback can be canceled by the application.
doit
doit:

  CwTextVerifyCallbackData Provides call data for text and combo-box modifyVerifyCallback. These callbacks can be canceled by the application.
currInsert
endPos
startPos
text
text:

  CwDrawingCallbackData Provides call data for callbacks such as composite expose and interceptExpose callbacks, drawing area input callbacks, and drawn-button activate and expose callbacks.
event
window

  CwListCallbackData Provides call data for callbacks such as list browseSelect, singleSelect, multipleSelect, extendedSelect, and defaultAction callbacks.
item
itemPosition
selectedItemCount
selectedItemPositions
selectedItems

  CwRowColumnCallbackData Provides call data for callbacks such as row-column entryCallback.
widget
data
callbackData

  CwToggleButtonCallbackData Provides call data for callbacks such as the toggle-button valueChangedCallback. set
  CwValueCallbackData Provides call data for callbacks such as scale and scroll bar drag and valueChangedCallback, and scroll bar decrement, increment, pageDecrement, pageIncrement, toBottom, and toTop callbacks. value
Tip:Call data objects are only valid during the callback. Do not store a call data object in a callback method and attempt to reference it later.

The following table lists the callbacks supported by each widget.

Table 33. Callbacks supported by each widget

Widgets Callbacks supported
CwArrowButton activate, arm, destroy, disarm, help, resize
CwBasicWidget destroy, resize
CwBulletinBoard destroy, expose, focus, help, interceptExpose, losingFocus, map, resize, unmap
CwCascadeButton cascading, destroy, help, resize
CwComboBox activate, destroy, focus, help, losingFocus, modifyVerify, popdown, popup, resize, singleSelection, valueChanged
CwComposite destroy, expose, focus, help, interceptExpose, losingFocus, resize
CwCompositeBox destroy, expose, focus, help, interceptExpose, losingFocus, map, ok, resize, unmap
CwDialogShell destroy, focus, iconify, popdown, popup, resize, windowClose
CwDrawingArea destroy, expose, focus, help, input, interceptExpose, losingFocus, resize
CwDrawnButton activate, arm, destroy, disarm, expose, focus, help, losingFocus, resize
CwForm destroy, expose, focus, help, interceptExpose, losingFocus, map, resize, unmap
CwFrame destroy, expose, focus, help, interceptExpose, losingFocus, resize
CwLabel destroy, help, resize
CwList browseSelection, defaultAction, destroy, extendedSelection, help, multipleSelection, resize, singleSelection
CwMainWindow destroy, expose, focus, help, interceptExpose, losingFocus, resize
CwMessageBox cancel, destroy, expose, focus, help, interceptExpose, losingFocus, map, ok, resize, unmap
CwOverrideShell destroy, popdown, popup, resize
CwPrimitive destroy, help, resize
CwPushButton activate, arm, destroy, disarm, help, resize
CwRowColumn destroy, entry, expose, focus, help, interceptExpose, losingFocus, map, resize, simple, unmap
CwScale destroy, drag, expose, focus, help, interceptExpose, losingFocus, resize, valueChanged
CwScrollBar decrement, destroy, drag, help, increment, pageDecrement, pageIncrement, resize, toBottom, toTop, valueChanged
CwScrolledWindow destroy, expose, focus, help, interceptExpose, losingFocus, resize
CwSelectionBox apply, cancel, destroy, expose, focus, help, interceptExpose, losingFocus, map, noMatch, ok, resize, unmap
CwSeparator destroy, help, resize
CwShell destroy, popdown, popup, resize
CwText activate, destroy, help, focus, losingFocus, modifyVerify, resize, valueChanged
CwToggleButton arm, destroy, disarm, help, resize, valueChanged
CwTopLevelShell destroy, focus, iconify, popdown, popup, resize, windowClose
CwWidget destroy, dragDetect, resize
CwWMShell destroy, focus, iconify, popdown, popup, resize, windowClose


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]