XtDispatchEvent()XtDispatchEvent()NameXtDispatchEvent - 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.
DescriptionXtDispatchEvent() 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 trans‐
lation 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 fil‐
ter (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 trans‐
parently. 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 Intrin‐
sics 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
previous 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 regis‐
tered 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 dis‐
patch 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 CascadeXtAddGrab() (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, XtDis‐
patchEvent() 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 widget, 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 dis‐
patched, the Intrinsics do not modify the contents of the event.
Dispatching Events with Redirected Keyboard FocusXtSetKeyboardFocus() causes XtDispatchEvent() to remap keyboard events
occurring within the specified subtree and dispatch them to the speci‐
fied descendant widget or to an ancestor. If the descendant's class is
not a subclass of Core, the descendant is replaced by its closest win‐
dowed 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).
· 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.
· Beginning with the ancestor of E closest to the root that has redi‐
rected the keyboard focus or E if no such ancestor exists, if the
target 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 iden‐
tified above is in the active subset of the cascade, the event is dis‐
patched; 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 descendant
if focus change events have been selected by the descendant.
See AlsoXtAddEventHandler(1), XtAddGrab(1), XtAppMainLoop(1), XtInsertEven‐
tHandler(1).
Xt - Event Handling XtDispatchEvent()
