1
<?xml version="1.0" encoding="UTF-8" ?>
2
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
3
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
4
<chapter id="event_handling_functions">
5
<title>Event Handling Functions</title>
8
This chapter discusses the Xlib functions you can use to:
11
<listitem><para>Select events</para></listitem>
12
<listitem><para>Handle the output buffer and the event queue</para></listitem>
13
<listitem><para>Select events from the event queue</para></listitem>
14
<listitem><para>Send and get events</para></listitem>
15
<listitem><para>Handle protocol errors</para></listitem>
18
Some toolkits use their own event-handling functions and do not allow you to
19
interchange these event-handling functions with those in Xlib. For further
20
information, see the documentation supplied with the toolkit.
24
Most applications simply are event loops: they wait for an event, decide what to do with it,
25
execute some amount of code that results in changes to the display, and then wait for the next
29
<sect1 id="Selecting_Events">
30
<title>Selecting Events</title>
32
<!-- (SN Selecting Events -->
36
There are two ways to select the events you want reported to your client
38
One way is to set the event_mask member of the
39
<structname>XSetWindowAttributes</structname>
40
structure when you call
41
<function>XCreateWindow</function>
43
<function>XChangeWindowAttributes</function>.
45
<function>XSelectInput</function>.
46
<indexterm significance="preferred"><primary>XSelectInput</primary></indexterm>
50
<funcdef><function>XSelectInput</function></funcdef>
51
<paramdef>Display<parameter> *display</parameter></paramdef>
52
<paramdef>Window<parameter> w</parameter></paramdef>
53
<paramdef>long<parameter> event_mask</parameter></paramdef>
60
<emphasis remap='I'>display</emphasis>
64
Specifies the connection to the X server.
65
<!-- .ds Wi whose events you are interested in -->
71
<emphasis remap='I'>w</emphasis>
75
Specifies the window (Wi.
81
<emphasis remap='I'>event_mask</emphasis>
85
Specifies the event mask.
95
<function>XSelectInput</function>
96
function requests that the X server report the events associated with the
98
Initially, X will not report any of these events.
99
Events are reported relative to a window.
100
If a window is not interested in a device event, it usually propagates to
101
the closest ancestor that is interested,
102
unless the do_not_propagate mask prohibits it.
103
<indexterm><primary>Event</primary><secondary>propagation</secondary></indexterm>
107
Setting the event-mask attribute of a window overrides any previous call
108
for the same window but not for other clients.
109
Multiple clients can select for the same events on the same window
110
with the following restrictions:
115
Multiple clients can select events on the same window because their event masks
117
When the X server generates an event, it reports it
118
to all interested clients.
123
Only one client at a time can select
124
<symbol>CirculateRequest</symbol>,
125
<symbol>ConfigureRequest</symbol>,
127
<symbol>MapRequest</symbol>
128
events, which are associated with
130
<symbol>SubstructureRedirectMask</symbol>.
135
Only one client at a time can select
137
<symbol>ResizeRequest</symbol>
138
event, which is associated with
140
<symbol>ResizeRedirectMask</symbol>.
145
Only one client at a time can select a
146
<symbol>ButtonPress</symbol>
147
event, which is associated with
149
<symbol>ButtonPressMask</symbol>.
155
The server reports the event to all interested clients.
159
<function>XSelectInput</function>
161
<errorname>BadWindow</errorname>
165
<sect1 id="Handling_the_Output_Buffer">
166
<title>Handling the Output Buffer</title>
168
<!-- (SN Handling the Output Buffer -->
172
The output buffer is an area used by Xlib to store requests.
173
The functions described in this section flush the output buffer
174
if the function would block or not return an event.
175
That is, all requests residing in the output buffer that
176
have not yet been sent are transmitted to the X server.
177
These functions differ in the additional tasks they might perform.
182
To flush the output buffer, use
183
<function>XFlush</function>.
184
<indexterm significance="preferred"><primary>XFlush</primary></indexterm>
188
<funcdef><function>XFlush</function></funcdef>
189
<paramdef>Display<parameter> *display</parameter></paramdef>
196
<emphasis remap='I'>display</emphasis>
200
Specifies the connection to the X server.
210
<function>XFlush</function>
212
flushes the output buffer.
213
Most client applications need not use this function because the output
214
buffer is automatically flushed as needed by calls to
215
<function>XPending</function>,
216
<function>XNextEvent</function>,
218
<function>XWindowEvent</function>.
219
<indexterm><primary>XPending</primary></indexterm>
220
<indexterm><primary>XNextEvent</primary></indexterm>
221
<indexterm><primary>XWindowEvent</primary></indexterm>
222
Events generated by the server may be enqueued into the library's event queue.
227
To flush the output buffer and then wait until all requests have been processed,
229
<function>XSync</function>.
230
<indexterm significance="preferred"><primary>XSync</primary></indexterm>
234
<funcdef><function>XSync</function></funcdef>
235
<paramdef>Display<parameter> *display</parameter></paramdef>
236
<paramdef>Bool<parameter> discard</parameter></paramdef>
243
<emphasis remap='I'>display</emphasis>
247
Specifies the connection to the X server.
253
<emphasis remap='I'>discard</emphasis>
257
Specifies a Boolean value that indicates whether
258
<function>XSync</function>
259
discards all events on the event queue.
269
<function>XSync</function>
271
flushes the output buffer and then waits until all requests have been received
272
and processed by the X server.
273
Any errors generated must be handled by the error handler.
274
For each protocol error received by Xlib,
275
<function>XSync</function>
276
calls the client application's error handling routine (see section 11.8.2).
277
Any events generated by the server are enqueued into the library's
282
Finally, if you passed
283
<symbol>False</symbol>,
284
<function>XSync</function>
285
does not discard the events in the queue.
287
<symbol>True</symbol>,
288
<function>XSync</function>
289
discards all events in the queue,
290
including those events that were on the queue before
291
<function>XSync</function>
293
Client applications seldom need to call
294
<function>XSync</function>.
297
<sect1 id="Event_Queue_Management">
298
<title>Event Queue Management</title>
300
<!-- (SN Event Queue Management -->
304
Xlib maintains an event queue.
305
However, the operating system also may be buffering data
306
in its network connection that is not yet read into the event queue.
311
To check the number of events in the event queue, use
312
<function>XEventsQueued</function>.
313
<indexterm significance="preferred"><primary>XEventsQueued</primary></indexterm>
317
<funcdef>int <function>XEventsQueued</function></funcdef>
318
<paramdef>Display<parameter> *display</parameter></paramdef>
319
<paramdef>int<parameter> mode</parameter></paramdef>
326
<emphasis remap='I'>display</emphasis>
330
Specifies the connection to the X server.
336
<emphasis remap='I'>mode</emphasis>
342
<symbol>QueuedAlready</symbol>,
343
<symbol>QueuedAfterFlush</symbol>,
345
<symbol>QueuedAfterReading</symbol>.
355
<symbol>QueuedAlready</symbol>,
356
<function>XEventsQueued</function>
357
returns the number of events
358
already in the event queue (and never performs a system call).
360
<symbol>QueuedAfterFlush</symbol>,
361
<function>XEventsQueued</function>
362
returns the number of events already in the queue if the number is nonzero.
363
If there are no events in the queue,
364
<function>XEventsQueued</function>
365
flushes the output buffer,
366
attempts to read more events out of the application's connection,
367
and returns the number read.
369
<symbol>QueuedAfterReading</symbol>,
370
<function>XEventsQueued</function>
371
returns the number of events already in the queue if the number is nonzero.
372
If there are no events in the queue,
373
<function>XEventsQueued</function>
374
attempts to read more events out of the application's connection
375
without flushing the output buffer and returns the number read.
379
<function>XEventsQueued</function>
380
always returns immediately without I/O if there are events already in the
382
<function>XEventsQueued</function>
384
<symbol>QueuedAfterFlush</symbol>
385
is identical in behavior to
386
<function>XPending</function>.
387
<function>XEventsQueued</function>
389
<symbol>QueuedAlready</symbol>
391
<function>XQLength</function>
397
To return the number of events that are pending, use
398
<function>XPending</function>.
399
<indexterm significance="preferred"><primary>XPending</primary></indexterm>
403
<funcdef>int <function>XPending</function></funcdef>
404
<paramdef>Display<parameter> *display</parameter></paramdef>
411
<emphasis remap='I'>display</emphasis>
415
Specifies the connection to the X server.
425
<function>XPending</function>
426
function returns the number of events that have been received from the
427
X server but have not been removed from the event queue.
428
<function>XPending</function>
430
<function>XEventsQueued</function>
432
<symbol>QueuedAfterFlush</symbol>
436
<sect1 id="Manipulating_the_Event_Queue">
437
<title>Manipulating the Event Queue</title>
439
<!-- (SN Manipulating the Event Queue -->
443
Xlib provides functions that let you manipulate the event queue.
444
This section discusses how to:
449
Obtain events, in order, and remove them from the queue
454
Peek at events in the queue without removing them
459
Obtain events that match the event mask or the arbitrary
460
predicate procedures that you provide
464
<sect2 id="Returning_the_Next_Event">
465
<title>Returning the Next Event</title>
467
<!-- (SN Returning the Next Event -->
471
To get the next event and remove it from the queue, use
472
<function>XNextEvent</function>.
473
<indexterm significance="preferred"><primary>XNextEvent</primary></indexterm>
477
<funcdef><function>XNextEvent</function></funcdef>
478
<paramdef>Display<parameter> *display</parameter></paramdef>
479
<paramdef>XEvent<parameter> *event_return</parameter></paramdef>
486
<emphasis remap='I'>display</emphasis>
490
Specifies the connection to the X server.
496
<emphasis remap='I'>event_return</emphasis>
500
Returns the next event in the queue.
510
<function>XNextEvent</function>
511
function copies the first event from the event queue into the specified
512
<structname>XEvent</structname>
513
structure and then removes it from the queue.
514
If the event queue is empty,
515
<function>XNextEvent</function>
516
flushes the output buffer and blocks until an event is received.
521
To peek at the event queue, use
522
<function>XPeekEvent</function>.
523
<indexterm significance="preferred"><primary>XPeekEvent</primary></indexterm>
527
<funcdef><function>XPeekEvent</function></funcdef>
528
<paramdef>Display<parameter> *display</parameter></paramdef>
529
<paramdef>XEvent<parameter> *event_return</parameter></paramdef>
536
<emphasis remap='I'>display</emphasis>
540
Specifies the connection to the X server.
546
<emphasis remap='I'>event_return</emphasis>
550
Returns a copy of the matched event's associated structure.
560
<function>XPeekEvent</function>
561
function returns the first event from the event queue,
562
but it does not remove the event from the queue.
563
If the queue is empty,
564
<function>XPeekEvent</function>
565
flushes the output buffer and blocks until an event is received.
566
It then copies the event into the client-supplied
567
<structname>XEvent</structname>
568
structure without removing it from the event queue.
571
<sect2 id="Selecting_Events_Using_a_Predicate_Procedure">
572
<title>Selecting Events Using a Predicate Procedure</title>
574
<!-- (SN Selecting Events Using a Predicate Procedure -->
578
Each of the functions discussed in this section requires you to
579
pass a predicate procedure that determines if an event matches
581
Your predicate procedure must decide if the event is useful
582
without calling any Xlib functions.
583
If the predicate directly or indirectly causes the state of the event queue
584
to change, the result is not defined.
585
If Xlib has been initialized for threads, the predicate is called with
586
the display locked and the result of a call by the predicate to any
587
Xlib function that locks the display is not defined unless the caller
589
<function>XLockDisplay</function>.
593
The predicate procedure and its associated arguments are:
597
<funcdef><type>Bool</type></funcdef>
598
<paramdef>Display<parameter> *display</parameter></paramdef>
599
<paramdef>XEvent<parameter> *event</parameter></paramdef>
600
<paramdef>XPointer<parameter> arg</parameter></paramdef>
607
<emphasis remap='I'>display</emphasis>
611
Specifies the connection to the X server.
617
<emphasis remap='I'>event</emphasis>
622
<structname>XEvent</structname>
629
<emphasis remap='I'>arg</emphasis>
633
Specifies the argument passed in from the
634
<function>XIfEvent</function>,
635
<function>XCheckIfEvent</function>,
637
<function>XPeekIfEvent</function>
647
The predicate procedure is called once for each
648
event in the queue until it finds a match.
649
After finding a match, the predicate procedure must return
650
<symbol>True</symbol>.
651
If it did not find a match, it must return
652
<symbol>False</symbol>.
657
To check the event queue for a matching event
658
and, if found, remove the event from the queue, use
659
<function>XIfEvent</function>.
660
<indexterm significance="preferred"><primary>XIfEvent</primary></indexterm>
664
<funcdef><function>XIfEvent</function></funcdef>
665
<paramdef>Display<parameter> *display</parameter></paramdef>
666
<paramdef>XEvent<parameter> *event_return</parameter></paramdef>
667
<paramdef>Bool<parameter> (*predicate)()</parameter></paramdef>
668
<paramdef>XPointer<parameter> arg</parameter></paramdef>
675
<emphasis remap='I'>display</emphasis>
679
Specifies the connection to the X server.
685
<emphasis remap='I'>event_return</emphasis>
689
Returns the matched event's associated structure.
695
<emphasis remap='I'>predicate</emphasis>
699
Specifies the procedure that is to be called to determine
700
if the next event in the queue matches what you want.
706
<emphasis remap='I'>arg</emphasis>
710
Specifies the user-supplied argument that will be passed to the predicate procedure.
720
<function>XIfEvent</function>
721
function completes only when the specified predicate
723
<symbol>True</symbol>
725
which indicates an event in the queue matches.
726
<function>XIfEvent</function>
727
flushes the output buffer if it blocks waiting for additional events.
728
<function>XIfEvent</function>
729
removes the matching event from the queue
730
and copies the structure into the client-supplied
731
<structname>XEvent</structname>
737
To check the event queue for a matching event without blocking, use
738
<function>XCheckIfEvent</function>.
739
<indexterm significance="preferred"><primary>XCheckIfEvent</primary></indexterm>
743
<funcdef>Bool <function>XCheckIfEvent</function></funcdef>
744
<paramdef>Display<parameter> *display</parameter></paramdef>
745
<paramdef>XEvent<parameter> *event_return</parameter></paramdef>
746
<paramdef>Bool<parameter> (*predicate)()</parameter></paramdef>
747
<paramdef>XPointer<parameter> arg</parameter></paramdef>
754
<emphasis remap='I'>display</emphasis>
758
Specifies the connection to the X server.
764
<emphasis remap='I'>event_return</emphasis>
768
Returns a copy of the matched event's associated structure.
774
<emphasis remap='I'>predicate</emphasis>
778
Specifies the procedure that is to be called to determine
779
if the next event in the queue matches what you want.
785
<emphasis remap='I'>arg</emphasis>
789
Specifies the user-supplied argument that will be passed to the predicate procedure.
798
When the predicate procedure finds a match,
799
<function>XCheckIfEvent</function>
800
copies the matched event into the client-supplied
801
<structname>XEvent</structname>
802
structure and returns
803
<symbol>True</symbol>.
804
(This event is removed from the queue.)
805
If the predicate procedure finds no match,
806
<function>XCheckIfEvent</function>
808
<symbol>False</symbol>,
809
and the output buffer will have been flushed.
810
All earlier events stored in the queue are not discarded.
815
To check the event queue for a matching event
816
without removing the event from the queue, use
817
<function>XPeekIfEvent</function>.
818
<indexterm significance="preferred"><primary>XPeekIfEvent</primary></indexterm>
822
<funcdef><function>XPeekIfEvent</function></funcdef>
823
<paramdef>Display<parameter> *display</parameter></paramdef>
824
<paramdef>XEvent<parameter> *event_return</parameter></paramdef>
825
<paramdef>Bool<parameter> (*predicate)()</parameter></paramdef>
826
<paramdef>XPointer<parameter> arg</parameter></paramdef>
833
<emphasis remap='I'>display</emphasis>
837
Specifies the connection to the X server.
843
<emphasis remap='I'>event_return</emphasis>
847
Returns a copy of the matched event's associated structure.
853
<emphasis remap='I'>predicate</emphasis>
857
Specifies the procedure that is to be called to determine
858
if the next event in the queue matches what you want.
864
<emphasis remap='I'>arg</emphasis>
868
Specifies the user-supplied argument that will be passed to the predicate procedure.
878
<function>XPeekIfEvent</function>
879
function returns only when the specified predicate
881
<symbol>True</symbol>
883
After the predicate procedure finds a match,
884
<function>XPeekIfEvent</function>
885
copies the matched event into the client-supplied
886
<structname>XEvent</structname>
887
structure without removing the event from the queue.
888
<function>XPeekIfEvent</function>
889
flushes the output buffer if it blocks waiting for additional events.
892
<sect2 id="Selecting_Events_Using_a_Window_or_Event_Mask">
893
<title>Selecting Events Using a Window or Event Mask</title>
895
<!-- (SN Selecting Events Using a Window or Event Mask -->
899
The functions discussed in this section let you select events by window
900
or event types, allowing you to process events out of order.
905
To remove the next event that matches both a window and an event mask, use
906
<function>XWindowEvent</function>.
907
<indexterm significance="preferred"><primary>XWindowEvent</primary></indexterm>
911
<funcdef><function>XWindowEvent</function></funcdef>
912
<paramdef>Display<parameter> *display</parameter></paramdef>
913
<paramdef>Window<parameter> w</parameter></paramdef>
914
<paramdef>long<parameter> event_mask</parameter></paramdef>
915
<paramdef>XEvent<parameter> *event_return</parameter></paramdef>
922
<emphasis remap='I'>display</emphasis>
926
Specifies the connection to the X server.
927
<!-- .ds Wi whose events you are interested in -->
933
<emphasis remap='I'>w</emphasis>
937
Specifies the window (Wi.
943
<emphasis remap='I'>event_mask</emphasis>
947
Specifies the event mask.
953
<emphasis remap='I'>event_return</emphasis>
957
Returns the matched event's associated structure.
967
<function>XWindowEvent</function>
968
function searches the event queue for an event that matches both the specified
969
window and event mask.
970
When it finds a match,
971
<function>XWindowEvent</function>
972
removes that event from the queue and copies it into the specified
973
<structname>XEvent</structname>
975
The other events stored in the queue are not discarded.
976
If a matching event is not in the queue,
977
<function>XWindowEvent</function>
978
flushes the output buffer and blocks until one is received.
983
To remove the next event that matches both a window and an event mask (if any),
985
<function>XCheckWindowEvent</function>.
986
<indexterm><primary>XCheckWindowEvent</primary></indexterm>
987
This function is similar to
988
<function>XWindowEvent</function>
989
except that it never blocks and it returns a
991
indicating if the event was returned.
992
<indexterm significance="preferred"><primary>XCheckWindowEvent</primary></indexterm>
996
<funcdef>Bool <function>XCheckWindowEvent</function></funcdef>
997
<paramdef>Display<parameter> *display</parameter></paramdef>
998
<paramdef>Window<parameter> w</parameter></paramdef>
999
<paramdef>long<parameter> event_mask</parameter></paramdef>
1000
<paramdef>XEvent<parameter> *event_return</parameter></paramdef>
1007
<emphasis remap='I'>display</emphasis>
1011
Specifies the connection to the X server.
1012
<!-- .ds Wi whose events you are interested in -->
1018
<emphasis remap='I'>w</emphasis>
1022
Specifies the window (Wi.
1028
<emphasis remap='I'>event_mask</emphasis>
1032
Specifies the event mask.
1038
<emphasis remap='I'>event_return</emphasis>
1042
Returns the matched event's associated structure.
1052
<function>XCheckWindowEvent</function>
1053
function searches the event queue and then the events available
1054
on the server connection for the first event that matches the specified window
1056
If it finds a match,
1057
<function>XCheckWindowEvent</function>
1058
removes that event, copies it into the specified
1059
<structname>XEvent</structname>
1060
structure, and returns
1061
<symbol>True</symbol>.
1062
The other events stored in the queue are not discarded.
1063
If the event you requested is not available,
1064
<function>XCheckWindowEvent</function>
1066
<symbol>False</symbol>,
1067
and the output buffer will have been flushed.
1072
To remove the next event that matches an event mask, use
1073
<function>XMaskEvent</function>.
1074
<indexterm significance="preferred"><primary>XMaskEvent</primary></indexterm>
1078
<funcdef><function>XMaskEvent</function></funcdef>
1079
<paramdef>Display<parameter> *display</parameter></paramdef>
1080
<paramdef>long<parameter> event_mask</parameter></paramdef>
1081
<paramdef>XEvent<parameter> *event_return</parameter></paramdef>
1088
<emphasis remap='I'>display</emphasis>
1092
Specifies the connection to the X server.
1098
<emphasis remap='I'>event_mask</emphasis>
1102
Specifies the event mask.
1108
<emphasis remap='I'>event_return</emphasis>
1112
Returns the matched event's associated structure.
1122
<function>XMaskEvent</function>
1123
function searches the event queue for the events associated with the
1125
When it finds a match,
1126
<function>XMaskEvent</function>
1127
removes that event and copies it into the specified
1128
<structname>XEvent</structname>
1130
The other events stored in the queue are not discarded.
1131
If the event you requested is not in the queue,
1132
<function>XMaskEvent</function>
1133
flushes the output buffer and blocks until one is received.
1138
To return and remove the next event that matches an event mask (if any), use
1139
<function>XCheckMaskEvent</function>.
1140
This function is similar to
1141
<function>XMaskEvent</function>
1142
except that it never blocks and it returns a
1144
indicating if the event was returned.
1145
<indexterm significance="preferred"><primary>XCheckMaskEvent</primary></indexterm>
1149
<funcdef>Bool <function>XCheckMaskEvent</function></funcdef>
1150
<paramdef>Display<parameter> *display</parameter></paramdef>
1151
<paramdef>long<parameter> event_mask</parameter></paramdef>
1152
<paramdef>XEvent<parameter> *event_return</parameter></paramdef>
1159
<emphasis remap='I'>display</emphasis>
1163
Specifies the connection to the X server.
1169
<emphasis remap='I'>event_mask</emphasis>
1173
Specifies the event mask.
1179
<emphasis remap='I'>event_return</emphasis>
1183
Returns the matched event's associated structure.
1193
<function>XCheckMaskEvent</function>
1194
function searches the event queue and then any events available on the
1195
server connection for the first event that matches the specified mask.
1196
If it finds a match,
1197
<function>XCheckMaskEvent</function>
1198
removes that event, copies it into the specified
1199
<structname>XEvent</structname>
1200
structure, and returns
1201
<symbol>True</symbol>.
1202
The other events stored in the queue are not discarded.
1203
If the event you requested is not available,
1204
<function>XCheckMaskEvent</function>
1206
<symbol>False</symbol>,
1207
and the output buffer will have been flushed.
1212
To return and remove the next event in the queue that matches an event type, use
1213
<function>XCheckTypedEvent</function>.
1214
<indexterm significance="preferred"><primary>XCheckTypedEvent</primary></indexterm>
1218
<funcdef>Bool <function>XCheckTypedEvent</function></funcdef>
1219
<paramdef>Display<parameter> *display</parameter></paramdef>
1220
<paramdef>int<parameter> event_type</parameter></paramdef>
1221
<paramdef>XEvent<parameter> *event_return</parameter></paramdef>
1228
<emphasis remap='I'>display</emphasis>
1232
Specifies the connection to the X server.
1238
<emphasis remap='I'>event_type</emphasis>
1242
Specifies the event type to be compared.
1249
<emphasis remap='I'>event_return</emphasis>
1253
Returns the matched event's associated structure.
1263
<function>XCheckTypedEvent</function>
1264
function searches the event queue and then any events available
1265
on the server connection for the first event that matches the specified type.
1266
If it finds a match,
1267
<function>XCheckTypedEvent</function>
1268
removes that event, copies it into the specified
1269
<structname>XEvent</structname>
1270
structure, and returns
1271
<symbol>True</symbol>.
1272
The other events in the queue are not discarded.
1273
If the event is not available,
1274
<function>XCheckTypedEvent</function>
1276
<symbol>False</symbol>,
1277
and the output buffer will have been flushed.
1282
To return and remove the next event in the queue that matches an event type
1284
<function>XCheckTypedWindowEvent</function>.
1285
<indexterm significance="preferred"><primary>XCheckTypedWindowEvent</primary></indexterm>
1289
<funcdef>Bool <function>XCheckTypedWindowEvent</function></funcdef>
1290
<paramdef>Display<parameter> *display</parameter></paramdef>
1291
<paramdef>Window<parameter> w</parameter></paramdef>
1292
<paramdef>int<parameter> event_type</parameter></paramdef>
1293
<paramdef>XEvent<parameter> *event_return</parameter></paramdef>
1300
<emphasis remap='I'>display</emphasis>
1304
Specifies the connection to the X server.
1310
<emphasis remap='I'>w</emphasis>
1314
Specifies the window.
1320
<emphasis remap='I'>event_type</emphasis>
1324
Specifies the event type to be compared.
1331
<emphasis remap='I'>event_return</emphasis>
1335
Returns the matched event's associated structure.
1345
<function>XCheckTypedWindowEvent</function>
1346
function searches the event queue and then any events available
1347
on the server connection for the first event that matches the specified
1349
If it finds a match,
1350
<function>XCheckTypedWindowEvent</function>
1351
removes the event from the queue, copies it into the specified
1352
<structname>XEvent</structname>
1353
structure, and returns
1354
<symbol>True</symbol>.
1355
The other events in the queue are not discarded.
1356
If the event is not available,
1357
<function>XCheckTypedWindowEvent</function>
1359
<symbol>False</symbol>,
1360
and the output buffer will have been flushed.
1364
<sect1 id="Putting_an_Event_Back_into_the_Queue">
1365
<title>Putting an Event Back into the Queue</title>
1367
<!-- (SN Putting an Event Back into the Queue -->
1371
To push an event back into the event queue, use
1372
<function>XPutBackEvent</function>.
1373
<indexterm significance="preferred"><primary>XPutBackEvent</primary></indexterm>
1377
<funcdef><function>XPutBackEvent</function></funcdef>
1378
<paramdef>Display<parameter> *display</parameter></paramdef>
1379
<paramdef>XEvent<parameter> *event</parameter></paramdef>
1386
<emphasis remap='I'>display</emphasis>
1390
Specifies the connection to the X server.
1396
<emphasis remap='I'>event</emphasis>
1400
Specifies the event.
1410
<function>XPutBackEvent</function>
1411
function pushes an event back onto the head of the display's event queue
1412
by copying the event into the queue.
1413
This can be useful if you read an event and then decide that you
1414
would rather deal with it later.
1415
There is no limit to the number of times in succession that you can call
1416
<function>XPutBackEvent</function>.
1419
<sect1 id="Sending_Events_to_Other_Applications">
1420
<title>Sending Events to Other Applications</title>
1422
<!-- (SN Sending Events to Other Applications -->
1426
To send an event to a specified window, use
1427
<function>XSendEvent</function>.
1428
<indexterm><primary>XSendEvent</primary></indexterm>
1429
This function is often used in selection processing.
1430
For example, the owner of a selection should use
1431
<function>XSendEvent</function>
1433
<symbol>SelectionNotify</symbol>
1434
event to a requestor when a selection has been converted
1435
and stored as a property.
1436
<indexterm significance="preferred"><primary>XSendEvent</primary></indexterm>
1440
<funcdef>Status <function>XSendEvent</function></funcdef>
1441
<paramdef>Display<parameter> *display</parameter></paramdef>
1442
<paramdef>Window<parameter> w</parameter></paramdef>
1443
<paramdef>Bool<parameter> propagate</parameter></paramdef>
1444
<paramdef>long<parameter> event_mask</parameter></paramdef>
1445
<paramdef>XEvent<parameter> *event_send</parameter></paramdef>
1452
<emphasis remap='I'>display</emphasis>
1456
Specifies the connection to the X server.
1462
<emphasis remap='I'>w</emphasis>
1466
Specifies the window the event is to be sent to, or
1467
<symbol>PointerWindow</symbol>,
1469
<symbol>InputFocus</symbol>.
1475
<emphasis remap='I'>propagate</emphasis>
1479
Specifies a Boolean value.
1485
<emphasis remap='I'>event_mask</emphasis>
1489
Specifies the event mask.
1495
<emphasis remap='I'>event_send</emphasis>
1499
Specifies the event that is to be sent.
1509
<function>XSendEvent</function>
1510
function identifies the destination window,
1511
determines which clients should receive the specified events,
1512
and ignores any active grabs.
1513
This function requires you to pass an event mask.
1514
For a discussion of the valid event mask names,
1516
This function uses the w argument to identify the destination window as follows:
1522
<symbol>PointerWindow</symbol>,
1523
the destination window is the window that contains the pointer.
1529
<symbol>InputFocus</symbol>
1530
and if the focus window contains the pointer,
1531
the destination window is the window that contains the pointer;
1532
otherwise, the destination window is the focus window.
1538
To determine which clients should receive the specified events,
1539
<function>XSendEvent</function>
1540
uses the propagate argument as follows:
1545
If event_mask is the empty set,
1546
the event is sent to the client that created the destination window.
1547
If that client no longer exists,
1554
<symbol>False</symbol>,
1555
the event is sent to every client selecting on destination any of the event
1556
types in the event_mask argument.
1562
<symbol>True</symbol>
1563
and no clients have selected on destination any of
1564
the event types in event-mask, the destination is replaced with the
1565
closest ancestor of destination for which some client has selected a
1566
type in event-mask and for which no intervening window has that type in its
1567
do-not-propagate-mask.
1568
If no such window exists or if the window is
1569
an ancestor of the focus window and
1570
<symbol>InputFocus</symbol>
1571
was originally specified
1572
as the destination, the event is not sent to any clients.
1573
Otherwise, the event is reported to every client selecting on the final
1574
destination any of the types specified in event_mask.
1581
<structname>XEvent</structname>
1582
structure must be one of the core events or one of the events
1583
defined by an extension (or a
1584
<errorname>BadValue</errorname>
1585
error results) so that the X server can correctly byte-swap
1586
the contents as necessary.
1587
The contents of the event are
1588
otherwise unaltered and unchecked by the X server except to force send_event to
1589
<symbol>True</symbol>
1590
in the forwarded event and to set the serial number in the event correctly;
1591
therefore these fields
1592
and the display field are ignored by
1593
<function>XSendEvent</function>.
1597
<function>XSendEvent</function>
1598
returns zero if the conversion to wire protocol format failed
1599
and returns nonzero otherwise.
1603
<function>XSendEvent</function>
1605
<errorname>BadValue</errorname>
1607
<errorname>BadWindow</errorname>
1611
<sect1 id="Getting_Pointer_Motion_History">
1612
<title>Getting Pointer Motion History</title>
1614
<!-- (SN Getting Pointer Motion History -->
1618
Some X server implementations will maintain a more complete
1619
history of pointer motion than is reported by event notification.
1620
The pointer position at each pointer hardware interrupt may be
1621
stored in a buffer for later retrieval.
1622
This buffer is called the motion history buffer.
1623
For example, a few applications, such as paint programs,
1624
want to have a precise history of where the pointer
1626
However, this historical information is highly excessive for most applications.
1631
To determine the approximate maximum number of elements in the motion buffer,
1633
<function>XDisplayMotionBufferSize</function>.
1634
<indexterm significance="preferred"><primary>XDisplayMotionBufferSize</primary></indexterm>
1638
<funcdef>unsigned <type>long</type></funcdef>
1639
<paramdef>Display<parameter> *display</parameter></paramdef>
1646
<emphasis remap='I'>display</emphasis>
1650
Specifies the connection to the X server.
1659
The server may retain the recent history of the pointer motion
1660
and do so to a finer granularity than is reported by
1661
<symbol>MotionNotify</symbol>
1664
<function>XGetMotionEvents</function>
1665
function makes this history available.
1670
To get the motion history for a specified window and time, use
1671
<function>XGetMotionEvents</function>.
1672
<indexterm significance="preferred"><primary>XGetMotionEvents</primary></indexterm>
1676
<funcdef>XTimeCoord *<function>XGetMotionEvents</function></funcdef>
1677
<paramdef>Display<parameter> *display</parameter></paramdef>
1678
<paramdef>Window<parameter> w</parameter></paramdef>
1679
<paramdef>Timestart,<parameter> stop</parameter></paramdef>
1680
<paramdef>int<parameter> *nevents_return</parameter></paramdef>
1687
<emphasis remap='I'>display</emphasis>
1691
Specifies the connection to the X server.
1697
<emphasis remap='I'>w</emphasis>
1701
Specifies the window.
1707
<emphasis remap='I'>start</emphasis>
1718
<emphasis remap='I'>stop</emphasis>
1722
Specify the time interval in which the events are returned from the motion
1724
You can pass a timestamp or
1725
<symbol>CurrentTime</symbol>.
1731
<emphasis remap='I'>nevents_return</emphasis>
1735
Returns the number of events from the motion history buffer.
1745
<function>XGetMotionEvents</function>
1746
function returns all events in the motion history buffer that fall between the
1747
specified start and stop times, inclusive, and that have coordinates
1748
that lie within the specified window (including its borders) at its present
1750
If the server does not support motion history,
1751
if the start time is later than the stop time,
1752
or if the start time is in the future,
1753
no events are returned;
1754
<function>XGetMotionEvents</function>
1756
If the stop time is in the future, it is equivalent to specifying
1757
<symbol>CurrentTime</symbol>.
1758
The return type for this function is a structure defined as follows:
1762
<indexterm significance="preferred"><primary>XTimeCoord</primary></indexterm>
1764
<literallayout class="monospaced">
1776
The time member is set to the time, in milliseconds.
1777
The x and y members are set to the coordinates of the pointer and
1778
are reported relative to the origin
1779
of the specified window.
1780
To free the data returned from this call, use
1781
<function>XFree</function>.
1785
<function>XGetMotionEvents</function>
1787
<errorname>BadWindow</errorname>
1791
<sect1 id="Handling_Protocol_Errors">
1792
<title>Handling Protocol Errors</title>
1794
<!-- (SN Handling Protocol Errors -->
1798
Xlib provides functions that you can use to enable or disable synchronization
1799
and to use the default error handlers.
1801
<sect2 id="Enabling_or_Disabling_Synchronization">
1802
<title>Enabling or Disabling Synchronization</title>
1804
<!-- (SN Enabling or Disabling Synchronization -->
1808
When debugging X applications,
1809
it often is very convenient to require Xlib to behave synchronously
1810
so that errors are reported as they occur.
1811
The following function lets you disable or enable synchronous behavior.
1812
Note that graphics may occur 30 or more times more slowly when
1813
synchronization is enabled.
1814
<indexterm><primary>_Xdebug</primary></indexterm>
1815
On <acronym>POSIX</acronym>-conformant systems,
1816
there is also a global variable
1817
<varname>_Xdebug</varname>
1818
that, if set to nonzero before starting a program under a debugger, will force
1819
synchronous library behavior.
1823
After completing their work,
1824
all Xlib functions that generate protocol requests call what is known as
1826
<function>XSetAfterFunction</function>
1827
sets which function is to be called.
1828
<indexterm significance="preferred"><primary>XSetAfterFunction</primary></indexterm>
1832
<funcdef><type>int</type></funcdef>
1833
<paramdef>Display<parameter> *display</parameter></paramdef>
1834
<paramdef>int<parameter> (*procedure)()</parameter></paramdef>
1841
<emphasis remap='I'>display</emphasis>
1845
Specifies the connection to the X server.
1851
<emphasis remap='I'>procedure</emphasis>
1855
Specifies the procedure to be called.
1864
The specified procedure is called with only a display pointer.
1865
<function>XSetAfterFunction</function>
1866
returns the previous after function.
1870
To enable or disable synchronization, use
1871
<function>XSynchronize</function>.
1872
<indexterm><primary>Debugging</primary><secondary>synchronous mode</secondary></indexterm>
1873
<indexterm significance="preferred"><primary>XSynchronize</primary></indexterm>
1877
<funcdef><type>int</type></funcdef>
1878
<paramdef>Display<parameter> *display</parameter></paramdef>
1879
<paramdef>Bool<parameter> onoff</parameter></paramdef>
1886
<emphasis remap='I'>display</emphasis>
1890
Specifies the connection to the X server.
1896
<emphasis remap='I'>onoff</emphasis>
1900
Specifies a Boolean value that indicates whether to enable
1901
or disable synchronization.
1911
<function>XSynchronize</function>
1913
the previous after function.
1915
<symbol>True</symbol>,
1916
<function>XSynchronize</function>
1917
turns on synchronous behavior.
1919
<symbol>False</symbol>,
1920
<function>XSynchronize</function>
1921
turns off synchronous behavior.
1924
<sect2 id="Using_the_Default_Error_Handlers">
1925
<title>Using the Default Error Handlers</title>
1927
<!-- (SN Using the Default Error Handlers -->
1931
<indexterm><primary>Debugging</primary><secondary>error handlers</secondary></indexterm>
1932
<indexterm><primary>Error</primary><secondary>handlers</secondary></indexterm>
1933
There are two default error handlers in Xlib:
1934
one to handle typically fatal conditions (for example,
1935
the connection to a display server dying because a machine crashed)
1936
and one to handle protocol errors from the X server.
1937
These error handlers can be changed to user-supplied routines if you
1938
prefer your own error handling and can be changed as often as you like.
1939
If either function is passed a NULL pointer, it will
1940
reinvoke the default handler.
1941
The action of the default handlers is to print an explanatory
1947
To set the error handler, use
1948
<function>XSetErrorHandler</function>.
1949
<indexterm significance="preferred"><primary>XSetErrorHandler</primary></indexterm>
1953
<funcdef>int *<function>XSetErrorHandler</function></funcdef>
1954
<paramdef>int <parameter> *handler</parameter></paramdef>
1961
<emphasis remap='I'>handler</emphasis>
1965
Specifies the program's supplied error handler.
1974
Xlib generally calls the program's
1975
supplied error handler whenever an error is received.
1977
<errorname>BadName</errorname>
1979
<systemitem>OpenFont</systemitem>,
1980
<systemitem>LookupColor</systemitem>,
1982
<systemitem>AllocNamedColor</systemitem>
1983
protocol requests or on
1984
<errorname>BadFont</errorname>
1986
<systemitem>QueryFont</systemitem>
1988
These errors generally are reflected back to the program through the
1989
procedural interface.
1990
Because this condition is not assumed to be fatal,
1991
it is acceptable for your error handler to return;
1992
the returned value is ignored.
1993
However, the error handler should not
1994
call any functions (directly or indirectly) on the display
1995
that will generate protocol requests or that will look for input events.
1996
The previous error handler is returned.
2001
<structname>XErrorEvent</structname>
2003
<indexterm><primary>Debugging</primary><secondary>error event</secondary></indexterm>
2007
<indexterm significance="preferred"><primary>XErrorEvent</primary></indexterm>
2008
<literallayout class="monospaced">
2009
<!-- .TA .5i 2.5i -->
2010
<!-- .ta .5i 2.5i -->
2013
Display *display; /* Display the event was read from */
2014
unsigned long serial; /* serial number of failed request */
2015
unsigned char error_code; /* error code of failed request */
2016
unsigned char request_code; /* Major op-code of failed request */
2017
unsigned char minor_code; /* Minor op-code of failed request */
2018
XID resourceid; /* resource id */
2024
<indexterm><primary>Serial Number</primary></indexterm>
2025
The serial member is the number of requests, starting from one,
2026
sent over the network connection since it was opened.
2027
It is the number that was the value of
2028
<function>NextRequest</function>
2029
immediately before the failing call was made.
2030
The request_code member is a protocol request
2031
of the procedure that failed, as defined in
2032
< X11/Xproto.h .>
2033
The following error codes can be returned by the functions described in this
2038
<indexterm><primary>Debugging</primary><secondary>error numbers</secondary></indexterm>
2039
<indexterm><primary>Error</primary><secondary>codes</secondary></indexterm>
2041
<!-- .\"Error Codes -->
2042
<indexterm significance="preferred"><primary>BadAccess</primary></indexterm>
2043
<indexterm significance="preferred"><primary>BadAlloc</primary></indexterm>
2044
<indexterm significance="preferred"><primary>BadAtom</primary></indexterm>
2045
<indexterm significance="preferred"><primary>BadColor</primary></indexterm>
2046
<indexterm significance="preferred"><primary>BadCursor</primary></indexterm>
2047
<indexterm significance="preferred"><primary>BadDrawable</primary></indexterm>
2048
<indexterm significance="preferred"><primary>BadFont</primary></indexterm>
2049
<indexterm significance="preferred"><primary>BadGC</primary></indexterm>
2050
<indexterm significance="preferred"><primary>BadIDChoice</primary></indexterm>
2052
<tgroup cols='2' align='center'>
2053
<colspec colname='c1'/>
2054
<colspec colname='c2'/>
2057
<entry>Error Code</entry>
2058
<entry>Description</entry>
2063
<entry><errorname>BadAccess</errorname></entry>
2064
<entry>A client attempts to grab a key/button combination already grabbed
2065
by another client.</entry>
2069
<entry>A client attempts to free a colormap entry that it had not already allocated
2070
or to free an entry in a colormap that was created with all entries writable.</entry>
2074
<entry>A client attempts to store into a read-only or unallocated colormap entry.</entry>
2078
<entry>A client attempts to modify the access control list from other than the local
2079
(or otherwise authorized) host.</entry>
2083
<entry>A client attempts to select an event type that another client
2084
has already selected.</entry>
2087
<entry><errorname>BadAlloc</errorname></entry>
2088
<entry>The server fails to allocate the requested resource.
2089
Note that the explicit listing of
2090
<errorname>BadAlloc</errorname>
2091
errors in requests only covers allocation errors at a very coarse level
2092
and is not intended to (nor can it in practice hope to) cover all cases of
2093
a server running out of allocation space in the middle of service.
2094
The semantics when a server runs out of allocation space are left unspecified,
2095
but a server may generate a
2096
<errorname>BadAlloc</errorname>
2097
error on any request for this reason,
2098
and clients should be prepared to receive such errors and handle or discard
2102
<entry><errorname>BadAtom</errorname></entry>
2103
<entry>A value for an atom argument does not name a defined atom.</entry>
2106
<entry><errorname>BadColor</errorname></entry>
2107
<entry>A value for a colormap argument does not name a defined colormap.</entry>
2110
<entry><errorname>BadCursor</errorname></entry>
2111
<entry>A value for a cursor argument does not name a defined cursor.</entry>
2114
<entry><errorname>BadDrawable</errorname></entry>
2115
<entry>A value for a drawable argument does not name a defined window or pixmap.</entry>
2118
<entry><errorname>BadFont</errorname></entry>
2119
<entry>A value for a font argument does not name a defined font (or, in some cases,
2120
<type>GContext</type>).</entry>
2123
<entry><errorname>BadGC</errorname></entry>
2124
<entry>A value for a
2125
<type>GContext</type>
2126
argument does not name a defined
2127
<type>GContext</type>.</entry>
2130
<entry><errorname>BadIDChoice</errorname></entry>
2131
<entry>The value chosen for a resource identifier either is not included in the
2132
range assigned to the client or is already in use.
2133
Under normal circumstances,
2134
this cannot occur and should be considered a server or Xlib error.</entry>
2137
<entry><errorname>BadImplementation</errorname></entry>
2138
<entry>The server does not implement some aspect of the request.
2139
A server that generates this error for a core request is deficient.
2140
As such, this error is not listed for any of the requests,
2141
but clients should be prepared to receive such errors
2142
and handle or discard them.</entry>
2145
<entry><errorname>BadLength</errorname></entry>
2146
<entry>The length of a request is shorter or longer than that required to
2147
contain the arguments.
2148
This is an internal Xlib or server error.</entry>
2153
The length of a request exceeds the maximum length accepted by the server.</entry>
2156
<entry><errorname>BadMatch</errorname></entry>
2157
<entry>In a graphics request,
2158
the root and depth of the graphics context do not match those of the drawable.</entry>
2162
<entry>An <symbol>InputOnly</symbol> window is used as a drawable.</entry>
2167
Some argument or pair of arguments has the correct type and range,
2168
but it fails to match in some other way required by the request.</entry>
2172
<entry>An <symbol>InputOnly</symbol>
2173
window lacks this attribute.</entry>
2176
<entry><errorname>BadName</errorname></entry>
2177
<entry>A font or color of the specified name does not exist.</entry>
2180
<entry><errorname>BadPixmap</errorname></entry>
2181
<entry>A value for a pixmap argument does not name a defined pixmap.</entry>
2184
<entry><errorname>BadRequest</errorname></entry>
2185
<entry>The major or minor opcode does not specify a valid request.
2186
This usually is an Xlib or server error.</entry>
2189
<entry><errorname>BadValue</errorname></entry>
2190
<entry>Some numeric value falls outside of the range of values accepted
2192
Unless a specific range is specified for an argument,
2193
the full range defined by the argument's type is accepted.
2194
Any argument defined as a set of alternatives typically can generate
2195
this error (due to the encoding).</entry>
2198
<entry><errorname>BadWindow</errorname></entry>
2199
<entry>A value for a window argument does not name a defined window.</entry>
2205
<indexterm significance="preferred"><primary>BadImplementation</primary></indexterm>
2206
<indexterm significance="preferred"><primary>BadLength</primary></indexterm>
2207
<indexterm significance="preferred"><primary>BadMatch</primary></indexterm>
2208
<indexterm significance="preferred"><primary>BadName</primary></indexterm>
2209
<indexterm significance="preferred"><primary>BadPixmap</primary></indexterm>
2210
<indexterm significance="preferred"><primary>BadRequest</primary></indexterm>
2211
<indexterm significance="preferred"><primary>BadValue</primary></indexterm>
2212
<indexterm significance="preferred"><primary>BadWindow</primary></indexterm>
2218
<errorname>BadAtom</errorname>,
2219
<errorname>BadColor</errorname>,
2220
<errorname>BadCursor</errorname>,
2221
<errorname>BadDrawable</errorname>,
2222
<errorname>BadFont</errorname>,
2223
<errorname>BadGC</errorname>,
2224
<errorname>BadPixmap</errorname>,
2226
<errorname>BadWindow</errorname>
2227
errors are also used when the argument type is extended by a set of
2236
To obtain textual descriptions of the specified error code, use
2237
<function>XGetErrorText</function>.
2238
<indexterm significance="preferred"><primary>XGetErrorText</primary></indexterm>
2239
<indexterm><primary>Debugging</primary><secondary>error message strings</secondary></indexterm>
2243
<funcdef><function>XGetErrorText</function></funcdef>
2244
<paramdef>Display<parameter> *display</parameter></paramdef>
2245
<paramdef>int<parameter> code</parameter></paramdef>
2246
<paramdef>char<parameter> *buffer_return</parameter></paramdef>
2247
<paramdef>int<parameter> length</parameter></paramdef>
2254
<emphasis remap='I'>display</emphasis>
2258
Specifies the connection to the X server.
2264
<emphasis remap='I'>code</emphasis>
2268
Specifies the error code for which you want to obtain a description.
2274
<emphasis remap='I'>buffer_return</emphasis>
2278
Returns the error description.
2284
<emphasis remap='I'>length</emphasis>
2288
Specifies the size of the buffer.
2298
<function>XGetErrorText</function>
2299
function copies a null-terminated string describing the specified error code
2300
into the specified buffer.
2301
The returned text is in the encoding of the current locale.
2302
It is recommended that you use this function to obtain an error description
2303
because extensions to Xlib may define their own error codes
2309
To obtain error messages from the error database, use
2310
<function>XGetErrorDatabaseText</function>.
2311
<indexterm significance="preferred"><primary>XGetErrorDatabaseText</primary></indexterm>
2315
<funcdef><function>XGetErrorDatabaseText</function></funcdef>
2316
<paramdef>Display<parameter> *display</parameter></paramdef>
2317
<paramdef>char*name,<parameter> *message</parameter></paramdef>
2318
<paramdef>char<parameter> *default_string</parameter></paramdef>
2319
<paramdef>char<parameter> *buffer_return</parameter></paramdef>
2320
<paramdef>int<parameter> length</parameter></paramdef>
2327
<emphasis remap='I'>display</emphasis>
2331
Specifies the connection to the X server.
2337
<emphasis remap='I'>name</emphasis>
2341
Specifies the name of the application.
2347
<emphasis remap='I'>message</emphasis>
2351
Specifies the type of the error message.
2357
<emphasis remap='I'>default_string</emphasis>
2361
Specifies the default error message if none is found in the database.
2367
<emphasis remap='I'>buffer_return</emphasis>
2371
Returns the error description.
2377
<emphasis remap='I'>length</emphasis>
2381
Specifies the size of the buffer.
2391
<function>XGetErrorDatabaseText</function>
2392
function returns a null-terminated message
2393
(or the default message) from the error message
2395
Xlib uses this function internally to look up its error messages.
2396
The text in the default_string argument is assumed
2397
to be in the encoding of the current locale,
2398
and the text stored in the buffer_return argument
2399
is in the encoding of the current locale.
2403
The name argument should generally be the name of your application.
2404
The message argument should indicate which type of error message you want.
2405
If the name and message are not in the Host Portable Character Encoding,
2406
the result is implementation-dependent.
2407
Xlib uses three predefined ``application names'' to report errors.
2409
uppercase and lowercase matter.
2417
The protocol error number is used as a string for the message argument.
2427
These are the message strings that are used internally by the library.
2437
For a core protocol request,
2438
the major request protocol number is used for the message argument.
2439
For an extension request,
2440
the extension name (as given by
2441
<function>InitExtension</function>)
2442
followed by a period (.) and the minor request protocol number
2443
is used for the message argument.
2444
If no string is found in the error database,
2445
the default_string is returned to the buffer argument.
2454
To report an error to the user when the requested display does not exist, use
2455
<function>XDisplayName</function>.
2456
<indexterm significance="preferred"><primary>XDisplayName</primary></indexterm>
2460
<funcdef>char *<function>XDisplayName</function></funcdef>
2461
<paramdef>char<parameter> *string</parameter></paramdef>
2468
<emphasis remap='I'>string</emphasis>
2472
Specifies the character string.
2482
<function>XDisplayName</function>
2483
function returns the name of the display that
2484
<function>XOpenDisplay</function>
2485
would attempt to use.
2486
If a NULL string is specified,
2487
<function>XDisplayName</function>
2488
looks in the environment for the display and returns the display name that
2489
<function>XOpenDisplay</function>
2490
would attempt to use.
2491
This makes it easier to report to the user precisely which display the
2492
program attempted to open when the initial connection attempt failed.
2497
To handle fatal I/O errors, use
2498
<function>XSetIOErrorHandler</function>.
2499
<indexterm significance="preferred"><primary>XSetIOErrorHandler</primary></indexterm>
2503
<funcdef><type>int</type></funcdef>
2504
<paramdef>int(*handler)(Display<parameter> *)</parameter></paramdef>
2511
<emphasis remap='I'>handler</emphasis>
2515
Specifies the program's supplied error handler.
2525
<function>XSetIOErrorHandler</function>
2526
sets the fatal I/O error handler.
2527
Xlib calls the program's supplied error handler if any sort of system call
2528
error occurs (for example, the connection to the server was lost).
2529
This is assumed to be a fatal condition,
2530
and the called routine should not return.
2531
If the I/O error handler does return,
2532
the client process exits.
2536
Note that the previous error handler is returned.
added
removed
specs/libX11/CH11.xml
