Programmer Reference : Common Widgets : Creating and using widgets : Callbacks
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 widget that caused the callback
•The client data specified when the callback was registered
•Information specific to the type of callback, called the call data
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:
.. CwTableItemCallbackData
Provides call data for CwTable callbacks.
item
..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.
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
CwTable
activate, columnClick, destroy, draw, draw header, edit, find, help, modifyVerify, multipleSelection, singeleSelection, virtual, valueChanged
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
 
Last modified date: 11/29/2023