svn merge ^/branches/released .

1 files changed, 3555 insertions, 0 deletions

diff --git a/libXt/specs/CH07 b/libXt/specs/CH07
new file mode 100644
index 000000000..07b36746b
--- /dev/null
+++ b/libXt/specs/CH07
@@ -0,0 +1,3555 @@
+.\" $Xorg: CH07,v 1.4 2000/08/17 19:42:45 cpqbld Exp $
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1991, 1994
+.\" X Consortium
+.\" 
+.\" Permission is hereby granted, free of charge, to any person obtaining
+.\" a copy of this software and associated documentation files (the
+.\" "Software"), to deal in the Software without restriction, including
+.\" without limitation the rights to use, copy, modify, merge, publish,
+.\" distribute, sublicense, and/or sell copies of the Software, and to
+.\" permit persons to whom the Software is furnished to do so, subject to
+.\" the following conditions:
+.\" 
+.\" The above copyright notice and this permission notice shall be included
+.\" in all copies or substantial portions of the Software.
+.\" 
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
+.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+.\" OTHER DEALINGS IN THE SOFTWARE.
+.\" 
+.\" Except as contained in this notice, the name of the X Consortium shall
+.\" not be used in advertising or otherwise to promote the sale, use or
+.\" other dealings in this Software without prior written authorization
+.\" from the X Consortium.
+.\" 
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1991, 1994
+.\" Digital Equipment Corporation, Maynard, Massachusetts.
+.\" 
+.\" Permission to use, copy, modify and distribute this documentation for any
+.\" purpose and without fee is hereby granted, provided that the above copyright
+.\" notice appears in all copies and that both that copyright notice and this
+.\" permission notice appear in supporting documentation, and that the name of
+.\" Digital not be used in in advertising or publicity pertaining
+.\" to distribution of the software without specific, written prior permission.
+.\" Digital makes no representations about the suitability of the
+.\" software described herein for any purpose.
+.\" It is provided ``as is'' without express or implied warranty.
+.\"
+\&
+.sp 1
+.ce 3
+\s+1\fBChapter 7\fP\s-1
+
+\s+1\fBEvent Management\fP\s-1
+.sp 2
+.nr H1 7
+.nr H2 0
+.nr H3 0
+.nr H4 0
+.nr H5 0
+.LP
+.XS
+Chapter 7 \(em Event Management
+.XE
+While Xlib allows the reading and processing of events anywhere in an application,
+widgets in the \*(tk neither directly read events
+nor grab the server or pointer.
+Widgets register procedures that are to be called
+when an event or class of events occurs in that widget.
+.LP
+A typical application consists of startup code followed by an event loop
+that reads events and dispatches them by calling
+the procedures that widgets have registered.
+The default event loop provided by the \*(xI is
+.PN XtAppMainLoop .
+.LP
+The event manager is a collection of functions to perform the following tasks:
+.IP \(bu 5
+Add or remove event sources other than X server events (in particular,
+timer interrupts, file input, or POSIX signals).
+.IP \(bu 5
+Query the status of event sources.
+.IP \(bu 5
+Add or remove procedures to be called when an event occurs for a particular
+widget.
+.IP \(bu 5
+Enable and
+disable the dispatching of user-initiated events (keyboard and pointer events)
+for a particular widget.
+.IP \(bu 5
+Constrain the dispatching of events to a cascade of pop-up widgets.
+.IP \(bu 5
+Register procedures to be called when specific events arrive.
+.IP \(bu 5
+Register procedures to be called when the \*(xI will block.
+.IP \(bu 5
+Enable safe operation in a multi-threaded environment.
+.LP
+Most widgets do not need to call any of the event handler functions explicitly.
+The normal interface to X events is through the higher-level
+translation manager,
+which maps sequences of X events, with modifiers, into procedure calls.
+Applications rarely use any of the event manager routines besides
+.PN XtAppMainLoop .
+
+.NH 2
+Adding and Deleting Additional Event Sources
+.XS
+\fB\*(SN Adding and Deleting Additional Event Sources\fP
+.XE
+.LP
+While most applications are driven only by X events,
+some applications need to incorporate other sources of input 
+into the \*(xI event-handling mechanism.
+The event manager provides routines to integrate notification of timer events
+and file data pending into this mechanism.
+.LP
+The next section describes functions that provide input gathering from files.
+The application registers the files with the \*(xI read routine.
+When input is pending on one of the files,
+the registered callback procedures are invoked.
+
+.NH 3
+Adding and Removing Input Sources
+.XS
+\fB\*(SN Adding and Removing Input Sources\fP
+.XE
+.LP
+To register a new file as an input source for a given application context, use
+.PN XtAppAddInput .
+.LP
+.IN "XtAppAddInput" "" "@DEF@"
+.sM
+.FD 0
+XtInputId XtAppAddInput(\fIapp_context\fP, \fIsource\fP, \fIcondition\fP, \
+\fIproc\fP, \fIclient_data\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.br
+      int \fIsource\fP;
+.br
+      XtPointer \fIcondition\fP;
+.br
+      XtInputCallbackProc \fIproc\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context that identifies the application.
+.IP \fIsource\fP 1i
+Specifies the source file descriptor on a POSIX-based system
+or other operating-system-dependent device specification.
+.IP \fIcondition\fP 1i
+Specifies the mask that indicates a read, write, or exception condition
+or some other operating-system-dependent condition.
+.IP \fIproc\fP 1i
+Specifies the procedure to be called when the condition is found.
+.IP \fIclient_data\fP 1i
+Specifies an argument passed to the specified procedure
+when it is called.
+.LP
+.eM
+The
+.PN XtAppAddInput
+function registers with the \*(xI read routine a new source of events,
+which is usually file input but can also be file output.
+Note that \fIfile\fP should be loosely interpreted to mean any sink 
+or source of data.
+.PN XtAppAddInput
+also specifies the conditions under which the source can generate events.
+When an event is pending on this source,
+the callback procedure is called.
+.LP
+The legal values for the \fIcondition\fP argument are operating-system-dependent.
+On a POSIX-based system,
+\fIsource\fP is a file number and the condition is some union of the following:
+.IN "XtInputReadMask" "" "@DEF@"
+.IP \fBXtInputReadMask\fR 1.5i
+Specifies that \fIproc\fP is to be called when \fIsource\fP has data to be read.
+.IN "XtInputWriteMask" "" "@DEF@"
+.IP \fBXtInputWriteMask\fR 1.5i
+Specifies that \fIproc\fP is to be called when \fIsource\fP is ready
+for writing.
+.IN "XtInputExceptMask" "" "@DEF@"
+.IP \fBXtInputExceptMask\fR 1.5i
+Specifies that \fIproc\fP is to be called when \fIsource\fP has
+exception data.
+.LP
+Callback procedure pointers used to handle file events are of
+type
+.PN XtInputCallbackProc .
+.LP
+.IN "XtInputCallbackProc" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtInputCallbackProc)(XtPointer, int*, XtInputId*);
+.br
+      XtPointer \fIclient_data\fP;
+.br
+      int *\fIsource\fP;
+.br
+      XtInputId *\fIid\fP;
+.FN
+.IP \fIclient_data\fP 1i
+Passes the client data argument that was registered for this procedure in
+.PN XtApp\%AddInput .
+.IP \fIsource\fP 1i
+Passes the source file descriptor generating the event.
+.IP \fIid\fP 1i
+Passes the id returned from the corresponding
+.PN XtAppAddInput
+call.
+.LP
+.eM
+See Section 7.12 for information regarding the use of
+.PN XtAppAddInput
+in multiple threads.
+.sp
+.LP
+To discontinue a source of input, use
+.PN XtRemoveInput .
+.LP
+.IN "XtRemoveInput" "" "@DEF@"
+.sM
+.FD 0
+void XtRemoveInput(\fIid\fP)
+.br
+      XtInputId \fIid\fP;
+.FN
+.IP \fIid\fP 1i
+Specifies the id returned from the corresponding
+.PN XtAppAddInput
+call.
+.LP
+.eM
+The
+.PN XtRemoveInput
+function causes the \*(xI read routine to stop watching for events
+from the file source specified by \fIid\fP.
+.LP
+See Section 7.12 for information regarding the use of
+.PN XtRemoveInput
+in multiple threads.
+
+.NH 3
+Adding and Removing Blocking Notifications
+.XS
+\fB\*(SN Adding and Removing Blocking Notifications\fP
+.XE
+.LP
+Occasionally it is desirable for an application to receive notification
+when the \*(xI event manager detects no pending input from file sources
+and no pending input from X server event sources and is about to block
+in an operating system call.
+.sp
+.LP
+To register a hook that is called immediately prior to event blocking, use
+.PN XtAppAddBlockHook .
+.LP
+.IN "XtAppAddBlockHook" "" "@DEF@"
+.sM
+.FD 0
+XtBlockHookId XtAppAddBlockHook(\fIapp_context\fP, \fIproc\fP, \
+\fIclient_data\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.br
+      XtBlockHookProc \fIproc\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context that identifies the application.
+.IP \fIproc\fP 1i
+Specifies the procedure to be called before blocking.
+.IP \fIclient_data\fP 1i
+Specifies an argument passed to the specified procedure when it is called.
+.LP
+.eM
+The
+.PN XtAppAddBlockHook 
+function registers the specified procedure and returns an identifier for it.
+The hook procedure \fIproc\fP is called at any time in the future when
+the \*(xI are about to block pending some input.
+.LP
+The procedure pointers used to provide notification of event blocking
+are of type
+.PN XtBlockHookProc .
+.LP
+.IN "XtBlockHookProc" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtBlockHookProc)(XtPointer);
+.br
+      XtPointer \fIclient_data\fP;
+.FN
+.IP \fIclient_data\fP 1i
+Passes the client data argument that was registered for this procedure in
+.PN XtApp\%AddBlockHook .
+.LP
+.eM
+To discontinue the use of a procedure for blocking notification, use
+.PN XtRemoveBlockHook .
+.LP
+.IN "XtRemoveBlockHook" "" "@DEF@"
+.sM
+.FD 0
+void XtRemoveBlockHook(\fIid\fP)
+.br
+      XtBlockHookId \fIid\fP;
+.FN
+.IP \fIid\fP 1i
+Specifies the identifier returned from the corresponding call to
+.PN XtAppAddBlockHook .
+.LP
+.eM
+The 
+.PN XtRemoveBlockHook 
+function removes the specified procedure from the list of procedures
+that are called by the \*(xI read routine before blocking on event sources.
+
+.NH 3
+Adding and Removing Timeouts
+.XS
+\fB\*(SN Adding and Removing Timeouts\fP
+.XE
+.LP
+The timeout facility notifies the application or the widget
+through a callback procedure that a specified time interval has elapsed.
+Timeout values are uniquely identified by an interval id.
+.sp
+.LP
+To register a timeout callback, use
+.PN XtAppAddTimeOut .
+.LP
+.IN "XtAppAddTimeOut" "" "@DEF@"
+.sM
+.FD 0
+XtIntervalId XtAppAddTimeOut(\fIapp_context\fP, \fIinterval\fP, \fIproc\fP, \
+\fIclient_data\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.br
+      unsigned long \fIinterval\fP;
+.br
+      XtTimerCallbackProc \fIproc\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context for which the timer is to be set.
+.IP \fIinterval\fP 1i
+Specifies the time interval in milliseconds.
+.IP \fIproc\fP 1i
+Specifies the procedure to be called when the time expires.
+.IP \fIclient_data\fP 1i
+Specifies an argument passed to the specified procedure
+when it is called.
+.LP
+.eM
+The
+.PN XtAppAddTimeOut
+function creates a timeout and returns an identifier for it.
+The timeout value is set to \fIinterval\fP.
+The callback procedure \fIproc\fP is called when
+.PN XtAppNextEvent
+or
+.PN XtAppProcessEvent
+is next called after the time interval elapses,
+and then the timeout is removed.
+.LP
+Callback procedure pointers used with timeouts are of
+type
+.PN XtTimerCallbackProc .
+.LP
+.IN "XtTimerCallbackProc" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtTimerCallbackProc)(XtPointer, XtIntervalId*);
+.br
+      XtPointer \fIclient_data\fP;
+.br
+      XtIntervalId *\fItimer\fP;
+.FN
+.IP \fIclient_data\fP 1i
+Passes the client data argument that was registered for this procedure in
+.PN XtApp\%AddTimeOut .
+.IP \fItimer\fP 1i
+Passes the id returned from the corresponding
+.PN XtAppAddTimeOut
+call.
+.LP
+.eM
+See Section 7.12 for information regarding the use of
+.PN XtAppAddTimeOut
+in multiple threads.
+.sp
+.LP
+To clear a timeout value, use
+.PN XtRemoveTimeOut .
+.LP
+.IN "XtRemoveTimeOut" "" "@DEF@"
+.sM
+.FD 0
+void XtRemoveTimeOut(\fItimer\fP)
+.br
+      XtIntervalId \fItimer\fP;
+.FN
+.IP \fItimer\fP 1i
+Specifies the id for the timeout request to be cleared.
+.LP
+.eM
+The
+.PN XtRemoveTimeOut
+function removes the pending timeout.
+Note that timeouts are automatically removed once they trigger.
+.LP
+Please refer to Section 7.12 for information regarding the use of
+.PN XtRemoveTimeOut
+in multiple threads.
+
+.NH 3
+Adding and Removing Signal Callbacks
+.XS
+\fB\*(SN Adding and Removing Signal Callbacks\fP
+.XE
+.LP
+The signal facility notifies the application or the widget through a 
+callback procedure that a signal or other external asynchronous event 
+has occurred.  The registered callback procedures are uniquely identified 
+by a signal id.
+.sp
+.LP
+Prior to establishing a signal handler, the application or widget should
+call
+.PN XtAppAddSignal
+and store the resulting identifier in a place accessible to the signal
+handler.  When a signal arrives, the signal handler should call
+.PN XtNoticeSignal
+to notify the \*(xI that a signal has occured.  To register a signal 
+callback use
+.PN XtAppAddSignal .
+.LP
+.IN "XtAppAddSignal" "" "@DEF@"
+.sM
+.FD 0
+XtSignalId XtAppAddSignal(\fIapp_context\fP, \fIproc\fP, \fIclient_data\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.br
+      XtSignalCallbackProc \fIproc\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context that identifies the application.
+.IP \fIproc\fP 1i
+Specifies the procedure to be called when the signal is noticed.
+.IP \fIclient_data\fP 1i
+Specifies an argument passed to the specified procedure when it is called.
+.LP
+.eM
+The callback procedure pointers used to handle signal events are of type
+.PN XtSignalCallbackProc .
+.LP
+.IN "XtSignalCallbackProc" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtSignalCallbackProc)(XtPointer, XtSignalId*);
+.br
+	XtPointer \fIclient_data\fP;
+.br
+	XtSignalId *\fIid\fP;
+.FN
+.IP \fIclient_data\fP 1i
+Passes the client data argument that was registered for this procedure in
+.PN XtAppAddSignal .
+.IP \fIid\fP 1i
+Passes the id returned from the corresponding 
+.PN XtAppAddSignal
+call.
+.LP
+.eM
+To notify the \*(xI that a signal has occured, use
+.PN XtNoticeSignal .
+.LP
+.IN "XtNoticeSignal" "" "@DEF@"
+.sp
+.sM
+.FD 0
+void XtNoticeSignal(\fIid\fP)
+.br
+      XtSignalId \fIid\fP;
+.FN
+.IP \fIid\fP 1i
+Specifies the id returned from the corresponding
+.PN XtAppAddSignal
+call.
+.LP
+.eM
+On a POSIX-based system,
+.PN XtNoticeSignal
+is the only \*(xI function that can safely be called from a signal handler.
+If 
+.PN XtNoticeSignal
+is invoked multiple times before the \*(xI are able to invoke the
+registered callback, the callback is only called once.
+Logically, the \*(xI maintain ``pending'' flag for each registered callback.
+This flag is initially
+.PN False
+and is set to
+.PN True
+by
+.PN XtNoticeSignal .
+When 
+.PN XtAppNextEvent
+or
+.PN XtAppProcessEvent
+(with a mask including
+.PN XtIMSignal )
+is called, all registered callbacks with ``pending''
+.PN True
+are invoked and the flags are reset to
+.PN False .
+.LP
+If the signal handler wants to track how many times the signal has been
+raised, it can keep its own private counter.  Typically the handler would 
+not do any other work; the callback does the actual processing for the 
+signal. The \*(xI never block signals from being raised, so if a given 
+signal can be raised multiple times before the \*(xI can invoke the 
+callback for that signal, the callback must be designed to deal with 
+this.  In another case, a signal might be raised just after the \*(xI
+sets the pending flag to
+.PN False
+but before the callback can get control, in which case the pending flag
+will still be
+.PN True
+after the callback returns, and the \*(xI will invoke the callback
+again, even though all of the signal raises have been handled.  The
+callback must also be prepared to handle this case.
+.LP
+To remove a registered signal callback, call
+.PN XtRemoveSignal .
+.LP
+.IN "XtRemoveSignal" "" "@DEF@"
+.sM
+.FD 0
+void XtRemoveSignal(\fIid\fP)
+.br
+      XtSignalId \fIid\fP;
+.FN
+.IP \fIid\fP 1i
+Specifies the id returned by the corresponding call to
+.PN XtAppAddSignal .
+.LP
+.eM
+The client should typically disable the source of the signal before calling
+.PN XtRemoveSignal .
+If the signal could have been raised again before the source was disabled
+and the client wants to process it, then after disabling the source but
+before calling
+.PN XtRemoveSignal
+the client can test for signals with
+.PN XtAppPending
+and process them by calling
+.PN XtAppProcessEvent
+with the mask
+.PN XtIMSignal .
+
+.NH 2
+Constraining Events to a Cascade of Widgets
+.XS
+\fB\*(SN Constraining Events to a Cascade of Widgets\fP
+.XE
+.LP
+.IN "Grabbing Input"
+.IN "Input Grabbing"
+Modal widgets are widgets that, except for the input directed to them,
+lock out user input to the application.
+.LP
+When a modal menu or modal dialog box is popped up using
+.PN XtPopup ,
+user events (keyboard and pointer events) that occur outside the modal
+widget should be delivered to the modal widget or ignored.
+In no case will user events be delivered to a widget outside
+the modal widget.
+.LP
+Menus can pop up submenus, and dialog boxes can pop up further dialog
+boxes to create a pop-up cascade.
+In this case,
+user events may be delivered to one of several modal widgets in the cascade.
+.LP
+Display-related events should be delivered outside the modal cascade so that
+exposure events and the like keep the application's display up-to-date.
+Any event that occurs within the cascade is delivered as usual.
+The user events delivered to the most recent spring-loaded shell 
+in the cascade when they occur outside the cascade are called remap events 
+and are
+.PN KeyPress ,
+.PN KeyRelease ,
+.PN ButtonPress ,
+and
+.PN ButtonRelease .
+The user events ignored when they occur outside the cascade are
+.PN MotionNotify
+and
+.PN EnterNotify .
+All other events are delivered normally.
+In particular, note that this is one
+way in which widgets can receive
+.PN LeaveNotify
+events without first receiving
+.PN EnterNotify
+events; they should be prepared to deal with
+this, typically by ignoring any unmatched
+.PN LeaveNotify
+events.
+.LP
+.PN XtPopup
+uses the 
+.PN XtAddGrab
+and
+.PN XtRemoveGrab
+functions to constrain user events to a modal cascade 
+and subsequently to remove a grab when the modal widget is popped down.
+
+.sp
+.LP
+To constrain or redirect user input to a modal widget, use
+.PN XtAddGrab .
+.LP
+.IN "XtAddGrab" "" "@DEF@"
+.sM
+.FD 0
+void XtAddGrab(\fIw\fP, \fIexclusive\fP, \fIspring_loaded\fP)
+.br
+      Widget \fIw\fP;
+.br
+      Boolean \fIexclusive\fP;
+.br
+      Boolean \fIspring_loaded\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget to add to the modal cascade. \*(cI
+.IP \fIexclusive\fP 1i
+Specifies whether user events should be dispatched exclusively to this widget 
+or also to previous widgets in the cascade.
+.IP \fIspring_loaded\fP 1i
+Specifies whether this widget was popped up because the user pressed
+a pointer button.
+.LP
+.eM
+The
+.PN XtAddGrab
+function appends the widget to the modal cascade
+and checks that \fIexclusive\fP is 
+.PN True 
+if \fIspring_loaded\fP is 
+.PN True .
+If this condition is not met,
+.PN XtAddGrab
+generates a warning message.
+.LP
+The modal cascade is used by
+.PN XtDispatchEvent
+when it tries to dispatch a user event.
+When at least one modal widget is in the widget cascade, 
+.PN 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 \fIexclusive\fP parameter
+.PN True .
+.LP
+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.
+Modal menus with submenus generally add a submenu widget to the cascade
+with \fIexclusive\fP 
+.PN False .
+Modal dialog boxes that need to restrict user input to the most deeply nested
+dialog box add a subdialog widget to the cascade with \fIexclusive\fP 
+.PN True .
+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.
+.LP
+Regardless of where in the application they occur,
+remap events are always delivered to the most recent widget in the active
+subset of the cascade registered with \fIspring_loaded\fP 
+.PN 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 \*(xI do not modify
+the contents of the event.
+.sp
+.LP
+To remove the redirection of user input to a modal widget, use
+.PN XtRemoveGrab .
+.LP
+.IN "XtRemoveGrab" "" "@DEF@"
+.sM
+.FD 0
+void XtRemoveGrab(\fIw\fP)
+.br
+      Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget to remove from the modal cascade.
+.LP
+.eM
+The
+.PN XtRemoveGrab
+function removes widgets from the modal cascade starting 
+at the most recent widget up to and including the specified widget.
+It issues a warning if the specified widget is not on the modal cascade.
+
+.NH 3
+Requesting Key and Button Grabs
+.XS
+\fB\*(SN Requesting Key and Button Grabs\fP
+.XE
+.LP
+The \*(xI provide a set of key and button grab interfaces that
+are parallel to those provided by Xlib and that allow the \*(xI
+to modify event dispatching when necessary.  \*(tk applications and
+widgets that need to passively grab keys or buttons or actively grab
+the keyboard or pointer should use the
+following \*(xI routines rather than the corresponding Xlib
+routines.
+.sp
+.LP
+To passively grab a single key of the keyboard, use
+.PN XtGrabKey .
+.LP
+.IN "XtGrabKey" "" "@DEF@"
+.sM
+.FD 0
+void XtGrabKey(\fIwidget\fP, \fIkeycode\fP, \fImodifiers\fP, \
+\fIowner_events\fP, \fIpointer_mode\fP, \fIkeyboard_mode\fP)
+.br
+      Widget \fIwidget\fP;
+.br
+      KeyCode \fIkeycode\fP;
+.br
+      Modifiers \fImodifiers\fP;
+.br
+      Boolean \fIowner_events\fP;
+.br
+      int \fIpointer_mode\fP, \fIkeyboard_mode\fP;
+.FN
+.IP \fIwidget\fP 1i
+Specifies the widget in whose window the key is to be grabbed.  \*(cI
+.sp 6p
+.IP \fIkeycode\fP
+.br
+.ns
+.IP \fImodifiers\fP
+.br
+.ns
+.IP \fIowner_events\fP
+.br
+.ns
+.IP \fIpointer_mode\fP
+.br
+.ns
+.IP \fIkeyboard_mode\fP 1i
+Specify arguments to
+.PN XGrabKey ;
+see Section 12.2 in \fI\*(xL\fP.
+.LP
+.eM
+.PN XtGrabKey
+calls
+.PN XGrabKey
+specifying the widget's window as the grab
+window if the widget is realized.  The remaining arguments are exactly
+as for
+.PN XGrabKey .
+If the widget is not realized, or is later unrealized, the call to
+.PN XGrabKey
+is performed (again) when
+the widget is realized and its window becomes mapped.  In the future,
+if
+.PN XtDispatchEvent
+is called with a
+.PN KeyPress
+event matching the specified keycode and modifiers (which may be
+.PN AnyKey
+or
+.PN AnyModifier ,
+respectively) for the
+widget's window, the \*(xI will call
+.PN XtUngrabKeyboard
+with the timestamp from the
+.PN KeyPress
+event if either of the following conditions is true:
+.IP \(bu 3
+There is a modal cascade and the widget is not in
+the active subset of the cascade and the keyboard was not previously
+grabbed, or
+.IP \(bu 3
+.PN XFilterEvent
+returns
+.PN True .
+
+.sp
+.LP
+To cancel a passive key grab, use
+.PN XtUngrabKey .
+.LP
+.IN "XtUngrabKey" "" "@DEF@"
+.sM
+.FD 0
+void XtUngrabKey(\fIwidget\fP, \fIkeycode\fP\fI, modifiers\fP)
+.br
+      Widget \fIwidget\fP;
+.br
+      KeyCode \fIkeycode\fP;
+.br
+      Modifiers \fImodifiers\fP;
+.FN
+.IP \fIwidget\fP 1i
+Specifies the widget in whose window the key was grabbed.
+.sp 6p
+.IP \fIkeycode\fP
+.br
+.ns
+.IP \fImodifiers\fP 1i
+Specify arguments to
+.PN XUngrabKey ;
+see Section 12.2 in \fI\*(xL\fP.
+.LP
+.eM
+The
+.PN XtUngrabKey
+procedure calls
+.PN XUngrabKey
+specifying the widget's
+window as the ungrab window if the widget is realized.  The remaining
+arguments are exactly as for
+.PN XUngrabKey .
+If the widget is not realized,
+.PN XtUngrabKey
+removes a deferred
+.PN XtGrabKey
+request, if any, for the specified widget, keycode, and modifiers.
+.sp
+.LP
+To actively grab the keyboard, use
+.PN XtGrabKeyboard .
+.LP
+.IN "XtGrabKeyboard" "" "@DEF@"
+.sM
+.FD 0
+int XtGrabKeyboard(\fIwidget\fP, \fIowner_events\fP, \fIpointer_mode\fP, \
+\fIkeyboard_mode\fP, \fItime\fP)
+.br
+      Widget \fIwidget\fP;
+.br
+      Boolean \fIowner_events\fP;
+.br
+      int \fIpointer_mode\fP, \fIkeyboard_mode\fP;
+.br
+      Time \fItime\fP;
+.br
+.FN
+.IP \fIwidget\fP 1i
+Specifies the widget for whose window the keyboard is to be grabbed.
+\*(cI
+.sp 6p
+.IP \fIowner_events\fP
+.br
+.ns
+.IP \fIpointer_mode\fP
+.br
+.ns
+.IP \fIkeyboard_mode\fP
+.br
+.ns
+.IP \fItime\fP 1i
+Specify arguments to
+.PN XGrabKeyboard ;
+see Section 12.2 in \fI\*(xL\fP.
+.LP
+.eM
+If the specified widget is realized,
+.PN XtGrabKeyboard
+calls
+.PN XGrabKeyboard
+specifying the widget's window as the grab window.  The remaining
+arguments and return value are exactly as for
+.PN XGrabKeyboard .
+If the widget is not realized,
+.PN XtGrabKeyboard
+immediately returns
+.PN GrabNotViewable .
+No future automatic ungrab is implied by
+.PN XtGrabKeyboard .
+.sp
+.LP
+To cancel an active keyboard grab, use
+.PN XtUngrabKeyboard .
+.LP
+.IN "XtUngrabKeyboard" "" "@DEF@"
+.sM
+.FD 0
+void XtUngrabKeyboard(\fIwidget\fP, \fItime\fP)
+.br
+      Widget \fIwidget\fP;
+.br
+      Time \fItime\fP;
+.FN
+.IP \fIwidget\fP 1i
+Specifies the widget that has the active keyboard grab.
+.IP \fItime\fP 1i
+Specifies the additional argument to
+.PN XUngrabKeyboard ;
+see Section 12.2 in \fI\*(xL\fP.
+.LP
+.eM
+.PN XtUngrabKeyboard
+calls
+.PN XUngrabKeyboard
+with the specified time.
+.sp
+.LP
+To passively grab a single pointer button, use
+.PN XtGrabButton .
+.LP
+.IN "XtGrabButton" "" "@DEF@"
+.sM
+.FD 0
+void XtGrabButton(\fIwidget\fP, \fIbutton\fP, \fImodifiers\fP, \
+\fIowner_events\fP, \fIevent_mask\fP, \fIpointer_mode\fP,
+                  \fIkeyboard_mode\fP, \fIconfine_to\fP, \fIcursor\fP)
+.br
+      Widget \fIwidget\fP;
+.br
+      int \fIbutton\fP;
+.br
+      Modifiers \fImodifiers\fP;
+.br
+      Boolean \fIowner_events\fP;
+.br
+      unsigned int \fIevent_mask\fP;
+.br
+      int \fIpointer_mode\fP, \fIkeyboard_mode\fP;
+.br
+      Window \fIconfine_to\fP;
+.br
+      Cursor \fIcursor\fP;
+.FN
+.IP \fIwidget\fP 1i
+Specifies the widget in whose window the button is to be grabbed.  \*(cI
+.sp 6p
+.IP \fIbutton\fP
+.br
+.ns
+.IP \fImodifiers\fP
+.br
+.ns
+.IP \fIowner_events\fP
+.br
+.ns
+.IP \fIevent_mask\fP
+.br
+.ns
+.IP \fIpointer_mode\fP
+.br
+.ns
+.IP \fIkeyboard_mode\fP
+.br
+.ns
+.IP \fIconfine_to\fP
+.br
+.ns
+.IP \fIcursor\fP 1i
+Specify arguments to
+.PN XGrabButton ;
+see Section 12.1 in \fI\*(xL\fP.
+.LP
+.eM
+.PN XtGrabButton
+calls
+.PN XGrabButton
+specifying the widget's window as the
+grab window if the widget is realized.  The remaining arguments are
+exactly as for
+.PN XGrabButton .
+If the widget is not realized, or is later unrealized, the call to
+.PN XGrabButton
+is performed (again)
+when the widget is realized and its window becomes mapped.  In the
+future, if
+.PN XtDispatchEvent
+is called with a
+.PN ButtonPress
+event matching the specified button and modifiers (which may be
+.PN AnyButton
+or
+.PN AnyModifier ,
+respectively)
+for the widget's window, the \*(xI will call
+.PN XtUngrabPointer
+with the timestamp from the
+.PN ButtonPress
+event if either of the following conditions is true:
+.IP \(bu 3
+There is a modal cascade and the
+widget is not in the active subset of the cascade and the pointer was
+not previously grabbed, or
+.IP \(bu 3
+.PN XFilterEvent
+returns
+.PN True .
+
+.sp
+.LP
+To cancel a passive button grab, use
+.PN XtUngrabButton .
+.LP
+.IN "XtUngrabButton" "" "@DEF@"
+.sM
+.FD 0
+void XtUngrabButton(\fIwidget\fP, \fIbutton\fP, \fImodifiers\fP)
+.br
+      Widget \fIwidget\fP;
+.br
+      unsigned int \fIbutton\fP;
+.br
+      Modifiers \fImodifiers\fP;
+.FN
+.IP \fIwidget\fP 1i
+Specifies the widget in whose window the button was grabbed.
+.IP \fIbutton\fP
+.br
+.ns
+.IP \fImodifiers\fP 1i
+Specify arguments to
+.PN XUngrabButton ;
+see Section 12.1 in \fI\*(xL\fP.
+.LP
+.eM
+The
+.PN XtUngrabButton
+procedure calls
+.PN XUngrabButton
+specifying the
+widget's window as the ungrab window if the widget is realized.  The
+remaining arguments are exactly as for
+.PN XUngrabButton .
+If the widget is not realized,
+.PN XtUngrabButton
+removes a deferred
+.PN XtGrabButton
+request, if any, for the specified widget, button, and modifiers.
+.sp
+.LP
+To actively grab the pointer, use
+.PN XtGrabPointer .
+.LP
+.IN "XtGrabPointer" "" "@DEF@"
+.sM
+.FD 0
+int XtGrabPointer(\fIwidget\fP, \fIowner_events\fP, \fIevent_mask\fP, \
+\fIpointer_mode\fP, \fIkeyboard_mode\fP,
+                  \fIconfine_to\fP, \fIcursor\fP, \fItime\fP)
+.br
+      Widget \fIwidget\fP;
+.br
+      Boolean \fIowner_events\fP;
+.br
+      unsigned int \fIevent_mask\fP;
+.br
+      int \fIpointer_mode\fP, \fIkeyboard_mode\fP;
+.br
+      Window \fIconfine_to\fP;
+.br
+      Cursor \fIcursor\fP;
+.br
+      Time \fItime\fP;
+.FN
+.IP \fIwidget\fP 1i
+Specifies the widget for whose window the pointer is to be grabbed.  \*(cI
+.sp 6p
+.IP \fIowner_events\fP
+.br
+.ns
+.IP \fIevent_mask\fP
+.br
+.ns
+.IP \fIpointer_mode\fP
+.br
+.ns
+.IP \fIkeyboard_mode\fP
+.br
+.ns
+.IP \fIconfine_to\fP
+.br
+.ns
+.IP \fIcursor\fP
+.br
+.ns
+.IP \fItime\fP 1i
+Specify arguments to
+.PN XGrabPointer ;
+see Section 12.1 in \fI\*(xL\fP.
+.LP
+.eM
+If the specified widget is realized,
+.PN XtGrabPointer
+calls
+.PN XGrabPointer ,
+specifying the widget's window as the grab window.  The remaining
+arguments and return value are exactly as for
+.PN XGrabPointer .
+If the widget is not realized,
+.PN XtGrabPointer
+immediately returns
+.PN GrabNotViewable .
+No future automatic ungrab is implied by
+.PN XtGrabPointer .
+.sp
+.LP
+To cancel an active pointer grab, use
+.PN XtUngrabPointer .
+.LP
+.IN "XtUngrabPointer" "" "@DEF@"
+.sM
+.FD 0
+void XtUngrabPointer(\fIwidget\fP, \fItime\fP)
+.br
+      Widget \fIwidget\fP;
+.br
+      Time \fItime\fP;
+.FN
+.IP \fIwidget\fP 1i
+Specifies the widget that has the active pointer grab.
+.IP \fItime\fP 1i
+Specifies the time argument to
+.PN XUngrabPointer ;
+see Section 12.1 in \fI\*(xL\fP.
+.LP
+.eM
+.PN XtUngrabPointer
+calls
+.PN XUngrabPointer
+with the specified time.
+
+.NH 2
+Focusing Events on a Child
+.XS
+\fB\*(SN Focusing Events on a Child\fP
+.XE
+.LP
+To redirect keyboard input to a normal descendant of a
+widget without calling
+.PN XSetInputFocus ,
+use
+.PN XtSetKeyboardFocus .
+.LP
+.IN "XtSetKeyboardFocus" "" "@DEF@"
+.sM
+.FD 0
+void XtSetKeyboardFocus(\fIsubtree\fP\, \fIdescendant\fP)
+.br
+     Widget \fIsubtree\fP, \fIdescendant\fP;
+.FN
+.IP \fIsubtree\fP 1i
+Specifies the subtree of the hierarchy for which the keyboard focus is 
+to be set.  \*(cI
+.IP \fIdescendant\fP 1i
+Specifies either the normal (non-pop-up) descendant of \fIsubtree\fP to which
+keyboard events are logically directed, or 
+.PN None .
+It is not an error to specify
+.PN None
+when no input focus was previously set.  \*(oI
+.LP
+.eM
+.PN XtSetKeyboardFocus
+causes
+.PN 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.
+.LP
+When there is no modal cascade, keyboard events can be dispatched
+to a widget in one of five 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).
+.IP \(bu 3
+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
+.PN XtGrabKey
+with any value of \fIowner_events\fP, or
+if the keyboard is actively grabbed by E with \fIowner_events\fP
+.PN False
+via
+.PN XtGrabKeyboard
+or
+.PN XtGrabKey
+on a previous key press, the event is dispatched to E.
+.IP \(bu 3
+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 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.
+.RS
+.IP \- 3
+If E is the final focus target widget F or a descendant of F, the
+event is dispatched to E.
+.IP \- 3
+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
+.PN XtGrabKey
+for E,
+.PN XtUngrabKeyboard
+is called.
+.IP \- 3
+If E is an ancestor of F, and the event is a key press, and either
+.RS
+.IP + 3
+E has grabbed the key with
+.PN XtGrabKey
+and \fIowner_events\fP
+.PN False ,
+or
+.IP + 3
+E has grabbed the key with
+.PN XtGrabKey
+and \fIowner_events\fP
+.PN True ,
+and the coordinates of the event are outside the rectangle specified
+by E's geometry,
+.RE
+then the event is dispatched to E.
+.IP \- 3
+Otherwise, define A as the closest common ancestor of E and F:
+.RS
+.IP + 3
+If there is an active keyboard grab for any widget via either
+.PN XtGrabKeyboard
+or
+.PN XtGrabKey
+on a previous key press, or
+if no widget between F and A (noninclusive) has grabbed
+the key and modifier combination with
+.PN XtGrabKey
+and any value of \fIowner_events\fP, the event is dispatched to F.
+.IP + 3
+Else, the event is dispatched to the ancestor of F closest to A
+that has grabbed the key and modifier combination with
+.PN XtGrabKey .
+.RE
+.RE
+.LP
+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 \*(xI do not modify
+the contents of the event.
+.LP
+When \fIsubtree\fP 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
+.PN FocusIn
+event is generated for the descendant if
+.PN FocusChange
+events have been selected by the descendant.
+Similarly, when \fIsubtree\fP loses the X input focus
+or the keyboard focus for one of its ancestors, a
+.PN FocusOut
+event is generated for descendant if
+.PN FocusChange
+events have been selected by the descendant.
+.sp
+.LP
+A widget tree may also actively manage the X server input focus.  To
+do so, a widget class specifies an accept_focus procedure.
+.LP
+.IN "accept_focus procedure"
+The accept_focus procedure pointer is of type
+.PN XtAcceptFocusProc .
+.LP
+.IN "XtAcceptFocusProc" "" "@DEF@"
+.sM
+.FD 0
+typedef Boolean (*XtAcceptFocusProc)(Widget, Time*);
+.br
+      Widget \fIw\fP;
+.br
+      Time *\fItime\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget.
+.IP \fItime\fP 1i
+Specifies the X time of the event causing the accept focus.
+.LP
+.eM
+Widgets that need the input focus can call
+.PN XSetInputFocus
+explicitly, pursuant to the restrictions of the \fI\*(xC\fP.
+To allow outside agents, such as the parent,
+to cause a widget to take the input focus,
+every widget exports an accept_focus procedure.
+The widget returns a value indicating
+whether it actually took the focus or not,
+so that the parent can give the focus to another widget.
+Widgets that need to know when they lose the input focus must use
+the Xlib focus notification mechanism explicitly
+(typically by specifying translations for
+.PN FocusIn
+and
+.PN FocusOut
+events).
+Widgets classes that never want the input focus should set the
+\fIaccept_focus\fP field to NULL.
+.sp
+.LP
+To call a widget's accept_focus procedure, use
+.PN XtCallAcceptFocus .
+.LP
+.IN "XtCallAcceptFocus" "" "@DEF@"
+.sM
+.FD 0
+Boolean XtCallAcceptFocus(\fIw\fP, \fItime\fP)
+.br
+       Widget \fIw\fP;
+.br
+       Time *\fItime\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget.  \*(cI
+.IP \fItime\fP 1i
+Specifies the X time of the event that is causing the focus change.
+.LP
+.eM
+The
+.PN XtCallAcceptFocus
+function calls the specified widget's accept_focus procedure,
+passing it the specified widget and time, and returns what the accept_focus
+procedure returns.
+If \fIaccept_focus\fP is NULL,
+.PN XtCallAcceptFocus
+returns
+.PN False .
+
+.NH 3
+Events for Drawables That Are Not a Widget's Window
+.XS 
+\fB\*(SN Events for Drawables That Are Not a Widget's Window\fP
+.XE
+.LP
+Sometimes an application must handle events for drawables that are not
+associated with widgets in its widget tree.  Examples include handling
+.PN GraphicsExpose
+and
+.PN NoExpose
+events on Pixmaps, and handling 
+.PN PropertyNotify
+events on the root window.
+.LP
+To register a drawable with the \*(xI event dispatching, use
+.PN XtRegisterDrawable .
+.LP
+.IN "XtRegisterDrawable" "" "@DEF@"
+.sM
+.FD 0
+void XtRegisterDrawable(\fIdisplay\fP, \fIdrawable\fP, \fIwidget\fP)
+.br
+      Display *\fIdisplay\fP;
+.br
+      Drawable \fIdrawable\fP;
+.br
+      Widget \fIwidget\fP;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the drawable's display.
+.IP \fIdrawable\fP 1i
+Specifies the drawable to register.
+.IP \fIwidget\fP 1i
+Specifies the widget to register the drawable for.
+.LP
+.eM
+.PN XtRegisterDrawable
+associates the specified drawable with the specified widget
+so that future calls to
+.PN XtWindowToWidget
+with the drawable will return the widget.
+The default event dispatcher will dispatch future events that
+arrive for the drawable to the widget in the same manner as
+events that contain the widget's window.
+.LP
+If the drawable is already registered with another widget, or if the
+drawable is the window of a widget in the client's widget tree, the
+results of calling
+.PN XtRegisterDrawable
+are undefined.
+
+.LP
+To unregister a drawable with the Intrinsics event dispatching, use
+.PN XtUnregisterDrawable .
+.LP
+.IN "XtUnregisterDrawable" "" "@DEF@"
+.sM
+.FD 0
+void XtUnregisterDrawable(\fIdisplay\fP, \fIdrawable\fP)
+.br
+      Display *\fIdisplay\fP;
+.br
+      Drawable \fIdrawable\fP;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the drawable's display.
+.IP \fIdrawable\fP 1i
+Specifies the drawable to unregister.
+.LP
+.eM
+.PN XtUnregisterDrawable
+removes an association created with 
+.PN XtRegisterDrawable .  
+If the drawable is the window of a widget in the client's widget tree
+the results of calling 
+.PN XtUnregisterDrawable
+are undefined.
+
+.NH 2
+Querying Event Sources
+.XS
+\fB\*(SN Querying Event Sources\fP
+.XE
+.LP
+The event manager provides several functions to examine and read events
+(including file and timer events) that are in the queue.
+The next three functions are \*(xI equivalents of the
+.PN XPending ,
+.PN XPeekEvent ,
+and
+.PN XNextEvent
+Xlib calls.
+.sp
+.LP
+.IN "Events"
+To determine if there are any events on the input queue for a given application,
+use
+.PN XtAppPending .
+.LP
+.IN "XtAppPending" "" "@DEF@"
+.sM
+.FD 0
+XtInputMask XtAppPending(\fIapp_context\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context that identifies the application to check.
+.LP
+.eM
+The
+.PN XtAppPending
+function returns a nonzero value if there are
+events pending from the X server, timer pending, other input sources
+pending, or signal sources pending.  The
+value returned is a bit mask that is the OR of
+.PN XtIMXEvent ,
+.PN XtIMTimer ,
+.PN XtIMAlternateInput ,
+and 
+.PN XtIMSignal 
+(see
+.PN XtAppProcessEvent ).
+If there are no events pending, 
+.PN XtAppPending
+flushes the output buffers of each Display in the application context
+and returns zero.
+.sp
+.LP
+To return the event from the head of a given application's input queue
+without removing input from the queue, use
+.PN XtAppPeekEvent .
+.LP
+.IN "XtAppPeekEvent" "" "@DEF@"
+.sM
+.FD 0
+Boolean XtAppPeekEvent(\fIapp_context\fP, \fIevent_return\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.br
+      XEvent *\fIevent_return\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context that identifies the application.
+.IP \fIevent_return\fP 1i
+Returns the event information to the specified event structure.
+.LP
+.eM
+If there is an X event in the queue,
+.PN XtAppPeekEvent
+copies it into \fIevent_return\fP and returns
+.PN True .
+If no X input is on the queue,
+.PN XtAppPeekEvent
+flushes the output buffers of each Display in the application context
+and blocks until some input is available
+(possibly calling some timeout callbacks in the interim).
+If the next available input is an X event,
+.PN XtAppPeekEvent
+fills in \fIevent_return\fP and returns
+.PN True .
+Otherwise, the input is for an input source
+registered with
+.PN XtAppAddInput ,
+and
+.PN XtAppPeekEvent
+returns
+.PN False .
+.FS
+The sample implementations provides XtAppPeekEvent as described.  Timeout callbacks
+are called while blocking for input.  If some input for an input source is
+available, 
+.PN XtAppPeekEvent
+will return 
+.PN True
+without returning an event.
+.FE
+.sp
+.LP
+To remove and return the event
+from the head of a given application's X event queue,
+use
+.PN XtAppNextEvent .
+.LP
+.IN "XtAppNextEvent" "" "@DEF@"
+.sM
+.FD 0
+void XtAppNextEvent(\fIapp_context\fP, \fIevent_return\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.br
+      XEvent *\fIevent_return\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context that identifies the application.
+.IP \fIevent_return\fP 1i
+Returns the event information to the specified event structure.
+.LP
+.eM
+If the X event queue is empty,
+.PN XtAppNextEvent
+flushes the X output buffers of each Display in the application context
+and waits for an X event while looking at the other input sources
+and timeout values and calling any callback procedures triggered by them.
+This wait time can be used for background processing;
+see Section 7.8.
+
+.NH 2
+Dispatching Events
+.XS
+\fB\*(SN Dispatching Events\fP
+.XE
+.LP
+The \*(xI provide functions that dispatch events
+to widgets or other application code.
+Every client interested in X events on a widget uses
+.PN XtAddEventHandler
+to register which events it is
+interested in and a procedure (event handler) to be called
+when the event happens in that window.
+The translation manager automatically registers event handlers for widgets
+that use translation tables; see Chapter 10.
+.sp
+.LP
+Applications that need direct control of the processing of different types
+of input should use
+.PN XtAppProcessEvent .
+.LP
+.IN "XtAppProcessEvent" "" "@DEF@"
+.sM
+.FD 0
+void XtAppProcessEvent(\fIapp_context\fP, \fImask\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.br
+      XtInputMask \fImask\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context that identifies the
+application for which to process input.
+.IP \fImask\fP 1i
+Specifies what types of events to process.
+The mask is the bitwise inclusive OR of any combination of
+.PN XtIMXEvent ,
+.PN XtIMTimer ,
+.PN XtIMAlternateInput ,
+and
+.PN XtIMSignal .
+As a convenience,
+.PN Intrinsic.h
+defines the symbolic name
+.PN XtIMAll
+to be the bitwise inclusive OR of these four event types.
+.LP
+.eM
+The
+.PN XtAppProcessEvent
+function processes one timer, input source, signal source, or X event.
+If there is no event or input of the appropriate type to process, then
+.PN XtAppProcessEvent
+blocks until there is.
+If there is more than one type of input available to process,
+it is undefined which will get processed.
+Usually, this procedure is not called by client applications; see
+.PN XtAppMainLoop .
+.PN XtAppProcessEvent
+processes timer events by calling any appropriate timer callbacks,
+input sources by calling any appropriate input callbacks, 
+signal source by calling any appropriate signal callbacks,
+and X events by
+calling
+.PN XtDispatchEvent .
+.LP
+When an X event is received,
+it is passed to
+.PN XtDispatchEvent ,
+which calls the appropriate event handlers
+and passes them the widget, the event, and client-specific data
+registered with each procedure.
+If no handlers for that event are registered,
+the event is ignored and the dispatcher simply returns.
+
+.sp
+.LP
+To dispatch an event returned by
+.PN XtAppNextEvent ,
+retrieved directly from the Xlib queue, or synthetically constructed,
+to any registered event filters or event handlers, call
+.PN XtDispatchEvent .
+.LP
+.IN "XtDispatchEvent" "" "@DEF@"
+.sM
+.FD 0
+Boolean XtDispatchEvent(\fIevent\fP)
+.br
+      XEvent *\fIevent\fP;
+.FN
+.IP \fIevent\fP 1i
+Specifies a pointer to the event structure to be dispatched
+to the appropriate event handlers.
+.LP
+.eM
+The
+.PN XtDispatchEvent
+function first calls
+.PN XFilterEvent
+with the \fIevent\fP and the window of the widget to which the
+\*(xI intend to dispatch the event, or the event window if
+the \*(xI would not dispatch the event to any handlers.
+If
+.PN XFilterEvent
+returns
+.PN True
+and the event activated a server grab as identified
+by a previous call to
+.PN XtGrabKey
+or
+.PN XtGrabButton ,
+.PN XtDispatchEvent
+calls
+.PN XtUngrabKeyboard
+or
+.PN XtUngrabPointer
+with the timestamp from the event and immediately returns
+.PN True .
+If
+.PN XFilterEvent
+returns
+.PN True
+and a grab was not activated,
+.PN XtDispatchEvent
+just immediately returns
+.PN True .
+Otherwise,
+.PN XtDispatchEvent
+sends the event to the event handler functions that
+have been previously registered with the dispatch routine.
+.PN XtDispatchEvent
+returns 
+.PN True
+if
+.PN XFilterEvent
+returned
+.PN True ,
+or if the event was dispatched to some handler, and
+.PN False
+if it found no handler to which to dispatch the event.
+.PN XtDispatchEvent
+records the last timestamp in any event that
+contains a timestamp (see
+.PN XtLastTimestampProcessed ),
+regardless of whether it was filtered or dispatched.
+If a modal cascade is active with \fIspring_loaded\fP
+.PN True ,
+and if the event is a remap event as defined by
+.PN XtAddGrab ,
+.PN XtDispatchEvent
+may dispatch the event a second time.  If it does so,
+.PN XtDispatchEvent
+will call
+.PN XFilterEvent
+again with the window of the spring-loaded widget prior to the second
+dispatch, and if
+.PN XFilterEvent
+returns
+.PN True ,
+the second dispatch will not be performed.
+
+.NH 2
+The Application Input Loop
+.XS
+\fB\*(SN The Application Input Loop\fP
+.XE
+.LP
+To process all input from a given application in a continuous loop,
+use the convenience procedure
+.PN XtAppMainLoop .
+.LP
+.IN "XtAppMainLoop" "" "@DEF@"
+.sM
+.FD 0
+void XtAppMainLoop(\fIapp_context\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context that identifies the application.
+.LP
+.eM
+The
+.PN XtAppMainLoop
+function first reads the next incoming X event by calling
+.PN XtAppNextEvent 
+and then dispatches the event to the appropriate registered procedure 
+by calling
+.PN XtDispatchEvent .
+This constitutes the main loop of \*(tk applications.
+There is nothing special about
+.PN XtAppMainLoop ;
+it simply calls
+.PN XtAppNextEvent
+and then
+.PN XtDispatchEvent
+in a conditional loop.
+At the bottom of the loop, it checks to see if the specified
+application context's destroy flag is set.
+If the flag is set, the loop breaks.
+The whole loop is enclosed between a matching
+.PN XtAppLock
+and 
+.PN XtAppUnlock .
+.LP
+Applications can provide their own version of this loop,
+which tests some global termination flag or tests that the number
+of top-level widgets is larger than zero before circling back to the call to
+.PN XtAppNextEvent .
+
+.NH 2
+Setting and Checking the Sensitivity State of a Widget
+.XS
+\fB\*(SN Setting and Checking the Sensitivity State of a Widget\fP
+.XE
+.LP
+Many widgets have a mode in which they assume a different appearance
+(for example, are grayed out or stippled), do not respond to user events,
+and become dormant.
+.LP
+When dormant,
+a widget is considered to be insensitive.
+If a widget is insensitive,
+the event manager does not dispatch any events to the widget
+with an event type of
+.PN KeyPress ,
+.PN KeyRelease ,
+.PN ButtonPress ,
+.PN ButtonRelease ,
+.PN MotionNotify ,
+.PN EnterNotify ,
+.PN LeaveNotify ,
+.PN FocusIn ,
+or
+.PN FocusOut .
+.LP
+A widget can be insensitive because its \fIsensitive\fP field is
+.PN False
+or because one of its ancestors is insensitive and thus the widget's
+\fIancestor_sensitive\fP field also is 
+.PN False .
+A widget can but does not need to distinguish these two cases visually.
+.NT
+Pop-up shells will have
+\fIancestor_sensitive\fP
+.PN False
+if the parent was insensitive when the shell
+was created.  Since
+.PN XtSetSensitive
+on the parent will not
+modify the resource of the pop-up child, clients are advised to include
+a resource specification of the form
+``*TransientShell.ancestorSensitive: True''
+in the application defaults resource file or to
+otherwise ensure that the parent is
+sensitive when creating pop-up shells.
+.NE
+.sp
+.LP
+To set the sensitivity state of a widget, use
+.PN XtSetSensitive .
+.LP
+.IN "XtSetSensitive" "" "@DEF@"
+.sM
+.FD 0
+void XtSetSensitive(\fIw\fP, \fIsensitive\fP)
+.br
+      Widget \fIw\fP;
+.br
+      Boolean \fIsensitive\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget.  \*(rI
+.IP \fIsensitive\fP 1i
+Specifies whether the widget should receive
+keyboard, pointer, and focus events.
+.LP
+.eM
+The
+.PN XtSetSensitive
+function first calls
+.PN XtSetValues
+on the current widget with an argument list specifying the
+XtNsensitive resource and the new value.
+If \fIsensitive\fP is
+.PN False
+and the widget's class is a subclass of
+Composite,
+.PN XtSetSensitive
+recursively propagates the new value
+down the child tree by calling
+.PN XtSetValues
+on each child to set \fIancestor_sensitive\fP to
+.PN False .
+If \fIsensitive\fP is
+.PN True
+and the widget's class is a subclass of
+Composite
+and the widget's \fIancestor_sensitive\fP field is
+.PN True ,
+.PN XtSetSensitive
+sets the \fIancestor_sensitive\fP of each child to
+.PN True
+and then recursively calls
+.PN XtSetValues
+on each normal descendant that is now sensitive to set
+\fIancestor_sensitive\fP to
+.PN True .
+.LP
+.PN XtSetSensitive
+calls
+.PN XtSetValues
+to change the \fIsensitive\fP and \fIancestor_sensitive\fP fields
+of each affected widget.
+Therefore, when one of these changes,
+the widget's set_values procedure should
+take whatever display actions are needed
+(for example, graying out or stippling the widget).
+.LP
+.PN XtSetSensitive
+maintains the invariant that, if the parent has either \fIsensitive\fP 
+or \fIancestor_sensitive\fP 
+.PN False ,
+then all children have \fIancestor_sensitive\fP 
+.PN False .
+.sp
+.LP
+To check the current sensitivity state of a widget,
+use
+.PN XtIsSensitive .
+.LP
+.IN "XtIsSensitive" "" "@DEF@"
+.sM
+.FD 0
+Boolean XtIsSensitive(\fIw\fP)
+.br
+     Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the object.  \*(oI
+.LP
+.eM
+The
+.PN XtIsSensitive
+function returns 
+.PN True 
+or 
+.PN False 
+to indicate whether user input events are being dispatched.
+If object's class is a subclass of RectObj and
+both \fIsensitive\fP and \fIancestor_sensitive\fP are 
+.PN True ,
+.PN XtIsSensitive
+returns 
+.PN True ;
+otherwise, it returns 
+.PN False .
+
+.NH 2
+Adding Background Work Procedures
+.XS
+\fB\*(SN Adding Background Work Procedures\fP
+.XE
+.LP
+The \*(xI have some limited support for background processing.
+Because most applications spend most of their time waiting for input, 
+you can register an idle-time work procedure
+that is called when the toolkit would otherwise block in
+.PN XtAppNextEvent
+or
+.PN XtAppProcessEvent .
+Work procedure pointers are of type
+.PN XtWorkProc .
+.LP
+.IN "XtWorkProc" "" "@DEF@"
+.sM
+.FD 0
+typedef Boolean (*XtWorkProc)(XtPointer);
+.br
+      XtPointer \fIclient_data\fP;
+.FN
+.IP \fIclient_data\fP 1i
+Passes the client data specified when the work procedure was registered.
+.LP
+.eM
+This procedure should return
+.PN True
+when it is done to indicate that it
+should be removed.
+If the procedure returns
+.PN False ,
+it will remain registered and called again when the
+application is next idle.
+Work procedures should be very judicious about how much they do. 
+If they run for more than a small part of a second,
+interactive feel is likely to suffer.
+.sp
+.LP
+To register a work procedure for a given application, use
+.PN XtAppAddWorkProc .
+.LP
+.IN "XtAppAddWorkProc" "" "@DEF@"
+.sM
+.FD 0
+XtWorkProcId XtAppAddWorkProc(\fIapp_context\fP, \fIproc\fP, \fIclient_data\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.br
+      XtWorkProc \fIproc\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context that identifies the application.
+.IP \fIproc\fP 1i
+Specifies the procedure to be called when the application is idle.
+.IP \fIclient_data\fP 1i
+Specifies the argument passed to the specified procedure
+when it is called.
+.LP
+.eM
+The
+.PN XtAppAddWorkProc
+function adds the specified work procedure for the application identified
+by \fIapp_context\fP
+and returns an opaque unique identifier for this work procedure.
+Multiple work procedures can be registered,
+and the most recently added one is always the one that is called.
+However, if a work procedure adds another work procedure, 
+the newly added one has lower priority than the current one.
+.sp
+.LP
+To remove a work procedure, either return 
+.PN True 
+from the procedure when it is called or use
+.PN XtRemoveWorkProc
+outside of the procedure.
+.LP
+.IN "XtRemoveWorkProc" "" "@DEF@"
+.sM
+.FD 0
+void XtRemoveWorkProc(\fIid\fP)
+.br
+      XtWorkProcId \fIid\fP;
+.FN
+.IP \fIid\fP 1i
+Specifies which work procedure to remove.
+.LP
+.eM
+The
+.PN XtRemoveWorkProc
+function explicitly removes the specified background work procedure.
+
+.NH 2
+X Event Filters
+.XS
+\*(SN X Event Filters
+.XE
+.LP
+The event manager provides filters that can be applied to
+specific X events.
+The filters, which screen out events that are redundant or are temporarily
+unwanted, handle
+pointer motion compression,
+enter/leave compression, and
+exposure compression.
+
+.NH 3
+Pointer Motion Compression
+.XS
+\*(SN Pointer Motion Compression
+.XE
+.LP
+Widgets can have a hard time keeping up with a rapid stream of
+pointer motion events.  Furthermore,
+they usually do not care about every motion event.  To throw out
+redundant motion events, the widget class field \fIcompress_motion\fP should be
+.PN True .
+.IN "compress_motion field"
+When a request for an event would return a motion event,
+the \*(xI check if there are any other motion events
+for the same widget immediately
+following the current one and, if so, skip all but the last of them.
+
+.NH 3
+Enter/Leave Compression
+.XS
+\*(SN Enter/Leave Compression
+.XE
+.LP
+To throw out pairs of enter and leave events that have no intervening events,
+as can happen when the user moves the pointer across a widget 
+without stopping in it,
+the widget class field \fIcompress_enterleave\fP should be 
+.PN True .
+.IN "compress_enterleave field"
+These enter and leave events are not delivered to the client
+if they are found together in the input queue.
+
+.NH 3
+Exposure Compression
+.XS
+\*(SN Exposure Compression
+.XE
+.LP
+.IN "compress_expose field"
+Many widgets prefer to process a series of exposure events as a
+single expose region rather than as individual rectangles.  Widgets
+with complex displays might use the expose region as a clip list
+in a graphics context, and widgets with simple displays might
+ignore the region entirely and redisplay their whole window or
+might get the bounding box from the region and redisplay only that
+rectangle.
+.LP
+In either case, these widgets do not care about getting partial exposure events.
+The \fIcompress_exposure\fP field in the widget class
+structure specifies the type and number of exposure events that are
+dispatched to the widget's expose procedure.  This field must be
+initialized to one of the following values:
+.sp
+.sM
+.Ds 0
+.TA 3i
+.ta 3i
+#define XtExposeNoCompress	((XtEnum)False)
+#define XtExposeCompressSeries	((XtEnum)True)
+#define XtExposeCompressMultiple	<implementation-defined>
+#define XtExposeCompressMaximal	<implementation-defined>
+.De
+.LP
+.eM
+optionally ORed with any combination of the following flags (all with
+implementation-defined values):
+.PN XtExposeGraphicsExpose ,
+.PN XtExposeGraphicsExposeMerged ,
+.PN XtExposeNoExpose ,
+and
+.PN XtExposeNoRegion .
+
+.LP
+If the \fIcompress_exposure\fP field in the widget class structure does not
+specify
+.PN XtExposeNoCompress ,
+the event manager calls the widget's expose procedure only
+once for a series of exposure events.
+In this case, all
+.PN Expose
+or
+.PN GraphicsExpose
+events are accumulated into a region.
+When the final event is received,
+the event manager replaces the rectangle in the event with the
+bounding box for the region
+and calls the widget's expose procedure,
+passing the modified exposure event and (unless 
+.PN XtExposeNoRegion
+is specified) the region.
+For more information on regions, see Section 16.5 in \fI\*(xL\fP.)
+.LP
+The values have the following interpretation:
+.sp
+.LP
+.PN XtExposeNoCompress
+.IN "XtExposeNoCompress" "" "@DEF@"
+.IP
+No exposure compression is performed; every selected event is
+individually dispatched to the expose procedure with a \fIregion\fP
+argument of NULL.
+.sp
+.LP
+.PN XtExposeCompressSeries
+.IN "XtExposeCompressSeries" "" "@DEF@"
+.IP
+Each series of exposure events is coalesced into a single event,
+which is dispatched
+when an exposure event with count equal to zero is reached.
+.sp
+.LP
+.PN XtExposeCompressMultiple
+.IN "XtExposeCompressMultiple" "" "@DEF@"
+.IP
+Consecutive series of exposure events are coalesced into a single
+event, which is dispatched
+when an exposure event with count equal to zero is reached and either
+the event queue is empty or the next event is not an exposure event
+for the same widget.
+.sp
+.LP
+.PN XtExposeCompressMaximal
+.IN "XtExposeCompressMaximal" "" "@DEF"
+.IP
+All expose series currently in the queue for the widget
+are coalesced into a single
+event without regard to intervening nonexposure events.  If a
+partial series is in the end of the queue, the \*(xI will
+block until the end of the series is received.
+.sp
+.LP
+The additional flags have the following meaning:
+.sp
+.LP
+.PN XtExposeGraphicsExpose
+.IN "XtExposeGraphicsExpose" "" "@DEF@"
+.IP
+Specifies that
+.PN GraphicsExpose
+events are also to be dispatched to
+the expose procedure.
+.PN GraphicsExpose
+events are compressed, if specified, in the same manner as
+.PN Expose
+events.
+.sp
+.LP
+.PN XtExposeGraphicsExposeMerged
+.IN "XtExposeGraphicsExposeMerged" "" "@DEF@"
+.IP
+Specifies in the case of
+.PN XtExposeCompressMultiple
+and
+.PN XtExposeCompressMaximal
+that series of
+.PN GraphicsExpose
+and
+.PN Expose
+events are to be compressed together, with the final event type
+determining the type of the event passed to the expose procedure.
+If this flag is not set, then only series of the same event type
+as the event at the head of the queue are coalesced.  This flag
+also implies
+.PN XtExposeGraphicsExpose .
+.sp
+.LP
+.PN XtExposeNoExpose
+.IN "XtExposeNoExpose" "" "@DEF@"
+.IP
+Specifies that
+.PN NoExpose
+events are also to be dispatched to the expose procedure.
+.PN NoExpose
+events are never coalesced with
+other exposure events or with each other.
+.sp
+.LP
+.PN XtExposeNoRegion
+.IN "XtExposeNoRegion" "" "@DEF"
+.IP
+Specifies that the final region argument passed to the expose
+procedure is NULL.  The rectangle in the event will still
+contain bounding box information for the entire series of
+compressed exposure events.  This option saves processing time when the
+region is not needed by the widget.
+
+.NH 2
+Widget Exposure and Visibility
+.XS
+\*(SN Widget Exposure and Visibility
+.XE
+.LP
+Every primitive widget and some composite widgets display data on the screen
+by means of direct Xlib calls.
+Widgets cannot simply write to the screen and forget what they have done.
+They must keep enough state to redisplay the window or parts
+of it if a portion is obscured and then reexposed.
+
+.NH 3
+Redisplay of a Widget: The expose Procedure
+.XS
+\*(SN Redisplay of a Widget: The expose Procedure
+.XE
+.IN "expose procedure"
+.LP
+The expose procedure pointer in a widget class is of type
+.PN XtExposeProc .
+.LP
+.IN "XtExposeProc" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtExposeProc)(Widget, XEvent*, Region);
+.br
+      Widget \fIw\fP;
+.br
+      XEvent *\fIevent\fP;
+.br
+      Region \fIregion\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget instance requiring redisplay.
+.IP \fIevent\fP 1i
+Specifies the exposure event giving the rectangle requiring redisplay.
+.IP \fIregion\fP 1i
+Specifies the union of all rectangles in this exposure sequence.
+.LP
+.eM
+The redisplay of a widget upon exposure is the responsibility of the
+expose procedure in the widget's class record.
+If a widget has no display semantics,
+it can specify NULL for the \fIexpose\fP field.
+Many composite widgets serve only as containers for their children
+and have no expose procedure.
+.NT
+If the \fIexpose\fP procedure is NULL,
+.PN XtRealizeWidget
+fills in a default bit gravity of
+.PN NorthWestGravity
+before it calls the widget's realize procedure.
+.NE
+.LP
+If the widget's \fIcompress_exposure\fP class field specifies
+.PN XtExposeNoCompress
+or 
+.PN XtExposeNoRegion ,
+or if the event type is
+.PN NoExpose
+(see Section 7.9.3),
+\fIregion\fP is NULL.  If
+.PN XtExposeNoCompress
+is not specified and the event type is not
+.PN NoExpose ,
+the event is the final event in the compressed series
+but \fIx\fP, \fIy\fP, \fIwidth\fP, and \fIheight\fP contain
+the bounding box for all the compressed events.
+The region is created and destroyed by the \*(xI, but
+the widget is permitted to modify the region contents.
+.LP
+A small simple widget (for example, Label) can ignore the bounding box
+information in the event and redisplay the entire window.
+A more complicated widget (for example, Text) can use the bounding box
+information to minimize the amount of calculation and redisplay it does.
+A very complex widget uses the region as a clip list in a GC and
+ignores the event information.
+The expose procedure is not chained and is therefore
+responsible for exposure of all superclass data
+as well as its own.
+.LP
+However,
+it often is possible to anticipate the display needs of several levels
+of subclassing.
+For example, rather than implement separate display procedures for
+the widgets Label, Pushbutton, and Toggle,
+you could write a single display routine in Label that uses display state
+fields like
+.LP
+.DS
+Boolean invert;
+Boolean highlight;
+Dimension highlight_width;
+.DE
+Label would have \fIinvert\fP and \fIhighlight\fP always 
+.PN False
+and \fIhighlight_width\fP zero.
+Pushbutton would dynamically set \fIhighlight\fP and \fIhighlight_width\fP, 
+but it would leave \fIinvert\fP always 
+.PN False .
+Finally, Toggle would dynamically set all three.
+In this case,
+the expose procedures for Pushbutton and Toggle inherit
+their superclass's expose procedure;
+see Section 1.6.10.
+
+.NH 3
+Widget Visibility
+.XS
+\*(SN Widget Visibility
+.XE
+.LP
+Some widgets may use substantial computing resources to produce the
+data they will display.
+However, this effort is wasted if the widget is not actually visible
+on the screen, that is, if the widget is obscured by another application 
+or is iconified.
+.LP
+.IN "Visibility"
+The \fIvisible\fP field in the
+core
+widget structure provides a hint to the widget that it need not compute
+display data.
+This field is guaranteed to be
+.PN True
+by the time an
+exposure
+event is processed if any part of the widget is visible,
+but is
+.PN False 
+if the widget is fully obscured.
+.LP
+Widgets can use or ignore the \fIvisible\fP hint.
+If they ignore it,
+they should have \fIvisible_interest\fP in their widget class record set 
+.PN False .
+In such cases,
+the \fIvisible\fP field is initialized 
+.PN True 
+and never changes.
+If \fIvisible_interest\fP is 
+.PN True ,
+the event manager asks for
+.PN VisibilityNotify
+events for the widget and sets \fIvisible\fP to
+.PN True
+on
+.PN VisibilityUnobscured
+or
+.PN VisibilityPartiallyObscured
+.IN VisibilityNotify
+events and
+.PN False
+on
+.PN VisibilityFullyObscured
+events.
+
+.NH 2
+X Event Handlers
+.XS
+\*(SN X Event Handlers
+.XE
+.LP
+Event handlers are procedures called when specified events
+occur in a widget.
+Most widgets need not use event handlers explicitly.
+Instead, they use the \*(xI translation manager.
+Event handler procedure pointers are of the type
+.PN XtEventHandler .
+.LP
+.IN "XtEventHandler" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtEventHandler)(Widget, XtPointer, XEvent*, Boolean*);
+.br
+      Widget \fIw\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.br
+      XEvent *\fIevent\fP;
+.br
+      Boolean *\fIcontinue_to_dispatch\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget for which the event arrived.
+.IP \fIclient_data\fP 1i
+Specifies any client-specific information registered with the event handler.
+.IP \fIevent\fP 1i
+Specifies the triggering event.
+.IP \fIcontinue_to_dispatch\fP 1i
+Specifies whether the remaining event
+handlers registered for the current event
+should be called.
+.LP
+.eM
+After receiving an event and before calling any event handlers, the
+Boolean pointed to by \fIcontinue_to_dispatch\fP is initialized to
+.PN True .
+When an event handler is called, it may decide that further processing
+of the event is not desirable and may store
+.PN False
+in this Boolean, in
+which case any handlers remaining to be called for the event are
+ignored.
+.LP
+The circumstances under which the \*(xI may add event handlers
+to a widget are currently implementation-dependent.  Clients must
+therefore be aware that storing
+.PN False
+into the \fIcontinue_to_dispatch\fP argument can lead to portability problems.
+
+.NH 3
+Event Handlers That Select Events
+.XS
+\*(SN Event Handlers That Select Events
+.XE
+.LP
+To register an event handler procedure with the dispatch mechanism, use
+.PN XtAddEventHandler .
+.LP
+.IN "XtAddEventHandler" "" "@DEF@"
+.sM
+.FD 0
+void XtAddEventHandler(\fIw\fP, \fIevent_mask\fP, \fInonmaskable\fP, \
+\fIproc\fP, \fIclient_data\fP)
+.br
+      Widget \fIw\fP;
+.br
+      EventMask \fIevent_mask\fP;
+.br
+      Boolean \fInonmaskable\fP;
+.br
+      XtEventHandler \fIproc\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget for which this event handler is being registered.  \*(cI
+.IP \fIevent_mask\fP 1i
+Specifies the event mask for which to call this procedure.
+.IP \fInonmaskable\fP 1i
+Specifies whether this procedure should be 
+called on the nonmaskable events
+.Pn ( GraphicsExpose ,
+.PN NoExpose ,
+.PN SelectionClear ,
+.PN SelectionRequest ,
+.PN SelectionNotify ,
+.PN ClientMessage ,
+and
+.PN MappingNotify ).
+.IP \fIproc\fP 1i
+Specifies the procedure to be called.
+.IP \fIclient_data\fP 1i
+Specifies additional data to be passed to the event handler.
+.LP
+.eM
+The
+.PN XtAddEventHandler
+function registers a procedure with the dispatch mechanism that is
+to be called when an event that matches the mask occurs on the specified
+widget.
+Each widget has a single registered event handler list, which will
+contain any procedure/client_data pair exactly once regardless of
+the manner in which it is registered.
+If the procedure is already registered with the same \fIclient_data\fP
+value,
+the specified mask augments the existing mask.
+If the widget is realized,
+.PN XtAddEventHandler
+calls
+.PN XSelectInput ,
+if necessary.
+The order in which this procedure is called relative to other handlers
+registered for the same event is not defined.
+.sp
+.LP
+To remove a previously registered event handler, use
+.PN XtRemoveEventHandler .
+.LP
+.IN "XtRemoveEventHandler" "" "@DEF@"
+.sM
+.FD 0
+void XtRemoveEventHandler(\fIw\fP, \fIevent_mask\fP, \fInonmaskable\fP, \
+\fIproc\fP, \fIclient_data\fP)
+.br
+      Widget \fIw\fP;
+.br
+      EventMask \fIevent_mask\fP;
+.br
+      Boolean \fInonmaskable\fP;
+.br
+      XtEventHandler \fIproc\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget for which this procedure is registered.  \*(cI
+.IP \fIevent_mask\fP 1i
+Specifies the event mask for which to unregister this procedure.
+.IP \fInonmaskable\fP 1i
+Specifies whether this procedure should be 
+removed on the nonmaskable events
+.Pn ( GraphicsExpose ,
+.PN NoExpose ,
+.PN SelectionClear ,
+.PN SelectionRequest ,
+.PN SelectionNotify ,
+.PN ClientMessage ,
+and
+.PN MappingNotify ).
+.IP \fIproc\fP 1i
+Specifies the procedure to be removed.
+.IP \fIclient_data\fP 1i
+Specifies the registered client data.
+.LP
+.eM
+The
+.PN XtRemoveEventHandler
+function unregisters an event handler registered with
+.PN XtAddEventHandler
+or
+.PN XtInsertEventHandler
+for the specified events.
+The request is ignored if \fIclient_data\fP does not match the value given
+when the handler was registered.
+If the widget is realized and no other event handler requires the event,
+.PN XtRemoveEventHandler
+calls
+.PN XSelectInput .
+If the specified procedure has not been registered 
+or if it has been registered with a different value of \fIclient_data\fP,
+.PN XtRemoveEventHandler
+returns without reporting an error.
+.LP
+To stop a procedure registered with
+.PN XtAddEventHandler
+or
+.PN XtInsertEventHandler
+from receiving all selected events, call
+.PN XtRemoveEventHandler
+with an \fIevent_mask\fP of
+.PN XtAllEvents
+and \fInonmaskable\fP 
+.PN True .
+The procedure will continue to receive any events
+that have been specified in calls to
+.PN XtAddRawEventHandler
+or
+.PN XtInsertRawEventHandler .
+.sp
+.LP
+To register an event handler procedure that receives events before or
+after all previously registered event handlers, use
+.PN XtInsertEventHandler .
+.LP
+.IN "XtListPosition" "" "@DEF@"
+.IN "XtInsertEventHandler" "" "@DEF@"
+.sM
+.Ds 0
+typedef enum {XtListHead, XtListTail} XtListPosition;
+.De
+.LP
+.FD 0
+void XtInsertEventHandler(\fIw\fP, \fIevent_mask\fP, \fInonmaskable\fP, \
+\fIproc\fP, \fIclient_data\fP, \fIposition\fP)
+.br
+      Widget \fIw\fP;
+.br
+      EventMask \fIevent_mask\fP;
+.br
+      Boolean \fInonmaskable\fP;
+.br
+      XtEventHandler \fIproc\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.br
+      XtListPosition \fIposition\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget for which this event handler is being registered. \*(cI
+.IP \fIevent_mask\fP 1i
+Specifies the event mask for which to call this procedure.
+.IP \fInonmaskable\fP 1i
+Specifies whether this procedure should be 
+called on the nonmaskable events
+.Pn ( GraphicsExpose ,
+.PN NoExpose ,
+.PN SelectionClear ,
+.PN SelectionRequest ,
+.PN SelectionNotify ,
+.PN ClientMessage ,
+and
+.PN MappingNotify ).
+.IP \fIproc\fP 1i
+Specifies the procedure to be called.
+.IP \fIclient_data\fP 1i
+Specifies additional data to be passed to the client's event handler.
+.IP \fIposition\fP 1i
+Specifies when the event handler is to be called
+relative to other previously registered handlers.
+.LP
+.eM
+.PN XtInsertEventHandler
+is identical to
+.PN XtAddEventHandler
+with the additional \fIposition\fP argument.  If \fIposition\fP is
+.PN XtListHead ,
+the event
+handler is registered so that it is called before any event
+handlers that were previously registered for the same widget.  If
+\fIposition\fP is
+.PN XtListTail ,
+the event handler is registered to be called
+after any previously registered event handlers.  If the procedure is
+already registered with the same \fIclient_data\fP value, the specified mask
+augments the existing mask and the procedure is repositioned in
+the list.
+
+.NH 3
+Event Handlers That Do Not Select Events
+.XS
+\*(SN Event Handlers That Do Not Select Events
+.XE
+.LP
+On occasion,
+clients need to register an event handler procedure with the
+dispatch mechanism without explicitly
+causing the X server to select for that event.
+To do this, use
+.PN XtAddRawEventHandler .
+.LP
+.IN "XtAddRawEventHandler" "" "@DEF@"
+.sM
+.FD 0
+void XtAddRawEventHandler(\fIw\fP, \fIevent_mask\fP, \fInonmaskable\fP, \
+\fIproc\fP, \fIclient_data\fP)
+.br
+      Widget \fIw\fP;
+.br
+      EventMask \fIevent_mask\fP;
+.br
+      Boolean \fInonmaskable\fP;
+.br
+      XtEventHandler \fIproc\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget for which this event handler is being registered. \*(cI
+.IP \fIevent_mask\fP 1i
+Specifies the event mask for which to call this procedure.
+.IP \fInonmaskable\fP 1i
+Specifies whether this procedure should be 
+called on the nonmaskable events
+.Pn ( GraphicsExpose ,
+.PN NoExpose ,
+.PN SelectionClear ,
+.PN SelectionRequest ,
+.PN SelectionNotify ,
+.PN ClientMessage ,
+and
+.PN MappingNotify ).
+.IP \fIproc\fP 1i
+Specifies the procedure to be called.
+.IP \fIclient_data\fP 1i
+Specifies additional data to be passed to the client's event handler.
+.LP
+.eM
+The
+.PN XtAddRawEventHandler
+function is similar to
+.PN XtAddEventHandler 
+except that it does not affect the widget's event mask and never causes an
+.PN XSelectInput
+for its events.
+Note that the widget might already have those mask bits set
+because of other nonraw event handlers registered on it.
+If the procedure is already registered with the same \fIclient_data\fP,
+the specified mask augments the existing mask.
+The order in which this procedure is called relative to other handlers
+registered for the same event is not defined.
+.sp
+.LP
+To remove a previously registered raw event handler, use
+.PN XtRemoveRawEventHandler .
+.LP
+.IN "XtRemoveRawEventHandler" "" "@DEF@"
+.sM
+.FD 0
+void XtRemoveRawEventHandler(\fIw\fP, \fIevent_mask\fP, \fInonmaskable\fP, \
+\fIproc\fP, \fIclient_data\fP)
+.br
+      Widget \fIw\fP;
+.br
+      EventMask \fIevent_mask\fP;
+.br
+      Boolean \fInonmaskable\fP;
+.br
+      XtEventHandler \fIproc\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget for which this procedure is registered.  \*(cI
+.IP \fIevent_mask\fP 1i
+Specifies the event mask for which to unregister this procedure.
+.IP \fInonmaskable\fP 1i
+Specifies whether this procedure should be 
+removed on the nonmaskable events
+.Pn ( GraphicsExpose ,
+.PN NoExpose ,
+.PN SelectionClear ,
+.PN SelectionRequest ,
+.PN SelectionNotify ,
+.PN ClientMessage ,
+and
+.PN MappingNotify ).
+.IP \fIproc\fP 1i
+Specifies the procedure to be registered.
+.IP \fIclient_data\fP 1i
+Specifies the registered client data.
+.LP
+.eM
+The
+.PN XtRemoveRawEventHandler
+function unregisters an event handler registered with
+.PN XtAddRawEventHandler
+or
+.PN XtInsertRawEventHandler
+for the specified events without changing
+the window event mask.
+The request is ignored if \fIclient_data\fP does not match the value given
+when the handler was registered.
+If the specified procedure has not been registered 
+or if it has been registered with a different value of \fIclient_data\fP,
+.PN XtRemoveRawEventHandler
+returns without reporting an error.
+.LP
+To stop a procedure
+registered with
+.PN XtAddRawEventHandler
+or
+.PN XtInsertRawEventHandler
+from receiving all nonselected events, call
+.PN XtRemoveRawEventHandler
+with an \fIevent_mask\fP of
+.PN XtAllEvents
+and \fInonmaskable\fP
+.PN True .
+The procedure
+will continue to receive any events that have been specified in calls to
+.PN XtAddEventHandler
+or
+.PN XtInsertEventHandler .
+.sp
+.LP
+To register an event handler procedure that receives events before or
+after all previously registered event handlers without selecting for
+the events, use
+.PN XtInsertRawEventHandler .
+.LP
+.IN "XtInsertRawEventHandler" "" "@DEF@"
+.sM
+.FD 0
+void XtInsertRawEventHandler(\fIw\fP, \fIevent_mask\fP, \fInonmaskable\fP, \
+\fIproc\fP, \fIclient_data\fP, \fIposition\fP)
+.br
+      Widget \fIw\fP;
+.br
+      EventMask \fIevent_mask\fP;
+.br
+      Boolean \fInonmaskable\fP;
+.br
+      XtEventHandler \fIproc\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.br
+      XtListPosition \fIposition\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget for which this event handler is being registered. \*(cI
+.IP \fIevent_mask\fP 1i
+Specifies the event mask for which to call this procedure.
+.IP \fInonmaskable\fP 1i
+Specifies whether this procedure should be 
+called on the nonmaskable events
+.Pn ( GraphicsExpose ,
+.PN NoExpose ,
+.PN SelectionClear ,
+.PN SelectionRequest ,
+.PN SelectionNotify ,
+.PN ClientMessage ,
+and
+.PN MappingNotify ).
+.IP \fIproc\fP 1i
+Specifies the procedure to be registered.
+.IP \fIclient_data\fP 1i
+Specifies additional data to be passed to the client's event handler.
+.IP \fIposition\fP 1i
+Specifies when the event handler is to be called
+relative to other previously registered handlers.
+.LP
+.eM
+The
+.PN XtInsertRawEventHandler
+function is similar to
+.PN XtInsertEventHandler
+except that it does not modify the widget's event
+mask and never causes an
+.PN XSelectInput
+for the specified events.  If
+the procedure is already registered with the same \fIclient_data\fP
+value, the
+specified mask augments the existing mask and the procedure is
+repositioned in the list.
+
+.NH 3
+Current Event Mask
+.XS
+\*(SN Current Event Mask
+.XE
+.LP
+To retrieve the event mask for a given widget, use
+.PN XtBuildEventMask .
+.LP
+.IN "XtBuildEventMask" "" "@DEF@"
+.sM
+.FD 0
+EventMask XtBuildEventMask(\fIw\fP)
+.br
+      Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget.  \*(cI
+.LP
+.eM
+The
+.PN XtBuildEventMask
+function returns the event mask representing the logical OR
+of all event masks for event handlers registered on the widget with
+.PN XtAddEventHandler
+and
+.PN XtInsertEventHandler
+and all event translations, including accelerators,
+installed on the widget.
+This is the same event mask stored into the 
+.PN XSetWindowAttributes
+structure by
+.PN XtRealizeWidget
+and sent to the server when event handlers and translations are installed or
+removed on the realized widget.
+
+.NH 3
+Event Handlers for X11 Protocol Extensions
+.XS
+\fB\*(SN Event Handlers for X11 Protocol Extensions\fP
+.XE
+.LP
+To register an event handler procedure with the \*(xI dispatch
+mechanism according to an event type, use 
+.PN XtInsertEventTypeHandler .
+.LP
+.IN "XtInsertEventTypeHandler" "" "@DEF"
+.sM
+.FD 0
+void XtInsertEventTypeHandler(\fIwidget\fP, \fIevent_type\fP, \
+\fIselect_data\fP, \fIproc\fP, \fIclient_data\fP, \fIposition\fP)
+.br
+      Widget \fIwidget\fP;
+.br
+      int \fIevent_type\fP;
+.br
+      XtPointer \fIselect_data\fP;
+.br
+      XtEventHandler \fIproc\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.br
+      XtListPosition \fIposition\fP;
+.FN
+.IP \fIwidget\fP 1i
+Specifies the widget for which this event handler is being registered.  \*(cI
+.IP \fIevent_type\fP 1i
+Specifies the event type for which to call this event handler.
+.IP \fIselect_data\fP 1i
+Specifies data used to request events of the specified type from the server,
+or NULL.
+.IP \fIproc\fP 1i
+Specifies the event handler to be called.
+.IP \fIclient_data\fP 1i
+Specifies additional data to be passed to the event handler.
+.IP \fIposition\fP 1i
+Specifies when the event handler is to be called relative to other
+previously registered handlers.
+.LP
+.eM
+.PN XtInsertEventTypeHandler
+registers a procedure with the
+dispatch mechanism that is to be called when an event that matches the
+specified \fIevent_type\fP is dispatched to the specified \fIwidget\fP.  
+.LP
+If \fIevent_type\fP specifies one of the core X protocol events, then
+\fIselect_data\fP must be a pointer to a value of type 
+.PN EventMask ,
+indicating
+the event mask to be used to select for the desired event.  This event
+mask is included in the value returned by 
+.PN XtBuildEventMask .
+If the widget is realized,
+.PN XtInsertEventTypeHandler 
+calls 
+.PN XSelectInput
+if necessary.  Specifying NULL for \fIselect_data\fP is equivalent to
+specifying a pointer to an event mask containing 0.  This is similar
+to the 
+.PN XtInsertRawEventHandler
+function.  
+.LP
+If \fIevent_type\fP specifies an extension event type, then the semantics of
+the data pointed to by \fIselect_data\fP are defined by the extension
+selector registered for the specified event type.
+.LP
+In either case the \*(xI are not required to copy the data
+pointed to by \fIselect_data\fP, so the caller must ensure that it remains
+valid as long as the event handler remains registered with this value
+of \fIselect_data\fP.
+.LP
+The \fIposition\fP argument allows the client to control the order of
+invocation of event handlers registered for the same event type.  If
+the client does not care about the order, it should normally specify
+.PN XtListTail ,
+which registers this event handler after any previously
+registered handlers for this event type.
+.LP
+Each widget has a single registered event handler list, which will
+contain any procedure/client_data pair exactly once if it is
+registered with 
+.PN XtInsertEventTypeHandler ,
+regardless of the manner
+in which it is registered and regardless of the value(s)
+of \fIselect_data\fP.  If the procedure is already registered with the
+same \fIclient_data\fP value, the specified mask augments the existing
+mask and the procedure is repositioned in the list.
+.sp
+.LP
+To remove an event handler registered with 
+.PN XtInsertEventTypeHandler ,
+use
+.PN XtRemoveEventTypeHandler .
+.LP
+.IN "XtRemoveEventTypeHandler" "" "@DEF"
+.sM
+.FD 0
+void XtRemoveEventTypeHandler(\fIwidget\fP, \fIevent_type\fP, \
+\fIselect_data\fP, \fIproc\fP, \fIclient_data\fP)
+.br
+      Widget \fIwidget\fP;
+.br
+      int \fIevent_type\fP;
+.br
+      XtPointer \fIselect_data\fP;
+.br
+      XtEventHandler \fIproc\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.FN
+.IP \fIwidget\fP 1i
+Specifies the widget for which the event handler was registered.  \*(cI
+.IP \fIevent_type\fP 1i
+Specifies the event type for which the handler was registered.
+.IP \fIselect_data\fP 1i
+Specifies data used to deselect events of the specified type 
+from the server, or NULL.
+.IP \fIproc\fP 1i
+Specifies the event handler to be removed.
+.IP \fIclient_data\fP 1i
+Specifies the additional client data with which the procedure was registered.
+.LP
+.eM
+The
+.PN XtRemoveEventTypeHandler
+function unregisters an event handler
+registered with
+.PN XtInsertEventTypeHandler
+for the specified event type.
+The request is ignored if \fIclient_data\fP does not match the value given
+when the handler was registered.
+.LP
+If \fIevent_type\fP specifies one of the core X protocol events,
+\fIselect_data\fP must be a pointer to a value of type 
+.PN EventMask, indicating the event
+mask to be used to deselect for the appropriate event.  If the widget
+is realized, 
+.PN XtRemoveEventTypeHandler
+calls
+.PN XSelectInput
+if necessary.
+Specifying NULL for \fIselect_data\fP is equivalent to specifying a pointer
+to an event mask containing 0.  This is similar to the
+.PN XtRemoveRawEventHandler
+function.
+.LP
+If \fIevent_type\fP specifies an extension event type, then the semantics of
+the data pointed to by \fIselect_data\fP are defined by the extension
+selector registered for the specified event type.
+.sp
+.LP
+To register a procedure to select extension events for a widget, use
+.PN XtRegisterExtensionSelector .
+.LP
+.IN "XtRegisterExtensionSelector" "" "@DEF@"
+.sM
+.FD 0
+void XtRegisterExtensionSelector(\fIdisplay\fP, \fImin_event_type\fP, \
+\fImax_event_type\fP, \fIproc\fP,
+                                                     \fIclient_data\fP)
+.br
+      Display \fI*display\fP;
+.br
+      int \fImin_event_type\fP;
+.br
+      int \fImax_event_type\fP;
+.br
+      XtExtensionSelectProc \fIproc\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.FN
+.IP \fIdisplay\fP 1.5i
+Specifies the display for which the extension selector is to be registered.
+.IP \fImin_event_type\fP
+.IP \fImax_event_type\fP 1.5i
+Specifies the range of event types for the extension.
+.IP \fIproc\fP 1.5i
+Specifies the extension selector procedure.
+.IP \fIclient_data\fP 1.5i
+Specifies additional data to be passed to the extension selector.
+.LP
+.eM
+The
+.PN XtRegisterExtensionSelector
+function registers a procedure to arrange 
+for the delivery of extension events to widgets.
+.LP
+If \fImin_event_type\fP and \fImax_event_type\fP match the parameters
+to a previous call to
+.PN XtRegisterExtensionSelector
+for the same \fIdisplay\fP, then \fIproc\fP and \fIclient_data\fP
+replace the previously
+registered values.  If the range specified by \fImin_event_type\fP
+and \fImax_event_type\fP overlaps the range of the parameters to a
+previous call for the same display in any other way, an error results.
+.LP
+When a widget is realized, 
+after the \fIcore.realize\fP method is called,
+the \*(xI check to see if any event
+handler specifies an event type within the range of a registered
+extension selector.  If so, the \*(xI call each such selector.
+If an event type handler is added or removed, the \*(xI check to
+see if the event type falls within the range of a registered extension
+selector, and if it does, calls the selector.  In either case the \*(xI
+pass a list of all the widget's event types that are within the
+selector's range.  The corresponding select data are also passed.  The
+selector is responsible for enabling the delivery of extension events
+required by the widget.
+.sp
+.LP
+An extension selector is of type
+.PN XtExtensionSelectProc .
+.LP
+.IN "XtExtensionSelectProc" "" "@DEF"
+.sM
+.FD 0
+typedef void (*XtExtensionSelectProc)(Widget, int *, XtPointer *, int, \
+XtPointer);
+.br
+      Widget \fIwidget\fP;
+.br
+      int *\fIevent_types\fP;
+.br
+      XtPointer *\fIselect_data\fP;
+.br
+      int \fIcount\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.FN
+.IP \fIwidget\fP 1i
+Specifies the widget that is being realized or is having
+an event handler added or removed.
+.IP \fIevent_types\fP 1i
+Specifies a list of event types that the widget has
+registered event handlers for.
+.IP \fIselect_data\fP 1i
+Specifies a list of the select_data parameters specified in
+.PN XtInsertEventTypeHandler .
+.IP \fIcount\fP 1i
+Specifies the number of entries in the \fIevent_types\fP and \fIselect_data\fP
+lists.
+.IP \fIclient_data\fP 1i
+Specifies the additional client data with which the procedure was registered.
+.LP
+.eM
+The \fIevent_types\fP and \fIselect_data\fP lists will always have the
+same number of elements, specified by \fIcount\fP.  
+Each event type/select data pair represents one call to
+.PN XtInsertEventTypeHandler .
+.sp
+.LP
+To register a procedure to dispatch events of a specific type within
+.PN XtDispatchEvent ,
+use
+.PN XtSetEventDispatcher .
+.LP
+.IN "XtSetEventDispatcher" "" "@DEF@"
+.sM
+.FD 0
+XtEventDispatchProc XtSetEventDispatcher(\fIdisplay\fP, \fIevent_type\fP, \
+\fIproc\fP)
+.br
+      Display *\fIdisplay\fP;
+.br
+      int \fIevent_type\fP;
+.br
+      XtEventDispatchProc \fIproc\fP;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the display for which the event dispatcher is to be registered.
+.IP \fIevent_type\fP 1i
+Specifies the event type for which the dispatcher should be invoked.
+.IP \fIproc\fP 1i
+Specifies the event dispatcher procedure.
+.LP
+.eM
+The 
+.PN XtSetEventDispatcher
+function registers the event dispatcher procedure specified by \fIproc\fP
+for events with the type \fIevent_type\fP.  The previously registered
+dispatcher (or the default dispatcher if there was no previously registered
+dispatcher) is returned.  If \fIproc\fP is NULL, the default procedure is
+restored for the specified type.
+.LP
+In the future, when
+.PN XtDispatchEvent
+is called with an event type of \fIevent_type\fP, the specified \fIproc\fP
+(or the default dispatcher) is invoked to determine a widget
+to which to dispatch the event. 
+.LP
+The default dispatcher handles the \*(xI modal cascade and keyboard
+focus mechanisms, handles the semantics of \fIcompress_enterleave\fP
+and \fIcompress_motion\fP, and discards all extension events.
+.sp
+.LP
+An event dispatcher procedure pointer is of type
+.PN XtEventDispatchProc .
+.LP
+.IN "XtEventDispatchProc" "" "@DEF@"
+.sM
+.FD 0
+typedef Boolean (*XtEventDispatchProc)(XEvent*)
+.br
+      XEvent *\fIevent\fP;
+.FN
+.IP \fIevent\fP 1i
+Passes the event to be dispatched.
+.LP
+.eM
+The event dispatcher procedure should determine whether this event is of
+a type that should be dispatched to a widget.  
+.LP
+If the event should be dispatched to a widget, the event dispatcher
+procedure should determine the appropriate widget to receive the
+event, call 
+.PN XFilterEvent
+with the window of this widget, or
+.PN None
+if the event is to be discarded, and if
+.PN XFilterEvent
+returns
+.PN False ,
+dispatch the event to the widget using
+.PN XtDispatchEventToWidget .
+The procedure should return
+.PN True
+if either
+.PN XFilterEvent
+or
+.PN XtDispatchEventToWidget
+returned
+.PN True
+and
+.PN False
+otherwise.
+.LP
+If the event should not be dispatched to a widget, the event
+dispatcher procedure should attempt to dispatch the event elsewhere as
+appropriate and return
+.PN True
+if it successfully dispatched the event and
+.PN False
+otherwise.
+.sp
+.LP
+Some dispatchers for extension events may wish to forward events
+according to the Intrinsics' keyboard focus mechanism.  To determine
+which widget is the end result of keyboard event forwarding, use
+.PN XtGetKeyboardFocusWidget .
+.LP
+.IN "XtGetKeyboardFocusWidget" "" "@DEF@"
+.sM
+.FD 0
+Widget XtGetKeyboardFocusWidget(\fIwidget\fP)
+.br
+      Widget \fIwidget\fP;
+.FN
+.IP \fIwidget\fP 1i
+Specifies the widget to get forwarding information for.
+.LP
+.eM
+The
+.PN XtGetKeyboardFocusWidget 
+function returns the widget that would be the end result of keyboard
+event forwarding for a keyboard event for the specified widget.
+.sp
+.LP
+To dispatch an event to a specified widget, use
+.PN XtDispatchEventToWidget .
+.LP
+.IN "XtDispatchEventToWidget" "" "@DEF@"
+.sM
+.FD 0
+Boolean XtDispatchEventToWidget(\fIwidget\fP, \fIevent\fP)
+.br
+      Widget \fIwidget\fP;
+.br
+      XEvent *\fIevent\fP;
+.FN
+.IP \fIwidget\fP 1i
+Specifies the widget to which to dispatch the event.
+.IP \fIevent\fP 1i
+Specifies a pointer to the event to be dispatched.
+.LP
+.eM
+The 
+.PN XtDispatchEventToWidget
+function scans the list of registered event handlers for the
+specified widget and calls each handler that has been registered
+for the specified event type, subject to the \fIcontinue_to_dispatch\fP
+value returned by each handler.
+The \*(xI behave as if event handlers were registered at the head
+of the list for
+.PN Expose ,
+.PN NoExpose ,
+.PN GraphicsExpose ,
+and
+.PN VisibilityNotify
+events to invoke the widget's expose procedure according to the exposure
+compression rules and to update the widget's \fIvisible\fP field
+if \fIvisible_interest\fP is
+.PN True .
+These internal event handlers never set \fIcontinue_to_dispatch\fP to
+.PN False .
+.LP
+.PN XtDispatchEventToWidget
+returns
+.PN True
+if any event handler was called and
+.PN False
+otherwise.
+
+.NH 2
+Using the \*(xI in a Multi-Threaded Environment
+.XS
+\*(SN Using the \*(xI in a Multi-Threaded Environment
+.XE
+.LP
+The \*(xI may be used in environments that offer multiple threads
+of execution within the context of a single process.  A multi-threaded 
+application using the \*(xI must explicitly initialize the toolkit 
+for mutually exclusive access by calling
+.PN XtToolkitThreadInitialize .
+
+.NH 3
+Initializing a Multi-Threaded \*(xI Application
+.XS
+\fB\*(SN Initializing a Multi-Threaded \*(xI Application\fP
+.XE
+.LP
+To test and initialize \*(xI support for mutually exclusive thread
+access, call
+.PN XtToolkitThreadInitialize .
+.LP
+.IN "XtToolkitThreadInitialize" "" "@DEF@"
+.sM
+.FD 0
+Boolean XtToolkitThreadInitialize()
+.FN
+.LP
+.eM
+.PN XtToolkitThreadInitialize
+returns \fBTrue\fP if the \*(xI support mutually exclusive thread 
+access, otherwise it returns \fBFalse\fP. \fBXtToolkitThreadInitialize\fP
+must be called before
+.PN XtCreateApplicationContext ,
+.PN XtAppInitialize ,
+.PN XtOpenApplication ,
+or
+.PN XtSetLanguageProc
+is called. \fBXtToolkitThreadInitialize\fP may be called more than once;
+however, the application writer must ensure that it is not called 
+simultaneously by two or more threads.
+
+.NH 3
+Locking \*(tk Data Structures
+.XS
+\fB\*(SN Locking \*(tk Data Structures\fP
+.XE
+.LP
+The \*(xI employs two levels of locking: application context and
+process.  Locking an application context ensures mutually exclusive
+access by a thread to the state associated with the application context,
+including all displays and widgets associated with it.  Locking a
+process ensures mutually exclusive access by a thread to \*(xI process
+global data.
+.LP
+A client may acquire a lock multiple times and the effect is cumulative.
+The client must ensure that the lock is released an equal number of times in
+order for the lock to be acquired by another thread.
+.LP
+Most application writers will have little need to use locking as the
+\*(xI performs the necessary locking internally.
+Resource converters are an exception.
+They require the application context or process to be locked
+before the application can safely call them directly, for example:
+.LP
+.KS
+.Ds
+.TA .5i 2i
+.ta .5i 2i
+	...
+	XtAppLock(app_context);
+	XtCvtStringToPixel(dpy, args, num_args, fromVal, toVal, closure_ret);
+	XtAppUnlock(app_context);
+	...
+.De
+.KE
+.LP
+When the application relies upon
+.PN XtConvertAndStore
+or a converter to provide the storage for the results of a
+conversion, the application should acquire the process lock before
+calling out and hold the lock until the results have been copied.
+.LP
+Application writers who write their own
+utility functions, such as one which retrieves the being_destroyed field from
+a widget instance, must lock the application context before accessing
+widget internal data.  For example:
+.LP
+.KS
+.Ds
+.TA .5i 2i
+.ta .5i 2i
+#include <X11/CoreP.h>
+Boolean BeingDestroyed (widget)
+	Widget widget;
+{
+	Boolean ret;
+	XtAppLock(XtWidgetToApplicationContext(widget));
+	ret = widget->core.being_destroyed;
+	XtAppUnlock(XtWidgetToApplicationContext(widget));
+	return ret;
+}
+.De
+.KE
+A client that wishes to atomically call two or more \*(xI functions 
+must lock the application context.  For example:
+.LP
+.KS
+.Ds
+.TA .5i 2i
+.ta .5i 2i
+	...
+	XtAppLock(XtWidgetToApplicationContext(widget));
+	XtUnmanageChild (widget1);
+	XtManageChild (widget2);
+	XtAppUnlock(XtWidgetToApplicationContext(widget));
+	...
+.De
+.KE
+
+.NH 4
+Locking the Application Context
+.XS
+\fB\*(SN Locking the Application Context\fP
+.XE
+.LP
+To ensure mutual exclusion of application context, display, or 
+widget internal state, use
+.PN XtAppLock.
+.LP
+.IN "XtAppLock" "" "@DEF@"
+.sM
+.FD 0
+void XtAppLock(\fIapp_context\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context to lock.
+.LP
+.eM
+\fBXtAppLock\fP blocks until it is able to acquire the lock.  Locking the 
+application context also ensures that only the thread holding the lock 
+makes Xlib calls from within Xt.  An application that makes its own
+direct Xlib calls must either lock the application context around every 
+call or enable thread locking in Xlib.
+.LP
+To unlock a locked application context, use
+.PN XtAppUnlock.
+.LP
+.IN "XtAppUnlock" "" "@DEF@"
+.sM
+.FD 0
+void XtAppUnlock(\fIapp_context\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context that was previously locked.
+.LP
+.eM
+
+.NH 4
+Locking the Process
+.XS
+\*(SN Locking the Process
+.XE
+.LP
+To ensure mutual exclusion of \*(tk process global data, a
+widget writer must use
+.PN XtProcessLock.
+.LP
+.IN "XtProcessLock" "" "@DEF@"
+.sM
+.FD 0
+void XtProcessLock()
+.FN
+.LP
+.eM
+\fBXtProcessLock\fP blocks until it is able to acquire the lock.
+Widget writers may use XtProcessLock to guarantee mutually exclusive 
+access to widget static data.
+.LP
+To unlock a locked process, use
+.PN XtProcessUnlock .
+.LP
+.IN "XtProcessUnlock" "" "@DEF@"
+.sM
+.FD 0
+void XtProcessUnlock()
+.FN
+.LP
+.eM
+To lock both an application context and the process at the same 
+time, call
+.PN XtAppLock
+first and then
+.PN XtProcessLock .
+To release both locks, call
+.PN XtProcessUnlock
+first and then
+.PN XtAppUnlock .
+The order is important to avoid deadlock.
+
+.NH 3
+Event Management in a Multi-Threaded Environment
+.XS
+\fB\*(SN Event Management in a Multi-Threaded Environment\fP
+.XE
+.LP
+In a nonthreaded environment an application writer could reasonably
+assume that it is safe to exit the application from a quit callback. 
+This assumption may no longer hold true in a multi-threaded environment; 
+therefore it is desirable to provide a mechanism to terminate an
+event-processing loop without necessarily terminating its thread.
+.LP
+To indicate that the event loop should terminate after the current 
+event dispatch has completed, use
+.PN XtAppSetExitFlag .
+.LP
+.IN "XtAppSetExitFlag" "" "@DEF@"
+.sM
+.FD 0
+void XtAppSetExitFlag(\fIapp_context\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context.
+.LP
+.eM
+.PN XtAppMainLoop
+tests the value of the flag and will return if the flag is \fBTrue\fP.
+.LP
+Application writers who implement their own main loop may test the 
+value of the exit flag with
+.PN XtAppGetExitFlag .
+.LP
+.IN "XtAppGetExitFlag" "" "@DEF@"
+.sM
+.FD 0
+Boolean XtAppGetExitFlag(\fIapp_context\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context.
+.LP
+.eM
+.PN XtAppGetExitFlag
+will normally return \fBFalse\fP, indicating that event processing
+may continue.  When
+.PN XtAppGetExitFlag
+returns \fBTrue\fP, the loop must terminate and return to the caller,
+which might then destroy the application context.
+.LP
+Application writers should be aware that, if a thread is blocked in 
+.PN XtAppNextEvent , 
+.PN XtAppPeekEvent , 
+or 
+.PN XtAppProcessEvent
+and another thread in the same application context opens a new display, 
+adds an alternate input, or a timeout, any new source(s) will not 
+normally be "noticed" by the blocked thread.  Any new sources are
+"noticed" the next time one of these functions is called.
+.LP
+The \*(xI manage access to events on a last-in, first-out basis.  If 
+multiple threads in the same application context block in
+.PN XtAppNextEvent , 
+.PN XtAppPeekEvent , 
+or 
+.PN XtAppProcessEvent ,
+the last thread to call one of these functions is the first
+thread to return.
+.bp