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:
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. |
|
CwConfirmationCallbackData | Provides call data for callbacks such as the shell windowCloseCallback. This callback can be canceled by the application. |
|
CwTextVerifyCallbackData | Provides call data for text and combo-box modifyVerifyCallback. These callbacks can be canceled by the application. |
|
CwDrawingCallbackData | Provides call data for callbacks such as composite expose and interceptExpose callbacks, drawing area input callbacks, and drawn-button activate and expose callbacks. |
|
CwListCallbackData | Provides call data for callbacks such as list browseSelect, singleSelect, multipleSelect, extendedSelect, and defaultAction callbacks. |
|
CwRowColumnCallbackData | Provides call data for callbacks such as row-column entryCallback. |
|
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 |