2.17. Action Tables 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:
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.
XtActionsRec actionTable[] = {
{"Set", Set},
{"Unset", Unset},
{"Highlight",Highlight},
{"Unhighlight",Unhighlight}
{"Notify",Notify},
};
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.
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.
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.
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.
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.
Action hooks should not modify any of the data pointed to by the arguments other than the client_data argument.
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.
To add an action hook, use XtAppAddActionHook.
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.
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.
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.
XtRemoveActionHook removes the specified action hook procedure from the list in which it was registered.
void XtRemoveActionHook(id)
XtActionHookId id;
id Specifies the action hook id returned by XtAppAddActionHook.
