xfilterevent(3x11) [osf1 man page]
XFilterEvent(3X11) XFilterEvent(3X11) NAME
XFilterEvent - filter X events for an input method SYNOPSIS
Bool XFilterEvent(event, w) XEvent *event; Window w; ARGUMENTS
Specifies the event to filter. Specifies the window for which the filter is to be applied. DESCRIPTION
If the window argument is None, XFilterEvent applies the filter to the window specified in the XEvent structure. The window argument is provided so that layers above Xlib that do event redirection can indicate to which window an event has been redirected. If XFilterEvent returns True, then some input method has filtered the event, and the client should discard the event. If XFilterEvent returns False, then the client should continue processing the event. If a grab has occurred in the client and XFilterEvent returns True, the client should ungrab the keyboard. SEE ALSO
XNextEvent(3X11) Xlib -- C Language X Interface XFilterEvent(3X11)
Check Out this Related Man Page
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()