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)

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()