Using a Callback

A callback is a function or procedure that is executed when an event or combination of events occurs. For example, a callback is used to achieve the desired result when a push button is "pressed." It is easy for a dtksh shell script to assign a command to be activated whenever a particular callback is invoked for a widget. The command could be as simple as a string of commands blocked together, or the name of the shell function to invoke.

Registering a Callback

An application registers a callback with a widget to specify a condition in which it is interested and to specify what action should occur when that condition occurs. The callback is registered using XtAddCallback. The action can be any valid dtksh command. For example:

XtAddCallback $WIDGET activateCallback "ActivateProc" 
XtAddCallback $WIDGET activateCallback \    
     "XtSetSensitive $BUTTON false"

Passing Data to a Callback

A callback needs to be passed context information, so it can determine what condition led to its call. For a C procedure, this information is typically passed in a callData structure. For example, a scale widget invoking a valueChangedCallback passes an instance of the following structure in callData:

typedef struct {
             int  reason;
             XEvent event;
             int value; 
}XmScaleCallbackStruct;

The C application's callback then does something like:

if (scaleCallData->reason == XmCR_VALUE_CHANGED)  
{
     eventType =scaleCallData->event->type;
     display =scaleCallData->event->xany.display;  
}

Similarly, when a callback is invoked in dtksh, the following special environment variable is set up before the callback command executes:

CB_WIDGET

This is set to the widget ID for the widget that is invoking the callback.

CB_CALL_DATA

This is set to the address of the callData structure passed by the widget to the callback.

The CB_CALL_DATA environment variable represents a pointer to a structure, and access to its fields uses a syntax similar to that of C. Nested environment variables are defined, named the same as the fields of the structure (but all in uppercase), and a dot is used to indicate containment of an element in a structure. Thus, the previous C code to access the callData provided by the scale widget translates to:

if [ ${CB_CALL_DATA.REASON} = "CR_VALUE_CHANGED" ]; then    
		eventType=${CB_CALL_DATA.EVENT.TYPE}    
		display=${CB_CALL_DATA.EVENT.XANY.DISPLAY}  
fi

The same is true of the event structure within the callData structure.

For most callback structures, the shell script is able to reference any of the fields defined for the particular callback structure, using the technique described earlier. In most cases, the shell script is not able to alter the values of the fields within these structures. The exception to this is the XmTextVerifyCallbackStruct, which is available during the losingFocusCallback, the modifyVerifyCallback and the motionVerifyCallback for the text widget. dtksh supports the modification of certain fields within this structure, to the extent that it is supported by Motif. The following fields within the callback structure are capable of being modified:

• CB_CALL_DATA.DOIT

• CB_CALL_DATA.STARTPOS

• CB_CALL_DATA.TEXT.PTR

• CB_CALL_DATA.TEXT.LENGTH

• CB_CALL_DATA.TEXT.FORMAT

This is an example of how one of these fields can be modified:

• CB_CALL_DATA.DOIT="false"

• CB_CALL_DATA.TEXT.PTR="*"

• CB_CALL_DATA.TEXT.LENGTH=1