XtAddActions() XtAddActions()
Name
XtAddActions - register an action table with the Translation Manager.
Synopsis
void XtAddActions(actions, num_actions)
XtActionList actions;
Cardinal num_actions;
Inputs
actions Specifies the action table to register.
num_actions
Specifies the number of entries in this action table.
Availability
Superseded by XtAppAddActions().
Description
XtAddActions() registers actions, an array of num_actions XtActionsRec structures with the Translation Manager. 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.
Usage
XtAddActions() has been superseded by XtAppAddActions(), which performs the same function on a per-application context basis. XtAddAc-
tions() now calls XtAppAddActions() passing the default application context created by XtInitialize(). Very few programs need multiple
application contexts, and you can continue to use XtAddActions() if you initialize your application with XtInitialize(). We recommend,
however, that you use XtAppInitialize(), XtAppAddActions(), and the other XtApp*() application context specific functions.
See XtAppAddActions() for more information about how to use actions.
See AlsoXtAppAddActions(1),
XtActionProc(2).
Xt - Translations and Actions XtAddActions()
Check Out this Related Man Page
XtActionProc() XtActionProc()
Name
XtActionProc - interface definition for action procedure.
Synopsis
typedef void (*XtActionProc)(Widget, XEvent *, String *, Cardinal *);
Widget w;
XEvent *event;
String *params;
Cardinal *num_params;
Inputs
w Specifies the widget in which the event occurred 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 an array of strings that were specified in the translation table as comma-separated arguments to the action.
num_params
Specifies the number of strings in params.
Description
An XtActionProc is an action procedure. Action procedures are given names in an XtActionList and that array of name/procedure pairs is
then registered with the Translation Manager either through a call to XtAppAddActions() or by statically initializing the actions field of
the Core widget record. The translation table of a widget binds event sequences into a sequence of action procedures, and the Translation
Manager automatically invokes the action procedures when the specified event sequences occur.
The params argument is an array of strings that the action may use. These strings are the comma-separated arguments specified in the
translation table. An action procedure may use or ignore them, and may invoke a resource converter to convert strings to convert each of
the strings to some other desired type.
Action procedures should not assume that the widget in which they are invoked is realized; an accelerator can cause an action procedure to
be called for a widget that does not yet have a window.
Usage
As an application programmer, you can often customize the behavior of a widget either by adding callback functions to one of the lists
defined by the widget, or by writing and registering custom action procedures and invoking them from the widget's translation table. Call-
backs are the simpler approach and are usually sufficient. Action procedures are usually used when you need to directly bind particular
user events to particular actions-for example, when the widget does not provide a callback that is invoked in response to the event type
that you are interested in. If you wanted to pop up a menu when the mouse entered a widget, or draw a box when the user clicked and
dragged the mouse, for example, you would probably use action procedures. Note that action procedures are not registered with a
client_data argument as callbacks are, and so application-level action procedures may have to depend on global data. Widget-level action
procedures can usually get all the data they need from their widget argument.
Note that it is usually a widget's action procedures that invoke the functions registered on that widget's callback lists.
Many action routines are intentionally written not to depend on the detailed information inside any particular type of event, so that the
user may use the translation table to invoke the action in response to different types of events. For example, it is useful for an action
routine normally triggered by a pointer click to work when called in response to a key instead. Such an action should not depend on the
event structure fields unique to button events. If your action does depend on the details of a particular event type, you must cast the
event argument to a pointer to an event structure of the appropriate type.
When you write a widget or an application, you should document each of the action procedures that users may invoke from a translation ta-
ble, and document any arguments each action expects, and also the event types that the action can be safely called on. Also, if an action
procedure invokes the procedures on a callback list without checking that the widget is realized, the callback documentation must note that
the widget may not yet be realized.
In many action procedures, the last two arguments are unused. When you don't use the last two arguments, be sure to place the lint comment
/*ARGSUSED*/ just before the action procedure definition. To conform to ANSI-C standards, all four arguments of an action should be
declared, even if the trailing arguments are not used.
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
The following two action procedures are from the Xaw Command widget:
static void
Highlight(w,event,params,num_params)
Widget w;
XEvent *event;
String *params;
Cardinal *num_params;
{
CommandWidget cbw = (CommandWidget)w;
if ( *num_params == (Cardinal) 0)
cbw->command.highlighted = HighlightWhenUnset;
else {
if ( *num_params != (Cardinal) 1)
XtWarning("Too many parameters passed to highlight action table.");
switch (params[0][0]) {
case 'A':
case 'a':
cbw->command.highlighted = HighlightAlways;
break;
default:
cbw->command.highlighted = HighlightWhenUnset;
break;
}
}
if (XtIsRealized(w))
PaintCommandWidget(w, HighlightRegion(cbw), TRUE);
}
/* ARGSUSED */
static void
Notify(w,event,params,num_params)
Widget w;
XEvent *event;
String *params; /* unused */
Cardinal *num_params; /* unused */
{
CommandWidget cbw = (CommandWidget)w;
/* check to be sure state is still Set so that user can cancel
the action (e.g., by moving outside the window, in the default
bindings.
*/
if (cbw->command.set)
XtCallCallbackList(w, cbw->command.callbacks, NULL);
}
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 AlsoXtAppAddActions(1).
Xt - Translations and Actions XtActionProc()