XtActionProc()XtActionProc()NameXtActionProc - 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 XtAp‐
pAddActions() 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 trans‐
lation 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. Callbacks 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 table,
and document any arguments each action expects, and also the event
types that the action can be safely called on. Also, if an action pro‐
cedure 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()
