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:
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