2.17. Action Tables   

All widget class records contain an action table, an array of XtActionsRec entries. In addition, an application can register its own action tables with the translation manager so that the translation tables it provides to widget instances can access application functionality directly. The translation action procedure pointer is of type XtActionProc.

typedef void (*XtActionProc)(Widget, XEvent*, String*, Cardinal*);
Widget w;
XEvent *event;
String *params;
Cardinal *num_params;
w Specifies the widget that caused the action to be called.
event Specifies the event that caused the action to be called.
If the action is called after a sequence of events, then the last event in the sequence is used.
params Specifies a pointer to the list of strings that were specified
in the translation table as arguments to the action, or NULL.
num_params Specifies the number of entries in params.
    typedef struct _XtActionsRec {

String string;
XtActionProc proc;
} XtActionsRec, *XtActionList;
The string field is the name used in translation tables to access the procedure. The proc field is a pointer to a procedure that implements the functionality.

When the action list is specified as the CoreClassPart actions field the string pointed to by string must be permanently allocated prior to or during the execution of the class initialization procedure and must not be subsequently deallocated.

Action procedures should not assume that the widget in which they are invoked is realized; an accelerator specification can cause an action procedure to be called for a widget that does not yet have a window. Widget writers should also note which of a widget's callback lists are invoked from action procedures and warn clients not to assume the widget is realized in those callbacks.

For example, a Pushbutton widget has procedures to take the following actions:

Set the button to indicate it is activated.

Unset the button back to its normal mode.

Highlight the button borders.

Unhighlight the button borders.

Notify any callbacks that the button has been activated.

The action table for the Pushbutton widget class makes these functions available to translation tables written for Pushbutton or any subclass. The string entry is the name used in translation tables. The procedure entry (usually spelled identically to the string) is the name of the C procedure that implements that function:

XtActionsRec actionTable[] = {
{"Set", Set},
{"Unset", Unset},
The Intrinsics reserve all action names and parameters starting with the characters ``Xt'' for future standard enhancements. Users, applications, and widgets should not declare action names or pass parameters starting with these characters except to invoke specified built-in Intrinsics functions.

2.17.1. Action Table Registration   

The actions and num_actions fields of CoreClassPart specify the actions implemented by a widget class. These are automatically registered with the Intrinsics when the class is initialized and must be allocated in writable storage prior to Core class_part initialization, and never deallocated. To save memory and optimize access, the Intrinsics may overwrite the storage in order to compile the list into an internal representation.

To declare an action table within an application and register it with the translation manager, use XtAppAddActions.

void XtAppAddActions(app_context, actions, num_actions)
XtAppContext app_context;
XtActionList actions;
Cardinal num_actions;
app_context Specifies the application context.
actions Specifies the action table to register.
num_actions Specifies the number of entries in this action table.
If more than one action is registered with the same name, the most recently registered action is used. If duplicate actions exist in an action table, the first is used. The Intrinsics register an action table containing XtMenuPopup and XtMenuPopdown as part of XtCreateApplicationContext.

2.17.2. Action Names to Procedure Translations   

The translation manager uses a simple algorithm to resolve the name of a procedure specified in a translation table into the actual procedure specified in an action table. When the widget is realized, the translation manager performs a search for the name in the following tables, in order:

The widget's class and all superclass action tables, in subclass-to-superclass order.

The parent's class and all superclass action tables, in subclass-to-superclass order, then on up the ancestor tree.

The action tables registered with XtAppAddActions and XtAddActions from the most recently added table to the oldest table.

As soon as it finds a name, the translation manager stops the search. If it cannot find a name, the translation manager generates a warning message.

2.17.3. Action Hook Registration   

An application can specify a procedure that will be called just before every action routine is dispatched by the translation manager. To do so, the application supplies a procedure pointer of type XtActionHookProc.

typedef void (*XtActionHookProc)(Widget, XtPointer, String, XEvent*, String*, Cardinal*);
Widget w;
XtPointer client_data;
String action_name;
XEvent* event;
String* params;
Cardinal* num_params;
w Specifies the widget whose action is about to be dispatched.
client_data Specifies the application-specific closure that was passed to XtAppAddActionHook.
action_name Specifies the name of the action to be dispatched.
event Specifies the event argument that will be passed to the action routine.
params Specifies the action parameters that will be passed to the action routine.
num_params Specifies the number of entries in params.
Action hooks should not modify any of the data pointed to by the arguments other than the client_data argument.

To add an action hook, use XtAppAddActionHook.

XtActionHookId XtAppAddActionHook(app, proc, client_data)
XtAppContext app;
XtActionHookProc proc;
XtPointer client_data;
app Specifies the application context.
proc Specifies the action hook procedure.
client_data Specifies application-specific data to be passed to the action hook.
XtAppAddActionHook adds the specified procedure to the front of a list maintained in the application context. In the future, when an action routine is about to be invoked for any widget in this application context, either through the translation manager or via XtCallActionProc, the action hook procedures will be called in reverse order of registration just prior to invoking the action routine.

Action hook procedures are removed automatically and the XtActionHookIds destroyed when the application context in which they were added is destroyed.

To remove an action hook procedure without destroying the application context, use XtRemoveActionHook.

void XtRemoveActionHook(id)
XtActionHookId id;
id Specifies the action hook id returned by XtAppAddActionHook.
XtRemoveActionHook removes the specified action hook procedure from the list in which it was registered.