diff options
Diffstat (limited to 'libXt/specs/CH07')
| -rw-r--r-- | libXt/specs/CH07 | 3555 |
1 files changed, 0 insertions, 3555 deletions
diff --git a/libXt/specs/CH07 b/libXt/specs/CH07 deleted file mode 100644 index 07b36746b..000000000 --- a/libXt/specs/CH07 +++ /dev/null @@ -1,3555 +0,0 @@ -.\" $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 |