Name

XtAddEventHandler — register a procedure to handle events. 

Synopsis

void XtAddEventHandler(w, event_mask, nonmaskable, proc, client_data)

    Widget w;
    EventMask event_mask;
    Boolean nonmaskable;
    XtEventHandler proc;
    XtPointer client_data;

Arguments

wSpecifies the widget for which this event handler is being registered. 

event_mask
Specifies the event mask for which to call this procedure.

nonmaskable
Specifies a Boolean value that indicates whether this procedure should be called on the nonmaskable events.  (This argument should almost always be False.) 

procSpecifies the procedure that is to be called.  See XtEventHandler(2). 

client_data
Specifies additional data to be passed to the client’s event handler.

Description

XtAddEventHandler registers with the dispatch mechanism.  The procedure thus registered will be called when an event matching the event_mask occurs in the specified widget. XtAddEventHandler can be called at any time during the widget’s lifetime; it ensures that Xlib will deliver the requested event by calling XSelectInput directly if the widget is realized, and it ORs the mask bits into the widget’s event mask otherwise.  (Compare XtAddRawEventHandler.) 

See XtEventHandler(2) for a description of an event handler procedure. 

A procedure may be registered with the same client_data to handle multiple events.  Further, more than one event handler can be registered for a given event.  If multiple handlers are registered, the handlers will be called, but in an indeterminate order.  Translations and event handlers can also be registered for the same event. 

If a widget should wish to be informed when a nonmaskable event occurs, nonmaskable should be set to True.  The nonmaskable events are GraphicsExpose, NoExpose, SelectionClear, SelectionRequest, SelectionNotify, ClientMessage, and MappingNotify.  Ordinarily, nonmaskable events are of interest only to the Intrinsics. 

Chapter 8, More Input Techniques, in Volume Four, X Toolkit Intrinsics Programming Manual, provides example code for tracking pointer motion, pointer motion hints, and keyboard events. 

Structures

The event_mask is formed by combining the event mask symbols listed in the first column of the table below using the bitwise OR operator (|). Each mask symbol sets a bit in the event_mask. 

The table also briefly describes the circumstances under which you would want to specify each symbol. 

See Also

XtAddRawEventHandler(1), XtInsertEventHandler(1), XtRemoveEventHandler(1),
XtEventHandler(2).