1 .\" $Xorg: CH07,v 1.4 2000/08/17 19:42:45 cpqbld Exp $
2 .\" Copyright \(co 1985, 1986, 1987, 1988, 1991, 1994
5 .\" Permission is hereby granted, free of charge, to any person obtaining
6 .\" a copy of this software and associated documentation files (the
7 .\" "Software"), to deal in the Software without restriction, including
8 .\" without limitation the rights to use, copy, modify, merge, publish,
9 .\" distribute, sublicense, and/or sell copies of the Software, and to
10 .\" permit persons to whom the Software is furnished to do so, subject to
11 .\" the following conditions:
13 .\" The above copyright notice and this permission notice shall be included
14 .\" in all copies or substantial portions of the Software.
16 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
17 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
18 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
19 .\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
20 .\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
21 .\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
22 .\" OTHER DEALINGS IN THE SOFTWARE.
24 .\" Except as contained in this notice, the name of the X Consortium shall
25 .\" not be used in advertising or otherwise to promote the sale, use or
26 .\" other dealings in this Software without prior written authorization
27 .\" from the X Consortium.
29 .\" Copyright \(co 1985, 1986, 1987, 1988, 1991, 1994
30 .\" Digital Equipment Corporation, Maynard, Massachusetts.
32 .\" Permission to use, copy, modify and distribute this documentation for any
33 .\" purpose and without fee is hereby granted, provided that the above copyright
34 .\" notice appears in all copies and that both that copyright notice and this
35 .\" permission notice appear in supporting documentation, and that the name of
36 .\" Digital not be used in in advertising or publicity pertaining
37 .\" to distribution of the software without specific, written prior permission.
38 .\" Digital makes no representations about the suitability of the
39 .\" software described herein for any purpose.
40 .\" It is provided ``as is'' without express or implied warranty.
45 \s+1\fBChapter 7\fP\s-1
47 \s+1\fBEvent Management\fP\s-1
56 Chapter 7 \(em Event Management
58 While Xlib allows the reading and processing of events anywhere in an application,
59 widgets in the \*(tk neither directly read events
60 nor grab the server or pointer.
61 Widgets register procedures that are to be called
62 when an event or class of events occurs in that widget.
64 A typical application consists of startup code followed by an event loop
65 that reads events and dispatches them by calling
66 the procedures that widgets have registered.
67 The default event loop provided by the \*(xI is
70 The event manager is a collection of functions to perform the following tasks:
72 Add or remove event sources other than X server events (in particular,
73 timer interrupts, file input, or POSIX signals).
75 Query the status of event sources.
77 Add or remove procedures to be called when an event occurs for a particular
81 disable the dispatching of user-initiated events (keyboard and pointer events)
82 for a particular widget.
84 Constrain the dispatching of events to a cascade of pop-up widgets.
86 Register procedures to be called when specific events arrive.
88 Register procedures to be called when the \*(xI will block.
90 Enable safe operation in a multi-threaded environment.
92 Most widgets do not need to call any of the event handler functions explicitly.
93 The normal interface to X events is through the higher-level
95 which maps sequences of X events, with modifiers, into procedure calls.
96 Applications rarely use any of the event manager routines besides
100 Adding and Deleting Additional Event Sources
102 \fB\*(SN Adding and Deleting Additional Event Sources\fP
105 While most applications are driven only by X events,
106 some applications need to incorporate other sources of input
107 into the \*(xI event-handling mechanism.
108 The event manager provides routines to integrate notification of timer events
109 and file data pending into this mechanism.
111 The next section describes functions that provide input gathering from files.
112 The application registers the files with the \*(xI read routine.
113 When input is pending on one of the files,
114 the registered callback procedures are invoked.
117 Adding and Removing Input Sources
119 \fB\*(SN Adding and Removing Input Sources\fP
122 To register a new file as an input source for a given application context, use
125 .IN "XtAppAddInput" "" "@DEF@"
128 XtInputId XtAppAddInput(\fIapp_context\fP, \fIsource\fP, \fIcondition\fP, \
129 \fIproc\fP, \fIclient_data\fP)
131 XtAppContext \fIapp_context\fP;
135 XtPointer \fIcondition\fP;
137 XtInputCallbackProc \fIproc\fP;
139 XtPointer \fIclient_data\fP;
141 .IP \fIapp_context\fP 1i
142 Specifies the application context that identifies the application.
144 Specifies the source file descriptor on a POSIX-based system
145 or other operating-system-dependent device specification.
146 .IP \fIcondition\fP 1i
147 Specifies the mask that indicates a read, write, or exception condition
148 or some other operating-system-dependent condition.
150 Specifies the procedure to be called when the condition is found.
151 .IP \fIclient_data\fP 1i
152 Specifies an argument passed to the specified procedure
158 function registers with the \*(xI read routine a new source of events,
159 which is usually file input but can also be file output.
160 Note that \fIfile\fP should be loosely interpreted to mean any sink
163 also specifies the conditions under which the source can generate events.
164 When an event is pending on this source,
165 the callback procedure is called.
167 The legal values for the \fIcondition\fP argument are operating-system-dependent.
168 On a POSIX-based system,
169 \fIsource\fP is a file number and the condition is some union of the following:
170 .IN "XtInputReadMask" "" "@DEF@"
171 .IP \fBXtInputReadMask\fR 1.5i
172 Specifies that \fIproc\fP is to be called when \fIsource\fP has data to be read.
173 .IN "XtInputWriteMask" "" "@DEF@"
174 .IP \fBXtInputWriteMask\fR 1.5i
175 Specifies that \fIproc\fP is to be called when \fIsource\fP is ready
177 .IN "XtInputExceptMask" "" "@DEF@"
178 .IP \fBXtInputExceptMask\fR 1.5i
179 Specifies that \fIproc\fP is to be called when \fIsource\fP has
182 Callback procedure pointers used to handle file events are of
184 .PN XtInputCallbackProc .
186 .IN "XtInputCallbackProc" "" "@DEF@"
189 typedef void (*XtInputCallbackProc)(XtPointer, int*, XtInputId*);
191 XtPointer \fIclient_data\fP;
197 .IP \fIclient_data\fP 1i
198 Passes the client data argument that was registered for this procedure in
199 .PN XtApp\%AddInput .
201 Passes the source file descriptor generating the event.
203 Passes the id returned from the corresponding
208 See Section 7.12 for information regarding the use of
213 To discontinue a source of input, use
216 .IN "XtRemoveInput" "" "@DEF@"
219 void XtRemoveInput(\fIid\fP)
224 Specifies the id returned from the corresponding
231 function causes the \*(xI read routine to stop watching for events
232 from the file source specified by \fIid\fP.
234 See Section 7.12 for information regarding the use of
239 Adding and Removing Blocking Notifications
241 \fB\*(SN Adding and Removing Blocking Notifications\fP
244 Occasionally it is desirable for an application to receive notification
245 when the \*(xI event manager detects no pending input from file sources
246 and no pending input from X server event sources and is about to block
247 in an operating system call.
250 To register a hook that is called immediately prior to event blocking, use
251 .PN XtAppAddBlockHook .
253 .IN "XtAppAddBlockHook" "" "@DEF@"
256 XtBlockHookId XtAppAddBlockHook(\fIapp_context\fP, \fIproc\fP, \
259 XtAppContext \fIapp_context\fP;
261 XtBlockHookProc \fIproc\fP;
263 XtPointer \fIclient_data\fP;
265 .IP \fIapp_context\fP 1i
266 Specifies the application context that identifies the application.
268 Specifies the procedure to be called before blocking.
269 .IP \fIclient_data\fP 1i
270 Specifies an argument passed to the specified procedure when it is called.
274 .PN XtAppAddBlockHook
275 function registers the specified procedure and returns an identifier for it.
276 The hook procedure \fIproc\fP is called at any time in the future when
277 the \*(xI are about to block pending some input.
279 The procedure pointers used to provide notification of event blocking
281 .PN XtBlockHookProc .
283 .IN "XtBlockHookProc" "" "@DEF@"
286 typedef void (*XtBlockHookProc)(XtPointer);
288 XtPointer \fIclient_data\fP;
290 .IP \fIclient_data\fP 1i
291 Passes the client data argument that was registered for this procedure in
292 .PN XtApp\%AddBlockHook .
295 To discontinue the use of a procedure for blocking notification, use
296 .PN XtRemoveBlockHook .
298 .IN "XtRemoveBlockHook" "" "@DEF@"
301 void XtRemoveBlockHook(\fIid\fP)
303 XtBlockHookId \fIid\fP;
306 Specifies the identifier returned from the corresponding call to
307 .PN XtAppAddBlockHook .
311 .PN XtRemoveBlockHook
312 function removes the specified procedure from the list of procedures
313 that are called by the \*(xI read routine before blocking on event sources.
316 Adding and Removing Timeouts
318 \fB\*(SN Adding and Removing Timeouts\fP
321 The timeout facility notifies the application or the widget
322 through a callback procedure that a specified time interval has elapsed.
323 Timeout values are uniquely identified by an interval id.
326 To register a timeout callback, use
327 .PN XtAppAddTimeOut .
329 .IN "XtAppAddTimeOut" "" "@DEF@"
332 XtIntervalId XtAppAddTimeOut(\fIapp_context\fP, \fIinterval\fP, \fIproc\fP, \
335 XtAppContext \fIapp_context\fP;
337 unsigned long \fIinterval\fP;
339 XtTimerCallbackProc \fIproc\fP;
341 XtPointer \fIclient_data\fP;
343 .IP \fIapp_context\fP 1i
344 Specifies the application context for which the timer is to be set.
345 .IP \fIinterval\fP 1i
346 Specifies the time interval in milliseconds.
348 Specifies the procedure to be called when the time expires.
349 .IP \fIclient_data\fP 1i
350 Specifies an argument passed to the specified procedure
356 function creates a timeout and returns an identifier for it.
357 The timeout value is set to \fIinterval\fP.
358 The callback procedure \fIproc\fP is called when
361 .PN XtAppProcessEvent
362 is next called after the time interval elapses,
363 and then the timeout is removed.
365 Callback procedure pointers used with timeouts are of
367 .PN XtTimerCallbackProc .
369 .IN "XtTimerCallbackProc" "" "@DEF@"
372 typedef void (*XtTimerCallbackProc)(XtPointer, XtIntervalId*);
374 XtPointer \fIclient_data\fP;
376 XtIntervalId *\fItimer\fP;
378 .IP \fIclient_data\fP 1i
379 Passes the client data argument that was registered for this procedure in
380 .PN XtApp\%AddTimeOut .
382 Passes the id returned from the corresponding
387 See Section 7.12 for information regarding the use of
392 To clear a timeout value, use
393 .PN XtRemoveTimeOut .
395 .IN "XtRemoveTimeOut" "" "@DEF@"
398 void XtRemoveTimeOut(\fItimer\fP)
400 XtIntervalId \fItimer\fP;
403 Specifies the id for the timeout request to be cleared.
408 function removes the pending timeout.
409 Note that timeouts are automatically removed once they trigger.
411 Please refer to Section 7.12 for information regarding the use of
416 Adding and Removing Signal Callbacks
418 \fB\*(SN Adding and Removing Signal Callbacks\fP
421 The signal facility notifies the application or the widget through a
422 callback procedure that a signal or other external asynchronous event
423 has occurred. The registered callback procedures are uniquely identified
427 Prior to establishing a signal handler, the application or widget should
430 and store the resulting identifier in a place accessible to the signal
431 handler. When a signal arrives, the signal handler should call
433 to notify the \*(xI that a signal has occured. To register a signal
437 .IN "XtAppAddSignal" "" "@DEF@"
440 XtSignalId XtAppAddSignal(\fIapp_context\fP, \fIproc\fP, \fIclient_data\fP)
442 XtAppContext \fIapp_context\fP;
444 XtSignalCallbackProc \fIproc\fP;
446 XtPointer \fIclient_data\fP;
448 .IP \fIapp_context\fP 1i
449 Specifies the application context that identifies the application.
451 Specifies the procedure to be called when the signal is noticed.
452 .IP \fIclient_data\fP 1i
453 Specifies an argument passed to the specified procedure when it is called.
456 The callback procedure pointers used to handle signal events are of type
457 .PN XtSignalCallbackProc .
459 .IN "XtSignalCallbackProc" "" "@DEF@"
462 typedef void (*XtSignalCallbackProc)(XtPointer, XtSignalId*);
464 XtPointer \fIclient_data\fP;
466 XtSignalId *\fIid\fP;
468 .IP \fIclient_data\fP 1i
469 Passes the client data argument that was registered for this procedure in
472 Passes the id returned from the corresponding
477 To notify the \*(xI that a signal has occured, use
480 .IN "XtNoticeSignal" "" "@DEF@"
484 void XtNoticeSignal(\fIid\fP)
489 Specifies the id returned from the corresponding
494 On a POSIX-based system,
496 is the only \*(xI function that can safely be called from a signal handler.
499 is invoked multiple times before the \*(xI are able to invoke the
500 registered callback, the callback is only called once.
501 Logically, the \*(xI maintain ``pending'' flag for each registered callback.
502 This flag is initially
511 .PN XtAppProcessEvent
512 (with a mask including
514 is called, all registered callbacks with ``pending''
516 are invoked and the flags are reset to
519 If the signal handler wants to track how many times the signal has been
520 raised, it can keep its own private counter. Typically the handler would
521 not do any other work; the callback does the actual processing for the
522 signal. The \*(xI never block signals from being raised, so if a given
523 signal can be raised multiple times before the \*(xI can invoke the
524 callback for that signal, the callback must be designed to deal with
525 this. In another case, a signal might be raised just after the \*(xI
526 sets the pending flag to
528 but before the callback can get control, in which case the pending flag
531 after the callback returns, and the \*(xI will invoke the callback
532 again, even though all of the signal raises have been handled. The
533 callback must also be prepared to handle this case.
535 To remove a registered signal callback, call
538 .IN "XtRemoveSignal" "" "@DEF@"
541 void XtRemoveSignal(\fIid\fP)
546 Specifies the id returned by the corresponding call to
550 The client should typically disable the source of the signal before calling
552 If the signal could have been raised again before the source was disabled
553 and the client wants to process it, then after disabling the source but
556 the client can test for signals with
558 and process them by calling
559 .PN XtAppProcessEvent
564 Constraining Events to a Cascade of Widgets
566 \fB\*(SN Constraining Events to a Cascade of Widgets\fP
571 Modal widgets are widgets that, except for the input directed to them,
572 lock out user input to the application.
574 When a modal menu or modal dialog box is popped up using
576 user events (keyboard and pointer events) that occur outside the modal
577 widget should be delivered to the modal widget or ignored.
578 In no case will user events be delivered to a widget outside
581 Menus can pop up submenus, and dialog boxes can pop up further dialog
582 boxes to create a pop-up cascade.
584 user events may be delivered to one of several modal widgets in the cascade.
586 Display-related events should be delivered outside the modal cascade so that
587 exposure events and the like keep the application's display up-to-date.
588 Any event that occurs within the cascade is delivered as usual.
589 The user events delivered to the most recent spring-loaded shell
590 in the cascade when they occur outside the cascade are called remap events
597 The user events ignored when they occur outside the cascade are
601 All other events are delivered normally.
602 In particular, note that this is one
603 way in which widgets can receive
605 events without first receiving
607 events; they should be prepared to deal with
608 this, typically by ignoring any unmatched
617 functions to constrain user events to a modal cascade
618 and subsequently to remove a grab when the modal widget is popped down.
622 To constrain or redirect user input to a modal widget, use
625 .IN "XtAddGrab" "" "@DEF@"
628 void XtAddGrab(\fIw\fP, \fIexclusive\fP, \fIspring_loaded\fP)
632 Boolean \fIexclusive\fP;
634 Boolean \fIspring_loaded\fP;
637 Specifies the widget to add to the modal cascade. \*(cI
638 .IP \fIexclusive\fP 1i
639 Specifies whether user events should be dispatched exclusively to this widget
640 or also to previous widgets in the cascade.
641 .IP \fIspring_loaded\fP 1i
642 Specifies whether this widget was popped up because the user pressed
648 function appends the widget to the modal cascade
649 and checks that \fIexclusive\fP is
651 if \fIspring_loaded\fP is
653 If this condition is not met,
655 generates a warning message.
657 The modal cascade is used by
659 when it tries to dispatch a user event.
660 When at least one modal widget is in the widget cascade,
662 first determines if the event should be delivered.
663 It starts at the most recent cascade entry and follows the cascade up to and
664 including the most recent cascade entry added with the \fIexclusive\fP parameter
667 This subset of the modal cascade along with all descendants of these widgets
668 comprise the active subset.
669 User events that occur outside the widgets in this subset are ignored
671 Modal menus with submenus generally add a submenu widget to the cascade
674 Modal dialog boxes that need to restrict user input to the most deeply nested
675 dialog box add a subdialog widget to the cascade with \fIexclusive\fP
677 User events that occur within the active subset are delivered to the
678 appropriate widget, which is usually a child or further descendant of the modal
681 Regardless of where in the application they occur,
682 remap events are always delivered to the most recent widget in the active
683 subset of the cascade registered with \fIspring_loaded\fP
685 if any such widget exists.
687 occurred in the active subset of the cascade but outside the
688 spring-loaded widget, it is delivered normally before being
689 delivered also to the spring-loaded widget.
690 Regardless of where it is dispatched, the \*(xI do not modify
691 the contents of the event.
694 To remove the redirection of user input to a modal widget, use
697 .IN "XtRemoveGrab" "" "@DEF@"
700 void XtRemoveGrab(\fIw\fP)
705 Specifies the widget to remove from the modal cascade.
710 function removes widgets from the modal cascade starting
711 at the most recent widget up to and including the specified widget.
712 It issues a warning if the specified widget is not on the modal cascade.
715 Requesting Key and Button Grabs
717 \fB\*(SN Requesting Key and Button Grabs\fP
720 The \*(xI provide a set of key and button grab interfaces that
721 are parallel to those provided by Xlib and that allow the \*(xI
722 to modify event dispatching when necessary. \*(tk applications and
723 widgets that need to passively grab keys or buttons or actively grab
724 the keyboard or pointer should use the
725 following \*(xI routines rather than the corresponding Xlib
729 To passively grab a single key of the keyboard, use
732 .IN "XtGrabKey" "" "@DEF@"
735 void XtGrabKey(\fIwidget\fP, \fIkeycode\fP, \fImodifiers\fP, \
736 \fIowner_events\fP, \fIpointer_mode\fP, \fIkeyboard_mode\fP)
740 KeyCode \fIkeycode\fP;
742 Modifiers \fImodifiers\fP;
744 Boolean \fIowner_events\fP;
746 int \fIpointer_mode\fP, \fIkeyboard_mode\fP;
749 Specifies the widget in whose window the key is to be grabbed. \*(cI
757 .IP \fIowner_events\fP
760 .IP \fIpointer_mode\fP
763 .IP \fIkeyboard_mode\fP 1i
766 see Section 12.2 in \fI\*(xL\fP.
772 specifying the widget's window as the grab
773 window if the widget is realized. The remaining arguments are exactly
776 If the widget is not realized, or is later unrealized, the call to
778 is performed (again) when
779 the widget is realized and its window becomes mapped. In the future,
784 event matching the specified keycode and modifiers (which may be
788 respectively) for the
789 widget's window, the \*(xI will call
791 with the timestamp from the
793 event if either of the following conditions is true:
795 There is a modal cascade and the widget is not in
796 the active subset of the cascade and the keyboard was not previously
805 To cancel a passive key grab, use
808 .IN "XtUngrabKey" "" "@DEF@"
811 void XtUngrabKey(\fIwidget\fP, \fIkeycode\fP\fI, modifiers\fP)
815 KeyCode \fIkeycode\fP;
817 Modifiers \fImodifiers\fP;
820 Specifies the widget in whose window the key was grabbed.
825 .IP \fImodifiers\fP 1i
828 see Section 12.2 in \fI\*(xL\fP.
835 specifying the widget's
836 window as the ungrab window if the widget is realized. The remaining
837 arguments are exactly as for
839 If the widget is not realized,
843 request, if any, for the specified widget, keycode, and modifiers.
846 To actively grab the keyboard, use
849 .IN "XtGrabKeyboard" "" "@DEF@"
852 int XtGrabKeyboard(\fIwidget\fP, \fIowner_events\fP, \fIpointer_mode\fP, \
853 \fIkeyboard_mode\fP, \fItime\fP)
857 Boolean \fIowner_events\fP;
859 int \fIpointer_mode\fP, \fIkeyboard_mode\fP;
865 Specifies the widget for whose window the keyboard is to be grabbed.
868 .IP \fIowner_events\fP
871 .IP \fIpointer_mode\fP
874 .IP \fIkeyboard_mode\fP
880 see Section 12.2 in \fI\*(xL\fP.
883 If the specified widget is realized,
887 specifying the widget's window as the grab window. The remaining
888 arguments and return value are exactly as for
890 If the widget is not realized,
893 .PN GrabNotViewable .
894 No future automatic ungrab is implied by
898 To cancel an active keyboard grab, use
899 .PN XtUngrabKeyboard .
901 .IN "XtUngrabKeyboard" "" "@DEF@"
904 void XtUngrabKeyboard(\fIwidget\fP, \fItime\fP)
911 Specifies the widget that has the active keyboard grab.
913 Specifies the additional argument to
914 .PN XUngrabKeyboard ;
915 see Section 12.2 in \fI\*(xL\fP.
921 with the specified time.
924 To passively grab a single pointer button, use
927 .IN "XtGrabButton" "" "@DEF@"
930 void XtGrabButton(\fIwidget\fP, \fIbutton\fP, \fImodifiers\fP, \
931 \fIowner_events\fP, \fIevent_mask\fP, \fIpointer_mode\fP,
932 \fIkeyboard_mode\fP, \fIconfine_to\fP, \fIcursor\fP)
938 Modifiers \fImodifiers\fP;
940 Boolean \fIowner_events\fP;
942 unsigned int \fIevent_mask\fP;
944 int \fIpointer_mode\fP, \fIkeyboard_mode\fP;
946 Window \fIconfine_to\fP;
951 Specifies the widget in whose window the button is to be grabbed. \*(cI
959 .IP \fIowner_events\fP
965 .IP \fIpointer_mode\fP
968 .IP \fIkeyboard_mode\fP
977 see Section 12.1 in \fI\*(xL\fP.
983 specifying the widget's window as the
984 grab window if the widget is realized. The remaining arguments are
987 If the widget is not realized, or is later unrealized, the call to
990 when the widget is realized and its window becomes mapped. In the
995 event matching the specified button and modifiers (which may be
1000 for the widget's window, the \*(xI will call
1002 with the timestamp from the
1004 event if either of the following conditions is true:
1006 There is a modal cascade and the
1007 widget is not in the active subset of the cascade and the pointer was
1008 not previously grabbed, or
1016 To cancel a passive button grab, use
1017 .PN XtUngrabButton .
1019 .IN "XtUngrabButton" "" "@DEF@"
1022 void XtUngrabButton(\fIwidget\fP, \fIbutton\fP, \fImodifiers\fP)
1024 Widget \fIwidget\fP;
1026 unsigned int \fIbutton\fP;
1028 Modifiers \fImodifiers\fP;
1031 Specifies the widget in whose window the button was grabbed.
1035 .IP \fImodifiers\fP 1i
1036 Specify arguments to
1038 see Section 12.1 in \fI\*(xL\fP.
1046 widget's window as the ungrab window if the widget is realized. The
1047 remaining arguments are exactly as for
1049 If the widget is not realized,
1053 request, if any, for the specified widget, button, and modifiers.
1056 To actively grab the pointer, use
1059 .IN "XtGrabPointer" "" "@DEF@"
1062 int XtGrabPointer(\fIwidget\fP, \fIowner_events\fP, \fIevent_mask\fP, \
1063 \fIpointer_mode\fP, \fIkeyboard_mode\fP,
1064 \fIconfine_to\fP, \fIcursor\fP, \fItime\fP)
1066 Widget \fIwidget\fP;
1068 Boolean \fIowner_events\fP;
1070 unsigned int \fIevent_mask\fP;
1072 int \fIpointer_mode\fP, \fIkeyboard_mode\fP;
1074 Window \fIconfine_to\fP;
1076 Cursor \fIcursor\fP;
1081 Specifies the widget for whose window the pointer is to be grabbed. \*(cI
1083 .IP \fIowner_events\fP
1086 .IP \fIevent_mask\fP
1089 .IP \fIpointer_mode\fP
1092 .IP \fIkeyboard_mode\fP
1095 .IP \fIconfine_to\fP
1102 Specify arguments to
1104 see Section 12.1 in \fI\*(xL\fP.
1107 If the specified widget is realized,
1111 specifying the widget's window as the grab window. The remaining
1112 arguments and return value are exactly as for
1114 If the widget is not realized,
1117 .PN GrabNotViewable .
1118 No future automatic ungrab is implied by
1122 To cancel an active pointer grab, use
1123 .PN XtUngrabPointer .
1125 .IN "XtUngrabPointer" "" "@DEF@"
1128 void XtUngrabPointer(\fIwidget\fP, \fItime\fP)
1130 Widget \fIwidget\fP;
1135 Specifies the widget that has the active pointer grab.
1137 Specifies the time argument to
1138 .PN XUngrabPointer ;
1139 see Section 12.1 in \fI\*(xL\fP.
1145 with the specified time.
1148 Focusing Events on a Child
1150 \fB\*(SN Focusing Events on a Child\fP
1153 To redirect keyboard input to a normal descendant of a
1154 widget without calling
1155 .PN XSetInputFocus ,
1157 .PN XtSetKeyboardFocus .
1159 .IN "XtSetKeyboardFocus" "" "@DEF@"
1162 void XtSetKeyboardFocus(\fIsubtree\fP\, \fIdescendant\fP)
1164 Widget \fIsubtree\fP, \fIdescendant\fP;
1166 .IP \fIsubtree\fP 1i
1167 Specifies the subtree of the hierarchy for which the keyboard focus is
1169 .IP \fIdescendant\fP 1i
1170 Specifies either the normal (non-pop-up) descendant of \fIsubtree\fP to which
1171 keyboard events are logically directed, or
1173 It is not an error to specify
1175 when no input focus was previously set. \*(oI
1178 .PN XtSetKeyboardFocus
1181 to remap keyboard events occurring within the specified subtree
1182 and dispatch them to the specified descendant widget or to an ancestor.
1183 If the descendant's class is not a subclass of Core, the descendant is
1184 replaced by its closest windowed ancestor.
1186 When there is no modal cascade, keyboard events can be dispatched
1187 to a widget in one of five ways. Assume the server delivered the
1188 event to the window for widget E (because of X input focus, key or
1189 keyboard grabs, or pointer position).
1191 If neither E nor any of E's ancestors have redirected the keyboard
1192 focus, or if the event activated a grab for E as specified by a call
1195 with any value of \fIowner_events\fP, or
1196 if the keyboard is actively grabbed by E with \fIowner_events\fP
1202 on a previous key press, the event is dispatched to E.
1204 Beginning with the ancestor of E closest to the root that has
1205 redirected the keyboard focus or E if no such ancestor exists, if
1206 the target of that focus redirection has in turn redirected the
1207 keyboard focus, recursively follow this focus chain to find a widget
1208 F that has not redirected focus.
1211 If E is the final focus target widget F or a descendant of F, the
1212 event is dispatched to E.
1214 If E is not F, an ancestor of F, or a descendant of F, and the event
1215 activated a grab for E as specified by a call to
1218 .PN XtUngrabKeyboard
1221 If E is an ancestor of F, and the event is a key press, and either
1224 E has grabbed the key with
1226 and \fIowner_events\fP
1230 E has grabbed the key with
1232 and \fIowner_events\fP
1234 and the coordinates of the event are outside the rectangle specified
1237 then the event is dispatched to E.
1239 Otherwise, define A as the closest common ancestor of E and F:
1242 If there is an active keyboard grab for any widget via either
1246 on a previous key press, or
1247 if no widget between F and A (noninclusive) has grabbed
1248 the key and modifier combination with
1250 and any value of \fIowner_events\fP, the event is dispatched to F.
1252 Else, the event is dispatched to the ancestor of F closest to A
1253 that has grabbed the key and modifier combination with
1258 When there is a modal cascade, if the final destination widget as
1259 identified above is in the active subset of the cascade, the event is
1260 dispatched; otherwise the event is remapped to a spring-loaded shell
1262 Regardless of where it is dispatched, the \*(xI do not modify
1263 the contents of the event.
1265 When \fIsubtree\fP or one of its descendants acquires the X input focus
1266 or the pointer moves into the subtree such that keyboard events would
1267 now be delivered to the subtree, a
1269 event is generated for the descendant if
1271 events have been selected by the descendant.
1272 Similarly, when \fIsubtree\fP loses the X input focus
1273 or the keyboard focus for one of its ancestors, a
1275 event is generated for descendant if
1277 events have been selected by the descendant.
1280 A widget tree may also actively manage the X server input focus. To
1281 do so, a widget class specifies an accept_focus procedure.
1283 .IN "accept_focus procedure"
1284 The accept_focus procedure pointer is of type
1285 .PN XtAcceptFocusProc .
1287 .IN "XtAcceptFocusProc" "" "@DEF@"
1290 typedef Boolean (*XtAcceptFocusProc)(Widget, Time*);
1297 Specifies the widget.
1299 Specifies the X time of the event causing the accept focus.
1302 Widgets that need the input focus can call
1304 explicitly, pursuant to the restrictions of the \fI\*(xC\fP.
1305 To allow outside agents, such as the parent,
1306 to cause a widget to take the input focus,
1307 every widget exports an accept_focus procedure.
1308 The widget returns a value indicating
1309 whether it actually took the focus or not,
1310 so that the parent can give the focus to another widget.
1311 Widgets that need to know when they lose the input focus must use
1312 the Xlib focus notification mechanism explicitly
1313 (typically by specifying translations for
1318 Widgets classes that never want the input focus should set the
1319 \fIaccept_focus\fP field to NULL.
1322 To call a widget's accept_focus procedure, use
1323 .PN XtCallAcceptFocus .
1325 .IN "XtCallAcceptFocus" "" "@DEF@"
1328 Boolean XtCallAcceptFocus(\fIw\fP, \fItime\fP)
1335 Specifies the widget. \*(cI
1337 Specifies the X time of the event that is causing the focus change.
1341 .PN XtCallAcceptFocus
1342 function calls the specified widget's accept_focus procedure,
1343 passing it the specified widget and time, and returns what the accept_focus
1345 If \fIaccept_focus\fP is NULL,
1346 .PN XtCallAcceptFocus
1351 Events for Drawables That Are Not a Widget's Window
1353 \fB\*(SN Events for Drawables That Are Not a Widget's Window\fP
1356 Sometimes an application must handle events for drawables that are not
1357 associated with widgets in its widget tree. Examples include handling
1361 events on Pixmaps, and handling
1363 events on the root window.
1365 To register a drawable with the \*(xI event dispatching, use
1366 .PN XtRegisterDrawable .
1368 .IN "XtRegisterDrawable" "" "@DEF@"
1371 void XtRegisterDrawable(\fIdisplay\fP, \fIdrawable\fP, \fIwidget\fP)
1373 Display *\fIdisplay\fP;
1375 Drawable \fIdrawable\fP;
1377 Widget \fIwidget\fP;
1379 .IP \fIdisplay\fP 1i
1380 Specifies the drawable's display.
1381 .IP \fIdrawable\fP 1i
1382 Specifies the drawable to register.
1384 Specifies the widget to register the drawable for.
1387 .PN XtRegisterDrawable
1388 associates the specified drawable with the specified widget
1389 so that future calls to
1390 .PN XtWindowToWidget
1391 with the drawable will return the widget.
1392 The default event dispatcher will dispatch future events that
1393 arrive for the drawable to the widget in the same manner as
1394 events that contain the widget's window.
1396 If the drawable is already registered with another widget, or if the
1397 drawable is the window of a widget in the client's widget tree, the
1399 .PN XtRegisterDrawable
1403 To unregister a drawable with the Intrinsics event dispatching, use
1404 .PN XtUnregisterDrawable .
1406 .IN "XtUnregisterDrawable" "" "@DEF@"
1409 void XtUnregisterDrawable(\fIdisplay\fP, \fIdrawable\fP)
1411 Display *\fIdisplay\fP;
1413 Drawable \fIdrawable\fP;
1415 .IP \fIdisplay\fP 1i
1416 Specifies the drawable's display.
1417 .IP \fIdrawable\fP 1i
1418 Specifies the drawable to unregister.
1421 .PN XtUnregisterDrawable
1422 removes an association created with
1423 .PN XtRegisterDrawable .
1424 If the drawable is the window of a widget in the client's widget tree
1425 the results of calling
1426 .PN XtUnregisterDrawable
1430 Querying Event Sources
1432 \fB\*(SN Querying Event Sources\fP
1435 The event manager provides several functions to examine and read events
1436 (including file and timer events) that are in the queue.
1437 The next three functions are \*(xI equivalents of the
1446 To determine if there are any events on the input queue for a given application,
1450 .IN "XtAppPending" "" "@DEF@"
1453 XtInputMask XtAppPending(\fIapp_context\fP)
1455 XtAppContext \fIapp_context\fP;
1457 .IP \fIapp_context\fP 1i
1458 Specifies the application context that identifies the application to check.
1463 function returns a nonzero value if there are
1464 events pending from the X server, timer pending, other input sources
1465 pending, or signal sources pending. The
1466 value returned is a bit mask that is the OR of
1469 .PN XtIMAlternateInput ,
1473 .PN XtAppProcessEvent ).
1474 If there are no events pending,
1476 flushes the output buffers of each Display in the application context
1480 To return the event from the head of a given application's input queue
1481 without removing input from the queue, use
1482 .PN XtAppPeekEvent .
1484 .IN "XtAppPeekEvent" "" "@DEF@"
1487 Boolean XtAppPeekEvent(\fIapp_context\fP, \fIevent_return\fP)
1489 XtAppContext \fIapp_context\fP;
1491 XEvent *\fIevent_return\fP;
1493 .IP \fIapp_context\fP 1i
1494 Specifies the application context that identifies the application.
1495 .IP \fIevent_return\fP 1i
1496 Returns the event information to the specified event structure.
1499 If there is an X event in the queue,
1501 copies it into \fIevent_return\fP and returns
1503 If no X input is on the queue,
1505 flushes the output buffers of each Display in the application context
1506 and blocks until some input is available
1507 (possibly calling some timeout callbacks in the interim).
1508 If the next available input is an X event,
1510 fills in \fIevent_return\fP and returns
1512 Otherwise, the input is for an input source
1520 The sample implementations provides XtAppPeekEvent as described. Timeout callbacks
1521 are called while blocking for input. If some input for an input source is
1526 without returning an event.
1530 To remove and return the event
1531 from the head of a given application's X event queue,
1533 .PN XtAppNextEvent .
1535 .IN "XtAppNextEvent" "" "@DEF@"
1538 void XtAppNextEvent(\fIapp_context\fP, \fIevent_return\fP)
1540 XtAppContext \fIapp_context\fP;
1542 XEvent *\fIevent_return\fP;
1544 .IP \fIapp_context\fP 1i
1545 Specifies the application context that identifies the application.
1546 .IP \fIevent_return\fP 1i
1547 Returns the event information to the specified event structure.
1550 If the X event queue is empty,
1552 flushes the X output buffers of each Display in the application context
1553 and waits for an X event while looking at the other input sources
1554 and timeout values and calling any callback procedures triggered by them.
1555 This wait time can be used for background processing;
1561 \fB\*(SN Dispatching Events\fP
1564 The \*(xI provide functions that dispatch events
1565 to widgets or other application code.
1566 Every client interested in X events on a widget uses
1567 .PN XtAddEventHandler
1568 to register which events it is
1569 interested in and a procedure (event handler) to be called
1570 when the event happens in that window.
1571 The translation manager automatically registers event handlers for widgets
1572 that use translation tables; see Chapter 10.
1575 Applications that need direct control of the processing of different types
1577 .PN XtAppProcessEvent .
1579 .IN "XtAppProcessEvent" "" "@DEF@"
1582 void XtAppProcessEvent(\fIapp_context\fP, \fImask\fP)
1584 XtAppContext \fIapp_context\fP;
1586 XtInputMask \fImask\fP;
1588 .IP \fIapp_context\fP 1i
1589 Specifies the application context that identifies the
1590 application for which to process input.
1592 Specifies what types of events to process.
1593 The mask is the bitwise inclusive OR of any combination of
1596 .PN XtIMAlternateInput ,
1601 defines the symbolic name
1603 to be the bitwise inclusive OR of these four event types.
1607 .PN XtAppProcessEvent
1608 function processes one timer, input source, signal source, or X event.
1609 If there is no event or input of the appropriate type to process, then
1610 .PN XtAppProcessEvent
1611 blocks until there is.
1612 If there is more than one type of input available to process,
1613 it is undefined which will get processed.
1614 Usually, this procedure is not called by client applications; see
1616 .PN XtAppProcessEvent
1617 processes timer events by calling any appropriate timer callbacks,
1618 input sources by calling any appropriate input callbacks,
1619 signal source by calling any appropriate signal callbacks,
1622 .PN XtDispatchEvent .
1624 When an X event is received,
1626 .PN XtDispatchEvent ,
1627 which calls the appropriate event handlers
1628 and passes them the widget, the event, and client-specific data
1629 registered with each procedure.
1630 If no handlers for that event are registered,
1631 the event is ignored and the dispatcher simply returns.
1635 To dispatch an event returned by
1636 .PN XtAppNextEvent ,
1637 retrieved directly from the Xlib queue, or synthetically constructed,
1638 to any registered event filters or event handlers, call
1639 .PN XtDispatchEvent .
1641 .IN "XtDispatchEvent" "" "@DEF@"
1644 Boolean XtDispatchEvent(\fIevent\fP)
1646 XEvent *\fIevent\fP;
1649 Specifies a pointer to the event structure to be dispatched
1650 to the appropriate event handlers.
1655 function first calls
1657 with the \fIevent\fP and the window of the widget to which the
1658 \*(xI intend to dispatch the event, or the event window if
1659 the \*(xI would not dispatch the event to any handlers.
1664 and the event activated a server grab as identified
1665 by a previous call to
1671 .PN XtUngrabKeyboard
1674 with the timestamp from the event and immediately returns
1680 and a grab was not activated,
1682 just immediately returns
1686 sends the event to the event handler functions that
1687 have been previously registered with the dispatch routine.
1695 or if the event was dispatched to some handler, and
1697 if it found no handler to which to dispatch the event.
1699 records the last timestamp in any event that
1700 contains a timestamp (see
1701 .PN XtLastTimestampProcessed ),
1702 regardless of whether it was filtered or dispatched.
1703 If a modal cascade is active with \fIspring_loaded\fP
1705 and if the event is a remap event as defined by
1708 may dispatch the event a second time. If it does so,
1712 again with the window of the spring-loaded widget prior to the second
1717 the second dispatch will not be performed.
1720 The Application Input Loop
1722 \fB\*(SN The Application Input Loop\fP
1725 To process all input from a given application in a continuous loop,
1726 use the convenience procedure
1729 .IN "XtAppMainLoop" "" "@DEF@"
1732 void XtAppMainLoop(\fIapp_context\fP)
1734 XtAppContext \fIapp_context\fP;
1736 .IP \fIapp_context\fP 1i
1737 Specifies the application context that identifies the application.
1742 function first reads the next incoming X event by calling
1744 and then dispatches the event to the appropriate registered procedure
1746 .PN XtDispatchEvent .
1747 This constitutes the main loop of \*(tk applications.
1748 There is nothing special about
1754 in a conditional loop.
1755 At the bottom of the loop, it checks to see if the specified
1756 application context's destroy flag is set.
1757 If the flag is set, the loop breaks.
1758 The whole loop is enclosed between a matching
1763 Applications can provide their own version of this loop,
1764 which tests some global termination flag or tests that the number
1765 of top-level widgets is larger than zero before circling back to the call to
1766 .PN XtAppNextEvent .
1769 Setting and Checking the Sensitivity State of a Widget
1771 \fB\*(SN Setting and Checking the Sensitivity State of a Widget\fP
1774 Many widgets have a mode in which they assume a different appearance
1775 (for example, are grayed out or stippled), do not respond to user events,
1779 a widget is considered to be insensitive.
1780 If a widget is insensitive,
1781 the event manager does not dispatch any events to the widget
1782 with an event type of
1794 A widget can be insensitive because its \fIsensitive\fP field is
1796 or because one of its ancestors is insensitive and thus the widget's
1797 \fIancestor_sensitive\fP field also is
1799 A widget can but does not need to distinguish these two cases visually.
1801 Pop-up shells will have
1802 \fIancestor_sensitive\fP
1804 if the parent was insensitive when the shell
1807 on the parent will not
1808 modify the resource of the pop-up child, clients are advised to include
1809 a resource specification of the form
1810 ``*TransientShell.ancestorSensitive: True''
1811 in the application defaults resource file or to
1812 otherwise ensure that the parent is
1813 sensitive when creating pop-up shells.
1817 To set the sensitivity state of a widget, use
1818 .PN XtSetSensitive .
1820 .IN "XtSetSensitive" "" "@DEF@"
1823 void XtSetSensitive(\fIw\fP, \fIsensitive\fP)
1827 Boolean \fIsensitive\fP;
1830 Specifies the widget. \*(rI
1831 .IP \fIsensitive\fP 1i
1832 Specifies whether the widget should receive
1833 keyboard, pointer, and focus events.
1838 function first calls
1840 on the current widget with an argument list specifying the
1841 XtNsensitive resource and the new value.
1842 If \fIsensitive\fP is
1844 and the widget's class is a subclass of
1847 recursively propagates the new value
1848 down the child tree by calling
1850 on each child to set \fIancestor_sensitive\fP to
1852 If \fIsensitive\fP is
1854 and the widget's class is a subclass of
1856 and the widget's \fIancestor_sensitive\fP field is
1859 sets the \fIancestor_sensitive\fP of each child to
1861 and then recursively calls
1863 on each normal descendant that is now sensitive to set
1864 \fIancestor_sensitive\fP to
1870 to change the \fIsensitive\fP and \fIancestor_sensitive\fP fields
1871 of each affected widget.
1872 Therefore, when one of these changes,
1873 the widget's set_values procedure should
1874 take whatever display actions are needed
1875 (for example, graying out or stippling the widget).
1878 maintains the invariant that, if the parent has either \fIsensitive\fP
1879 or \fIancestor_sensitive\fP
1881 then all children have \fIancestor_sensitive\fP
1885 To check the current sensitivity state of a widget,
1889 .IN "XtIsSensitive" "" "@DEF@"
1892 Boolean XtIsSensitive(\fIw\fP)
1897 Specifies the object. \*(oI
1906 to indicate whether user input events are being dispatched.
1907 If object's class is a subclass of RectObj and
1908 both \fIsensitive\fP and \fIancestor_sensitive\fP are
1913 otherwise, it returns
1917 Adding Background Work Procedures
1919 \fB\*(SN Adding Background Work Procedures\fP
1922 The \*(xI have some limited support for background processing.
1923 Because most applications spend most of their time waiting for input,
1924 you can register an idle-time work procedure
1925 that is called when the toolkit would otherwise block in
1928 .PN XtAppProcessEvent .
1929 Work procedure pointers are of type
1932 .IN "XtWorkProc" "" "@DEF@"
1935 typedef Boolean (*XtWorkProc)(XtPointer);
1937 XtPointer \fIclient_data\fP;
1939 .IP \fIclient_data\fP 1i
1940 Passes the client data specified when the work procedure was registered.
1943 This procedure should return
1945 when it is done to indicate that it
1947 If the procedure returns
1949 it will remain registered and called again when the
1950 application is next idle.
1951 Work procedures should be very judicious about how much they do.
1952 If they run for more than a small part of a second,
1953 interactive feel is likely to suffer.
1956 To register a work procedure for a given application, use
1957 .PN XtAppAddWorkProc .
1959 .IN "XtAppAddWorkProc" "" "@DEF@"
1962 XtWorkProcId XtAppAddWorkProc(\fIapp_context\fP, \fIproc\fP, \fIclient_data\fP)
1964 XtAppContext \fIapp_context\fP;
1966 XtWorkProc \fIproc\fP;
1968 XtPointer \fIclient_data\fP;
1970 .IP \fIapp_context\fP 1i
1971 Specifies the application context that identifies the application.
1973 Specifies the procedure to be called when the application is idle.
1974 .IP \fIclient_data\fP 1i
1975 Specifies the argument passed to the specified procedure
1980 .PN XtAppAddWorkProc
1981 function adds the specified work procedure for the application identified
1982 by \fIapp_context\fP
1983 and returns an opaque unique identifier for this work procedure.
1984 Multiple work procedures can be registered,
1985 and the most recently added one is always the one that is called.
1986 However, if a work procedure adds another work procedure,
1987 the newly added one has lower priority than the current one.
1990 To remove a work procedure, either return
1992 from the procedure when it is called or use
1993 .PN XtRemoveWorkProc
1994 outside of the procedure.
1996 .IN "XtRemoveWorkProc" "" "@DEF@"
1999 void XtRemoveWorkProc(\fIid\fP)
2001 XtWorkProcId \fIid\fP;
2004 Specifies which work procedure to remove.
2008 .PN XtRemoveWorkProc
2009 function explicitly removes the specified background work procedure.
2014 \*(SN X Event Filters
2017 The event manager provides filters that can be applied to
2019 The filters, which screen out events that are redundant or are temporarily
2021 pointer motion compression,
2022 enter/leave compression, and
2023 exposure compression.
2026 Pointer Motion Compression
2028 \*(SN Pointer Motion Compression
2031 Widgets can have a hard time keeping up with a rapid stream of
2032 pointer motion events. Furthermore,
2033 they usually do not care about every motion event. To throw out
2034 redundant motion events, the widget class field \fIcompress_motion\fP should be
2036 .IN "compress_motion field"
2037 When a request for an event would return a motion event,
2038 the \*(xI check if there are any other motion events
2039 for the same widget immediately
2040 following the current one and, if so, skip all but the last of them.
2043 Enter/Leave Compression
2045 \*(SN Enter/Leave Compression
2048 To throw out pairs of enter and leave events that have no intervening events,
2049 as can happen when the user moves the pointer across a widget
2050 without stopping in it,
2051 the widget class field \fIcompress_enterleave\fP should be
2053 .IN "compress_enterleave field"
2054 These enter and leave events are not delivered to the client
2055 if they are found together in the input queue.
2058 Exposure Compression
2060 \*(SN Exposure Compression
2063 .IN "compress_expose field"
2064 Many widgets prefer to process a series of exposure events as a
2065 single expose region rather than as individual rectangles. Widgets
2066 with complex displays might use the expose region as a clip list
2067 in a graphics context, and widgets with simple displays might
2068 ignore the region entirely and redisplay their whole window or
2069 might get the bounding box from the region and redisplay only that
2072 In either case, these widgets do not care about getting partial exposure events.
2073 The \fIcompress_exposure\fP field in the widget class
2074 structure specifies the type and number of exposure events that are
2075 dispatched to the widget's expose procedure. This field must be
2076 initialized to one of the following values:
2082 #define XtExposeNoCompress ((XtEnum)False)
2083 #define XtExposeCompressSeries ((XtEnum)True)
2084 #define XtExposeCompressMultiple <implementation-defined>
2085 #define XtExposeCompressMaximal <implementation-defined>
2089 optionally ORed with any combination of the following flags (all with
2090 implementation-defined values):
2091 .PN XtExposeGraphicsExpose ,
2092 .PN XtExposeGraphicsExposeMerged ,
2093 .PN XtExposeNoExpose ,
2095 .PN XtExposeNoRegion .
2098 If the \fIcompress_exposure\fP field in the widget class structure does not
2100 .PN XtExposeNoCompress ,
2101 the event manager calls the widget's expose procedure only
2102 once for a series of exposure events.
2107 events are accumulated into a region.
2108 When the final event is received,
2109 the event manager replaces the rectangle in the event with the
2110 bounding box for the region
2111 and calls the widget's expose procedure,
2112 passing the modified exposure event and (unless
2113 .PN XtExposeNoRegion
2114 is specified) the region.
2115 For more information on regions, see Section 16.5 in \fI\*(xL\fP.)
2117 The values have the following interpretation:
2120 .PN XtExposeNoCompress
2121 .IN "XtExposeNoCompress" "" "@DEF@"
2123 No exposure compression is performed; every selected event is
2124 individually dispatched to the expose procedure with a \fIregion\fP
2128 .PN XtExposeCompressSeries
2129 .IN "XtExposeCompressSeries" "" "@DEF@"
2131 Each series of exposure events is coalesced into a single event,
2133 when an exposure event with count equal to zero is reached.
2136 .PN XtExposeCompressMultiple
2137 .IN "XtExposeCompressMultiple" "" "@DEF@"
2139 Consecutive series of exposure events are coalesced into a single
2140 event, which is dispatched
2141 when an exposure event with count equal to zero is reached and either
2142 the event queue is empty or the next event is not an exposure event
2143 for the same widget.
2146 .PN XtExposeCompressMaximal
2147 .IN "XtExposeCompressMaximal" "" "@DEF"
2149 All expose series currently in the queue for the widget
2150 are coalesced into a single
2151 event without regard to intervening nonexposure events. If a
2152 partial series is in the end of the queue, the \*(xI will
2153 block until the end of the series is received.
2156 The additional flags have the following meaning:
2159 .PN XtExposeGraphicsExpose
2160 .IN "XtExposeGraphicsExpose" "" "@DEF@"
2164 events are also to be dispatched to
2165 the expose procedure.
2167 events are compressed, if specified, in the same manner as
2172 .PN XtExposeGraphicsExposeMerged
2173 .IN "XtExposeGraphicsExposeMerged" "" "@DEF@"
2175 Specifies in the case of
2176 .PN XtExposeCompressMultiple
2178 .PN XtExposeCompressMaximal
2183 events are to be compressed together, with the final event type
2184 determining the type of the event passed to the expose procedure.
2185 If this flag is not set, then only series of the same event type
2186 as the event at the head of the queue are coalesced. This flag
2188 .PN XtExposeGraphicsExpose .
2191 .PN XtExposeNoExpose
2192 .IN "XtExposeNoExpose" "" "@DEF@"
2196 events are also to be dispatched to the expose procedure.
2198 events are never coalesced with
2199 other exposure events or with each other.
2202 .PN XtExposeNoRegion
2203 .IN "XtExposeNoRegion" "" "@DEF"
2205 Specifies that the final region argument passed to the expose
2206 procedure is NULL. The rectangle in the event will still
2207 contain bounding box information for the entire series of
2208 compressed exposure events. This option saves processing time when the
2209 region is not needed by the widget.
2212 Widget Exposure and Visibility
2214 \*(SN Widget Exposure and Visibility
2217 Every primitive widget and some composite widgets display data on the screen
2218 by means of direct Xlib calls.
2219 Widgets cannot simply write to the screen and forget what they have done.
2220 They must keep enough state to redisplay the window or parts
2221 of it if a portion is obscured and then reexposed.
2224 Redisplay of a Widget: The expose Procedure
2226 \*(SN Redisplay of a Widget: The expose Procedure
2228 .IN "expose procedure"
2230 The expose procedure pointer in a widget class is of type
2233 .IN "XtExposeProc" "" "@DEF@"
2236 typedef void (*XtExposeProc)(Widget, XEvent*, Region);
2240 XEvent *\fIevent\fP;
2242 Region \fIregion\fP;
2245 Specifies the widget instance requiring redisplay.
2247 Specifies the exposure event giving the rectangle requiring redisplay.
2249 Specifies the union of all rectangles in this exposure sequence.
2252 The redisplay of a widget upon exposure is the responsibility of the
2253 expose procedure in the widget's class record.
2254 If a widget has no display semantics,
2255 it can specify NULL for the \fIexpose\fP field.
2256 Many composite widgets serve only as containers for their children
2257 and have no expose procedure.
2259 If the \fIexpose\fP procedure is NULL,
2261 fills in a default bit gravity of
2262 .PN NorthWestGravity
2263 before it calls the widget's realize procedure.
2266 If the widget's \fIcompress_exposure\fP class field specifies
2267 .PN XtExposeNoCompress
2269 .PN XtExposeNoRegion ,
2270 or if the event type is
2272 (see Section 7.9.3),
2273 \fIregion\fP is NULL. If
2274 .PN XtExposeNoCompress
2275 is not specified and the event type is not
2277 the event is the final event in the compressed series
2278 but \fIx\fP, \fIy\fP, \fIwidth\fP, and \fIheight\fP contain
2279 the bounding box for all the compressed events.
2280 The region is created and destroyed by the \*(xI, but
2281 the widget is permitted to modify the region contents.
2283 A small simple widget (for example, Label) can ignore the bounding box
2284 information in the event and redisplay the entire window.
2285 A more complicated widget (for example, Text) can use the bounding box
2286 information to minimize the amount of calculation and redisplay it does.
2287 A very complex widget uses the region as a clip list in a GC and
2288 ignores the event information.
2289 The expose procedure is not chained and is therefore
2290 responsible for exposure of all superclass data
2294 it often is possible to anticipate the display needs of several levels
2296 For example, rather than implement separate display procedures for
2297 the widgets Label, Pushbutton, and Toggle,
2298 you could write a single display routine in Label that uses display state
2304 Dimension highlight_width;
2306 Label would have \fIinvert\fP and \fIhighlight\fP always
2308 and \fIhighlight_width\fP zero.
2309 Pushbutton would dynamically set \fIhighlight\fP and \fIhighlight_width\fP,
2310 but it would leave \fIinvert\fP always
2312 Finally, Toggle would dynamically set all three.
2314 the expose procedures for Pushbutton and Toggle inherit
2315 their superclass's expose procedure;
2321 \*(SN Widget Visibility
2324 Some widgets may use substantial computing resources to produce the
2325 data they will display.
2326 However, this effort is wasted if the widget is not actually visible
2327 on the screen, that is, if the widget is obscured by another application
2331 The \fIvisible\fP field in the
2333 widget structure provides a hint to the widget that it need not compute
2335 This field is guaranteed to be
2339 event is processed if any part of the widget is visible,
2342 if the widget is fully obscured.
2344 Widgets can use or ignore the \fIvisible\fP hint.
2346 they should have \fIvisible_interest\fP in their widget class record set
2349 the \fIvisible\fP field is initialized
2352 If \fIvisible_interest\fP is
2354 the event manager asks for
2355 .PN VisibilityNotify
2356 events for the widget and sets \fIvisible\fP to
2359 .PN VisibilityUnobscured
2361 .PN VisibilityPartiallyObscured
2362 .IN VisibilityNotify
2366 .PN VisibilityFullyObscured
2372 \*(SN X Event Handlers
2375 Event handlers are procedures called when specified events
2377 Most widgets need not use event handlers explicitly.
2378 Instead, they use the \*(xI translation manager.
2379 Event handler procedure pointers are of the type
2380 .PN XtEventHandler .
2382 .IN "XtEventHandler" "" "@DEF@"
2385 typedef void (*XtEventHandler)(Widget, XtPointer, XEvent*, Boolean*);
2389 XtPointer \fIclient_data\fP;
2391 XEvent *\fIevent\fP;
2393 Boolean *\fIcontinue_to_dispatch\fP;
2396 Specifies the widget for which the event arrived.
2397 .IP \fIclient_data\fP 1i
2398 Specifies any client-specific information registered with the event handler.
2400 Specifies the triggering event.
2401 .IP \fIcontinue_to_dispatch\fP 1i
2402 Specifies whether the remaining event
2403 handlers registered for the current event
2407 After receiving an event and before calling any event handlers, the
2408 Boolean pointed to by \fIcontinue_to_dispatch\fP is initialized to
2410 When an event handler is called, it may decide that further processing
2411 of the event is not desirable and may store
2414 which case any handlers remaining to be called for the event are
2417 The circumstances under which the \*(xI may add event handlers
2418 to a widget are currently implementation-dependent. Clients must
2419 therefore be aware that storing
2421 into the \fIcontinue_to_dispatch\fP argument can lead to portability problems.
2424 Event Handlers That Select Events
2426 \*(SN Event Handlers That Select Events
2429 To register an event handler procedure with the dispatch mechanism, use
2430 .PN XtAddEventHandler .
2432 .IN "XtAddEventHandler" "" "@DEF@"
2435 void XtAddEventHandler(\fIw\fP, \fIevent_mask\fP, \fInonmaskable\fP, \
2436 \fIproc\fP, \fIclient_data\fP)
2440 EventMask \fIevent_mask\fP;
2442 Boolean \fInonmaskable\fP;
2444 XtEventHandler \fIproc\fP;
2446 XtPointer \fIclient_data\fP;
2449 Specifies the widget for which this event handler is being registered. \*(cI
2450 .IP \fIevent_mask\fP 1i
2451 Specifies the event mask for which to call this procedure.
2452 .IP \fInonmaskable\fP 1i
2453 Specifies whether this procedure should be
2454 called on the nonmaskable events
2455 .Pn ( GraphicsExpose ,
2457 .PN SelectionClear ,
2458 .PN SelectionRequest ,
2459 .PN SelectionNotify ,
2462 .PN MappingNotify ).
2464 Specifies the procedure to be called.
2465 .IP \fIclient_data\fP 1i
2466 Specifies additional data to be passed to the event handler.
2470 .PN XtAddEventHandler
2471 function registers a procedure with the dispatch mechanism that is
2472 to be called when an event that matches the mask occurs on the specified
2474 Each widget has a single registered event handler list, which will
2475 contain any procedure/client_data pair exactly once regardless of
2476 the manner in which it is registered.
2477 If the procedure is already registered with the same \fIclient_data\fP
2479 the specified mask augments the existing mask.
2480 If the widget is realized,
2481 .PN XtAddEventHandler
2485 The order in which this procedure is called relative to other handlers
2486 registered for the same event is not defined.
2489 To remove a previously registered event handler, use
2490 .PN XtRemoveEventHandler .
2492 .IN "XtRemoveEventHandler" "" "@DEF@"
2495 void XtRemoveEventHandler(\fIw\fP, \fIevent_mask\fP, \fInonmaskable\fP, \
2496 \fIproc\fP, \fIclient_data\fP)
2500 EventMask \fIevent_mask\fP;
2502 Boolean \fInonmaskable\fP;
2504 XtEventHandler \fIproc\fP;
2506 XtPointer \fIclient_data\fP;
2509 Specifies the widget for which this procedure is registered. \*(cI
2510 .IP \fIevent_mask\fP 1i
2511 Specifies the event mask for which to unregister this procedure.
2512 .IP \fInonmaskable\fP 1i
2513 Specifies whether this procedure should be
2514 removed on the nonmaskable events
2515 .Pn ( GraphicsExpose ,
2517 .PN SelectionClear ,
2518 .PN SelectionRequest ,
2519 .PN SelectionNotify ,
2522 .PN MappingNotify ).
2524 Specifies the procedure to be removed.
2525 .IP \fIclient_data\fP 1i
2526 Specifies the registered client data.
2530 .PN XtRemoveEventHandler
2531 function unregisters an event handler registered with
2532 .PN XtAddEventHandler
2534 .PN XtInsertEventHandler
2535 for the specified events.
2536 The request is ignored if \fIclient_data\fP does not match the value given
2537 when the handler was registered.
2538 If the widget is realized and no other event handler requires the event,
2539 .PN XtRemoveEventHandler
2542 If the specified procedure has not been registered
2543 or if it has been registered with a different value of \fIclient_data\fP,
2544 .PN XtRemoveEventHandler
2545 returns without reporting an error.
2547 To stop a procedure registered with
2548 .PN XtAddEventHandler
2550 .PN XtInsertEventHandler
2551 from receiving all selected events, call
2552 .PN XtRemoveEventHandler
2553 with an \fIevent_mask\fP of
2555 and \fInonmaskable\fP
2557 The procedure will continue to receive any events
2558 that have been specified in calls to
2559 .PN XtAddRawEventHandler
2561 .PN XtInsertRawEventHandler .
2564 To register an event handler procedure that receives events before or
2565 after all previously registered event handlers, use
2566 .PN XtInsertEventHandler .
2568 .IN "XtListPosition" "" "@DEF@"
2569 .IN "XtInsertEventHandler" "" "@DEF@"
2572 typedef enum {XtListHead, XtListTail} XtListPosition;
2576 void XtInsertEventHandler(\fIw\fP, \fIevent_mask\fP, \fInonmaskable\fP, \
2577 \fIproc\fP, \fIclient_data\fP, \fIposition\fP)
2581 EventMask \fIevent_mask\fP;
2583 Boolean \fInonmaskable\fP;
2585 XtEventHandler \fIproc\fP;
2587 XtPointer \fIclient_data\fP;
2589 XtListPosition \fIposition\fP;
2592 Specifies the widget for which this event handler is being registered. \*(cI
2593 .IP \fIevent_mask\fP 1i
2594 Specifies the event mask for which to call this procedure.
2595 .IP \fInonmaskable\fP 1i
2596 Specifies whether this procedure should be
2597 called on the nonmaskable events
2598 .Pn ( GraphicsExpose ,
2600 .PN SelectionClear ,
2601 .PN SelectionRequest ,
2602 .PN SelectionNotify ,
2605 .PN MappingNotify ).
2607 Specifies the procedure to be called.
2608 .IP \fIclient_data\fP 1i
2609 Specifies additional data to be passed to the client's event handler.
2610 .IP \fIposition\fP 1i
2611 Specifies when the event handler is to be called
2612 relative to other previously registered handlers.
2615 .PN XtInsertEventHandler
2617 .PN XtAddEventHandler
2618 with the additional \fIposition\fP argument. If \fIposition\fP is
2621 handler is registered so that it is called before any event
2622 handlers that were previously registered for the same widget. If
2625 the event handler is registered to be called
2626 after any previously registered event handlers. If the procedure is
2627 already registered with the same \fIclient_data\fP value, the specified mask
2628 augments the existing mask and the procedure is repositioned in
2632 Event Handlers That Do Not Select Events
2634 \*(SN Event Handlers That Do Not Select Events
2638 clients need to register an event handler procedure with the
2639 dispatch mechanism without explicitly
2640 causing the X server to select for that event.
2642 .PN XtAddRawEventHandler .
2644 .IN "XtAddRawEventHandler" "" "@DEF@"
2647 void XtAddRawEventHandler(\fIw\fP, \fIevent_mask\fP, \fInonmaskable\fP, \
2648 \fIproc\fP, \fIclient_data\fP)
2652 EventMask \fIevent_mask\fP;
2654 Boolean \fInonmaskable\fP;
2656 XtEventHandler \fIproc\fP;
2658 XtPointer \fIclient_data\fP;
2661 Specifies the widget for which this event handler is being registered. \*(cI
2662 .IP \fIevent_mask\fP 1i
2663 Specifies the event mask for which to call this procedure.
2664 .IP \fInonmaskable\fP 1i
2665 Specifies whether this procedure should be
2666 called on the nonmaskable events
2667 .Pn ( GraphicsExpose ,
2669 .PN SelectionClear ,
2670 .PN SelectionRequest ,
2671 .PN SelectionNotify ,
2674 .PN MappingNotify ).
2676 Specifies the procedure to be called.
2677 .IP \fIclient_data\fP 1i
2678 Specifies additional data to be passed to the client's event handler.
2682 .PN XtAddRawEventHandler
2683 function is similar to
2684 .PN XtAddEventHandler
2685 except that it does not affect the widget's event mask and never causes an
2688 Note that the widget might already have those mask bits set
2689 because of other nonraw event handlers registered on it.
2690 If the procedure is already registered with the same \fIclient_data\fP,
2691 the specified mask augments the existing mask.
2692 The order in which this procedure is called relative to other handlers
2693 registered for the same event is not defined.
2696 To remove a previously registered raw event handler, use
2697 .PN XtRemoveRawEventHandler .
2699 .IN "XtRemoveRawEventHandler" "" "@DEF@"
2702 void XtRemoveRawEventHandler(\fIw\fP, \fIevent_mask\fP, \fInonmaskable\fP, \
2703 \fIproc\fP, \fIclient_data\fP)
2707 EventMask \fIevent_mask\fP;
2709 Boolean \fInonmaskable\fP;
2711 XtEventHandler \fIproc\fP;
2713 XtPointer \fIclient_data\fP;
2716 Specifies the widget for which this procedure is registered. \*(cI
2717 .IP \fIevent_mask\fP 1i
2718 Specifies the event mask for which to unregister this procedure.
2719 .IP \fInonmaskable\fP 1i
2720 Specifies whether this procedure should be
2721 removed on the nonmaskable events
2722 .Pn ( GraphicsExpose ,
2724 .PN SelectionClear ,
2725 .PN SelectionRequest ,
2726 .PN SelectionNotify ,
2729 .PN MappingNotify ).
2731 Specifies the procedure to be registered.
2732 .IP \fIclient_data\fP 1i
2733 Specifies the registered client data.
2737 .PN XtRemoveRawEventHandler
2738 function unregisters an event handler registered with
2739 .PN XtAddRawEventHandler
2741 .PN XtInsertRawEventHandler
2742 for the specified events without changing
2743 the window event mask.
2744 The request is ignored if \fIclient_data\fP does not match the value given
2745 when the handler was registered.
2746 If the specified procedure has not been registered
2747 or if it has been registered with a different value of \fIclient_data\fP,
2748 .PN XtRemoveRawEventHandler
2749 returns without reporting an error.
2753 .PN XtAddRawEventHandler
2755 .PN XtInsertRawEventHandler
2756 from receiving all nonselected events, call
2757 .PN XtRemoveRawEventHandler
2758 with an \fIevent_mask\fP of
2760 and \fInonmaskable\fP
2763 will continue to receive any events that have been specified in calls to
2764 .PN XtAddEventHandler
2766 .PN XtInsertEventHandler .
2769 To register an event handler procedure that receives events before or
2770 after all previously registered event handlers without selecting for
2772 .PN XtInsertRawEventHandler .
2774 .IN "XtInsertRawEventHandler" "" "@DEF@"
2777 void XtInsertRawEventHandler(\fIw\fP, \fIevent_mask\fP, \fInonmaskable\fP, \
2778 \fIproc\fP, \fIclient_data\fP, \fIposition\fP)
2782 EventMask \fIevent_mask\fP;
2784 Boolean \fInonmaskable\fP;
2786 XtEventHandler \fIproc\fP;
2788 XtPointer \fIclient_data\fP;
2790 XtListPosition \fIposition\fP;
2793 Specifies the widget for which this event handler is being registered. \*(cI
2794 .IP \fIevent_mask\fP 1i
2795 Specifies the event mask for which to call this procedure.
2796 .IP \fInonmaskable\fP 1i
2797 Specifies whether this procedure should be
2798 called on the nonmaskable events
2799 .Pn ( GraphicsExpose ,
2801 .PN SelectionClear ,
2802 .PN SelectionRequest ,
2803 .PN SelectionNotify ,
2806 .PN MappingNotify ).
2808 Specifies the procedure to be registered.
2809 .IP \fIclient_data\fP 1i
2810 Specifies additional data to be passed to the client's event handler.
2811 .IP \fIposition\fP 1i
2812 Specifies when the event handler is to be called
2813 relative to other previously registered handlers.
2817 .PN XtInsertRawEventHandler
2818 function is similar to
2819 .PN XtInsertEventHandler
2820 except that it does not modify the widget's event
2821 mask and never causes an
2823 for the specified events. If
2824 the procedure is already registered with the same \fIclient_data\fP
2826 specified mask augments the existing mask and the procedure is
2827 repositioned in the list.
2832 \*(SN Current Event Mask
2835 To retrieve the event mask for a given widget, use
2836 .PN XtBuildEventMask .
2838 .IN "XtBuildEventMask" "" "@DEF@"
2841 EventMask XtBuildEventMask(\fIw\fP)
2846 Specifies the widget. \*(cI
2850 .PN XtBuildEventMask
2851 function returns the event mask representing the logical OR
2852 of all event masks for event handlers registered on the widget with
2853 .PN XtAddEventHandler
2855 .PN XtInsertEventHandler
2856 and all event translations, including accelerators,
2857 installed on the widget.
2858 This is the same event mask stored into the
2859 .PN XSetWindowAttributes
2862 and sent to the server when event handlers and translations are installed or
2863 removed on the realized widget.
2866 Event Handlers for X11 Protocol Extensions
2868 \fB\*(SN Event Handlers for X11 Protocol Extensions\fP
2871 To register an event handler procedure with the \*(xI dispatch
2872 mechanism according to an event type, use
2873 .PN XtInsertEventTypeHandler .
2875 .IN "XtInsertEventTypeHandler" "" "@DEF"
2878 void XtInsertEventTypeHandler(\fIwidget\fP, \fIevent_type\fP, \
2879 \fIselect_data\fP, \fIproc\fP, \fIclient_data\fP, \fIposition\fP)
2881 Widget \fIwidget\fP;
2883 int \fIevent_type\fP;
2885 XtPointer \fIselect_data\fP;
2887 XtEventHandler \fIproc\fP;
2889 XtPointer \fIclient_data\fP;
2891 XtListPosition \fIposition\fP;
2894 Specifies the widget for which this event handler is being registered. \*(cI
2895 .IP \fIevent_type\fP 1i
2896 Specifies the event type for which to call this event handler.
2897 .IP \fIselect_data\fP 1i
2898 Specifies data used to request events of the specified type from the server,
2901 Specifies the event handler to be called.
2902 .IP \fIclient_data\fP 1i
2903 Specifies additional data to be passed to the event handler.
2904 .IP \fIposition\fP 1i
2905 Specifies when the event handler is to be called relative to other
2906 previously registered handlers.
2909 .PN XtInsertEventTypeHandler
2910 registers a procedure with the
2911 dispatch mechanism that is to be called when an event that matches the
2912 specified \fIevent_type\fP is dispatched to the specified \fIwidget\fP.
2914 If \fIevent_type\fP specifies one of the core X protocol events, then
2915 \fIselect_data\fP must be a pointer to a value of type
2918 the event mask to be used to select for the desired event. This event
2919 mask is included in the value returned by
2920 .PN XtBuildEventMask .
2921 If the widget is realized,
2922 .PN XtInsertEventTypeHandler
2925 if necessary. Specifying NULL for \fIselect_data\fP is equivalent to
2926 specifying a pointer to an event mask containing 0. This is similar
2928 .PN XtInsertRawEventHandler
2931 If \fIevent_type\fP specifies an extension event type, then the semantics of
2932 the data pointed to by \fIselect_data\fP are defined by the extension
2933 selector registered for the specified event type.
2935 In either case the \*(xI are not required to copy the data
2936 pointed to by \fIselect_data\fP, so the caller must ensure that it remains
2937 valid as long as the event handler remains registered with this value
2938 of \fIselect_data\fP.
2940 The \fIposition\fP argument allows the client to control the order of
2941 invocation of event handlers registered for the same event type. If
2942 the client does not care about the order, it should normally specify
2944 which registers this event handler after any previously
2945 registered handlers for this event type.
2947 Each widget has a single registered event handler list, which will
2948 contain any procedure/client_data pair exactly once if it is
2950 .PN XtInsertEventTypeHandler ,
2951 regardless of the manner
2952 in which it is registered and regardless of the value(s)
2953 of \fIselect_data\fP. If the procedure is already registered with the
2954 same \fIclient_data\fP value, the specified mask augments the existing
2955 mask and the procedure is repositioned in the list.
2958 To remove an event handler registered with
2959 .PN XtInsertEventTypeHandler ,
2961 .PN XtRemoveEventTypeHandler .
2963 .IN "XtRemoveEventTypeHandler" "" "@DEF"
2966 void XtRemoveEventTypeHandler(\fIwidget\fP, \fIevent_type\fP, \
2967 \fIselect_data\fP, \fIproc\fP, \fIclient_data\fP)
2969 Widget \fIwidget\fP;
2971 int \fIevent_type\fP;
2973 XtPointer \fIselect_data\fP;
2975 XtEventHandler \fIproc\fP;
2977 XtPointer \fIclient_data\fP;
2980 Specifies the widget for which the event handler was registered. \*(cI
2981 .IP \fIevent_type\fP 1i
2982 Specifies the event type for which the handler was registered.
2983 .IP \fIselect_data\fP 1i
2984 Specifies data used to deselect events of the specified type
2985 from the server, or NULL.
2987 Specifies the event handler to be removed.
2988 .IP \fIclient_data\fP 1i
2989 Specifies the additional client data with which the procedure was registered.
2993 .PN XtRemoveEventTypeHandler
2994 function unregisters an event handler
2996 .PN XtInsertEventTypeHandler
2997 for the specified event type.
2998 The request is ignored if \fIclient_data\fP does not match the value given
2999 when the handler was registered.
3001 If \fIevent_type\fP specifies one of the core X protocol events,
3002 \fIselect_data\fP must be a pointer to a value of type
3003 .PN EventMask, indicating the event
3004 mask to be used to deselect for the appropriate event. If the widget
3006 .PN XtRemoveEventTypeHandler
3010 Specifying NULL for \fIselect_data\fP is equivalent to specifying a pointer
3011 to an event mask containing 0. This is similar to the
3012 .PN XtRemoveRawEventHandler
3015 If \fIevent_type\fP specifies an extension event type, then the semantics of
3016 the data pointed to by \fIselect_data\fP are defined by the extension
3017 selector registered for the specified event type.
3020 To register a procedure to select extension events for a widget, use
3021 .PN XtRegisterExtensionSelector .
3023 .IN "XtRegisterExtensionSelector" "" "@DEF@"
3026 void XtRegisterExtensionSelector(\fIdisplay\fP, \fImin_event_type\fP, \
3027 \fImax_event_type\fP, \fIproc\fP,
3030 Display \fI*display\fP;
3032 int \fImin_event_type\fP;
3034 int \fImax_event_type\fP;
3036 XtExtensionSelectProc \fIproc\fP;
3038 XtPointer \fIclient_data\fP;
3040 .IP \fIdisplay\fP 1.5i
3041 Specifies the display for which the extension selector is to be registered.
3042 .IP \fImin_event_type\fP
3043 .IP \fImax_event_type\fP 1.5i
3044 Specifies the range of event types for the extension.
3046 Specifies the extension selector procedure.
3047 .IP \fIclient_data\fP 1.5i
3048 Specifies additional data to be passed to the extension selector.
3052 .PN XtRegisterExtensionSelector
3053 function registers a procedure to arrange
3054 for the delivery of extension events to widgets.
3056 If \fImin_event_type\fP and \fImax_event_type\fP match the parameters
3057 to a previous call to
3058 .PN XtRegisterExtensionSelector
3059 for the same \fIdisplay\fP, then \fIproc\fP and \fIclient_data\fP
3060 replace the previously
3061 registered values. If the range specified by \fImin_event_type\fP
3062 and \fImax_event_type\fP overlaps the range of the parameters to a
3063 previous call for the same display in any other way, an error results.
3065 When a widget is realized,
3066 after the \fIcore.realize\fP method is called,
3067 the \*(xI check to see if any event
3068 handler specifies an event type within the range of a registered
3069 extension selector. If so, the \*(xI call each such selector.
3070 If an event type handler is added or removed, the \*(xI check to
3071 see if the event type falls within the range of a registered extension
3072 selector, and if it does, calls the selector. In either case the \*(xI
3073 pass a list of all the widget's event types that are within the
3074 selector's range. The corresponding select data are also passed. The
3075 selector is responsible for enabling the delivery of extension events
3076 required by the widget.
3079 An extension selector is of type
3080 .PN XtExtensionSelectProc .
3082 .IN "XtExtensionSelectProc" "" "@DEF"
3085 typedef void (*XtExtensionSelectProc)(Widget, int *, XtPointer *, int, \
3088 Widget \fIwidget\fP;
3090 int *\fIevent_types\fP;
3092 XtPointer *\fIselect_data\fP;
3096 XtPointer \fIclient_data\fP;
3099 Specifies the widget that is being realized or is having
3100 an event handler added or removed.
3101 .IP \fIevent_types\fP 1i
3102 Specifies a list of event types that the widget has
3103 registered event handlers for.
3104 .IP \fIselect_data\fP 1i
3105 Specifies a list of the select_data parameters specified in
3106 .PN XtInsertEventTypeHandler .
3108 Specifies the number of entries in the \fIevent_types\fP and \fIselect_data\fP
3110 .IP \fIclient_data\fP 1i
3111 Specifies the additional client data with which the procedure was registered.
3114 The \fIevent_types\fP and \fIselect_data\fP lists will always have the
3115 same number of elements, specified by \fIcount\fP.
3116 Each event type/select data pair represents one call to
3117 .PN XtInsertEventTypeHandler .
3120 To register a procedure to dispatch events of a specific type within
3121 .PN XtDispatchEvent ,
3123 .PN XtSetEventDispatcher .
3125 .IN "XtSetEventDispatcher" "" "@DEF@"
3128 XtEventDispatchProc XtSetEventDispatcher(\fIdisplay\fP, \fIevent_type\fP, \
3131 Display *\fIdisplay\fP;
3133 int \fIevent_type\fP;
3135 XtEventDispatchProc \fIproc\fP;
3137 .IP \fIdisplay\fP 1i
3138 Specifies the display for which the event dispatcher is to be registered.
3139 .IP \fIevent_type\fP 1i
3140 Specifies the event type for which the dispatcher should be invoked.
3142 Specifies the event dispatcher procedure.
3146 .PN XtSetEventDispatcher
3147 function registers the event dispatcher procedure specified by \fIproc\fP
3148 for events with the type \fIevent_type\fP. The previously registered
3149 dispatcher (or the default dispatcher if there was no previously registered
3150 dispatcher) is returned. If \fIproc\fP is NULL, the default procedure is
3151 restored for the specified type.
3155 is called with an event type of \fIevent_type\fP, the specified \fIproc\fP
3156 (or the default dispatcher) is invoked to determine a widget
3157 to which to dispatch the event.
3159 The default dispatcher handles the \*(xI modal cascade and keyboard
3160 focus mechanisms, handles the semantics of \fIcompress_enterleave\fP
3161 and \fIcompress_motion\fP, and discards all extension events.
3164 An event dispatcher procedure pointer is of type
3165 .PN XtEventDispatchProc .
3167 .IN "XtEventDispatchProc" "" "@DEF@"
3170 typedef Boolean (*XtEventDispatchProc)(XEvent*)
3172 XEvent *\fIevent\fP;
3175 Passes the event to be dispatched.
3178 The event dispatcher procedure should determine whether this event is of
3179 a type that should be dispatched to a widget.
3181 If the event should be dispatched to a widget, the event dispatcher
3182 procedure should determine the appropriate widget to receive the
3185 with the window of this widget, or
3187 if the event is to be discarded, and if
3191 dispatch the event to the widget using
3192 .PN XtDispatchEventToWidget .
3193 The procedure should return
3198 .PN XtDispatchEventToWidget
3205 If the event should not be dispatched to a widget, the event
3206 dispatcher procedure should attempt to dispatch the event elsewhere as
3207 appropriate and return
3209 if it successfully dispatched the event and
3214 Some dispatchers for extension events may wish to forward events
3215 according to the Intrinsics' keyboard focus mechanism. To determine
3216 which widget is the end result of keyboard event forwarding, use
3217 .PN XtGetKeyboardFocusWidget .
3219 .IN "XtGetKeyboardFocusWidget" "" "@DEF@"
3222 Widget XtGetKeyboardFocusWidget(\fIwidget\fP)
3224 Widget \fIwidget\fP;
3227 Specifies the widget to get forwarding information for.
3231 .PN XtGetKeyboardFocusWidget
3232 function returns the widget that would be the end result of keyboard
3233 event forwarding for a keyboard event for the specified widget.
3236 To dispatch an event to a specified widget, use
3237 .PN XtDispatchEventToWidget .
3239 .IN "XtDispatchEventToWidget" "" "@DEF@"
3242 Boolean XtDispatchEventToWidget(\fIwidget\fP, \fIevent\fP)
3244 Widget \fIwidget\fP;
3246 XEvent *\fIevent\fP;
3249 Specifies the widget to which to dispatch the event.
3251 Specifies a pointer to the event to be dispatched.
3255 .PN XtDispatchEventToWidget
3256 function scans the list of registered event handlers for the
3257 specified widget and calls each handler that has been registered
3258 for the specified event type, subject to the \fIcontinue_to_dispatch\fP
3259 value returned by each handler.
3260 The \*(xI behave as if event handlers were registered at the head
3264 .PN GraphicsExpose ,
3266 .PN VisibilityNotify
3267 events to invoke the widget's expose procedure according to the exposure
3268 compression rules and to update the widget's \fIvisible\fP field
3269 if \fIvisible_interest\fP is
3271 These internal event handlers never set \fIcontinue_to_dispatch\fP to
3274 .PN XtDispatchEventToWidget
3277 if any event handler was called and
3282 Using the \*(xI in a Multi-Threaded Environment
3284 \*(SN Using the \*(xI in a Multi-Threaded Environment
3287 The \*(xI may be used in environments that offer multiple threads
3288 of execution within the context of a single process. A multi-threaded
3289 application using the \*(xI must explicitly initialize the toolkit
3290 for mutually exclusive access by calling
3291 .PN XtToolkitThreadInitialize .
3294 Initializing a Multi-Threaded \*(xI Application
3296 \fB\*(SN Initializing a Multi-Threaded \*(xI Application\fP
3299 To test and initialize \*(xI support for mutually exclusive thread
3301 .PN XtToolkitThreadInitialize .
3303 .IN "XtToolkitThreadInitialize" "" "@DEF@"
3306 Boolean XtToolkitThreadInitialize()
3310 .PN XtToolkitThreadInitialize
3311 returns \fBTrue\fP if the \*(xI support mutually exclusive thread
3312 access, otherwise it returns \fBFalse\fP. \fBXtToolkitThreadInitialize\fP
3313 must be called before
3314 .PN XtCreateApplicationContext ,
3315 .PN XtAppInitialize ,
3316 .PN XtOpenApplication ,
3318 .PN XtSetLanguageProc
3319 is called. \fBXtToolkitThreadInitialize\fP may be called more than once;
3320 however, the application writer must ensure that it is not called
3321 simultaneously by two or more threads.
3324 Locking \*(tk Data Structures
3326 \fB\*(SN Locking \*(tk Data Structures\fP
3329 The \*(xI employs two levels of locking: application context and
3330 process. Locking an application context ensures mutually exclusive
3331 access by a thread to the state associated with the application context,
3332 including all displays and widgets associated with it. Locking a
3333 process ensures mutually exclusive access by a thread to \*(xI process
3336 A client may acquire a lock multiple times and the effect is cumulative.
3337 The client must ensure that the lock is released an equal number of times in
3338 order for the lock to be acquired by another thread.
3340 Most application writers will have little need to use locking as the
3341 \*(xI performs the necessary locking internally.
3342 Resource converters are an exception.
3343 They require the application context or process to be locked
3344 before the application can safely call them directly, for example:
3351 XtAppLock(app_context);
3352 XtCvtStringToPixel(dpy, args, num_args, fromVal, toVal, closure_ret);
3353 XtAppUnlock(app_context);
3358 When the application relies upon
3359 .PN XtConvertAndStore
3360 or a converter to provide the storage for the results of a
3361 conversion, the application should acquire the process lock before
3362 calling out and hold the lock until the results have been copied.
3364 Application writers who write their own
3365 utility functions, such as one which retrieves the being_destroyed field from
3366 a widget instance, must lock the application context before accessing
3367 widget internal data. For example:
3373 #include <X11/CoreP.h>
3374 Boolean BeingDestroyed (widget)
3378 XtAppLock(XtWidgetToApplicationContext(widget));
3379 ret = widget->core.being_destroyed;
3380 XtAppUnlock(XtWidgetToApplicationContext(widget));
3385 A client that wishes to atomically call two or more \*(xI functions
3386 must lock the application context. For example:
3393 XtAppLock(XtWidgetToApplicationContext(widget));
3394 XtUnmanageChild (widget1);
3395 XtManageChild (widget2);
3396 XtAppUnlock(XtWidgetToApplicationContext(widget));
3402 Locking the Application Context
3404 \fB\*(SN Locking the Application Context\fP
3407 To ensure mutual exclusion of application context, display, or
3408 widget internal state, use
3411 .IN "XtAppLock" "" "@DEF@"
3414 void XtAppLock(\fIapp_context\fP)
3416 XtAppContext \fIapp_context\fP;
3418 .IP \fIapp_context\fP 1i
3419 Specifies the application context to lock.
3422 \fBXtAppLock\fP blocks until it is able to acquire the lock. Locking the
3423 application context also ensures that only the thread holding the lock
3424 makes Xlib calls from within Xt. An application that makes its own
3425 direct Xlib calls must either lock the application context around every
3426 call or enable thread locking in Xlib.
3428 To unlock a locked application context, use
3431 .IN "XtAppUnlock" "" "@DEF@"
3434 void XtAppUnlock(\fIapp_context\fP)
3436 XtAppContext \fIapp_context\fP;
3438 .IP \fIapp_context\fP 1i
3439 Specifies the application context that was previously locked.
3446 \*(SN Locking the Process
3449 To ensure mutual exclusion of \*(tk process global data, a
3450 widget writer must use
3453 .IN "XtProcessLock" "" "@DEF@"
3456 void XtProcessLock()
3460 \fBXtProcessLock\fP blocks until it is able to acquire the lock.
3461 Widget writers may use XtProcessLock to guarantee mutually exclusive
3462 access to widget static data.
3464 To unlock a locked process, use
3465 .PN XtProcessUnlock .
3467 .IN "XtProcessUnlock" "" "@DEF@"
3470 void XtProcessUnlock()
3474 To lock both an application context and the process at the same
3479 To release both locks, call
3483 The order is important to avoid deadlock.
3486 Event Management in a Multi-Threaded Environment
3488 \fB\*(SN Event Management in a Multi-Threaded Environment\fP
3491 In a nonthreaded environment an application writer could reasonably
3492 assume that it is safe to exit the application from a quit callback.
3493 This assumption may no longer hold true in a multi-threaded environment;
3494 therefore it is desirable to provide a mechanism to terminate an
3495 event-processing loop without necessarily terminating its thread.
3497 To indicate that the event loop should terminate after the current
3498 event dispatch has completed, use
3499 .PN XtAppSetExitFlag .
3501 .IN "XtAppSetExitFlag" "" "@DEF@"
3504 void XtAppSetExitFlag(\fIapp_context\fP)
3506 XtAppContext \fIapp_context\fP;
3508 .IP \fIapp_context\fP 1i
3509 Specifies the application context.
3513 tests the value of the flag and will return if the flag is \fBTrue\fP.
3515 Application writers who implement their own main loop may test the
3516 value of the exit flag with
3517 .PN XtAppGetExitFlag .
3519 .IN "XtAppGetExitFlag" "" "@DEF@"
3522 Boolean XtAppGetExitFlag(\fIapp_context\fP)
3524 XtAppContext \fIapp_context\fP;
3526 .IP \fIapp_context\fP 1i
3527 Specifies the application context.
3530 .PN XtAppGetExitFlag
3531 will normally return \fBFalse\fP, indicating that event processing
3533 .PN XtAppGetExitFlag
3534 returns \fBTrue\fP, the loop must terminate and return to the caller,
3535 which might then destroy the application context.
3537 Application writers should be aware that, if a thread is blocked in
3538 .PN XtAppNextEvent ,
3539 .PN XtAppPeekEvent ,
3541 .PN XtAppProcessEvent
3542 and another thread in the same application context opens a new display,
3543 adds an alternate input, or a timeout, any new source(s) will not
3544 normally be "noticed" by the blocked thread. Any new sources are
3545 "noticed" the next time one of these functions is called.
3547 The \*(xI manage access to events on a last-in, first-out basis. If
3548 multiple threads in the same application context block in
3549 .PN XtAppNextEvent ,
3550 .PN XtAppPeekEvent ,
3552 .PN XtAppProcessEvent ,
3553 the last thread to call one of these functions is the first
projects / framework / uifw / xorg / lib / libxt.git / blob