« back to all changes in this revision
Viewing changes to specs/CH07
- browse files at revision 8
- compare with another revision
- download diff
- download tarball
- view history from revision 8
- Committer: Bazaar Package Importer
- Author(s): Cyril Brulebois, Julien Cristau, Robert Hooker, Christopher James Halse Rogers, Cyril Brulebois
- Date: 2011-01-14 04:45:31 UTC
- mfrom: (4.1.3 experimental)
- Revision ID: james.westby@ubuntu.com-20110114044531-1fdwgh8s7vixn43p
Tags: 1:1.0.9-1
[ Julien Cristau ]
* Rename the build directory to not include DEB_BUILD_GNU_TYPE for no
good reason. Thanks, Colin Watson!
* New upstream release.
* Update debian/copyright from upstream COPYING.
[ Robert Hooker ]
* Don't install makestrs and its man page in libxt-dev, it's not shipped
anymore.
[ Christopher James Halse Rogers ]
* New new upstream release.
* Drop debian/patches/02_dont_export_private_deps.diff:
- Upstream has trimmed the Required list in xt.pc, and a libXt header
includes a #define which uses a libX11 symbol, so libX11 should be
in the Requires field (and is). This fixes lots of FTBFS with
binutils-gold, which doesn't consider indirect dependencies.
[ Cyril Brulebois ]
* Update debian/copyright from upstream COPYING.
* Exclude libXt.la in dh_install call.
* Switch dh_install from --list-missing to --fail-missing for added
safety.
* Add myself to Uploaders.
* Rename the build directory to not include DEB_BUILD_GNU_TYPE for no
good reason. Thanks, Colin Watson!
* New upstream release.
* Update debian/copyright from upstream COPYING.
[ Robert Hooker ]
* Don't install makestrs and its man page in libxt-dev, it's not shipped
anymore.
[ Christopher James Halse Rogers ]
* New new upstream release.
* Drop debian/patches/02_dont_export_private_deps.diff:
- Upstream has trimmed the Required list in xt.pc, and a libXt header
includes a #define which uses a libX11 symbol, so libX11 should be
in the Requires field (and is). This fixes lots of FTBFS with
binutils-gold, which doesn't consider indirect dependencies.
[ Cyril Brulebois ]
* Update debian/copyright from upstream COPYING.
* Exclude libXt.la in dh_install call.
* Switch dh_install from --list-missing to --fail-missing for added
safety.
* Add myself to Uploaders.
added
removed
specs/CH07
1
.\" $Xorg: CH07,v 1.4 2000/08/17 19:42:45 cpqbld Exp $
2
.\" Copyright \(co 1985, 1986, 1987, 1988, 1991, 1994
3
.\" X Consortium
4
.\"
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:
12
.\"
13
.\" The above copyright notice and this permission notice shall be included
14
.\" in all copies or substantial portions of the Software.
15
.\"
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.
23
.\"
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.
28
.\"
29
.\" Copyright \(co 1985, 1986, 1987, 1988, 1991, 1994
30
.\" Digital Equipment Corporation, Maynard, Massachusetts.
31
.\"
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.
41
.\"
42
\&
43
.sp 1
44
.ce 3
45
\s+1\fBChapter 7\fP\s-1
46
47
\s+1\fBEvent Management\fP\s-1
48
.sp 2
49
.nr H1 7
50
.nr H2 0
51
.nr H3 0
52
.nr H4 0
53
.nr H5 0
54
.LP
55
.XS
56
Chapter 7 \(em Event Management
57
.XE
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.
63
.LP
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
68
.PN XtAppMainLoop .
69
.LP
70
The event manager is a collection of functions to perform the following tasks:
71
.IP \(bu 5
72
Add or remove event sources other than X server events (in particular,
73
timer interrupts, file input, or POSIX signals).
74
.IP \(bu 5
75
Query the status of event sources.
76
.IP \(bu 5
77
Add or remove procedures to be called when an event occurs for a particular
78
widget.
79
.IP \(bu 5
80
Enable and
81
disable the dispatching of user-initiated events (keyboard and pointer events)
82
for a particular widget.
83
.IP \(bu 5
84
Constrain the dispatching of events to a cascade of pop-up widgets.
85
.IP \(bu 5
86
Register procedures to be called when specific events arrive.
87
.IP \(bu 5
88
Register procedures to be called when the \*(xI will block.
89
.IP \(bu 5
90
Enable safe operation in a multi-threaded environment.
91
.LP
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
94
translation manager,
95
which maps sequences of X events, with modifiers, into procedure calls.
96
Applications rarely use any of the event manager routines besides
97
.PN XtAppMainLoop .
98
99
.NH 2
100
Adding and Deleting Additional Event Sources
101
.XS
102
\fB\*(SN Adding and Deleting Additional Event Sources\fP
103
.XE
104
.LP
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.
110
.LP
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.
115
116
.NH 3
117
Adding and Removing Input Sources
118
.XS
119
\fB\*(SN Adding and Removing Input Sources\fP
120
.XE
121
.LP
122
To register a new file as an input source for a given application context, use
123
.PN XtAppAddInput .
124
.LP
125
.IN "XtAppAddInput" "" "@DEF@"
126
.sM
127
.FD 0
128
XtInputId XtAppAddInput(\fIapp_context\fP, \fIsource\fP, \fIcondition\fP, \
129
\fIproc\fP, \fIclient_data\fP)
130
.br
131
XtAppContext \fIapp_context\fP;
132
.br
133
int \fIsource\fP;
134
.br
135
XtPointer \fIcondition\fP;
136
.br
137
XtInputCallbackProc \fIproc\fP;
138
.br
139
XtPointer \fIclient_data\fP;
140
.FN
141
.IP \fIapp_context\fP 1i
142
Specifies the application context that identifies the application.
143
.IP \fIsource\fP 1i
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.
149
.IP \fIproc\fP 1i
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
153
when it is called.
154
.LP
155
.eM
156
The
157
.PN XtAppAddInput
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
161
or source of data.
162
.PN XtAppAddInput
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.
166
.LP
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
176
for writing.
177
.IN "XtInputExceptMask" "" "@DEF@"
178
.IP \fBXtInputExceptMask\fR 1.5i
179
Specifies that \fIproc\fP is to be called when \fIsource\fP has
180
exception data.
181
.LP
182
Callback procedure pointers used to handle file events are of
183
type
184
.PN XtInputCallbackProc .
185
.LP
186
.IN "XtInputCallbackProc" "" "@DEF@"
187
.sM
188
.FD 0
189
typedef void (*XtInputCallbackProc)(XtPointer, int*, XtInputId*);
190
.br
191
XtPointer \fIclient_data\fP;
192
.br
193
int *\fIsource\fP;
194
.br
195
XtInputId *\fIid\fP;
196
.FN
197
.IP \fIclient_data\fP 1i
198
Passes the client data argument that was registered for this procedure in
199
.PN XtApp\%AddInput .
200
.IP \fIsource\fP 1i
201
Passes the source file descriptor generating the event.
202
.IP \fIid\fP 1i
203
Passes the id returned from the corresponding
204
.PN XtAppAddInput
205
call.
206
.LP
207
.eM
208
See Section 7.12 for information regarding the use of
209
.PN XtAppAddInput
210
in multiple threads.
211
.sp
212
.LP
213
To discontinue a source of input, use
214
.PN XtRemoveInput .
215
.LP
216
.IN "XtRemoveInput" "" "@DEF@"
217
.sM
218
.FD 0
219
void XtRemoveInput(\fIid\fP)
220
.br
221
XtInputId \fIid\fP;
222
.FN
223
.IP \fIid\fP 1i
224
Specifies the id returned from the corresponding
225
.PN XtAppAddInput
226
call.
227
.LP
228
.eM
229
The
230
.PN XtRemoveInput
231
function causes the \*(xI read routine to stop watching for events
232
from the file source specified by \fIid\fP.
233
.LP
234
See Section 7.12 for information regarding the use of
235
.PN XtRemoveInput
236
in multiple threads.
237
238
.NH 3
239
Adding and Removing Blocking Notifications
240
.XS
241
\fB\*(SN Adding and Removing Blocking Notifications\fP
242
.XE
243
.LP
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.
248
.sp
249
.LP
250
To register a hook that is called immediately prior to event blocking, use
251
.PN XtAppAddBlockHook .
252
.LP
253
.IN "XtAppAddBlockHook" "" "@DEF@"
254
.sM
255
.FD 0
256
XtBlockHookId XtAppAddBlockHook(\fIapp_context\fP, \fIproc\fP, \
257
\fIclient_data\fP)
258
.br
259
XtAppContext \fIapp_context\fP;
260
.br
261
XtBlockHookProc \fIproc\fP;
262
.br
263
XtPointer \fIclient_data\fP;
264
.FN
265
.IP \fIapp_context\fP 1i
266
Specifies the application context that identifies the application.
267
.IP \fIproc\fP 1i
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.
271
.LP
272
.eM
273
The
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.
278
.LP
279
The procedure pointers used to provide notification of event blocking
280
are of type
281
.PN XtBlockHookProc .
282
.LP
283
.IN "XtBlockHookProc" "" "@DEF@"
284
.sM
285
.FD 0
286
typedef void (*XtBlockHookProc)(XtPointer);
287
.br
288
XtPointer \fIclient_data\fP;
289
.FN
290
.IP \fIclient_data\fP 1i
291
Passes the client data argument that was registered for this procedure in
292
.PN XtApp\%AddBlockHook .
293
.LP
294
.eM
295
To discontinue the use of a procedure for blocking notification, use
296
.PN XtRemoveBlockHook .
297
.LP
298
.IN "XtRemoveBlockHook" "" "@DEF@"
299
.sM
300
.FD 0
301
void XtRemoveBlockHook(\fIid\fP)
302
.br
303
XtBlockHookId \fIid\fP;
304
.FN
305
.IP \fIid\fP 1i
306
Specifies the identifier returned from the corresponding call to
307
.PN XtAppAddBlockHook .
308
.LP
309
.eM
310
The
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.
314
315
.NH 3
316
Adding and Removing Timeouts
317
.XS
318
\fB\*(SN Adding and Removing Timeouts\fP
319
.XE
320
.LP
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.
324
.sp
325
.LP
326
To register a timeout callback, use
327
.PN XtAppAddTimeOut .
328
.LP
329
.IN "XtAppAddTimeOut" "" "@DEF@"
330
.sM
331
.FD 0
332
XtIntervalId XtAppAddTimeOut(\fIapp_context\fP, \fIinterval\fP, \fIproc\fP, \
333
\fIclient_data\fP)
334
.br
335
XtAppContext \fIapp_context\fP;
336
.br
337
unsigned long \fIinterval\fP;
338
.br
339
XtTimerCallbackProc \fIproc\fP;
340
.br
341
XtPointer \fIclient_data\fP;
342
.FN
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.
347
.IP \fIproc\fP 1i
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
351
when it is called.
352
.LP
353
.eM
354
The
355
.PN XtAppAddTimeOut
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
359
.PN XtAppNextEvent
360
or
361
.PN XtAppProcessEvent
362
is next called after the time interval elapses,
363
and then the timeout is removed.
364
.LP
365
Callback procedure pointers used with timeouts are of
366
type
367
.PN XtTimerCallbackProc .
368
.LP
369
.IN "XtTimerCallbackProc" "" "@DEF@"
370
.sM
371
.FD 0
372
typedef void (*XtTimerCallbackProc)(XtPointer, XtIntervalId*);
373
.br
374
XtPointer \fIclient_data\fP;
375
.br
376
XtIntervalId *\fItimer\fP;
377
.FN
378
.IP \fIclient_data\fP 1i
379
Passes the client data argument that was registered for this procedure in
380
.PN XtApp\%AddTimeOut .
381
.IP \fItimer\fP 1i
382
Passes the id returned from the corresponding
383
.PN XtAppAddTimeOut
384
call.
385
.LP
386
.eM
387
See Section 7.12 for information regarding the use of
388
.PN XtAppAddTimeOut
389
in multiple threads.
390
.sp
391
.LP
392
To clear a timeout value, use
393
.PN XtRemoveTimeOut .
394
.LP
395
.IN "XtRemoveTimeOut" "" "@DEF@"
396
.sM
397
.FD 0
398
void XtRemoveTimeOut(\fItimer\fP)
399
.br
400
XtIntervalId \fItimer\fP;
401
.FN
402
.IP \fItimer\fP 1i
403
Specifies the id for the timeout request to be cleared.
404
.LP
405
.eM
406
The
407
.PN XtRemoveTimeOut
408
function removes the pending timeout.
409
Note that timeouts are automatically removed once they trigger.
410
.LP
411
Please refer to Section 7.12 for information regarding the use of
412
.PN XtRemoveTimeOut
413
in multiple threads.
414
415
.NH 3
416
Adding and Removing Signal Callbacks
417
.XS
418
\fB\*(SN Adding and Removing Signal Callbacks\fP
419
.XE
420
.LP
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
424
by a signal id.
425
.sp
426
.LP
427
Prior to establishing a signal handler, the application or widget should
428
call
429
.PN XtAppAddSignal
430
and store the resulting identifier in a place accessible to the signal
431
handler. When a signal arrives, the signal handler should call
432
.PN XtNoticeSignal
433
to notify the \*(xI that a signal has occured. To register a signal
434
callback use
435
.PN XtAppAddSignal .
436
.LP
437
.IN "XtAppAddSignal" "" "@DEF@"
438
.sM
439
.FD 0
440
XtSignalId XtAppAddSignal(\fIapp_context\fP, \fIproc\fP, \fIclient_data\fP)
441
.br
442
XtAppContext \fIapp_context\fP;
443
.br
444
XtSignalCallbackProc \fIproc\fP;
445
.br
446
XtPointer \fIclient_data\fP;
447
.FN
448
.IP \fIapp_context\fP 1i
449
Specifies the application context that identifies the application.
450
.IP \fIproc\fP 1i
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.
454
.LP
455
.eM
456
The callback procedure pointers used to handle signal events are of type
457
.PN XtSignalCallbackProc .
458
.LP
459
.IN "XtSignalCallbackProc" "" "@DEF@"
460
.sM
461
.FD 0
462
typedef void (*XtSignalCallbackProc)(XtPointer, XtSignalId*);
463
.br
464
XtPointer \fIclient_data\fP;
465
.br
466
XtSignalId *\fIid\fP;
467
.FN
468
.IP \fIclient_data\fP 1i
469
Passes the client data argument that was registered for this procedure in
470
.PN XtAppAddSignal .
471
.IP \fIid\fP 1i
472
Passes the id returned from the corresponding
473
.PN XtAppAddSignal
474
call.
475
.LP
476
.eM
477
To notify the \*(xI that a signal has occured, use
478
.PN XtNoticeSignal .
479
.LP
480
.IN "XtNoticeSignal" "" "@DEF@"
481
.sp
482
.sM
483
.FD 0
484
void XtNoticeSignal(\fIid\fP)
485
.br
486
XtSignalId \fIid\fP;
487
.FN
488
.IP \fIid\fP 1i
489
Specifies the id returned from the corresponding
490
.PN XtAppAddSignal
491
call.
492
.LP
493
.eM
494
On a POSIX-based system,
495
.PN XtNoticeSignal
496
is the only \*(xI function that can safely be called from a signal handler.
497
If
498
.PN XtNoticeSignal
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
503
.PN False
504
and is set to
505
.PN True
506
by
507
.PN XtNoticeSignal .
508
When
509
.PN XtAppNextEvent
510
or
511
.PN XtAppProcessEvent
512
(with a mask including
513
.PN XtIMSignal )
514
is called, all registered callbacks with ``pending''
515
.PN True
516
are invoked and the flags are reset to
517
.PN False .
518
.LP
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
527
.PN False
528
but before the callback can get control, in which case the pending flag
529
will still be
530
.PN True
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.
534
.LP
535
To remove a registered signal callback, call
536
.PN XtRemoveSignal .
537
.LP
538
.IN "XtRemoveSignal" "" "@DEF@"
539
.sM
540
.FD 0
541
void XtRemoveSignal(\fIid\fP)
542
.br
543
XtSignalId \fIid\fP;
544
.FN
545
.IP \fIid\fP 1i
546
Specifies the id returned by the corresponding call to
547
.PN XtAppAddSignal .
548
.LP
549
.eM
550
The client should typically disable the source of the signal before calling
551
.PN XtRemoveSignal .
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
554
before calling
555
.PN XtRemoveSignal
556
the client can test for signals with
557
.PN XtAppPending
558
and process them by calling
559
.PN XtAppProcessEvent
560
with the mask
561
.PN XtIMSignal .
562
563
.NH 2
564
Constraining Events to a Cascade of Widgets
565
.XS
566
\fB\*(SN Constraining Events to a Cascade of Widgets\fP
567
.XE
568
.LP
569
.IN "Grabbing Input"
570
.IN "Input Grabbing"
571
Modal widgets are widgets that, except for the input directed to them,
572
lock out user input to the application.
573
.LP
574
When a modal menu or modal dialog box is popped up using
575
.PN XtPopup ,
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
579
the modal widget.
580
.LP
581
Menus can pop up submenus, and dialog boxes can pop up further dialog
582
boxes to create a pop-up cascade.
583
In this case,
584
user events may be delivered to one of several modal widgets in the cascade.
585
.LP
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
591
and are
592
.PN KeyPress ,
593
.PN KeyRelease ,
594
.PN ButtonPress ,
595
and
596
.PN ButtonRelease .
597
The user events ignored when they occur outside the cascade are
598
.PN MotionNotify
599
and
600
.PN EnterNotify .
601
All other events are delivered normally.
602
In particular, note that this is one
603
way in which widgets can receive
604
.PN LeaveNotify
605
events without first receiving
606
.PN EnterNotify
607
events; they should be prepared to deal with
608
this, typically by ignoring any unmatched
609
.PN LeaveNotify
610
events.
611
.LP
612
.PN XtPopup
613
uses the
614
.PN XtAddGrab
615
and
616
.PN XtRemoveGrab
617
functions to constrain user events to a modal cascade
618
and subsequently to remove a grab when the modal widget is popped down.
619
620
.sp
621
.LP
622
To constrain or redirect user input to a modal widget, use
623
.PN XtAddGrab .
624
.LP
625
.IN "XtAddGrab" "" "@DEF@"
626
.sM
627
.FD 0
628
void XtAddGrab(\fIw\fP, \fIexclusive\fP, \fIspring_loaded\fP)
629
.br
630
Widget \fIw\fP;
631
.br
632
Boolean \fIexclusive\fP;
633
.br
634
Boolean \fIspring_loaded\fP;
635
.FN
636
.IP \fIw\fP 1i
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
643
a pointer button.
644
.LP
645
.eM
646
The
647
.PN XtAddGrab
648
function appends the widget to the modal cascade
649
and checks that \fIexclusive\fP is
650
.PN True
651
if \fIspring_loaded\fP is
652
.PN True .
653
If this condition is not met,
654
.PN XtAddGrab
655
generates a warning message.
656
.LP
657
The modal cascade is used by
658
.PN XtDispatchEvent
659
when it tries to dispatch a user event.
660
When at least one modal widget is in the widget cascade,
661
.PN XtDispatchEvent
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
665
.PN True .
666
.LP
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
670
or remapped.
671
Modal menus with submenus generally add a submenu widget to the cascade
672
with \fIexclusive\fP
673
.PN False .
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
676
.PN True .
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
679
widget.
680
.LP
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
684
.PN True ,
685
if any such widget exists.
686
If the event
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.
692
.sp
693
.LP
694
To remove the redirection of user input to a modal widget, use
695
.PN XtRemoveGrab .
696
.LP
697
.IN "XtRemoveGrab" "" "@DEF@"
698
.sM
699
.FD 0
700
void XtRemoveGrab(\fIw\fP)
701
.br
702
Widget \fIw\fP;
703
.FN
704
.IP \fIw\fP 1i
705
Specifies the widget to remove from the modal cascade.
706
.LP
707
.eM
708
The
709
.PN XtRemoveGrab
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.
713
714
.NH 3
715
Requesting Key and Button Grabs
716
.XS
717
\fB\*(SN Requesting Key and Button Grabs\fP
718
.XE
719
.LP
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
726
routines.
727
.sp
728
.LP
729
To passively grab a single key of the keyboard, use
730
.PN XtGrabKey .
731
.LP
732
.IN "XtGrabKey" "" "@DEF@"
733
.sM
734
.FD 0
735
void XtGrabKey(\fIwidget\fP, \fIkeycode\fP, \fImodifiers\fP, \
736
\fIowner_events\fP, \fIpointer_mode\fP, \fIkeyboard_mode\fP)
737
.br
738
Widget \fIwidget\fP;
739
.br
740
KeyCode \fIkeycode\fP;
741
.br
742
Modifiers \fImodifiers\fP;
743
.br
744
Boolean \fIowner_events\fP;
745
.br
746
int \fIpointer_mode\fP, \fIkeyboard_mode\fP;
747
.FN
748
.IP \fIwidget\fP 1i
749
Specifies the widget in whose window the key is to be grabbed. \*(cI
750
.sp 6p
751
.IP \fIkeycode\fP
752
.br
753
.ns
754
.IP \fImodifiers\fP
755
.br
756
.ns
757
.IP \fIowner_events\fP
758
.br
759
.ns
760
.IP \fIpointer_mode\fP
761
.br
762
.ns
763
.IP \fIkeyboard_mode\fP 1i
764
Specify arguments to
765
.PN XGrabKey ;
766
see Section 12.2 in \fI\*(xL\fP.
767
.LP
768
.eM
769
.PN XtGrabKey
770
calls
771
.PN XGrabKey
772
specifying the widget's window as the grab
773
window if the widget is realized. The remaining arguments are exactly
774
as for
775
.PN XGrabKey .
776
If the widget is not realized, or is later unrealized, the call to
777
.PN XGrabKey
778
is performed (again) when
779
the widget is realized and its window becomes mapped. In the future,
780
if
781
.PN XtDispatchEvent
782
is called with a
783
.PN KeyPress
784
event matching the specified keycode and modifiers (which may be
785
.PN AnyKey
786
or
787
.PN AnyModifier ,
788
respectively) for the
789
widget's window, the \*(xI will call
790
.PN XtUngrabKeyboard
791
with the timestamp from the
792
.PN KeyPress
793
event if either of the following conditions is true:
794
.IP \(bu 3
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
797
grabbed, or
798
.IP \(bu 3
799
.PN XFilterEvent
800
returns
801
.PN True .
802
803
.sp
804
.LP
805
To cancel a passive key grab, use
806
.PN XtUngrabKey .
807
.LP
808
.IN "XtUngrabKey" "" "@DEF@"
809
.sM
810
.FD 0
811
void XtUngrabKey(\fIwidget\fP, \fIkeycode\fP\fI, modifiers\fP)
812
.br
813
Widget \fIwidget\fP;
814
.br
815
KeyCode \fIkeycode\fP;
816
.br
817
Modifiers \fImodifiers\fP;
818
.FN
819
.IP \fIwidget\fP 1i
820
Specifies the widget in whose window the key was grabbed.
821
.sp 6p
822
.IP \fIkeycode\fP
823
.br
824
.ns
825
.IP \fImodifiers\fP 1i
826
Specify arguments to
827
.PN XUngrabKey ;
828
see Section 12.2 in \fI\*(xL\fP.
829
.LP
830
.eM
831
The
832
.PN XtUngrabKey
833
procedure calls
834
.PN XUngrabKey
835
specifying the widget's
836
window as the ungrab window if the widget is realized. The remaining
837
arguments are exactly as for
838
.PN XUngrabKey .
839
If the widget is not realized,
840
.PN XtUngrabKey
841
removes a deferred
842
.PN XtGrabKey
843
request, if any, for the specified widget, keycode, and modifiers.
844
.sp
845
.LP
846
To actively grab the keyboard, use
847
.PN XtGrabKeyboard .
848
.LP
849
.IN "XtGrabKeyboard" "" "@DEF@"
850
.sM
851
.FD 0
852
int XtGrabKeyboard(\fIwidget\fP, \fIowner_events\fP, \fIpointer_mode\fP, \
853
\fIkeyboard_mode\fP, \fItime\fP)
854
.br
855
Widget \fIwidget\fP;
856
.br
857
Boolean \fIowner_events\fP;
858
.br
859
int \fIpointer_mode\fP, \fIkeyboard_mode\fP;
860
.br
861
Time \fItime\fP;
862
.br
863
.FN
864
.IP \fIwidget\fP 1i
865
Specifies the widget for whose window the keyboard is to be grabbed.
866
\*(cI
867
.sp 6p
868
.IP \fIowner_events\fP
869
.br
870
.ns
871
.IP \fIpointer_mode\fP
872
.br
873
.ns
874
.IP \fIkeyboard_mode\fP
875
.br
876
.ns
877
.IP \fItime\fP 1i
878
Specify arguments to
879
.PN XGrabKeyboard ;
880
see Section 12.2 in \fI\*(xL\fP.
881
.LP
882
.eM
883
If the specified widget is realized,
884
.PN XtGrabKeyboard
885
calls
886
.PN XGrabKeyboard
887
specifying the widget's window as the grab window. The remaining
888
arguments and return value are exactly as for
889
.PN XGrabKeyboard .
890
If the widget is not realized,
891
.PN XtGrabKeyboard
892
immediately returns
893
.PN GrabNotViewable .
894
No future automatic ungrab is implied by
895
.PN XtGrabKeyboard .
896
.sp
897
.LP
898
To cancel an active keyboard grab, use
899
.PN XtUngrabKeyboard .
900
.LP
901
.IN "XtUngrabKeyboard" "" "@DEF@"
902
.sM
903
.FD 0
904
void XtUngrabKeyboard(\fIwidget\fP, \fItime\fP)
905
.br
906
Widget \fIwidget\fP;
907
.br
908
Time \fItime\fP;
909
.FN
910
.IP \fIwidget\fP 1i
911
Specifies the widget that has the active keyboard grab.
912
.IP \fItime\fP 1i
913
Specifies the additional argument to
914
.PN XUngrabKeyboard ;
915
see Section 12.2 in \fI\*(xL\fP.
916
.LP
917
.eM
918
.PN XtUngrabKeyboard
919
calls
920
.PN XUngrabKeyboard
921
with the specified time.
922
.sp
923
.LP
924
To passively grab a single pointer button, use
925
.PN XtGrabButton .
926
.LP
927
.IN "XtGrabButton" "" "@DEF@"
928
.sM
929
.FD 0
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)
933
.br
934
Widget \fIwidget\fP;
935
.br
936
int \fIbutton\fP;
937
.br
938
Modifiers \fImodifiers\fP;
939
.br
940
Boolean \fIowner_events\fP;
941
.br
942
unsigned int \fIevent_mask\fP;
943
.br
944
int \fIpointer_mode\fP, \fIkeyboard_mode\fP;
945
.br
946
Window \fIconfine_to\fP;
947
.br
948
Cursor \fIcursor\fP;
949
.FN
950
.IP \fIwidget\fP 1i
951
Specifies the widget in whose window the button is to be grabbed. \*(cI
952
.sp 6p
953
.IP \fIbutton\fP
954
.br
955
.ns
956
.IP \fImodifiers\fP
957
.br
958
.ns
959
.IP \fIowner_events\fP
960
.br
961
.ns
962
.IP \fIevent_mask\fP
963
.br
964
.ns
965
.IP \fIpointer_mode\fP
966
.br
967
.ns
968
.IP \fIkeyboard_mode\fP
969
.br
970
.ns
971
.IP \fIconfine_to\fP
972
.br
973
.ns
974
.IP \fIcursor\fP 1i
975
Specify arguments to
976
.PN XGrabButton ;
977
see Section 12.1 in \fI\*(xL\fP.
978
.LP
979
.eM
980
.PN XtGrabButton
981
calls
982
.PN XGrabButton
983
specifying the widget's window as the
984
grab window if the widget is realized. The remaining arguments are
985
exactly as for
986
.PN XGrabButton .
987
If the widget is not realized, or is later unrealized, the call to
988
.PN XGrabButton
989
is performed (again)
990
when the widget is realized and its window becomes mapped. In the
991
future, if
992
.PN XtDispatchEvent
993
is called with a
994
.PN ButtonPress
995
event matching the specified button and modifiers (which may be
996
.PN AnyButton
997
or
998
.PN AnyModifier ,
999
respectively)
1000
for the widget's window, the \*(xI will call
1001
.PN XtUngrabPointer
1002
with the timestamp from the
1003
.PN ButtonPress
1004
event if either of the following conditions is true:
1005
.IP \(bu 3
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
1009
.IP \(bu 3
1010
.PN XFilterEvent
1011
returns
1012
.PN True .
1013
1014
.sp
1015
.LP
1016
To cancel a passive button grab, use
1017
.PN XtUngrabButton .
1018
.LP
1019
.IN "XtUngrabButton" "" "@DEF@"
1020
.sM
1021
.FD 0
1022
void XtUngrabButton(\fIwidget\fP, \fIbutton\fP, \fImodifiers\fP)
1023
.br
1024
Widget \fIwidget\fP;
1025
.br
1026
unsigned int \fIbutton\fP;
1027
.br
1028
Modifiers \fImodifiers\fP;
1029
.FN
1030
.IP \fIwidget\fP 1i
1031
Specifies the widget in whose window the button was grabbed.
1032
.IP \fIbutton\fP
1033
.br
1034
.ns
1035
.IP \fImodifiers\fP 1i
1036
Specify arguments to
1037
.PN XUngrabButton ;
1038
see Section 12.1 in \fI\*(xL\fP.
1039
.LP
1040
.eM
1041
The
1042
.PN XtUngrabButton
1043
procedure calls
1044
.PN XUngrabButton
1045
specifying the
1046
widget's window as the ungrab window if the widget is realized. The
1047
remaining arguments are exactly as for
1048
.PN XUngrabButton .
1049
If the widget is not realized,
1050
.PN XtUngrabButton
1051
removes a deferred
1052
.PN XtGrabButton
1053
request, if any, for the specified widget, button, and modifiers.
1054
.sp
1055
.LP
1056
To actively grab the pointer, use
1057
.PN XtGrabPointer .
1058
.LP
1059
.IN "XtGrabPointer" "" "@DEF@"
1060
.sM
1061
.FD 0
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)
1065
.br
1066
Widget \fIwidget\fP;
1067
.br
1068
Boolean \fIowner_events\fP;
1069
.br
1070
unsigned int \fIevent_mask\fP;
1071
.br
1072
int \fIpointer_mode\fP, \fIkeyboard_mode\fP;
1073
.br
1074
Window \fIconfine_to\fP;
1075
.br
1076
Cursor \fIcursor\fP;
1077
.br
1078
Time \fItime\fP;
1079
.FN
1080
.IP \fIwidget\fP 1i
1081
Specifies the widget for whose window the pointer is to be grabbed. \*(cI
1082
.sp 6p
1083
.IP \fIowner_events\fP
1084
.br
1085
.ns
1086
.IP \fIevent_mask\fP
1087
.br
1088
.ns
1089
.IP \fIpointer_mode\fP
1090
.br
1091
.ns
1092
.IP \fIkeyboard_mode\fP
1093
.br
1094
.ns
1095
.IP \fIconfine_to\fP
1096
.br
1097
.ns
1098
.IP \fIcursor\fP
1099
.br
1100
.ns
1101
.IP \fItime\fP 1i
1102
Specify arguments to
1103
.PN XGrabPointer ;
1104
see Section 12.1 in \fI\*(xL\fP.
1105
.LP
1106
.eM
1107
If the specified widget is realized,
1108
.PN XtGrabPointer
1109
calls
1110
.PN XGrabPointer ,
1111
specifying the widget's window as the grab window. The remaining
1112
arguments and return value are exactly as for
1113
.PN XGrabPointer .
1114
If the widget is not realized,
1115
.PN XtGrabPointer
1116
immediately returns
1117
.PN GrabNotViewable .
1118
No future automatic ungrab is implied by
1119
.PN XtGrabPointer .
1120
.sp
1121
.LP
1122
To cancel an active pointer grab, use
1123
.PN XtUngrabPointer .
1124
.LP
1125
.IN "XtUngrabPointer" "" "@DEF@"
1126
.sM
1127
.FD 0
1128
void XtUngrabPointer(\fIwidget\fP, \fItime\fP)
1129
.br
1130
Widget \fIwidget\fP;
1131
.br
1132
Time \fItime\fP;
1133
.FN
1134
.IP \fIwidget\fP 1i
1135
Specifies the widget that has the active pointer grab.
1136
.IP \fItime\fP 1i
1137
Specifies the time argument to
1138
.PN XUngrabPointer ;
1139
see Section 12.1 in \fI\*(xL\fP.
1140
.LP
1141
.eM
1142
.PN XtUngrabPointer
1143
calls
1144
.PN XUngrabPointer
1145
with the specified time.
1146
1147
.NH 2
1148
Focusing Events on a Child
1149
.XS
1150
\fB\*(SN Focusing Events on a Child\fP
1151
.XE
1152
.LP
1153
To redirect keyboard input to a normal descendant of a
1154
widget without calling
1155
.PN XSetInputFocus ,
1156
use
1157
.PN XtSetKeyboardFocus .
1158
.LP
1159
.IN "XtSetKeyboardFocus" "" "@DEF@"
1160
.sM
1161
.FD 0
1162
void XtSetKeyboardFocus(\fIsubtree\fP\, \fIdescendant\fP)
1163
.br
1164
Widget \fIsubtree\fP, \fIdescendant\fP;
1165
.FN
1166
.IP \fIsubtree\fP 1i
1167
Specifies the subtree of the hierarchy for which the keyboard focus is
1168
to be set. \*(cI
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
1172
.PN None .
1173
It is not an error to specify
1174
.PN None
1175
when no input focus was previously set. \*(oI
1176
.LP
1177
.eM
1178
.PN XtSetKeyboardFocus
1179
causes
1180
.PN XtDispatchEvent
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.
1185
.LP
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).
1190
.IP \(bu 3
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
1193
to
1194
.PN XtGrabKey
1195
with any value of \fIowner_events\fP, or
1196
if the keyboard is actively grabbed by E with \fIowner_events\fP
1197
.PN False
1198
via
1199
.PN XtGrabKeyboard
1200
or
1201
.PN XtGrabKey
1202
on a previous key press, the event is dispatched to E.
1203
.IP \(bu 3
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.
1209
.RS
1210
.IP \- 3
1211
If E is the final focus target widget F or a descendant of F, the
1212
event is dispatched to E.
1213
.IP \- 3
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
1216
.PN XtGrabKey
1217
for E,
1218
.PN XtUngrabKeyboard
1219
is called.
1220
.IP \- 3
1221
If E is an ancestor of F, and the event is a key press, and either
1222
.RS
1223
.IP + 3
1224
E has grabbed the key with
1225
.PN XtGrabKey
1226
and \fIowner_events\fP
1227
.PN False ,
1228
or
1229
.IP + 3
1230
E has grabbed the key with
1231
.PN XtGrabKey
1232
and \fIowner_events\fP
1233
.PN True ,
1234
and the coordinates of the event are outside the rectangle specified
1235
by E's geometry,
1236
.RE
1237
then the event is dispatched to E.
1238
.IP \- 3
1239
Otherwise, define A as the closest common ancestor of E and F:
1240
.RS
1241
.IP + 3
1242
If there is an active keyboard grab for any widget via either
1243
.PN XtGrabKeyboard
1244
or
1245
.PN XtGrabKey
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
1249
.PN XtGrabKey
1250
and any value of \fIowner_events\fP, the event is dispatched to F.
1251
.IP + 3
1252
Else, the event is dispatched to the ancestor of F closest to A
1253
that has grabbed the key and modifier combination with
1254
.PN XtGrabKey .
1255
.RE
1256
.RE
1257
.LP
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
1261
or discarded.
1262
Regardless of where it is dispatched, the \*(xI do not modify
1263
the contents of the event.
1264
.LP
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
1268
.PN FocusIn
1269
event is generated for the descendant if
1270
.PN FocusChange
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
1274
.PN FocusOut
1275
event is generated for descendant if
1276
.PN FocusChange
1277
events have been selected by the descendant.
1278
.sp
1279
.LP
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.
1282
.LP
1283
.IN "accept_focus procedure"
1284
The accept_focus procedure pointer is of type
1285
.PN XtAcceptFocusProc .
1286
.LP
1287
.IN "XtAcceptFocusProc" "" "@DEF@"
1288
.sM
1289
.FD 0
1290
typedef Boolean (*XtAcceptFocusProc)(Widget, Time*);
1291
.br
1292
Widget \fIw\fP;
1293
.br
1294
Time *\fItime\fP;
1295
.FN
1296
.IP \fIw\fP 1i
1297
Specifies the widget.
1298
.IP \fItime\fP 1i
1299
Specifies the X time of the event causing the accept focus.
1300
.LP
1301
.eM
1302
Widgets that need the input focus can call
1303
.PN XSetInputFocus
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
1314
.PN FocusIn
1315
and
1316
.PN FocusOut
1317
events).
1318
Widgets classes that never want the input focus should set the
1319
\fIaccept_focus\fP field to NULL.
1320
.sp
1321
.LP
1322
To call a widget's accept_focus procedure, use
1323
.PN XtCallAcceptFocus .
1324
.LP
1325
.IN "XtCallAcceptFocus" "" "@DEF@"
1326
.sM
1327
.FD 0
1328
Boolean XtCallAcceptFocus(\fIw\fP, \fItime\fP)
1329
.br
1330
Widget \fIw\fP;
1331
.br
1332
Time *\fItime\fP;
1333
.FN
1334
.IP \fIw\fP 1i
1335
Specifies the widget. \*(cI
1336
.IP \fItime\fP 1i
1337
Specifies the X time of the event that is causing the focus change.
1338
.LP
1339
.eM
1340
The
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
1344
procedure returns.
1345
If \fIaccept_focus\fP is NULL,
1346
.PN XtCallAcceptFocus
1347
returns
1348
.PN False .
1349
1350
.NH 3
1351
Events for Drawables That Are Not a Widget's Window
1352
.XS
1353
\fB\*(SN Events for Drawables That Are Not a Widget's Window\fP
1354
.XE
1355
.LP
1356
Sometimes an application must handle events for drawables that are not
1357
associated with widgets in its widget tree. Examples include handling
1358
.PN GraphicsExpose
1359
and
1360
.PN NoExpose
1361
events on Pixmaps, and handling
1362
.PN PropertyNotify
1363
events on the root window.
1364
.LP
1365
To register a drawable with the \*(xI event dispatching, use
1366
.PN XtRegisterDrawable .
1367
.LP
1368
.IN "XtRegisterDrawable" "" "@DEF@"
1369
.sM
1370
.FD 0
1371
void XtRegisterDrawable(\fIdisplay\fP, \fIdrawable\fP, \fIwidget\fP)
1372
.br
1373
Display *\fIdisplay\fP;
1374
.br
1375
Drawable \fIdrawable\fP;
1376
.br
1377
Widget \fIwidget\fP;
1378
.FN
1379
.IP \fIdisplay\fP 1i
1380
Specifies the drawable's display.
1381
.IP \fIdrawable\fP 1i
1382
Specifies the drawable to register.
1383
.IP \fIwidget\fP 1i
1384
Specifies the widget to register the drawable for.
1385
.LP
1386
.eM
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.
1395
.LP
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
1398
results of calling
1399
.PN XtRegisterDrawable
1400
are undefined.
1401
1402
.LP
1403
To unregister a drawable with the Intrinsics event dispatching, use
1404
.PN XtUnregisterDrawable .
1405
.LP
1406
.IN "XtUnregisterDrawable" "" "@DEF@"
1407
.sM
1408
.FD 0
1409
void XtUnregisterDrawable(\fIdisplay\fP, \fIdrawable\fP)
1410
.br
1411
Display *\fIdisplay\fP;
1412
.br
1413
Drawable \fIdrawable\fP;
1414
.FN
1415
.IP \fIdisplay\fP 1i
1416
Specifies the drawable's display.
1417
.IP \fIdrawable\fP 1i
1418
Specifies the drawable to unregister.
1419
.LP
1420
.eM
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
1427
are undefined.
1428
1429
.NH 2
1430
Querying Event Sources
1431
.XS
1432
\fB\*(SN Querying Event Sources\fP
1433
.XE
1434
.LP
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
1438
.PN XPending ,
1439
.PN XPeekEvent ,
1440
and
1441
.PN XNextEvent
1442
Xlib calls.
1443
.sp
1444
.LP
1445
.IN "Events"
1446
To determine if there are any events on the input queue for a given application,
1447
use
1448
.PN XtAppPending .
1449
.LP
1450
.IN "XtAppPending" "" "@DEF@"
1451
.sM
1452
.FD 0
1453
XtInputMask XtAppPending(\fIapp_context\fP)
1454
.br
1455
XtAppContext \fIapp_context\fP;
1456
.FN
1457
.IP \fIapp_context\fP 1i
1458
Specifies the application context that identifies the application to check.
1459
.LP
1460
.eM
1461
The
1462
.PN XtAppPending
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
1467
.PN XtIMXEvent ,
1468
.PN XtIMTimer ,
1469
.PN XtIMAlternateInput ,
1470
and
1471
.PN XtIMSignal
1472
(see
1473
.PN XtAppProcessEvent ).
1474
If there are no events pending,
1475
.PN XtAppPending
1476
flushes the output buffers of each Display in the application context
1477
and returns zero.
1478
.sp
1479
.LP
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 .
1483
.LP
1484
.IN "XtAppPeekEvent" "" "@DEF@"
1485
.sM
1486
.FD 0
1487
Boolean XtAppPeekEvent(\fIapp_context\fP, \fIevent_return\fP)
1488
.br
1489
XtAppContext \fIapp_context\fP;
1490
.br
1491
XEvent *\fIevent_return\fP;
1492
.FN
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.
1497
.LP
1498
.eM
1499
If there is an X event in the queue,
1500
.PN XtAppPeekEvent
1501
copies it into \fIevent_return\fP and returns
1502
.PN True .
1503
If no X input is on the queue,
1504
.PN XtAppPeekEvent
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,
1509
.PN XtAppPeekEvent
1510
fills in \fIevent_return\fP and returns
1511
.PN True .
1512
Otherwise, the input is for an input source
1513
registered with
1514
.PN XtAppAddInput ,
1515
and
1516
.PN XtAppPeekEvent
1517
returns
1518
.PN False .
1519
.FS
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
1522
available,
1523
.PN XtAppPeekEvent
1524
will return
1525
.PN True
1526
without returning an event.
1527
.FE
1528
.sp
1529
.LP
1530
To remove and return the event
1531
from the head of a given application's X event queue,
1532
use
1533
.PN XtAppNextEvent .
1534
.LP
1535
.IN "XtAppNextEvent" "" "@DEF@"
1536
.sM
1537
.FD 0
1538
void XtAppNextEvent(\fIapp_context\fP, \fIevent_return\fP)
1539
.br
1540
XtAppContext \fIapp_context\fP;
1541
.br
1542
XEvent *\fIevent_return\fP;
1543
.FN
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.
1548
.LP
1549
.eM
1550
If the X event queue is empty,
1551
.PN XtAppNextEvent
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;
1556
see Section 7.8.
1557
1558
.NH 2
1559
Dispatching Events
1560
.XS
1561
\fB\*(SN Dispatching Events\fP
1562
.XE
1563
.LP
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.
1573
.sp
1574
.LP
1575
Applications that need direct control of the processing of different types
1576
of input should use
1577
.PN XtAppProcessEvent .
1578
.LP
1579
.IN "XtAppProcessEvent" "" "@DEF@"
1580
.sM
1581
.FD 0
1582
void XtAppProcessEvent(\fIapp_context\fP, \fImask\fP)
1583
.br
1584
XtAppContext \fIapp_context\fP;
1585
.br
1586
XtInputMask \fImask\fP;
1587
.FN
1588
.IP \fIapp_context\fP 1i
1589
Specifies the application context that identifies the
1590
application for which to process input.
1591
.IP \fImask\fP 1i
1592
Specifies what types of events to process.
1593
The mask is the bitwise inclusive OR of any combination of
1594
.PN XtIMXEvent ,
1595
.PN XtIMTimer ,
1596
.PN XtIMAlternateInput ,
1597
and
1598
.PN XtIMSignal .
1599
As a convenience,
1600
.PN Intrinsic.h
1601
defines the symbolic name
1602
.PN XtIMAll
1603
to be the bitwise inclusive OR of these four event types.
1604
.LP
1605
.eM
1606
The
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
1615
.PN XtAppMainLoop .
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,
1620
and X events by
1621
calling
1622
.PN XtDispatchEvent .
1623
.LP
1624
When an X event is received,
1625
it is passed to
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.
1632
1633
.sp
1634
.LP
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 .
1640
.LP
1641
.IN "XtDispatchEvent" "" "@DEF@"
1642
.sM
1643
.FD 0
1644
Boolean XtDispatchEvent(\fIevent\fP)
1645
.br
1646
XEvent *\fIevent\fP;
1647
.FN
1648
.IP \fIevent\fP 1i
1649
Specifies a pointer to the event structure to be dispatched
1650
to the appropriate event handlers.
1651
.LP
1652
.eM
1653
The
1654
.PN XtDispatchEvent
1655
function first calls
1656
.PN XFilterEvent
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.
1660
If
1661
.PN XFilterEvent
1662
returns
1663
.PN True
1664
and the event activated a server grab as identified
1665
by a previous call to
1666
.PN XtGrabKey
1667
or
1668
.PN XtGrabButton ,
1669
.PN XtDispatchEvent
1670
calls
1671
.PN XtUngrabKeyboard
1672
or
1673
.PN XtUngrabPointer
1674
with the timestamp from the event and immediately returns
1675
.PN True .
1676
If
1677
.PN XFilterEvent
1678
returns
1679
.PN True
1680
and a grab was not activated,
1681
.PN XtDispatchEvent
1682
just immediately returns
1683
.PN True .
1684
Otherwise,
1685
.PN XtDispatchEvent
1686
sends the event to the event handler functions that
1687
have been previously registered with the dispatch routine.
1688
.PN XtDispatchEvent
1689
returns
1690
.PN True
1691
if
1692
.PN XFilterEvent
1693
returned
1694
.PN True ,
1695
or if the event was dispatched to some handler, and
1696
.PN False
1697
if it found no handler to which to dispatch the event.
1698
.PN XtDispatchEvent
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
1704
.PN True ,
1705
and if the event is a remap event as defined by
1706
.PN XtAddGrab ,
1707
.PN XtDispatchEvent
1708
may dispatch the event a second time. If it does so,
1709
.PN XtDispatchEvent
1710
will call
1711
.PN XFilterEvent
1712
again with the window of the spring-loaded widget prior to the second
1713
dispatch, and if
1714
.PN XFilterEvent
1715
returns
1716
.PN True ,
1717
the second dispatch will not be performed.
1718
1719
.NH 2
1720
The Application Input Loop
1721
.XS
1722
\fB\*(SN The Application Input Loop\fP
1723
.XE
1724
.LP
1725
To process all input from a given application in a continuous loop,
1726
use the convenience procedure
1727
.PN XtAppMainLoop .
1728
.LP
1729
.IN "XtAppMainLoop" "" "@DEF@"
1730
.sM
1731
.FD 0
1732
void XtAppMainLoop(\fIapp_context\fP)
1733
.br
1734
XtAppContext \fIapp_context\fP;
1735
.FN
1736
.IP \fIapp_context\fP 1i
1737
Specifies the application context that identifies the application.
1738
.LP
1739
.eM
1740
The
1741
.PN XtAppMainLoop
1742
function first reads the next incoming X event by calling
1743
.PN XtAppNextEvent
1744
and then dispatches the event to the appropriate registered procedure
1745
by calling
1746
.PN XtDispatchEvent .
1747
This constitutes the main loop of \*(tk applications.
1748
There is nothing special about
1749
.PN XtAppMainLoop ;
1750
it simply calls
1751
.PN XtAppNextEvent
1752
and then
1753
.PN XtDispatchEvent
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
1759
.PN XtAppLock
1760
and
1761
.PN XtAppUnlock .
1762
.LP
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 .
1767
1768
.NH 2
1769
Setting and Checking the Sensitivity State of a Widget
1770
.XS
1771
\fB\*(SN Setting and Checking the Sensitivity State of a Widget\fP
1772
.XE
1773
.LP
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,
1776
and become dormant.
1777
.LP
1778
When dormant,
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
1783
.PN KeyPress ,
1784
.PN KeyRelease ,
1785
.PN ButtonPress ,
1786
.PN ButtonRelease ,
1787
.PN MotionNotify ,
1788
.PN EnterNotify ,
1789
.PN LeaveNotify ,
1790
.PN FocusIn ,
1791
or
1792
.PN FocusOut .
1793
.LP
1794
A widget can be insensitive because its \fIsensitive\fP field is
1795
.PN False
1796
or because one of its ancestors is insensitive and thus the widget's
1797
\fIancestor_sensitive\fP field also is
1798
.PN False .
1799
A widget can but does not need to distinguish these two cases visually.
1800
.NT
1801
Pop-up shells will have
1802
\fIancestor_sensitive\fP
1803
.PN False
1804
if the parent was insensitive when the shell
1805
was created. Since
1806
.PN XtSetSensitive
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.
1814
.NE
1815
.sp
1816
.LP
1817
To set the sensitivity state of a widget, use
1818
.PN XtSetSensitive .
1819
.LP
1820
.IN "XtSetSensitive" "" "@DEF@"
1821
.sM
1822
.FD 0
1823
void XtSetSensitive(\fIw\fP, \fIsensitive\fP)
1824
.br
1825
Widget \fIw\fP;
1826
.br
1827
Boolean \fIsensitive\fP;
1828
.FN
1829
.IP \fIw\fP 1i
1830
Specifies the widget. \*(rI
1831
.IP \fIsensitive\fP 1i
1832
Specifies whether the widget should receive
1833
keyboard, pointer, and focus events.
1834
.LP
1835
.eM
1836
The
1837
.PN XtSetSensitive
1838
function first calls
1839
.PN XtSetValues
1840
on the current widget with an argument list specifying the
1841
XtNsensitive resource and the new value.
1842
If \fIsensitive\fP is
1843
.PN False
1844
and the widget's class is a subclass of
1845
Composite,
1846
.PN XtSetSensitive
1847
recursively propagates the new value
1848
down the child tree by calling
1849
.PN XtSetValues
1850
on each child to set \fIancestor_sensitive\fP to
1851
.PN False .
1852
If \fIsensitive\fP is
1853
.PN True
1854
and the widget's class is a subclass of
1855
Composite
1856
and the widget's \fIancestor_sensitive\fP field is
1857
.PN True ,
1858
.PN XtSetSensitive
1859
sets the \fIancestor_sensitive\fP of each child to
1860
.PN True
1861
and then recursively calls
1862
.PN XtSetValues
1863
on each normal descendant that is now sensitive to set
1864
\fIancestor_sensitive\fP to
1865
.PN True .
1866
.LP
1867
.PN XtSetSensitive
1868
calls
1869
.PN XtSetValues
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).
1876
.LP
1877
.PN XtSetSensitive
1878
maintains the invariant that, if the parent has either \fIsensitive\fP
1879
or \fIancestor_sensitive\fP
1880
.PN False ,
1881
then all children have \fIancestor_sensitive\fP
1882
.PN False .
1883
.sp
1884
.LP
1885
To check the current sensitivity state of a widget,
1886
use
1887
.PN XtIsSensitive .
1888
.LP
1889
.IN "XtIsSensitive" "" "@DEF@"
1890
.sM
1891
.FD 0
1892
Boolean XtIsSensitive(\fIw\fP)
1893
.br
1894
Widget \fIw\fP;
1895
.FN
1896
.IP \fIw\fP 1i
1897
Specifies the object. \*(oI
1898
.LP
1899
.eM
1900
The
1901
.PN XtIsSensitive
1902
function returns
1903
.PN True
1904
or
1905
.PN False
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
1909
.PN True ,
1910
.PN XtIsSensitive
1911
returns
1912
.PN True ;
1913
otherwise, it returns
1914
.PN False .
1915
1916
.NH 2
1917
Adding Background Work Procedures
1918
.XS
1919
\fB\*(SN Adding Background Work Procedures\fP
1920
.XE
1921
.LP
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
1926
.PN XtAppNextEvent
1927
or
1928
.PN XtAppProcessEvent .
1929
Work procedure pointers are of type
1930
.PN XtWorkProc .
1931
.LP
1932
.IN "XtWorkProc" "" "@DEF@"
1933
.sM
1934
.FD 0
1935
typedef Boolean (*XtWorkProc)(XtPointer);
1936
.br
1937
XtPointer \fIclient_data\fP;
1938
.FN
1939
.IP \fIclient_data\fP 1i
1940
Passes the client data specified when the work procedure was registered.
1941
.LP
1942
.eM
1943
This procedure should return
1944
.PN True
1945
when it is done to indicate that it
1946
should be removed.
1947
If the procedure returns
1948
.PN False ,
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.
1954
.sp
1955
.LP
1956
To register a work procedure for a given application, use
1957
.PN XtAppAddWorkProc .
1958
.LP
1959
.IN "XtAppAddWorkProc" "" "@DEF@"
1960
.sM
1961
.FD 0
1962
XtWorkProcId XtAppAddWorkProc(\fIapp_context\fP, \fIproc\fP, \fIclient_data\fP)
1963
.br
1964
XtAppContext \fIapp_context\fP;
1965
.br
1966
XtWorkProc \fIproc\fP;
1967
.br
1968
XtPointer \fIclient_data\fP;
1969
.FN
1970
.IP \fIapp_context\fP 1i
1971
Specifies the application context that identifies the application.
1972
.IP \fIproc\fP 1i
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
1976
when it is called.
1977
.LP
1978
.eM
1979
The
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.
1988
.sp
1989
.LP
1990
To remove a work procedure, either return
1991
.PN True
1992
from the procedure when it is called or use
1993
.PN XtRemoveWorkProc
1994
outside of the procedure.
1995
.LP
1996
.IN "XtRemoveWorkProc" "" "@DEF@"
1997
.sM
1998
.FD 0
1999
void XtRemoveWorkProc(\fIid\fP)
2000
.br
2001
XtWorkProcId \fIid\fP;
2002
.FN
2003
.IP \fIid\fP 1i
2004
Specifies which work procedure to remove.
2005
.LP
2006
.eM
2007
The
2008
.PN XtRemoveWorkProc
2009
function explicitly removes the specified background work procedure.
2010
2011
.NH 2
2012
X Event Filters
2013
.XS
2014
\*(SN X Event Filters
2015
.XE
2016
.LP
2017
The event manager provides filters that can be applied to
2018
specific X events.
2019
The filters, which screen out events that are redundant or are temporarily
2020
unwanted, handle
2021
pointer motion compression,
2022
enter/leave compression, and
2023
exposure compression.
2024
2025
.NH 3
2026
Pointer Motion Compression
2027
.XS
2028
\*(SN Pointer Motion Compression
2029
.XE
2030
.LP
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
2035
.PN True .
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.
2041
2042
.NH 3
2043
Enter/Leave Compression
2044
.XS
2045
\*(SN Enter/Leave Compression
2046
.XE
2047
.LP
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
2052
.PN True .
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.
2056
2057
.NH 3
2058
Exposure Compression
2059
.XS
2060
\*(SN Exposure Compression
2061
.XE
2062
.LP
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
2070
rectangle.
2071
.LP
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:
2077
.sp
2078
.sM
2079
.Ds 0
2080
.TA 3i
2081
.ta 3i
2082
#define XtExposeNoCompress ((XtEnum)False)
2083
#define XtExposeCompressSeries ((XtEnum)True)
2084
#define XtExposeCompressMultiple <implementation-defined>
2085
#define XtExposeCompressMaximal <implementation-defined>
2086
.De
2087
.LP
2088
.eM
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 ,
2094
and
2095
.PN XtExposeNoRegion .
2096
2097
.LP
2098
If the \fIcompress_exposure\fP field in the widget class structure does not
2099
specify
2100
.PN XtExposeNoCompress ,
2101
the event manager calls the widget's expose procedure only
2102
once for a series of exposure events.
2103
In this case, all
2104
.PN Expose
2105
or
2106
.PN GraphicsExpose
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.)
2116
.LP
2117
The values have the following interpretation:
2118
.sp
2119
.LP
2120
.PN XtExposeNoCompress
2121
.IN "XtExposeNoCompress" "" "@DEF@"
2122
.IP
2123
No exposure compression is performed; every selected event is
2124
individually dispatched to the expose procedure with a \fIregion\fP
2125
argument of NULL.
2126
.sp
2127
.LP
2128
.PN XtExposeCompressSeries
2129
.IN "XtExposeCompressSeries" "" "@DEF@"
2130
.IP
2131
Each series of exposure events is coalesced into a single event,
2132
which is dispatched
2133
when an exposure event with count equal to zero is reached.
2134
.sp
2135
.LP
2136
.PN XtExposeCompressMultiple
2137
.IN "XtExposeCompressMultiple" "" "@DEF@"
2138
.IP
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.
2144
.sp
2145
.LP
2146
.PN XtExposeCompressMaximal
2147
.IN "XtExposeCompressMaximal" "" "@DEF"
2148
.IP
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.
2154
.sp
2155
.LP
2156
The additional flags have the following meaning:
2157
.sp
2158
.LP
2159
.PN XtExposeGraphicsExpose
2160
.IN "XtExposeGraphicsExpose" "" "@DEF@"
2161
.IP
2162
Specifies that
2163
.PN GraphicsExpose
2164
events are also to be dispatched to
2165
the expose procedure.
2166
.PN GraphicsExpose
2167
events are compressed, if specified, in the same manner as
2168
.PN Expose
2169
events.
2170
.sp
2171
.LP
2172
.PN XtExposeGraphicsExposeMerged
2173
.IN "XtExposeGraphicsExposeMerged" "" "@DEF@"
2174
.IP
2175
Specifies in the case of
2176
.PN XtExposeCompressMultiple
2177
and
2178
.PN XtExposeCompressMaximal
2179
that series of
2180
.PN GraphicsExpose
2181
and
2182
.PN Expose
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
2187
also implies
2188
.PN XtExposeGraphicsExpose .
2189
.sp
2190
.LP
2191
.PN XtExposeNoExpose
2192
.IN "XtExposeNoExpose" "" "@DEF@"
2193
.IP
2194
Specifies that
2195
.PN NoExpose
2196
events are also to be dispatched to the expose procedure.
2197
.PN NoExpose
2198
events are never coalesced with
2199
other exposure events or with each other.
2200
.sp
2201
.LP
2202
.PN XtExposeNoRegion
2203
.IN "XtExposeNoRegion" "" "@DEF"
2204
.IP
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.
2210
2211
.NH 2
2212
Widget Exposure and Visibility
2213
.XS
2214
\*(SN Widget Exposure and Visibility
2215
.XE
2216
.LP
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.
2222
2223
.NH 3
2224
Redisplay of a Widget: The expose Procedure
2225
.XS
2226
\*(SN Redisplay of a Widget: The expose Procedure
2227
.XE
2228
.IN "expose procedure"
2229
.LP
2230
The expose procedure pointer in a widget class is of type
2231
.PN XtExposeProc .
2232
.LP
2233
.IN "XtExposeProc" "" "@DEF@"
2234
.sM
2235
.FD 0
2236
typedef void (*XtExposeProc)(Widget, XEvent*, Region);
2237
.br
2238
Widget \fIw\fP;
2239
.br
2240
XEvent *\fIevent\fP;
2241
.br
2242
Region \fIregion\fP;
2243
.FN
2244
.IP \fIw\fP 1i
2245
Specifies the widget instance requiring redisplay.
2246
.IP \fIevent\fP 1i
2247
Specifies the exposure event giving the rectangle requiring redisplay.
2248
.IP \fIregion\fP 1i
2249
Specifies the union of all rectangles in this exposure sequence.
2250
.LP
2251
.eM
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.
2258
.NT
2259
If the \fIexpose\fP procedure is NULL,
2260
.PN XtRealizeWidget
2261
fills in a default bit gravity of
2262
.PN NorthWestGravity
2263
before it calls the widget's realize procedure.
2264
.NE
2265
.LP
2266
If the widget's \fIcompress_exposure\fP class field specifies
2267
.PN XtExposeNoCompress
2268
or
2269
.PN XtExposeNoRegion ,
2270
or if the event type is
2271
.PN NoExpose
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
2276
.PN NoExpose ,
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.
2282
.LP
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
2291
as well as its own.
2292
.LP
2293
However,
2294
it often is possible to anticipate the display needs of several levels
2295
of subclassing.
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
2299
fields like
2300
.LP
2301
.DS
2302
Boolean invert;
2303
Boolean highlight;
2304
Dimension highlight_width;
2305
.DE
2306
Label would have \fIinvert\fP and \fIhighlight\fP always
2307
.PN False
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
2311
.PN False .
2312
Finally, Toggle would dynamically set all three.
2313
In this case,
2314
the expose procedures for Pushbutton and Toggle inherit
2315
their superclass's expose procedure;
2316
see Section 1.6.10.
2317
2318
.NH 3
2319
Widget Visibility
2320
.XS
2321
\*(SN Widget Visibility
2322
.XE
2323
.LP
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
2328
or is iconified.
2329
.LP
2330
.IN "Visibility"
2331
The \fIvisible\fP field in the
2332
core
2333
widget structure provides a hint to the widget that it need not compute
2334
display data.
2335
This field is guaranteed to be
2336
.PN True
2337
by the time an
2338
exposure
2339
event is processed if any part of the widget is visible,
2340
but is
2341
.PN False
2342
if the widget is fully obscured.
2343
.LP
2344
Widgets can use or ignore the \fIvisible\fP hint.
2345
If they ignore it,
2346
they should have \fIvisible_interest\fP in their widget class record set
2347
.PN False .
2348
In such cases,
2349
the \fIvisible\fP field is initialized
2350
.PN True
2351
and never changes.
2352
If \fIvisible_interest\fP is
2353
.PN True ,
2354
the event manager asks for
2355
.PN VisibilityNotify
2356
events for the widget and sets \fIvisible\fP to
2357
.PN True
2358
on
2359
.PN VisibilityUnobscured
2360
or
2361
.PN VisibilityPartiallyObscured
2362
.IN VisibilityNotify
2363
events and
2364
.PN False
2365
on
2366
.PN VisibilityFullyObscured
2367
events.
2368
2369
.NH 2
2370
X Event Handlers
2371
.XS
2372
\*(SN X Event Handlers
2373
.XE
2374
.LP
2375
Event handlers are procedures called when specified events
2376
occur in a widget.
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 .
2381
.LP
2382
.IN "XtEventHandler" "" "@DEF@"
2383
.sM
2384
.FD 0
2385
typedef void (*XtEventHandler)(Widget, XtPointer, XEvent*, Boolean*);
2386
.br
2387
Widget \fIw\fP;
2388
.br
2389
XtPointer \fIclient_data\fP;
2390
.br
2391
XEvent *\fIevent\fP;
2392
.br
2393
Boolean *\fIcontinue_to_dispatch\fP;
2394
.FN
2395
.IP \fIw\fP 1i
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.
2399
.IP \fIevent\fP 1i
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
2404
should be called.
2405
.LP
2406
.eM
2407
After receiving an event and before calling any event handlers, the
2408
Boolean pointed to by \fIcontinue_to_dispatch\fP is initialized to
2409
.PN True .
2410
When an event handler is called, it may decide that further processing
2411
of the event is not desirable and may store
2412
.PN False
2413
in this Boolean, in
2414
which case any handlers remaining to be called for the event are
2415
ignored.
2416
.LP
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
2420
.PN False
2421
into the \fIcontinue_to_dispatch\fP argument can lead to portability problems.
2422
2423
.NH 3
2424
Event Handlers That Select Events
2425
.XS
2426
\*(SN Event Handlers That Select Events
2427
.XE
2428
.LP
2429
To register an event handler procedure with the dispatch mechanism, use
2430
.PN XtAddEventHandler .
2431
.LP
2432
.IN "XtAddEventHandler" "" "@DEF@"
2433
.sM
2434
.FD 0
2435
void XtAddEventHandler(\fIw\fP, \fIevent_mask\fP, \fInonmaskable\fP, \
2436
\fIproc\fP, \fIclient_data\fP)
2437
.br
2438
Widget \fIw\fP;
2439
.br
2440
EventMask \fIevent_mask\fP;
2441
.br
2442
Boolean \fInonmaskable\fP;
2443
.br
2444
XtEventHandler \fIproc\fP;
2445
.br
2446
XtPointer \fIclient_data\fP;
2447
.FN
2448
.IP \fIw\fP 1i
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 ,
2456
.PN NoExpose ,
2457
.PN SelectionClear ,
2458
.PN SelectionRequest ,
2459
.PN SelectionNotify ,
2460
.PN ClientMessage ,
2461
and
2462
.PN MappingNotify ).
2463
.IP \fIproc\fP 1i
2464
Specifies the procedure to be called.
2465
.IP \fIclient_data\fP 1i
2466
Specifies additional data to be passed to the event handler.
2467
.LP
2468
.eM
2469
The
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
2473
widget.
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
2478
value,
2479
the specified mask augments the existing mask.
2480
If the widget is realized,
2481
.PN XtAddEventHandler
2482
calls
2483
.PN XSelectInput ,
2484
if necessary.
2485
The order in which this procedure is called relative to other handlers
2486
registered for the same event is not defined.
2487
.sp
2488
.LP
2489
To remove a previously registered event handler, use
2490
.PN XtRemoveEventHandler .
2491
.LP
2492
.IN "XtRemoveEventHandler" "" "@DEF@"
2493
.sM
2494
.FD 0
2495
void XtRemoveEventHandler(\fIw\fP, \fIevent_mask\fP, \fInonmaskable\fP, \
2496
\fIproc\fP, \fIclient_data\fP)
2497
.br
2498
Widget \fIw\fP;
2499
.br
2500
EventMask \fIevent_mask\fP;
2501
.br
2502
Boolean \fInonmaskable\fP;
2503
.br
2504
XtEventHandler \fIproc\fP;
2505
.br
2506
XtPointer \fIclient_data\fP;
2507
.FN
2508
.IP \fIw\fP 1i
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 ,
2516
.PN NoExpose ,
2517
.PN SelectionClear ,
2518
.PN SelectionRequest ,
2519
.PN SelectionNotify ,
2520
.PN ClientMessage ,
2521
and
2522
.PN MappingNotify ).
2523
.IP \fIproc\fP 1i
2524
Specifies the procedure to be removed.
2525
.IP \fIclient_data\fP 1i
2526
Specifies the registered client data.
2527
.LP
2528
.eM
2529
The
2530
.PN XtRemoveEventHandler
2531
function unregisters an event handler registered with
2532
.PN XtAddEventHandler
2533
or
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
2540
calls
2541
.PN XSelectInput .
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.
2546
.LP
2547
To stop a procedure registered with
2548
.PN XtAddEventHandler
2549
or
2550
.PN XtInsertEventHandler
2551
from receiving all selected events, call
2552
.PN XtRemoveEventHandler
2553
with an \fIevent_mask\fP of
2554
.PN XtAllEvents
2555
and \fInonmaskable\fP
2556
.PN True .
2557
The procedure will continue to receive any events
2558
that have been specified in calls to
2559
.PN XtAddRawEventHandler
2560
or
2561
.PN XtInsertRawEventHandler .
2562
.sp
2563
.LP
2564
To register an event handler procedure that receives events before or
2565
after all previously registered event handlers, use
2566
.PN XtInsertEventHandler .
2567
.LP
2568
.IN "XtListPosition" "" "@DEF@"
2569
.IN "XtInsertEventHandler" "" "@DEF@"
2570
.sM
2571
.Ds 0
2572
typedef enum {XtListHead, XtListTail} XtListPosition;
2573
.De
2574
.LP
2575
.FD 0
2576
void XtInsertEventHandler(\fIw\fP, \fIevent_mask\fP, \fInonmaskable\fP, \
2577
\fIproc\fP, \fIclient_data\fP, \fIposition\fP)
2578
.br
2579
Widget \fIw\fP;
2580
.br
2581
EventMask \fIevent_mask\fP;
2582
.br
2583
Boolean \fInonmaskable\fP;
2584
.br
2585
XtEventHandler \fIproc\fP;
2586
.br
2587
XtPointer \fIclient_data\fP;
2588
.br
2589
XtListPosition \fIposition\fP;
2590
.FN
2591
.IP \fIw\fP 1i
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 ,
2599
.PN NoExpose ,
2600
.PN SelectionClear ,
2601
.PN SelectionRequest ,
2602
.PN SelectionNotify ,
2603
.PN ClientMessage ,
2604
and
2605
.PN MappingNotify ).
2606
.IP \fIproc\fP 1i
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.
2613
.LP
2614
.eM
2615
.PN XtInsertEventHandler
2616
is identical to
2617
.PN XtAddEventHandler
2618
with the additional \fIposition\fP argument. If \fIposition\fP is
2619
.PN XtListHead ,
2620
the event
2621
handler is registered so that it is called before any event
2622
handlers that were previously registered for the same widget. If
2623
\fIposition\fP is
2624
.PN XtListTail ,
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
2629
the list.
2630
2631
.NH 3
2632
Event Handlers That Do Not Select Events
2633
.XS
2634
\*(SN Event Handlers That Do Not Select Events
2635
.XE
2636
.LP
2637
On occasion,
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.
2641
To do this, use
2642
.PN XtAddRawEventHandler .
2643
.LP
2644
.IN "XtAddRawEventHandler" "" "@DEF@"
2645
.sM
2646
.FD 0
2647
void XtAddRawEventHandler(\fIw\fP, \fIevent_mask\fP, \fInonmaskable\fP, \
2648
\fIproc\fP, \fIclient_data\fP)
2649
.br
2650
Widget \fIw\fP;
2651
.br
2652
EventMask \fIevent_mask\fP;
2653
.br
2654
Boolean \fInonmaskable\fP;
2655
.br
2656
XtEventHandler \fIproc\fP;
2657
.br
2658
XtPointer \fIclient_data\fP;
2659
.FN
2660
.IP \fIw\fP 1i
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 ,
2668
.PN NoExpose ,
2669
.PN SelectionClear ,
2670
.PN SelectionRequest ,
2671
.PN SelectionNotify ,
2672
.PN ClientMessage ,
2673
and
2674
.PN MappingNotify ).
2675
.IP \fIproc\fP 1i
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.
2679
.LP
2680
.eM
2681
The
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
2686
.PN XSelectInput
2687
for its events.
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.
2694
.sp
2695
.LP
2696
To remove a previously registered raw event handler, use
2697
.PN XtRemoveRawEventHandler .
2698
.LP
2699
.IN "XtRemoveRawEventHandler" "" "@DEF@"
2700
.sM
2701
.FD 0
2702
void XtRemoveRawEventHandler(\fIw\fP, \fIevent_mask\fP, \fInonmaskable\fP, \
2703
\fIproc\fP, \fIclient_data\fP)
2704
.br
2705
Widget \fIw\fP;
2706
.br
2707
EventMask \fIevent_mask\fP;
2708
.br
2709
Boolean \fInonmaskable\fP;
2710
.br
2711
XtEventHandler \fIproc\fP;
2712
.br
2713
XtPointer \fIclient_data\fP;
2714
.FN
2715
.IP \fIw\fP 1i
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 ,
2723
.PN NoExpose ,
2724
.PN SelectionClear ,
2725
.PN SelectionRequest ,
2726
.PN SelectionNotify ,
2727
.PN ClientMessage ,
2728
and
2729
.PN MappingNotify ).
2730
.IP \fIproc\fP 1i
2731
Specifies the procedure to be registered.
2732
.IP \fIclient_data\fP 1i
2733
Specifies the registered client data.
2734
.LP
2735
.eM
2736
The
2737
.PN XtRemoveRawEventHandler
2738
function unregisters an event handler registered with
2739
.PN XtAddRawEventHandler
2740
or
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.
2750
.LP
2751
To stop a procedure
2752
registered with
2753
.PN XtAddRawEventHandler
2754
or
2755
.PN XtInsertRawEventHandler
2756
from receiving all nonselected events, call
2757
.PN XtRemoveRawEventHandler
2758
with an \fIevent_mask\fP of
2759
.PN XtAllEvents
2760
and \fInonmaskable\fP
2761
.PN True .
2762
The procedure
2763
will continue to receive any events that have been specified in calls to
2764
.PN XtAddEventHandler
2765
or
2766
.PN XtInsertEventHandler .
2767
.sp
2768
.LP
2769
To register an event handler procedure that receives events before or
2770
after all previously registered event handlers without selecting for
2771
the events, use
2772
.PN XtInsertRawEventHandler .
2773
.LP
2774
.IN "XtInsertRawEventHandler" "" "@DEF@"
2775
.sM
2776
.FD 0
2777
void XtInsertRawEventHandler(\fIw\fP, \fIevent_mask\fP, \fInonmaskable\fP, \
2778
\fIproc\fP, \fIclient_data\fP, \fIposition\fP)
2779
.br
2780
Widget \fIw\fP;
2781
.br
2782
EventMask \fIevent_mask\fP;
2783
.br
2784
Boolean \fInonmaskable\fP;
2785
.br
2786
XtEventHandler \fIproc\fP;
2787
.br
2788
XtPointer \fIclient_data\fP;
2789
.br
2790
XtListPosition \fIposition\fP;
2791
.FN
2792
.IP \fIw\fP 1i
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 ,
2800
.PN NoExpose ,
2801
.PN SelectionClear ,
2802
.PN SelectionRequest ,
2803
.PN SelectionNotify ,
2804
.PN ClientMessage ,
2805
and
2806
.PN MappingNotify ).
2807
.IP \fIproc\fP 1i
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.
2814
.LP
2815
.eM
2816
The
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
2822
.PN XSelectInput
2823
for the specified events. If
2824
the procedure is already registered with the same \fIclient_data\fP
2825
value, the
2826
specified mask augments the existing mask and the procedure is
2827
repositioned in the list.
2828
2829
.NH 3
2830
Current Event Mask
2831
.XS
2832
\*(SN Current Event Mask
2833
.XE
2834
.LP
2835
To retrieve the event mask for a given widget, use
2836
.PN XtBuildEventMask .
2837
.LP
2838
.IN "XtBuildEventMask" "" "@DEF@"
2839
.sM
2840
.FD 0
2841
EventMask XtBuildEventMask(\fIw\fP)
2842
.br
2843
Widget \fIw\fP;
2844
.FN
2845
.IP \fIw\fP 1i
2846
Specifies the widget. \*(cI
2847
.LP
2848
.eM
2849
The
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
2854
and
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
2860
structure by
2861
.PN XtRealizeWidget
2862
and sent to the server when event handlers and translations are installed or
2863
removed on the realized widget.
2864
2865
.NH 3
2866
Event Handlers for X11 Protocol Extensions
2867
.XS
2868
\fB\*(SN Event Handlers for X11 Protocol Extensions\fP
2869
.XE
2870
.LP
2871
To register an event handler procedure with the \*(xI dispatch
2872
mechanism according to an event type, use
2873
.PN XtInsertEventTypeHandler .
2874
.LP
2875
.IN "XtInsertEventTypeHandler" "" "@DEF"
2876
.sM
2877
.FD 0
2878
void XtInsertEventTypeHandler(\fIwidget\fP, \fIevent_type\fP, \
2879
\fIselect_data\fP, \fIproc\fP, \fIclient_data\fP, \fIposition\fP)
2880
.br
2881
Widget \fIwidget\fP;
2882
.br
2883
int \fIevent_type\fP;
2884
.br
2885
XtPointer \fIselect_data\fP;
2886
.br
2887
XtEventHandler \fIproc\fP;
2888
.br
2889
XtPointer \fIclient_data\fP;
2890
.br
2891
XtListPosition \fIposition\fP;
2892
.FN
2893
.IP \fIwidget\fP 1i
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,
2899
or NULL.
2900
.IP \fIproc\fP 1i
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.
2907
.LP
2908
.eM
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.
2913
.LP
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
2916
.PN EventMask ,
2917
indicating
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
2923
calls
2924
.PN XSelectInput
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
2927
to the
2928
.PN XtInsertRawEventHandler
2929
function.
2930
.LP
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.
2934
.LP
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.
2939
.LP
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
2943
.PN XtListTail ,
2944
which registers this event handler after any previously
2945
registered handlers for this event type.
2946
.LP
2947
Each widget has a single registered event handler list, which will
2948
contain any procedure/client_data pair exactly once if it is
2949
registered with
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.
2956
.sp
2957
.LP
2958
To remove an event handler registered with
2959
.PN XtInsertEventTypeHandler ,
2960
use
2961
.PN XtRemoveEventTypeHandler .
2962
.LP
2963
.IN "XtRemoveEventTypeHandler" "" "@DEF"
2964
.sM
2965
.FD 0
2966
void XtRemoveEventTypeHandler(\fIwidget\fP, \fIevent_type\fP, \
2967
\fIselect_data\fP, \fIproc\fP, \fIclient_data\fP)
2968
.br
2969
Widget \fIwidget\fP;
2970
.br
2971
int \fIevent_type\fP;
2972
.br
2973
XtPointer \fIselect_data\fP;
2974
.br
2975
XtEventHandler \fIproc\fP;
2976
.br
2977
XtPointer \fIclient_data\fP;
2978
.FN
2979
.IP \fIwidget\fP 1i
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.
2986
.IP \fIproc\fP 1i
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.
2990
.LP
2991
.eM
2992
The
2993
.PN XtRemoveEventTypeHandler
2994
function unregisters an event handler
2995
registered with
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.
3000
.LP
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
3005
is realized,
3006
.PN XtRemoveEventTypeHandler
3007
calls
3008
.PN XSelectInput
3009
if necessary.
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
3013
function.
3014
.LP
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.
3018
.sp
3019
.LP
3020
To register a procedure to select extension events for a widget, use
3021
.PN XtRegisterExtensionSelector .
3022
.LP
3023
.IN "XtRegisterExtensionSelector" "" "@DEF@"
3024
.sM
3025
.FD 0
3026
void XtRegisterExtensionSelector(\fIdisplay\fP, \fImin_event_type\fP, \
3027
\fImax_event_type\fP, \fIproc\fP,
3028
\fIclient_data\fP)
3029
.br
3030
Display \fI*display\fP;
3031
.br
3032
int \fImin_event_type\fP;
3033
.br
3034
int \fImax_event_type\fP;
3035
.br
3036
XtExtensionSelectProc \fIproc\fP;
3037
.br
3038
XtPointer \fIclient_data\fP;
3039
.FN
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.
3045
.IP \fIproc\fP 1.5i
3046
Specifies the extension selector procedure.
3047
.IP \fIclient_data\fP 1.5i
3048
Specifies additional data to be passed to the extension selector.
3049
.LP
3050
.eM
3051
The
3052
.PN XtRegisterExtensionSelector
3053
function registers a procedure to arrange
3054
for the delivery of extension events to widgets.
3055
.LP
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.
3064
.LP
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.
3077
.sp
3078
.LP
3079
An extension selector is of type
3080
.PN XtExtensionSelectProc .
3081
.LP
3082
.IN "XtExtensionSelectProc" "" "@DEF"
3083
.sM
3084
.FD 0
3085
typedef void (*XtExtensionSelectProc)(Widget, int *, XtPointer *, int, \
3086
XtPointer);
3087
.br
3088
Widget \fIwidget\fP;
3089
.br
3090
int *\fIevent_types\fP;
3091
.br
3092
XtPointer *\fIselect_data\fP;
3093
.br
3094
int \fIcount\fP;
3095
.br
3096
XtPointer \fIclient_data\fP;
3097
.FN
3098
.IP \fIwidget\fP 1i
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 .
3107
.IP \fIcount\fP 1i
3108
Specifies the number of entries in the \fIevent_types\fP and \fIselect_data\fP
3109
lists.
3110
.IP \fIclient_data\fP 1i
3111
Specifies the additional client data with which the procedure was registered.
3112
.LP
3113
.eM
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 .
3118
.sp
3119
.LP
3120
To register a procedure to dispatch events of a specific type within
3121
.PN XtDispatchEvent ,
3122
use
3123
.PN XtSetEventDispatcher .
3124
.LP
3125
.IN "XtSetEventDispatcher" "" "@DEF@"
3126
.sM
3127
.FD 0
3128
XtEventDispatchProc XtSetEventDispatcher(\fIdisplay\fP, \fIevent_type\fP, \
3129
\fIproc\fP)
3130
.br
3131
Display *\fIdisplay\fP;
3132
.br
3133
int \fIevent_type\fP;
3134
.br
3135
XtEventDispatchProc \fIproc\fP;
3136
.FN
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.
3141
.IP \fIproc\fP 1i
3142
Specifies the event dispatcher procedure.
3143
.LP
3144
.eM
3145
The
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.
3152
.LP
3153
In the future, when
3154
.PN XtDispatchEvent
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.
3158
.LP
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.
3162
.sp
3163
.LP
3164
An event dispatcher procedure pointer is of type
3165
.PN XtEventDispatchProc .
3166
.LP
3167
.IN "XtEventDispatchProc" "" "@DEF@"
3168
.sM
3169
.FD 0
3170
typedef Boolean (*XtEventDispatchProc)(XEvent*)
3171
.br
3172
XEvent *\fIevent\fP;
3173
.FN
3174
.IP \fIevent\fP 1i
3175
Passes the event to be dispatched.
3176
.LP
3177
.eM
3178
The event dispatcher procedure should determine whether this event is of
3179
a type that should be dispatched to a widget.
3180
.LP
3181
If the event should be dispatched to a widget, the event dispatcher
3182
procedure should determine the appropriate widget to receive the
3183
event, call
3184
.PN XFilterEvent
3185
with the window of this widget, or
3186
.PN None
3187
if the event is to be discarded, and if
3188
.PN XFilterEvent
3189
returns
3190
.PN False ,
3191
dispatch the event to the widget using
3192
.PN XtDispatchEventToWidget .
3193
The procedure should return
3194
.PN True
3195
if either
3196
.PN XFilterEvent
3197
or
3198
.PN XtDispatchEventToWidget
3199
returned
3200
.PN True
3201
and
3202
.PN False
3203
otherwise.
3204
.LP
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
3208
.PN True
3209
if it successfully dispatched the event and
3210
.PN False
3211
otherwise.
3212
.sp
3213
.LP
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 .
3218
.LP
3219
.IN "XtGetKeyboardFocusWidget" "" "@DEF@"
3220
.sM
3221
.FD 0
3222
Widget XtGetKeyboardFocusWidget(\fIwidget\fP)
3223
.br
3224
Widget \fIwidget\fP;
3225
.FN
3226
.IP \fIwidget\fP 1i
3227
Specifies the widget to get forwarding information for.
3228
.LP
3229
.eM
3230
The
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.
3234
.sp
3235
.LP
3236
To dispatch an event to a specified widget, use
3237
.PN XtDispatchEventToWidget .
3238
.LP
3239
.IN "XtDispatchEventToWidget" "" "@DEF@"
3240
.sM
3241
.FD 0
3242
Boolean XtDispatchEventToWidget(\fIwidget\fP, \fIevent\fP)
3243
.br
3244
Widget \fIwidget\fP;
3245
.br
3246
XEvent *\fIevent\fP;
3247
.FN
3248
.IP \fIwidget\fP 1i
3249
Specifies the widget to which to dispatch the event.
3250
.IP \fIevent\fP 1i
3251
Specifies a pointer to the event to be dispatched.
3252
.LP
3253
.eM
3254
The
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
3261
of the list for
3262
.PN Expose ,
3263
.PN NoExpose ,
3264
.PN GraphicsExpose ,
3265
and
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
3270
.PN True .
3271
These internal event handlers never set \fIcontinue_to_dispatch\fP to
3272
.PN False .
3273
.LP
3274
.PN XtDispatchEventToWidget
3275
returns
3276
.PN True
3277
if any event handler was called and
3278
.PN False
3279
otherwise.
3280
3281
.NH 2
3282
Using the \*(xI in a Multi-Threaded Environment
3283
.XS
3284
\*(SN Using the \*(xI in a Multi-Threaded Environment
3285
.XE
3286
.LP
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 .
3292
3293
.NH 3
3294
Initializing a Multi-Threaded \*(xI Application
3295
.XS
3296
\fB\*(SN Initializing a Multi-Threaded \*(xI Application\fP
3297
.XE
3298
.LP
3299
To test and initialize \*(xI support for mutually exclusive thread
3300
access, call
3301
.PN XtToolkitThreadInitialize .
3302
.LP
3303
.IN "XtToolkitThreadInitialize" "" "@DEF@"
3304
.sM
3305
.FD 0
3306
Boolean XtToolkitThreadInitialize()
3307
.FN
3308
.LP
3309
.eM
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 ,
3317
or
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.
3322
3323
.NH 3
3324
Locking \*(tk Data Structures
3325
.XS
3326
\fB\*(SN Locking \*(tk Data Structures\fP
3327
.XE
3328
.LP
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
3334
global data.
3335
.LP
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.
3339
.LP
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:
3345
.LP
3346
.KS
3347
.Ds
3348
.TA .5i 2i
3349
.ta .5i 2i
3350
...
3351
XtAppLock(app_context);
3352
XtCvtStringToPixel(dpy, args, num_args, fromVal, toVal, closure_ret);
3353
XtAppUnlock(app_context);
3354
...
3355
.De
3356
.KE
3357
.LP
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.
3363
.LP
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:
3368
.LP
3369
.KS
3370
.Ds
3371
.TA .5i 2i
3372
.ta .5i 2i
3373
#include <X11/CoreP.h>
3374
Boolean BeingDestroyed (widget)
3375
Widget widget;
3376
{
3377
Boolean ret;
3378
XtAppLock(XtWidgetToApplicationContext(widget));
3379
ret = widget->core.being_destroyed;
3380
XtAppUnlock(XtWidgetToApplicationContext(widget));
3381
return ret;
3382
}
3383
.De
3384
.KE
3385
A client that wishes to atomically call two or more \*(xI functions
3386
must lock the application context. For example:
3387
.LP
3388
.KS
3389
.Ds
3390
.TA .5i 2i
3391
.ta .5i 2i
3392
...
3393
XtAppLock(XtWidgetToApplicationContext(widget));
3394
XtUnmanageChild (widget1);
3395
XtManageChild (widget2);
3396
XtAppUnlock(XtWidgetToApplicationContext(widget));
3397
...
3398
.De
3399
.KE
3400
3401
.NH 4
3402
Locking the Application Context
3403
.XS
3404
\fB\*(SN Locking the Application Context\fP
3405
.XE
3406
.LP
3407
To ensure mutual exclusion of application context, display, or
3408
widget internal state, use
3409
.PN XtAppLock.
3410
.LP
3411
.IN "XtAppLock" "" "@DEF@"
3412
.sM
3413
.FD 0
3414
void XtAppLock(\fIapp_context\fP)
3415
.br
3416
XtAppContext \fIapp_context\fP;
3417
.FN
3418
.IP \fIapp_context\fP 1i
3419
Specifies the application context to lock.
3420
.LP
3421
.eM
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.
3427
.LP
3428
To unlock a locked application context, use
3429
.PN XtAppUnlock.
3430
.LP
3431
.IN "XtAppUnlock" "" "@DEF@"
3432
.sM
3433
.FD 0
3434
void XtAppUnlock(\fIapp_context\fP)
3435
.br
3436
XtAppContext \fIapp_context\fP;
3437
.FN
3438
.IP \fIapp_context\fP 1i
3439
Specifies the application context that was previously locked.
3440
.LP
3441
.eM
3442
3443
.NH 4
3444
Locking the Process
3445
.XS
3446
\*(SN Locking the Process
3447
.XE
3448
.LP
3449
To ensure mutual exclusion of \*(tk process global data, a
3450
widget writer must use
3451
.PN XtProcessLock.
3452
.LP
3453
.IN "XtProcessLock" "" "@DEF@"
3454
.sM
3455
.FD 0
3456
void XtProcessLock()
3457
.FN
3458
.LP
3459
.eM
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.
3463
.LP
3464
To unlock a locked process, use
3465
.PN XtProcessUnlock .
3466
.LP
3467
.IN "XtProcessUnlock" "" "@DEF@"
3468
.sM
3469
.FD 0
3470
void XtProcessUnlock()
3471
.FN
3472
.LP
3473
.eM
3474
To lock both an application context and the process at the same
3475
time, call
3476
.PN XtAppLock
3477
first and then
3478
.PN XtProcessLock .
3479
To release both locks, call
3480
.PN XtProcessUnlock
3481
first and then
3482
.PN XtAppUnlock .
3483
The order is important to avoid deadlock.
3484
3485
.NH 3
3486
Event Management in a Multi-Threaded Environment
3487
.XS
3488
\fB\*(SN Event Management in a Multi-Threaded Environment\fP
3489
.XE
3490
.LP
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.
3496
.LP
3497
To indicate that the event loop should terminate after the current
3498
event dispatch has completed, use
3499
.PN XtAppSetExitFlag .
3500
.LP
3501
.IN "XtAppSetExitFlag" "" "@DEF@"
3502
.sM
3503
.FD 0
3504
void XtAppSetExitFlag(\fIapp_context\fP)
3505
.br
3506
XtAppContext \fIapp_context\fP;
3507
.FN
3508
.IP \fIapp_context\fP 1i
3509
Specifies the application context.
3510
.LP
3511
.eM
3512
.PN XtAppMainLoop
3513
tests the value of the flag and will return if the flag is \fBTrue\fP.
3514
.LP
3515
Application writers who implement their own main loop may test the
3516
value of the exit flag with
3517
.PN XtAppGetExitFlag .
3518
.LP
3519
.IN "XtAppGetExitFlag" "" "@DEF@"
3520
.sM
3521
.FD 0
3522
Boolean XtAppGetExitFlag(\fIapp_context\fP)
3523
.br
3524
XtAppContext \fIapp_context\fP;
3525
.FN
3526
.IP \fIapp_context\fP 1i
3527
Specifies the application context.
3528
.LP
3529
.eM
3530
.PN XtAppGetExitFlag
3531
will normally return \fBFalse\fP, indicating that event processing
3532
may continue. When
3533
.PN XtAppGetExitFlag
3534
returns \fBTrue\fP, the loop must terminate and return to the caller,
3535
which might then destroy the application context.
3536
.LP
3537
Application writers should be aware that, if a thread is blocked in
3538
.PN XtAppNextEvent ,
3539
.PN XtAppPeekEvent ,
3540
or
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.
3546
.LP
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 ,
3551
or
3552
.PN XtAppProcessEvent ,
3553
the last thread to call one of these functions is the first
3554
thread to return.
3555
.bp
Loggerhead is a web-based interface for Breezy
Version: 2.0.1