XtAppAddActions() XtAppAddActions()
Name
XtAppAddActions - register an action table with the Translation Manager.
Synopsis
void XtAppAddActions(app_context, actions, num_actions)
XtAppContext app_context;
XtActionList actions;
Cardinal num_actions;
Inputs
app_context
Specifies the application context.
actions Specifies the action table to register.
num_args Specifies the number of entries in this action table.
Description
XtAppAddActions() registers actions, an array of num_actions XtActionsRec structures with the Translation Manager for the application con-
text app_context. Each element of the array contains an action name and an action procedure pointer. When a named action is invoked
through a translation table, the procedure to be called is looked up in the action tables that have been registered.
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. XtAppAddActions() registers actions globally to an application context. This is in contrast to actions
placed in the Core widget class part actions field which are defined locally to a widget class only.
See XtActionProc(2) for an explanation of how to write an action procedure.
Usage
Note that there is no way to unregister actions. Registering an new definition for an action name will simply make the old definition
inaccessible.
Action procedures should not assume that the widget in which they are invoked is realized; an accelerator can cause an action to be called
for a widget that does not yet have a window.
You should never need to call XtAppAddActions() when writing a widget. Widget's actions are registered locally to the widget through the
Core class part actions field.
Background
The translation manager provides an interface to specify and manage the mapping of X event sequences into procedure calls, for example,
calling procedure Yes() when the `Y' key is pressed.
The translation manager uses two kinds of tables to perform translations:
o Action tables, which specify the mapping of externally available procedure name strings to the corresponding procedure.
o A translation table, which specifies the mapping of event sequences to procedure name strings.
The translation manager uses a simple algorithm to resolve the name of a procedure specified in a translation table into the actual proce-
dure 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:
o The widget's class and all superclass action tables, in subclass-to-superclass order.
o The parent's class and all superclass action tables, in subclass-to-superclass order, then on up the ancestor tree.
o 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 warn-
ing message.
The Intrinsics reserve all action names and parameters starting with the characters "Xt" for future standard enhancements. Users, applica-
tions, and widgets should not declare action names or pass parameters starting with these characters except to invoke specified built-in
Intrinsics functions.
Example
An action table is generally declared as a statically initialized array. By convention, the name of an action and the C function name are
identical except that the function name begins with an uppercase letter:
static XtActionsRec global_actions[] = {
{"confirm", Confirm},
{"quit", Quit},
};
This action table could be registered with the following command:
XtAppAddActions(app, global_actions, XtNumber(global_action));
Structures
The XtActionsRec structure and the XtActionList type are defined as follows:
typedef struct _XtActionsRec{
String string;
XtActionProc proc;
} XtActionsRec;
typedef struct _XtActionsRec *XtActionList;
See Also
XtActionProc(2).
Xt - Translations and Actions XtAppAddActions()