Name

XtActionProc — prototype action procedure. 

Synopsis

typedef void (∗XtActionProc)(Widget, XEvent ∗, String ∗, Cardinal ∗);

    Widget w;
    XEvent ∗event;
    String ∗params;
    Cardinal ∗num_params;

Arguments

wSpecifies the widget that caused the action to be called. 

eventSpecifies 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. 

paramsSpecifies a pointer to the list of strings that were specified in the translation table as arguments to the action. 

num_params
Specifies the number of arguments specified in the translation table.

Description

A widget class record can contain an action table.  In addition, using XtAppAddActions, an application can register its own action tables with the Resource Manager.  An action table consists of a list of string names (which can be used in translation tables to associate an action with one or more events) and corresponding function pointers (often spelled the same as the string).  The function pointer is of type XtActionProc. 

An action is a function with four arguments: a widget, an event, a string containing any arguments specified for the action, and the number of arguments contained in the string.  In most cases, 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 function definition.  To conform to ANSI C standards, all four arguments of an action should be declared, even if the trailing arguments are not used. 

One major difference between an action function and a callback function is that action functions are called with an event as an argument, whereas actions do not have the client_data or call_data arguments present for callback functions.  This means the only way to pass application data into an action function is through global variables.  On the other hand, the presence of the event argument means that you can use the contents of the event structure in the action function. 

Many action routines are intentionally written not to depend on the detailed information inside any particular type of event, so that the user uses the translation table to call 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. 

However, many other action routines, and most event handlers, do use the detailed information inside event structures. The first member of the event structure, type, identifies the type of event this structure represents, and hence implies what other fields are present in the structure. 

To access event structure fields other than type, you need to cast XEvent into the appropriate event structure type.  If you are expecting only one type of event to trigger this action, then you can simply print an error or warning message when an illegal event triggers it. 

static void
Turn(w, tevent)
Widget w;
XEvent ∗tevent;
{
    XButtonEvent ∗event = (XButtonEvent ∗) tevent;
    TetrisWidget tw = (TetrisWidget) w;
    /∗ we must now use only the fields in XButtonEvent ∗/
    if (event->type != ButtonPress)
        XtWarning("TetrisWidget: Turn action invoked\
            by wrong event type.\n");
      .
      .
}