XtDispatchEvent() XtDispatchEvent()
Name
XtDispatchEvent - dispatch an event to registered event handlers.
Synopsis
Boolean XtDispatchEvent(event)
XEvent *event;
Inputs
event Specifies a pointer to the event structure to be dispatched to the appropriate event handlers.
Returns
True if the event was dispatched to one or more event filters or event handlers. False if no handler could be found.
Description
XtDispatchEvent() sends events to Xlib event filters (new in Release 5) and to handler functions previously registered with XtAddEven-
tHandler(). Since the entire translation manager is an event handler, XtDispatchEvent() results in action functions being called if a
translation matches the event being dispatched. XtDispatchEvent() calls the appropriate handler functions and passes them the widget, the
event, and client-specific data. See the "Background" section below for details on how events are dispatched.
If no handlers for the event are registered, the event is ignored. If there are multiple handlers registered for an event, the order in
which handlers are called is undefined. (But see XtInsertEventHandler().)
XtDispatchEvent() returns True if it dispatched the event to some filter (in Release 5) or handler and False if it found no handler to dis-
patch the event to.
XtDispatchEvent() records the timestamp of the last event dispatched which contains a timestamp (see XtLastTimestampProcessed()) and also
is responsible for implementing the grab semantics of XtAddGrab().
Usage
In most applications, XtAppMainLoop() is used to dispatch events transparently. XtAppProcessEvent() can also be used to get and dispatch a
single event. XtAddEventHandler() and XtInsertEventHandler() are used to register event handlers.
The most common use of XtDispatchEvent() is to dispatch events acquired with XtAppNextEvent(). However, it also can be used to dispatch
user-constructed events.
Background
In Release 5, the function XFilterEvent() was added to Xlib to support event filtering for international input methods. The Release 5
Intrinsics support internationalized input by calling XFilterEvent() from within XtDispatchEvent(). Note that there is no public Xlib
interface for registering an event filter.
In Release 5, XtDispatchEvent() behaves as follows.
XtDispatchEvent() first calls XFilterEvent() with the event and the window of the widget to which the Intrinsics intend to dispatch the
event (the subsections below explain how XtDispatchEvent() decides which widget to dispatch to), or the event window if the Intrinsics
would not dispatch the event to any handlers. If XFilterEvent() returns True and the event activated a server grab as identified by a pre-
vious call to XtGrabKey() or XtGrabButton(), XtDispatchEvent()calls XtUngrabKeyboard() or XtUngrabPointer() with the timestamp from the
event and immediately returns True. If XFilterEvent() returns True and a grab was not activated, XtDispatchEvent() just immediately
returns True.
Otherwise, if XFilterEvent() returns False, XtDispatchEvent() sends the event to the event handler functions that have been previously reg-
istered with the dispatch routine. XtDispatchEvent() returns True if XFilterEvent() returned True, or if the event was dispatched to some
handler, and returns False if it found no handler to which to dispatch the event. XtDispatchEvent() records the last timestamp in any
event that contains a timestamp (see XtLastTimestampProcessed()), regardless of whether it was filtered or dispatched.
If a modal cascade is active with spring_loaded True, and if the event is a remap event as defined by XtAddGrab(), XtDispatchEvent() may
dispatch the event a second time. If it does so, XtDispatchEvent() will call XFilterEvent() again with the window of the spring-loaded
widget prior to the second dispatch and if XFilterEvent() returns True, the second dispatch will not be performed.
Dispatching Events to a Modal Cascade
XtAddGrab() (which is called by XtPopup()) adds a widget to the modal cascade. When there is a modal cascade, events that occur outside of
the cascade must not be delivered, or must be remapped to one of the widgets in the cascade. XtDispatchEvent() does this as follows.
When at least one modal widget is in the widget cascade, XtDispatchEvent() first determines if the event should be delivered. It starts at
the most recent cascade entry and follows the cascade up to and including the most recent cascade entry added with the exclusive parameter
True.
This subset of the modal cascade along with all descendants of these widgets comprise the active subset. User events that occur outside
the widgets in this subset are ignored or remapped. User events that occur within the active subset are delivered to the appropriate wid-
get, which is usually a child or further descendant of the modal widget.
Regardless of where in the application they occur, remap events (events of type KeyPress, KeyRelease, ButtonPress and ButtonRelease) are
always delivered to the most recent widget in the active subset of the cascade registered with spring_loaded True, if any such widget
exists. If the event occurred in the active subset of the cascade but outside the spring-loaded widget, it is delivered normally before
being delivered also to the spring-loaded widget. Regardless of where it is dispatched, the Intrinsics do not modify the contents of the
event.
Dispatching Events with Redirected Keyboard Focus
XtSetKeyboardFocus() causes XtDispatchEvent() to remap keyboard events occurring within the specified subtree and dispatch them to the
specified descendant widget or to an ancestor. If the descendant's class is not a subclass of Core, the descendant is replaced by its
closest windowed ancestor.
When there is no modal cascade, keyboard events can be dispatched to a widget in one of four ways. Assume the server delivered the event
to the window for widget E (because of X input focus, key or keyboard grabs, or pointer position).
o If neither E nor any of E's ancestors have redirected the keyboard focus, or if the event activated a grab for E as specified by a call
to XtGrabKey() with any value of owner_events, or if the keyboard is actively grabbed by E with owner_events False via XtGrabKeyboard()
or XtGrabKey() on a previous key press, the event is dispatched to E.
o Beginning with the ancestor of E closest to the root that has redirected the keyboard focus or E if no such ancestor exists, if the tar-
get of that focus redirection has in turn redirected the keyboard focus, recursively follow this focus chain to find a widget F that has
not redirected focus.
- If E is the final focus target widget F or a descendant of F, the event is dispatched to E.
- If E is not F, an ancestor of F, or a descendant of F, and the event activated a grab for E as specified by a call to XtGrabKey() for
E, XtUngrabKeyboard() is called.
- If E is an ancestor of F, and the event is a key press, and either
+ E has grabbed the key with XtGrabKey() and owner_events False, or
+ E has grabbed the key with XtGrabKey() and owner_events True, and the coordinates of the event are outside the rectangle specified
by E's geometry,
then the event is dispatched to E.
- Otherwise, define A as the closest common ancestor of E and F:
+ If there is an active keyboard grab for any widget via either XtGrabKeyboard() or XtGrabKey() on a previous key press, or if no
widget between F and A (noninclusive) has grabbed the key and modifier combination with XtGrabKey() and any value of owner_events,
the event is dispatched to F.
+ Else, the event is dispatched to the ancestor of F closest to A that has grabbed the key and modifier combination with
XtGrabKey().
When there is a modal cascade, if the final destination widget as identified above is in the active subset of the cascade, the event is
dispatched; otherwise the event is remapped to a spring-loaded shell or discarded. Regardless of where it is dispatched, the Intrinsics do
not modify the contents of the event.
When subtree or one of its descendants acquires the X input focus or the pointer moves into the subtree such that keyboard events would now
be delivered to the subtree, a FocusIn event is generated for the descendant if focus change events have been selected by the descendant.
Similarly, when subtree loses the X input focus or the keyboard focus for one of its ancestors, a FocusOut event is generated for descen-
dant if focus change events have been selected by the descendant.
See Also
XtAddEventHandler(1), XtAddGrab(1), XtAppMainLoop(1), XtInsertEventHandler(1).
Xt - Event Handling XtDispatchEvent()