An event handler is a function you provide to handle a particular type of event or group of event types. You register this function with a call to XtAddEventHandler() or XtInsertEventHandler(), specifying the widget in which the events are to be monitored. The difference between these two functions is described below.

You can later stop the function from being called with XtRemoveEventHandler(). On any widget, you can register as many event handlers as you want, each for the same or for different types of events. When more than one routine is registered for an event, the order in which they are invoked is undefined.

Within Motif applications, event handlers have one common use; they are used to pop up Motif popup menus. A popup menu is mapped where the user presses a mouse button in a particular widget, usually the application's main window. Since the application's main window probably doesn't have an XmNactivateCallback resource, the function that pops up the menu can't be registered as a callback. It can be registered as an event handler, however, because this requires no prior agreement from the widget. This function could also be added as an action from the application, but the required translations could interfere with the operation of the main window if it already uses ButtonPress events. Event handlers have the advantage that they work in parallel with Xt's other event dispatching mechanisms, and therefore they don't interfere. Example 9-1 shows how a typical application uses an event handler. The meaning of each argument will be described in a moment.

static void
PostMenu (w, client_data, event)
Widget         w;
XtPointer      client_data;
XEvent         *event;
{
    Widget popup = (Widget) client_data;
    if (event->button != Button3)
        return;
    XmMenuPosition(popup, event);
    XtManageChild(popup);
}
main(argc, argv)
int argc;
char **argv;
{
    Widget mainW, Menu;
      .
      .
      .
    Menu = XmCreatePopupMenu(mainW, "popMenu", NULL, 0);
    XtAddEventHandler(mainW,     /* events sent to this widget */
            ButtonPressMask,     /* events desired */
            False,               /* non-maskable events */
            PostMenu,            /* function */
            Menu);               /* client_data passed to function */
      .
      .
      .
}

Within widget code, event handlers are used for various special requirements of individual widgets. For example, RowColumn uses an event handler to implement keyboard mnemonics in menus. Manager uses event handlers to generate synthetic events for its gadget children. (Since gadgets do not have windows, they would normally not get EnterNotify and LeaveNotify events. So the Manager widget class keeps track of the pointer position, and when the pointer enters one of the gadget children, Manager sends that child a synthetic EnterNotify event.)

In general, however, event handlers are infrequently used in application or widget code. None of the Athena widgets use them, and, out of the 40 applications in MIT's core distribution, only xterm and xman use them. As mentioned earlier, event handlers are useful for handling high-volume events, such as MotionNotify events, with maximum speed. An event handler for motion events would probably be the best way to implement a drawing program. However, translation tables provide good speed even for motion events on most systems.

Event handlers would also be useful when the type of events being handled changes frequently, because there is some overhead involved in compiling and merging translation tables. Event handlers can also be used to handle events for which the user-configurability of translations is not needed or wanted, such as EnterWindow, LeaveWindow, FocusIn, and FocusOut events.

Another possible use of event handlers is to speed the handling of certain events when there is a very large translation table. For example, editors typically have a large number of translations for various key combinations. If an editor was to accept pointer motion as well (to allow drawing of simple graphics), it might pay to handle motion events in an event handler instead of through translations.

The call to XtAddEventHandler() specifies which events trigger the event handler function. This is done with an event mask argument.^[58] In an event mask, each bit represents one or more event types. Symbolic constants are defined by Xlib for each event mask bit. Multiple types of events can be selected at the same time by ORing together different masks with the bitwise OR operator (|). Note that there is not a one-to-one correspondence between event masks and event types. Some event masks select only one event, but others select multiple events. Furthermore, several of the masks select the same event type, but specify that it be delivered only when it occurs under special conditions. Table 9-1 shows the event masks and the event types they select.

The events that are always selected are called nonmaskable events. These can also be handled with an event handler, but not by specifying them in the event mask. An argument to the XtAddEventHandler() call, non_maskable, is a Boolean value that, if True, specifies that the event handler should be called for nonmaskable events. This event handler then must branch according to which of the seven types of nonmaskable events it is passed. A typical nonmaskable event handler is shown in Section 9.1.2, "Adding Nonmaskable Event Handlers."

extern void HandleFocusChange();
static void VTInitialize (request, new)
XtermWidget request, new;
{
    .
    .
    .
    XtAddEventHandler(topLevel,    /* widget */
            FocusChangeMask,       /* event mask */
            False,                 /* non-maskable events */
            HandleFocusChange,     /* event handler */
            (Opaque)NULL);         /* client_data */
    .
    .
    .
}
/*ARGSUSED*/
void HandleFocusChange(w, unused, event, continue_to_dispatch)
Widget w;
register XFocusChangeEvent *event;
XtPointer unused;                  /* client_data */
Boolean *continue_to_dispatch;
{
    if (event->type == FocusIn) {
                                   /* process FocusIn */
    .
    .
    .
    }
    else {
                                   /* process FocusOut */
    .
    .
    .
    }
    /*
     * If subsequent event handlers registered for this event
     * should not be called, set *continue_to_dispatch = False;
     * This is not recommended.
     */
}

static void
Realize(w, valueMask, attributes)
register Widget w;
Mask *valueMask;
XSetWindowAttributes *attributes;
{
    .
    .
    .
    XtAddEventHandler(w, 0, True,
            GExpose, NULL); /* Get Graphics Exposures */
} /* Realize */
/* ARGSUSED */
static void
GExpose(w, client_data, event)
Widget w;
XtPointer client_data;
XEvent *event;
{
    if (event->type == GraphicsExpose)
        Redisplay(w, event, NULL); /* call the expose method directly */
}

An event is a packet of information that the server sends to the client. Xlib takes this packet from the network and places it into an XEvent structure and places it on a queue until the client program requests it. Xt requests events from this queue and dispatches the event to the appropriate action routine or event handler for the widget in which the event occurred. The event itself is passed as an argument to the routine.^[59]

Actually, XEvent is a C-Language union of many event structures all the same size but with some different field names. The first member of the union, and of any of the individual event structures, is the event type. Table 9-2, later in this section, lists the event types and the matching event structure types.

Many action routines are intentionally written not to depend on the detailed information inside any particular type of event, so that the user can specify translations 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, type, identifies which type of event this structure represents, and hence implies which 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 declare the argument as the appropriate type, as shown in Example 9-4.

/*ARGSUSED*/
static void
ActionA(w, event, params, num_params)
Widget w;
XEvent *event;
String *params;
Cardinal *num_params;
{
   if ((event->type != ButtonPress) && (event->type != KeyPress)) {
       XtWarning("ActionA invoked by wrong event type.");
      /* possible exit here */
   }
      .
      .
}

When an action routine or event handler depends on the fields in a particular event structure, it is a good practice to check the event type in that action unless you are sure that the user can't change the translation (and thus the events used to invoke the action).

If you want the same code called for two event types, then you would do better to create two separate translations and two separate actions that each call a common routine. However, it is sometimes more convenient to have an action called by two different events. Example 9-5 shows the ToggleCell action from the BitmapEdit widget, which is called in response to either MotionNotify or ButtonPress events. This action inverts a pixel in the bitmap either if the pointer is clicked on a cell in the widget, or if it is dragged across the cell with the pointer buttons held down.

static void
ToggleCell(w, event)
Widget w;
XEvent *event;
{
   BitmapEditWidget cw = (BitmapEditWidget) w;
   static int oldx = -1, oldy = -1;
   GC gc;
   int mode;
   int newx, newy;
   if (event->type == ButtonPress) {
       newx = (w->bitmapEdit.cur_x + ((XButtonEvent *)event)->x) /
               w->bitmapEdit.cell_size_in_pixels;
       newy = (w->bitmapEdit.cur_y + ((XButtonEvent *)event)->y) /
               w->bitmapEdit.cell_size_in_pixels;
   }
   else if  (event->type == MotionNotify) {
       newx = (w->bitmapEdit.cur_x + ((XMotionEvent *)event)->x) /
               w->bitmapEdit.cell_size_in_pixels;
       newy = (w->bitmapEdit.cur_y + ((XMotionEvent *)event)->y) /
               w->bitmapEdit.cell_size_in_pixels;
   }
   else
       XtWarning("BitmapEdit: ToggleCell called with wrong event\
               type);
   .
   .
   .
}

Notice that some code is repeated to cast the event structure to the two different event types. With the current MIT implementation of Xlib, the positions of the x and y fields in the XButtonEvent and XMotionEvent structures are the same, and therefore this casting is unnecessary on many compilers. However, for strict ANSI C conformance these casts are necessary, and furthermore it is improper to depend on any particular implementation of Xlib. The order of the fields in one of these events could be different in some vendor's implementation of Xlib.

XtAppAddInput() allows a program to obtain input from a file. This is not merely reading the file once, but monitoring it for further activity. Under UNIX this can be used to get input from pipes and sockets, since they are variations of files. We will demonstrate getting file and pipe input in this section.

The XtAppAddInput() routine takes four arguments: a file descriptor, a flag (see below), your function, and client_data.

XtAppAddInput() returns an ID that uniquely identifies the XtAppAddInput() request. You can use the ID to cancel the request later with XtRemoveInput().

One argument of XtAppAddInput() is a file descriptor (this file must be open before calling XtAppAddInput()). Since implementation of files varies between operating systems, the actual contents of the parameter passed as the file descriptor argument to these routines is operating system-dependent. Therefore, this code is inherently nonportable.

Possible values for the mask and their meanings are as shown in Table 9-3.

Calling these argument values masks is something of a misnomer, since they cannot be ORed together. However, you can call XtAppAddInput() additional times to register a separate function (or the same function) for each of these masks on the same file descriptor.

echo "test string" > testfile
xfileinput testfile &
echo "more text" >> testfile

/* header files */
  .
  .
  .
/* ARGSUSED */
get_file_input(client_data, fid, id)
XtPointer client_data;    /* unused */
int *fid;
XtInputId *id;
{
    char buf[BUFSIZ];
    int nbytes;
    int i;
    if ((nbytes = read(*fid, buf, BUFSIZ)) == -1)
        perror("get_file_input");
    if (nbytes)
        for (i = 0; i < nbytes; i++)
            putchar(buf[i]);
}
main(argc, argv)
int argc;
char **argv;
{
    XtAppContext app_context;
    Widget topLevel, goodbye;
    FILE *fid;
    String filename;
	XtSetLanguageProc(NULL, (XtLanguageProc)NULL, NULL);
    topLevel = XtVaAppInitialize(&app_context, "XFileInput", NULL,
            0, &argc, argv, NULL, NULL);
    if (argv[1] == NULL) {
        fprintf(stderr, "xfileinput: filename must be specified on\
                command line.); \n"
        exit(1);
    }
    filename = argv[1];
      .
      .
      .
    /* open file */
    if ((fid = fopen(filename, "r")) == NULL)
        fprintf(stderr, "xfileinput: couldn't open input file. \n");
    /* register function to handle that input, NULL arg
     * is client_data */
    XtAppAddInput(app_context, fileno(fid), XtInputReadMask,
            get_file_input, NULL);
    XtRealizeWidget(topLevel);
    XtAppMainLoop(app_context);
}

spike% xpipeinput "cal 11 1989"
    November 1989
 S  M Tu  W Th  F  S
          1  2  3  4
 5  6  7  8  9 10 11
12 13 14 15 16 17 18
19 20 21 22 23 24 25
26 27 28 29 30
(Program continues to monitor pipe for further input until application exits.)

    XtAppAddInput(app_context, fileno(stdin), XtInputReadMask,
            get_file_input, NULL);

spike% cal 11 1989 | xpipeinput
    November 1989
 S  M Tu  W Th  F  S
          1  2  3  4
 5  6  7  8  9 10 11
12 13 14 15 16 17 18
19 20 21 22 23 24 25
26 27 28 29 30
(Program continues to monitor pipe for further input until application exits.)

A program may wish to be notified when a period of time has elapsed, while being able to do other things in the meantime. For example, a clock widget requires a periodic nudge to change the time it is displaying, but must also be able to redisplay itself at any time in case of exposure.

This is done by using XtAppAddTimeOut(). This routine is passed a time interval in milliseconds, and the address of a function to be invoked when the time interval expires. As usual, a client_data argument can also be registered. The XtAppAddTimeOut() routine returns a handle that can be used to cancel the timeout before it triggers, if necessary.

A timeout is automatically removed when the registered function is called. Therefore, to have a function called repeatedly, every N milliseconds, the registered function must add the timeout again by calling XtAppAddTimeOut().

One of the major applications of timeouts other than clocks is in real-time games. Figure 9-1 shows the appearance of a game called xtetris after it has been played for a couple of minutes.

Figure 9-1. xtetris in play

The object of the game is to steer falling blocks and rotate them so that they fit well into the existing fallen blocks.^[61] The game is over when the blocks pile up to the top of the window. Every time a row is completely filled, it is removed and all the blocks above it move down one row. The window in which the blocks fall is a specialized widget. This game uses timeouts to time the falling of the blocks.

Example 9-8 is an excerpt from a widget used by xtetris that adds the timeout. The timeout function itself is also shown.

static XtIntervalId timer;
static void
StartBlock(w)
TetrisWidget w;
{
    w->tetris.cur_x = 9;
    w->tetris.cur_y = 0;
    w->tetris.type = PickType();
    DrawBlock(w, DRAW);
    timer = XtAppAddTimeOut(XtWidgetToApplicationContext(w),
            w->tetris.delay, MoveDown, w);
}
static void
MoveDown(w, id)
BitmapEditWidget w;      /* client_data */
XtIntervalID *id;
{
    if (CanMoveDown(w)) {
        drawBlock(w, UNDRAW);
        w->tetris.cur_y++;
        DrawBlock(w, DRAW);
        CopyBlock(w);
        timer = XtAppAddTimeOut(XtWidgetToApplicationContext(w),
                w->tetris.delay, MoveDown, w);
    }
    else { /*block has hit bottom or other stationary blocks*/
        UpdateCellArray(w);
        KillRows(w);
        Score(w);
        w->tetris.delay -= 5;
        StartBlock(w);
    }
}

Notice that in widget code, the application context is specified using XtWidgetToApplicationContext().

Notice also that a timeout function is called with only one argument, client_data. Inside a widget, this argument is commonly used to pass in the widget instance pointer. Also notice that every time a block hits the bottom, the instance variable delay is decremented by 5, which reduces the number of milliseconds of delay used when XtAppAddTimeOut() is next called. In other words, the blocks fall progressively faster.

xtetris also needs to remove a timeout in one of its routines. The user can “drop” a block to score extra points (if there is enough time). Whenever a block is dropped, the block is immediately moved down as far as it will go, and a new block is started. If the Drop action did not remove the timeout, the new block would be started with a new timeout while an existing timeout was already in force. This would mean that the MoveDown timeout function would be invoked twice in quick succession when each of these timeouts expired. Example 9-9 shows the XtRemoveTimeOut() call in the Drop action.

/*ARGSUSED*/
static void
Drop(tw, tevent, params, num_params)
Widget tw;
XEvent *tevent;
String *params;
Cardinal *num_params;
{
     TetrisWidget w = (TetrisWidget) tw;
     XButtonEvent *event = (XButtonEvent *) tevent;
     XtRemoveTimeOut(timer);
     while (CanMoveDown(w)) {
         DrawBlock(w, UNDRAW);
         w->tetris.cur_y++;
         DrawBlock(w, DRAW);
         CopyBlock(w);
     }
     UpdateCellArray(w);
     KillRows(w);
     score++;
     Score(w);
     w->tetris.delay -= 5;
     StartBlock(w);
}

Notice that the timer ID returned from the calls to XtAppAddTimeOut() is a global variable. Xt calls the timeout function with only one argument, and that argument passes in the widget instance pointer. We could have created a structure containing the widget instance pointer and the timer ID and passed its pointer to the timeout function. But this wouldn't help, because the action routine in which we remove the timeout is passed with no client_data argument. (It has string parameters, but these are hardcoded in the actions table.) Therefore, we are forced to have a global variable for the timer ID.

Note that between the time when the timeout is registered and when it triggers, the application processes events in XtAppMainLoop(). Therefore, all the widget's actions and expose method are in operation between the invocations of the timeout function.

Timeouts operate regardless of the visibility of the application. Since it is pointless for most games to continue operating while obscured, it makes sense to remove the game's timeouts when the game is partially or fully obscured (or iconified). To do this, you can set the visible_interest field in the Core class structure to True, and then check the visible field of the Core instance structure periodically. When the application is fully obscured, you add a separate timeout to continue testing the visibility status. When the visibility status is satisfactory once again, the game can add its timeout again. All these changes are in the widget's .c file. First we set the visible_interest field to True in the Core structure:

TetrisClassRec tetrisClassRec  = {
     /* core_class fields */
    .
    .
    .
     /* visible_interest            */ True,
    .
    .
    .
}

Second we change:

timer = XtAppAddTimeOut(XtWidgetToApplicationContext
    (w), w->tetris.delay, MoveDown, w);

to:

if (w->core.visible == False)
            timer = XtAppAddTimeOut(XtWidgetToApplicationContext
                (w) 250, CheckVisibility, w);
        else
            timer = XtAppAddTimeOut(XtWidgetToApplicationContext
(w)
w->tetris.delay, MoveDown, w);

And finally, we add the timeout function that continues to check the visibility status.

static void
CheckVisibility(w)
BitmapEditWidget w;    /* client_data */
{
    if (w->core.visible == False)
        timer = XtAppAddTimeOut(250, CheckVisibility, w);
    else
        timer = XtAppAddTimeOut(w->tetris.delay,
                MoveDown, w);
}

Unfortunately, the Core visible field is True even if a tiny sliver of the widget is visible. The only way to get around this is to add an event handler (or translation) for VisibilityNotify events and to add an instance variable to maintain the visibility state. The event handler or action would check the state field of the event, and put the game into hibernation if the window is only partially obscured. However, this approach has the opposite problem; it disables the game even when only a sliver is obscured.

There is nothing you can do about the game continuing to run while being moved or resized with the window manager. However, using the Core visible_interest field does stop the game when it is iconified.

A work procedure is an application-supplied function that is executed while an application is idle waiting for an event. Work procedures are registered with XtAppAddWorkProc(). They can perform any calculation that is short enough that the routine will return in a small fraction of a second. If the work procedure is too long, the user's response time will suffer.

If a work procedure returns True, then Xt will remove it and it will not be called again. But if one returns False, it will be called repeatedly every time there is idle time, until the application calls XtRemoveWorkProc(). A work procedure would return True if it performs a one-time setup such as creating a popup widget. It would return False if it were continuously updating a disk file as security against a system crash or server connection failure.

You can register multiple work procedures, and they will be performed one at a time. The most recent work procedure added has the highest priority. Therefore, for example, if you want to create ten popup widgets during idle time, you should add ten work procedures. The popup that you expect to need first should be added in the last work procedure registered.

The call to register a work procedure is shown in Example 9-10.

static Boolean create_popup();
  .
  .
  .
main(argc, argv)
int argc;
char **argv;
{
    XtAppContext app_context;
    XtWorkProcId popup_work_ID;
    Widget topLevel;
       .
       .
    /* XtAppInitialize, create widgets, etc. */
       .
       .
    popup_work_ID = XtAppAddWorkProc(app_context,
            create_popup, topLevel);
       .
       .
    /*
     * popup_work_ID not actually needed because work proc
     * unregisters itself by returning True.
     */
    XtRealizeWidget(topLevel);
    XtAppMainLoop(app_context);
}

Notice that XtAppAddWorkProc() returns an ID of type XtWorkProcId, which is used only in any subsequent call to XtRemoveWorkProc(). You can cast the returned value to void if you do not intend to explicitly remove the work procedure.

The client_data argument passes application data into the work procedure. It is used just like the same argument in callback functions. Example 9-11 shows a work procedure to create a popup widget.

Widget getHelp;
/* work procedure */
Boolean
create_popup(client_data)
XtPointer client_data;
{
    Widget parent = (Widget) client_data;
    Widget helpBox;
    Widget temp;
    helpBox = XmCreateMessageDialog(parent, "message", NULL, 0);
    temp = XmMessageBoxGetChild (helpBox, XmDIALOG_CANCEL_BUTTON);
    XtUnmanageChild (temp);
    temp = XmMessageBoxGetChild (helpBox, XmDIALOG_HELP_BUTTON);
    XtUnmanageChild (temp);
    /* arrange for getHelp button to pop up helpBox */
    XtAddCallback(getHelp, XmNactivateCallback, PopupDialog, helpBox);
    return(True);   /* makes Xt remove this work proc automatically */
}

Remember that Xt cannot interrupt a work procedure while it is running; the procedure must voluntarily give up control by returning, and it must do so quickly to avoid slowing user response.

If your application has any big jobs that it must do, the only way to do them without resulting in long delays is to write the code that does the big job in a way that voluntarily interrupts itself and saves its state so that it can be restarted where it left off. One way to run such a task is as a work procedure, but this is only useful for tasks that need not be done before other application tasks can begin. If you want Expose processing to continue but no other application task to begin until your task is done, you would use the same type of code but place low-level event management routines in it, or make the rest of the application insensitive until the task is done.

As you know, an X Toolkit application simply calls XtAppMainLoop() to begin processing events. XtAppMainLoop() itself is quite simple: it consists of an infinite loop calling two lower-level routines, XtAppNextEvent() and XtDispatchEvent(). XtAppNextEvent() extracts the next event from the application's event queue; XtDispatchEvent() actually uses the event to invoke the appropriate actions or event handlers. (The functions registered by XtAppAddInput() and XtAppAddTimeOut() are dispatched directly by XtAppNextEvent(); if no events are available, XtAppNextEvent() flushes the X output buffer, and calls any work procedures registered by XtAppAddWorkProc().)

An application can provide its own version of this loop, as shown in Example 9-12. For example, it might test some application-dependent global flag or other termination condition before looping back and calling XtAppNextEvent(). Or for fine-grained debugging, it might be worthwhile to insert a routine that prints out the type of each event dispatched.

void MyMainLoop(app_con)
XtAppContext app_con;
{
     XEvent event;
     for (;;) {
         XtAppNextEvent(app_con, &event);
         XtDispatchEvent(&event);
    /* Do application-specific processing here */
     }
}