diff options
Diffstat (limited to 'libX11/specs/libX11/CH11')
| -rw-r--r-- | libX11/specs/libX11/CH11 | 1664 |
1 files changed, 0 insertions, 1664 deletions
diff --git a/libX11/specs/libX11/CH11 b/libX11/specs/libX11/CH11 deleted file mode 100644 index 09d845d35..000000000 --- a/libX11/specs/libX11/CH11 +++ /dev/null @@ -1,1664 +0,0 @@ -.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium -.\" -.\" Permission is hereby granted, free of charge, to any person obtaining -.\" a copy of this software and associated documentation files (the -.\" "Software"), to deal in the Software without restriction, including -.\" without limitation the rights to use, copy, modify, merge, publish, -.\" distribute, sublicense, and/or sell copies of the Software, and to -.\" permit persons to whom the Software is furnished to do so, subject to -.\" the following conditions: -.\" -.\" The above copyright notice and this permission notice shall be included -.\" in all copies or substantial portions of the Software. -.\" -.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS -.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. -.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR -.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, -.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR -.\" OTHER DEALINGS IN THE SOFTWARE. -.\" -.\" Except as contained in this notice, the name of the X Consortium shall -.\" not be used in advertising or otherwise to promote the sale, use or -.\" other dealings in this Software without prior written authorization -.\" from the X Consortium. -.\" -.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by -.\" Digital Equipment Corporation -.\" -.\" Portions Copyright \(co 1990, 1991 by -.\" Tektronix, Inc. -.\" -.\" Permission to use, copy, modify and distribute this documentation for -.\" any purpose and without fee is hereby granted, provided that the above -.\" copyright notice appears in all copies and that both that copyright notice -.\" and this permission notice appear in all copies, and that the names of -.\" Digital and Tektronix not be used in in advertising or publicity pertaining -.\" to this documentation without specific, written prior permission. -.\" Digital and Tektronix makes no representations about the suitability -.\" of this documentation for any purpose. -.\" It is provided ``as is'' without express or implied warranty. -.\" -\& -.sp 1 -.ce 3 -\s+1\fBChapter 11\fP\s-1 - -\s+1\fBEvent Handling Functions\fP\s-1 -.sp 2 -.nr H1 11 -.nr H2 0 -.nr H3 0 -.nr H4 0 -.nr H5 0 -.na -.LP -.XS -Chapter 11: Event Handling Functions -.XE -This chapter discusses the Xlib functions you can use to: -.IP \(bu 5 -Select events -.IP \(bu 5 -Handle the output buffer and the event queue -.IP \(bu 5 -Select events from the event queue -.IP \(bu 5 -Send and get events -.IP \(bu 5 -Handle protocol errors -.NT Note -Some toolkits use their own event-handling functions -and do not allow you to interchange these event-handling functions -with those in Xlib. -For further information, -see the documentation supplied with the toolkit. -.NE -.LP -Most applications simply are event loops: -they wait for an event, decide what to do with it, -execute some amount of code that results in changes to the display, -and then wait for the next event. -.NH 2 -Selecting Events -.XS -\*(SN Selecting Events -.XE -.LP -There are two ways to select the events you want reported to your client -application. -One way is to set the event_mask member of the -.PN XSetWindowAttributes -structure when you call -.PN XCreateWindow -and -.PN XChangeWindowAttributes . -Another way is to use -.PN XSelectInput . -.IN "XSelectInput" "" "@DEF@" -.sM -.FD 0 -XSelectInput\^(\^\fIdisplay\fP, \fIw\fP\^, \fIevent_mask\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - long \fIevent_mask\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.ds Wi whose events you are interested in -.IP \fIw\fP 1i -Specifies the window \*(Wi. -.IP \fIevent_mask\fP 1i -Specifies the event mask. -.LP -.eM -The -.PN XSelectInput -function requests that the X server report the events associated with the -specified event mask. -Initially, X will not report any of these events. -Events are reported relative to a window. -If a window is not interested in a device event, it usually propagates to -the closest ancestor that is interested, -unless the do_not_propagate mask prohibits it. -.IN "Event" "propagation" -.LP -Setting the event-mask attribute of a window overrides any previous call -for the same window but not for other clients. -Multiple clients can select for the same events on the same window -with the following restrictions: -.IP \(bu 5 -Multiple clients can select events on the same window because their event masks -are disjoint. -When the X server generates an event, it reports it -to all interested clients. -.IP \(bu 5 -Only one client at a time can select -.PN CirculateRequest , -.PN ConfigureRequest , -or -.PN MapRequest -events, which are associated with -the event mask -.PN SubstructureRedirectMask . -.IP \(bu 5 -Only one client at a time can select -a -.PN ResizeRequest -event, which is associated with -the event mask -.PN ResizeRedirectMask . -.IP \(bu 5 -Only one client at a time can select a -.PN ButtonPress -event, which is associated with -the event mask -.PN ButtonPressMask . -.LP -The server reports the event to all interested clients. -.LP -.PN XSelectInput -can generate a -.PN BadWindow -error. -.NH 2 -Handling the Output Buffer -.XS -\*(SN Handling the Output Buffer -.XE -.LP -The output buffer is an area used by Xlib to store requests. -The functions described in this section flush the output buffer -if the function would block or not return an event. -That is, all requests residing in the output buffer that -have not yet been sent are transmitted to the X server. -These functions differ in the additional tasks they might perform. -.LP -.sp -To flush the output buffer, use -.PN XFlush . -.IN "XFlush" "" "@DEF@" -.sM -.FD 0 -XFlush\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -The -.PN XFlush -function -flushes the output buffer. -Most client applications need not use this function because the output -buffer is automatically flushed as needed by calls to -.PN XPending , -.PN XNextEvent , -and -.PN XWindowEvent . -.IN "XPending" -.IN "XNextEvent" -.IN "XWindowEvent" -Events generated by the server may be enqueued into the library's event queue. -.LP -.sp -To flush the output buffer and then wait until all requests have been processed, -use -.PN XSync . -.IN "XSync" "" "@DEF@" -.sM -.FD 0 -XSync\^(\^\fIdisplay\fP, \fIdiscard\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Bool \fIdiscard\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIdiscard\fP 1i -Specifies a Boolean value that indicates whether -.PN XSync -discards all events on the event queue. -.LP -.eM -The -.PN XSync -function -flushes the output buffer and then waits until all requests have been received -and processed by the X server. -Any errors generated must be handled by the error handler. -For each protocol error received by Xlib, -.PN XSync -calls the client application's error handling routine (see section 11.8.2). -Any events generated by the server are enqueued into the library's -event queue. -.LP -Finally, if you passed -.PN False , -.PN XSync -does not discard the events in the queue. -If you passed -.PN True , -.PN XSync -discards all events in the queue, -including those events that were on the queue before -.PN XSync -was called. -Client applications seldom need to call -.PN XSync . -.NH 2 -Event Queue Management -.XS -\*(SN Event Queue Management -.XE -.LP -Xlib maintains an event queue. -However, the operating system also may be buffering data -in its network connection that is not yet read into the event queue. -.LP -.sp -To check the number of events in the event queue, use -.PN XEventsQueued . -.IN "XEventsQueued" "" "@DEF@" -.sM -.FD 0 -int XEventsQueued\^(\^\fIdisplay\fP, \fImode\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fImode\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fImode\fP 1i -Specifies the mode. -You can pass -.PN QueuedAlready , -.PN QueuedAfterFlush , -or -.PN QueuedAfterReading . -.LP -.eM -If mode is -.PN QueuedAlready , -.PN XEventsQueued -returns the number of events -already in the event queue (and never performs a system call). -If mode is -.PN QueuedAfterFlush , -.PN XEventsQueued -returns the number of events already in the queue if the number is nonzero. -If there are no events in the queue, -.PN XEventsQueued -flushes the output buffer, -attempts to read more events out of the application's connection, -and returns the number read. -If mode is -.PN QueuedAfterReading , -.PN XEventsQueued -returns the number of events already in the queue if the number is nonzero. -If there are no events in the queue, -.PN XEventsQueued -attempts to read more events out of the application's connection -without flushing the output buffer and returns the number read. -.LP -.PN XEventsQueued -always returns immediately without I/O if there are events already in the -queue. -.PN XEventsQueued -with mode -.PN QueuedAfterFlush -is identical in behavior to -.PN XPending . -.PN XEventsQueued -with mode -.PN QueuedAlready -is identical to the -.PN XQLength -function. -.LP -.sp -To return the number of events that are pending, use -.PN XPending . -.IN "XPending" "" "@DEF@" -.sM -.FD 0 -int XPending\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -The -.PN XPending -function returns the number of events that have been received from the -X server but have not been removed from the event queue. -.PN XPending -is identical to -.PN XEventsQueued -with the mode -.PN QueuedAfterFlush -specified. -.NH 2 -Manipulating the Event Queue -.XS -\*(SN Manipulating the Event Queue -.XE -.LP -Xlib provides functions that let you manipulate the event queue. -This section discusses how to: -.IP \(bu 5 -Obtain events, in order, and remove them from the queue -.IP \(bu 5 -Peek at events in the queue without removing them -.IP \(bu 5 -Obtain events that match the event mask or the arbitrary -predicate procedures that you provide -.NH 3 -Returning the Next Event -.XS -\*(SN Returning the Next Event -.XE -.LP -To get the next event and remove it from the queue, use -.PN XNextEvent . -.IN "XNextEvent" "" "@DEF@" -.sM -.FD 0 -XNextEvent\^(\^\fIdisplay\fP, \fIevent_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XEvent *\fIevent_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIevent_return\fP 1i -Returns the next event in the queue. -.LP -.eM -The -.PN XNextEvent -function copies the first event from the event queue into the specified -.PN XEvent -structure and then removes it from the queue. -If the event queue is empty, -.PN XNextEvent -flushes the output buffer and blocks until an event is received. -.LP -.sp -To peek at the event queue, use -.PN XPeekEvent . -.IN "XPeekEvent" "" "@DEF@" -.sM -.FD 0 -XPeekEvent\^(\^\fIdisplay\fP, \fIevent_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XEvent *\fIevent_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIevent_return\fP 1i -Returns a copy of the matched event's associated structure. -.LP -.eM -The -.PN XPeekEvent -function returns the first event from the event queue, -but it does not remove the event from the queue. -If the queue is empty, -.PN XPeekEvent -flushes the output buffer and blocks until an event is received. -It then copies the event into the client-supplied -.PN XEvent -structure without removing it from the event queue. -.NH 3 -Selecting Events Using a Predicate Procedure -.XS -\*(SN Selecting Events Using a Predicate Procedure -.XE -.LP -Each of the functions discussed in this section requires you to -pass a predicate procedure that determines if an event matches -what you want. -Your predicate procedure must decide if the event is useful -without calling any Xlib functions. -If the predicate directly or indirectly causes the state of the event queue -to change, the result is not defined. -If Xlib has been initialized for threads, the predicate is called with -the display locked and the result of a call by the predicate to any -Xlib function that locks the display is not defined unless the caller -has first called -.PN XLockDisplay . -.LP -The predicate procedure and its associated arguments are: -.sM -.FD 0 -Bool (\^*\fIpredicate\fP\^)\^(\^\fIdisplay\fP, \fIevent\fP, \fIarg\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XEvent *\fIevent\fP\^; -.br - XPointer \fIarg\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIevent\fP 1i -Specifies the -.PN XEvent -structure. -.IP \fIarg\fP 1i -Specifies the argument passed in from the -.PN XIfEvent , -.PN XCheckIfEvent , -or -.PN XPeekIfEvent -function. -.LP -.eM -The predicate procedure is called once for each -event in the queue until it finds a match. -After finding a match, the predicate procedure must return -.PN True . -If it did not find a match, it must return -.PN False . -.LP -.sp -To check the event queue for a matching event -and, if found, remove the event from the queue, use -.PN XIfEvent . -.IN "XIfEvent" "" "@DEF@" -.sM -.FD 0 -XIfEvent\^(\^\fIdisplay\fP, \fIevent_return\fP, \fIpredicate\fP, \fIarg\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XEvent *\fIevent_return\fP\^; -.br - Bool (\^*\fIpredicate\fP\^)\^(\^)\^; -.br - XPointer \fIarg\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIevent_return\fP 1i -Returns the matched event's associated structure. -.IP \fIpredicate\fP 1i -Specifies the procedure that is to be called to determine -if the next event in the queue matches what you want. -.IP \fIarg\fP 1i -Specifies the user-supplied argument that will be passed to the predicate procedure. -.LP -.eM -The -.PN XIfEvent -function completes only when the specified predicate -procedure returns -.PN True -for an event, -which indicates an event in the queue matches. -.PN XIfEvent -flushes the output buffer if it blocks waiting for additional events. -.PN XIfEvent -removes the matching event from the queue -and copies the structure into the client-supplied -.PN XEvent -structure. -.LP -.sp -To check the event queue for a matching event without blocking, use -.PN XCheckIfEvent . -.IN "XCheckIfEvent" "" "@DEF@" -.sM -.FD 0 -Bool XCheckIfEvent\^(\^\fIdisplay\fP, \fIevent_return\fP, \fIpredicate\fP, \fIarg\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XEvent *\fIevent_return\fP\^; -.br - Bool (\^*\fIpredicate\fP\^)\^(\^)\^; -.br - XPointer \fIarg\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIevent_return\fP 1i -Returns a copy of the matched event's associated structure. -.IP \fIpredicate\fP 1i -Specifies the procedure that is to be called to determine -if the next event in the queue matches what you want. -.IP \fIarg\fP 1i -Specifies the user-supplied argument that will be passed to the predicate procedure. -.LP -.eM -When the predicate procedure finds a match, -.PN XCheckIfEvent -copies the matched event into the client-supplied -.PN XEvent -structure and returns -.PN True . -(This event is removed from the queue.) -If the predicate procedure finds no match, -.PN XCheckIfEvent -returns -.PN False , -and the output buffer will have been flushed. -All earlier events stored in the queue are not discarded. -.LP -.sp -To check the event queue for a matching event -without removing the event from the queue, use -.PN XPeekIfEvent . -.IN "XPeekIfEvent" "" "@DEF@" -.sM -.FD 0 -XPeekIfEvent\^(\^\fIdisplay\fP, \fIevent_return\fP, \fIpredicate\fP, \fIarg\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XEvent *\fIevent_return\fP\^; -.br - Bool (\^*\fIpredicate\fP\^)\^(\^)\^; -.br - XPointer \fIarg\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIevent_return\fP 1i -Returns a copy of the matched event's associated structure. -.IP \fIpredicate\fP 1i -Specifies the procedure that is to be called to determine -if the next event in the queue matches what you want. -.IP \fIarg\fP 1i -Specifies the user-supplied argument that will be passed to the predicate procedure. -.LP -.eM -The -.PN XPeekIfEvent -function returns only when the specified predicate -procedure returns -.PN True -for an event. -After the predicate procedure finds a match, -.PN XPeekIfEvent -copies the matched event into the client-supplied -.PN XEvent -structure without removing the event from the queue. -.PN XPeekIfEvent -flushes the output buffer if it blocks waiting for additional events. -.NH 3 -Selecting Events Using a Window or Event Mask -.XS -\*(SN Selecting Events Using a Window or Event Mask -.XE -.LP -The functions discussed in this section let you select events by window -or event types, allowing you to process events out of order. -.LP -.sp -To remove the next event that matches both a window and an event mask, use -.PN XWindowEvent . -.IN "XWindowEvent" "" "@DEF@" -.sM -.FD 0 -XWindowEvent\^(\^\fIdisplay\fP, \fIw\fP\^, \fIevent_mask\fP\^, \fIevent_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - long \fIevent_mask\fP\^; -.br - XEvent *\fIevent_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.ds Wi whose events you are interested in -.IP \fIw\fP 1i -Specifies the window \*(Wi. -.IP \fIevent_mask\fP 1i -Specifies the event mask. -.IP \fIevent_return\fP 1i -Returns the matched event's associated structure. -.LP -.eM -The -.PN XWindowEvent -function searches the event queue for an event that matches both the specified -window and event mask. -When it finds a match, -.PN XWindowEvent -removes that event from the queue and copies it into the specified -.PN XEvent -structure. -The other events stored in the queue are not discarded. -If a matching event is not in the queue, -.PN XWindowEvent -flushes the output buffer and blocks until one is received. -.LP -.sp -To remove the next event that matches both a window and an event mask (if any), -use -.PN XCheckWindowEvent . -.IN "XCheckWindowEvent" -This function is similar to -.PN XWindowEvent -except that it never blocks and it returns a -.PN Bool -indicating if the event was returned. -.IN "XCheckWindowEvent" "" "@DEF@" -.sM -.FD 0 -Bool XCheckWindowEvent\^(\^\fIdisplay\fP, \fIw\fP\^, \fIevent_mask\fP\^, \fIevent_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - long \fIevent_mask\fP\^; -.br - XEvent *\fIevent_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.ds Wi whose events you are interested in -.IP \fIw\fP 1i -Specifies the window \*(Wi. -.IP \fIevent_mask\fP 1i -Specifies the event mask. -.IP \fIevent_return\fP 1i -Returns the matched event's associated structure. -.LP -.eM -The -.PN XCheckWindowEvent -function searches the event queue and then the events available -on the server connection for the first event that matches the specified window -and event mask. -If it finds a match, -.PN XCheckWindowEvent -removes that event, copies it into the specified -.PN XEvent -structure, and returns -.PN True . -The other events stored in the queue are not discarded. -If the event you requested is not available, -.PN XCheckWindowEvent -returns -.PN False , -and the output buffer will have been flushed. -.LP -.sp -To remove the next event that matches an event mask, use -.PN XMaskEvent . -.IN "XMaskEvent" "" "@DEF@" -.sM -.FD 0 -XMaskEvent\^(\^\fIdisplay\fP, \fIevent_mask\fP\^, \fIevent_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - long \fIevent_mask\fP\^; -.br - XEvent *\fIevent_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIevent_mask\fP 1i -Specifies the event mask. -.IP \fIevent_return\fP 1i -Returns the matched event's associated structure. -.LP -.eM -The -.PN XMaskEvent -function searches the event queue for the events associated with the -specified mask. -When it finds a match, -.PN XMaskEvent -removes that event and copies it into the specified -.PN XEvent -structure. -The other events stored in the queue are not discarded. -If the event you requested is not in the queue, -.PN XMaskEvent -flushes the output buffer and blocks until one is received. -.LP -.sp -To return and remove the next event that matches an event mask (if any), use -.PN XCheckMaskEvent . -This function is similar to -.PN XMaskEvent -except that it never blocks and it returns a -.PN Bool -indicating if the event was returned. -.IN "XCheckMaskEvent" "" "@DEF@" -.sM -.FD 0 -Bool XCheckMaskEvent\^(\^\fIdisplay\fP, \fIevent_mask\fP\^, \fIevent_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - long \fIevent_mask\fP\^; -.br - XEvent *\fIevent_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIevent_mask\fP 1i -Specifies the event mask. -.IP \fIevent_return\fP 1i -Returns the matched event's associated structure. -.LP -.eM -The -.PN XCheckMaskEvent -function searches the event queue and then any events available on the -server connection for the first event that matches the specified mask. -If it finds a match, -.PN XCheckMaskEvent -removes that event, copies it into the specified -.PN XEvent -structure, and returns -.PN True . -The other events stored in the queue are not discarded. -If the event you requested is not available, -.PN XCheckMaskEvent -returns -.PN False , -and the output buffer will have been flushed. -.LP -.sp -To return and remove the next event in the queue that matches an event type, use -.PN XCheckTypedEvent . -.IN "XCheckTypedEvent" "" "@DEF@" -.sM -.FD 0 -Bool XCheckTypedEvent\^(\^\fIdisplay\fP, \fIevent_type\fP\^, \fIevent_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIevent_type\fP\^; -.br - XEvent *\fIevent_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIevent_type\fP 1i -Specifies the event type to be compared. - -.IP \fIevent_return\fP 1i -Returns the matched event's associated structure. -.LP -.eM -The -.PN XCheckTypedEvent -function searches the event queue and then any events available -on the server connection for the first event that matches the specified type. -If it finds a match, -.PN XCheckTypedEvent -removes that event, copies it into the specified -.PN XEvent -structure, and returns -.PN True . -The other events in the queue are not discarded. -If the event is not available, -.PN XCheckTypedEvent -returns -.PN False , -and the output buffer will have been flushed. -.LP -.sp -To return and remove the next event in the queue that matches an event type -and a window, use -.PN XCheckTypedWindowEvent . -.IN "XCheckTypedWindowEvent" "" "@DEF@" -.sM -.FD 0 -Bool XCheckTypedWindowEvent\^(\^\fIdisplay\fP, \fIw\fP\^, \fIevent_type\fP\^, \fIevent_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - int \fIevent_type\fP\^; -.br - XEvent *\fIevent_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIevent_type\fP 1i -Specifies the event type to be compared. - -.IP \fIevent_return\fP 1i -Returns the matched event's associated structure. -.LP -.eM -The -.PN XCheckTypedWindowEvent -function searches the event queue and then any events available -on the server connection for the first event that matches the specified -type and window. -If it finds a match, -.PN XCheckTypedWindowEvent -removes the event from the queue, copies it into the specified -.PN XEvent -structure, and returns -.PN True . -The other events in the queue are not discarded. -If the event is not available, -.PN XCheckTypedWindowEvent -returns -.PN False , -and the output buffer will have been flushed. -.NH 2 -Putting an Event Back into the Queue -.XS -\*(SN Putting an Event Back into the Queue -.XE -.LP -To push an event back into the event queue, use -.PN XPutBackEvent . -.IN "XPutBackEvent" "" "@DEF@" -.sM -.FD 0 -XPutBackEvent\^(\^\fIdisplay\fP, \fIevent\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XEvent *\fIevent\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIevent\fP 1i -Specifies the event. -.LP -.eM -The -.PN XPutBackEvent -function pushes an event back onto the head of the display's event queue -by copying the event into the queue. -This can be useful if you read an event and then decide that you -would rather deal with it later. -There is no limit to the number of times in succession that you can call -.PN XPutBackEvent . -.NH 2 -Sending Events to Other Applications -.XS -\*(SN Sending Events to Other Applications -.XE -.LP -To send an event to a specified window, use -.PN XSendEvent . -.IN "XSendEvent" -This function is often used in selection processing. -For example, the owner of a selection should use -.PN XSendEvent -to send a -.PN SelectionNotify -event to a requestor when a selection has been converted -and stored as a property. -.IN "XSendEvent" "" "@DEF@" -.sM -.FD 0 -Status XSendEvent\^(\^\fIdisplay\fP, \fIw\fP\^, \fIpropagate\fP\^, \fIevent_mask\fP\^, \fIevent_send\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - Bool \fIpropagate\fP\^; -.br - long \fIevent_mask\fP\^; -.br - XEvent *\fIevent_send\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window the event is to be sent to, or -.PN PointerWindow , -or -.PN InputFocus . -.IP \fIpropagate\fP 1i -Specifies a Boolean value. -.IP \fIevent_mask\fP 1i -Specifies the event mask. -.IP \fIevent_send\fP 1i -Specifies the event that is to be sent. -.LP -.eM -The -.PN XSendEvent -function identifies the destination window, -determines which clients should receive the specified events, -and ignores any active grabs. -This function requires you to pass an event mask. -For a discussion of the valid event mask names, -see section 10.3. -This function uses the w argument to identify the destination window as follows: -.IP \(bu 5 -If w is -.PN PointerWindow , -the destination window is the window that contains the pointer. -.IP \(bu 5 -If w is -.PN InputFocus -and if the focus window contains the pointer, -the destination window is the window that contains the pointer; -otherwise, the destination window is the focus window. -.LP -To determine which clients should receive the specified events, -.PN XSendEvent -uses the propagate argument as follows: -.IP \(bu 5 -If event_mask is the empty set, -the event is sent to the client that created the destination window. -If that client no longer exists, -no event is sent. -.IP \(bu 5 -If propagate is -.PN False , -the event is sent to every client selecting on destination any of the event -types in the event_mask argument. -.IP \(bu 5 -If propagate is -.PN True -and no clients have selected on destination any of -the event types in event-mask, the destination is replaced with the -closest ancestor of destination for which some client has selected a -type in event-mask and for which no intervening window has that type in its -do-not-propagate-mask. -If no such window exists or if the window is -an ancestor of the focus window and -.PN InputFocus -was originally specified -as the destination, the event is not sent to any clients. -Otherwise, the event is reported to every client selecting on the final -destination any of the types specified in event_mask. -.LP -The event in the -.PN XEvent -structure must be one of the core events or one of the events -defined by an extension (or a -.PN BadValue -error results) so that the X server can correctly byte-swap -the contents as necessary. -The contents of the event are -otherwise unaltered and unchecked by the X server except to force send_event to -.PN True -in the forwarded event and to set the serial number in the event correctly; -therefore these fields -and the display field are ignored by -.PN XSendEvent . -.LP -.PN XSendEvent -returns zero if the conversion to wire protocol format failed -and returns nonzero otherwise. -.LP -.PN XSendEvent -can generate -.PN BadValue -and -.PN BadWindow -errors. -.NH 2 -Getting Pointer Motion History -.XS -\*(SN Getting Pointer Motion History -.XE -.LP -Some X server implementations will maintain a more complete -history of pointer motion than is reported by event notification. -The pointer position at each pointer hardware interrupt may be -stored in a buffer for later retrieval. -This buffer is called the motion history buffer. -For example, a few applications, such as paint programs, -want to have a precise history of where the pointer -traveled. -However, this historical information is highly excessive for most applications. -.LP -.sp -To determine the approximate maximum number of elements in the motion buffer, -use -.PN XDisplayMotionBufferSize . -.IN "XDisplayMotionBufferSize" "" "@DEF@" -.sM -.FD 0 -unsigned long XDisplayMotionBufferSize\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -The server may retain the recent history of the pointer motion -and do so to a finer granularity than is reported by -.PN MotionNotify -events. -The -.PN XGetMotionEvents -function makes this history available. -.LP -.sp -To get the motion history for a specified window and time, use -.PN XGetMotionEvents . -.IN "XGetMotionEvents" "" "@DEF@" -.sM -.FD 0 -XTimeCoord *XGetMotionEvents\^(\^\fIdisplay\fP, \fIw\fP\^, \fIstart\fP\^, \fIstop\fP\^, \fInevents_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - Time \fIstart\fP\^, \fIstop\fP\^; -.br - int *\fInevents_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIstart\fP 1i -.br -.ns -.IP \fIstop\fP 1i -Specify the time interval in which the events are returned from the motion -history buffer. -You can pass a timestamp or -.PN CurrentTime . -.IP \fInevents_return\fP 1i -Returns the number of events from the motion history buffer. -.LP -.eM -The -.PN XGetMotionEvents -function returns all events in the motion history buffer that fall between the -specified start and stop times, inclusive, and that have coordinates -that lie within the specified window (including its borders) at its present -placement. -If the server does not support motion history, -if the start time is later than the stop time, -or if the start time is in the future, -no events are returned; -.PN XGetMotionEvents -returns NULL. -If the stop time is in the future, it is equivalent to specifying -.PN CurrentTime . -The return type for this function is a structure defined as follows: -.LP -.IN "XTimeCoord" "" "@DEF@" -.sM -.Ds 0 -.TA .5i -.ta .5i -typedef struct { - Time time; - short x, y; -} XTimeCoord; -.De -.LP -.eM -The time member is set to the time, in milliseconds. -The x and y members are set to the coordinates of the pointer and -are reported relative to the origin -of the specified window. -To free the data returned from this call, use -.PN XFree . -.LP -.PN XGetMotionEvents -can generate a -.PN BadWindow -error. -.NH 2 -Handling Protocol Errors -.XS -\*(SN Handling Protocol Errors -.XE -.LP -Xlib provides functions that you can use to enable or disable synchronization -and to use the default error handlers. -.NH 3 -Enabling or Disabling Synchronization -.XS -\*(SN Enabling or Disabling Synchronization -.XE -.LP -When debugging X applications, -it often is very convenient to require Xlib to behave synchronously -so that errors are reported as they occur. -The following function lets you disable or enable synchronous behavior. -Note that graphics may occur 30 or more times more slowly when -synchronization is enabled. -.IN "_Xdebug" -On POSIX-conformant systems, -there is also a global variable -.PN _Xdebug -that, if set to nonzero before starting a program under a debugger, will force -synchronous library behavior. -.LP -After completing their work, -all Xlib functions that generate protocol requests call what is known as -an after function. -.PN XSetAfterFunction -sets which function is to be called. -.IN "XSetAfterFunction" "" "@DEF@" -.sM -.FD 0 -int (*XSetAfterFunction\^(\^\fIdisplay\fP, \fIprocedure\fP\^))() -.br - Display *\fIdisplay\fP\^; -.br - int (\^*\^\fIprocedure\fP\^)\^(); -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIprocedure\fP 1i -Specifies the procedure to be called. -.LP -.eM -The specified procedure is called with only a display pointer. -.PN XSetAfterFunction -returns the previous after function. -.LP -To enable or disable synchronization, use -.PN XSynchronize . -.IN "Debugging" "synchronous mode" -.IN "XSynchronize" "" "@DEF@" -.sM -.FD 0 -int (*XSynchronize\^(\^\fIdisplay\fP, \fIonoff\fP\^)\^)() -.br - Display *\fIdisplay\fP\^; -.br - Bool \fIonoff\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIonoff\fP 1i -Specifies a Boolean value that indicates whether to enable -or disable synchronization. -.LP -.eM -The -.PN XSynchronize -function returns -the previous after function. -If onoff is -.PN True , -.PN XSynchronize -turns on synchronous behavior. -If onoff is -.PN False , -.PN XSynchronize -turns off synchronous behavior. -.NH 3 -Using the Default Error Handlers -.XS -\*(SN Using the Default Error Handlers -.XE -.LP -.IN "Debugging" "error handlers" -.IN "Error" "handlers" -There are two default error handlers in Xlib: -one to handle typically fatal conditions (for example, -the connection to a display server dying because a machine crashed) -and one to handle protocol errors from the X server. -These error handlers can be changed to user-supplied routines if you -prefer your own error handling and can be changed as often as you like. -If either function is passed a NULL pointer, it will -reinvoke the default handler. -The action of the default handlers is to print an explanatory -message and exit. -.LP -.sp -To set the error handler, use -.PN XSetErrorHandler . -.IN "XSetErrorHandler" "" "@DEF@" -.sM -.FD 0 -int (*XSetErrorHandler\^(\^\fIhandler\fP\^)\^)\^(\^) -.br - int (\^*\^\fIhandler\fP\^)\^(Display *, XErrorEvent *) -.FN -.IP \fIhandler\fP 1i -Specifies the program's supplied error handler. -.LP -.eM -Xlib generally calls the program's -supplied error handler whenever an error is received. -It is not called on -.PN BadName -errors from -.PN OpenFont , -.PN LookupColor , -or -.PN AllocNamedColor -protocol requests or on -.PN BadFont -errors from a -.PN QueryFont -protocol request. -These errors generally are reflected back to the program through the -procedural interface. -Because this condition is not assumed to be fatal, -it is acceptable for your error handler to return; -the returned value is ignored. -However, the error handler should not -call any functions (directly or indirectly) on the display -that will generate protocol requests or that will look for input events. -The previous error handler is returned. -.LP -The -.PN XErrorEvent -structure contains: -.IN "Debugging" "error event" -.LP -.IN "XErrorEvent" "" "@DEF" -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -typedef struct { - int type; - Display *display; /* Display the event was read from */ - unsigned long serial; /* serial number of failed request */ - unsigned char error_code; /* error code of failed request */ - unsigned char request_code; /* Major op-code of failed request */ - unsigned char minor_code; /* Minor op-code of failed request */ - XID resourceid; /* resource id */ -} XErrorEvent; -.De -.LP -.IN "Serial Number" -The serial member is the number of requests, starting from one, -sent over the network connection since it was opened. -It is the number that was the value of -.PN NextRequest -immediately before the failing call was made. -The request_code member is a protocol request -of the procedure that failed, as defined in -.hN X11/Xproto.h . -The following error codes can be returned by the functions described in this -chapter: -.br -.ne 13 -.IN "Debugging" "error numbers" -.IN "Error" "codes" -.\".CP T 3 -.\"Error Codes -.IN "BadAccess" "" "@DEF@" -.IN "BadAlloc" "" "@DEF@" -.IN "BadAtom" "" "@DEF@" -.IN "BadColor" "" "@DEF@" -.IN "BadCursor" "" "@DEF@" -.IN "BadDrawable" "" "@DEF@" -.IN "BadFont" "" "@DEF@" -.IN "BadGC" "" "@DEF@" -.IN "BadIDChoice" "" "@DEF@" -.TS H -l c -lw(1.75i) lw(4i). -_ -.sp 6p -.B -Error Code Description -.sp 6p -_ -.sp 6p -.TH -.R -T{ -.PN BadAccess -T} T{ -A client attempts to grab a key/button combination already grabbed -by another client. -.sp 3p -A client attempts to free a colormap entry that it had not already allocated -or to free an entry in a colormap that was created with all entries writable. -.sp 3p -A client attempts to store into a read-only or unallocated colormap entry. -.sp 3p -A client attempts to modify the access control list from other than the local -(or otherwise authorized) host. -.sp 3p -A client attempts to select an event type that another client -has already selected. -T} -.sp 3p -T{ -.PN BadAlloc -T} T{ -The server fails to allocate the requested resource. -Note that the explicit listing of -.PN BadAlloc -errors in requests only covers allocation errors at a very coarse level -and is not intended to (nor can it in practice hope to) cover all cases of -a server running out of allocation space in the middle of service. -The semantics when a server runs out of allocation space are left unspecified, -but a server may generate a -.PN BadAlloc -error on any request for this reason, -and clients should be prepared to receive such errors and handle or discard -them. -T} -.sp 3p -T{ -.PN BadAtom -T} T{ -A value for an atom argument does not name a defined atom. -T} -.sp 3p -T{ -.PN BadColor -T} T{ -A value for a colormap argument does not name a defined colormap. -T} -.sp 3p -T{ -.PN BadCursor -T} T{ -A value for a cursor argument does not name a defined cursor. -T} -.sp 3p -T{ -.PN BadDrawable -T} T{ -A value for a drawable argument does not name a defined window or pixmap. -T} -.sp 3p -T{ -.PN BadFont -T} T{ -A value for a font argument does not name a defined font (or, in some cases, -.PN GContext ). -T} -.sp 3p -T{ -.PN BadGC -T} T{ -A value for a -.PN GContext -argument does not name a defined -.PN GContext . -T} -.sp 3p -T{ -.PN BadIDChoice -T} T{ -The value chosen for a resource identifier either is not included in the -range assigned to the client or is already in use. -Under normal circumstances, -this cannot occur and should be considered a server or Xlib error. -T} -.sp 3p -T{ -.PN BadImplementation -T} T{ -The server does not implement some aspect of the request. -A server that generates this error for a core request is deficient. -As such, this error is not listed for any of the requests, -but clients should be prepared to receive such errors -and handle or discard them. -T} -.sp 3p -T{ -.PN BadLength -T} T{ -The length of a request is shorter or longer than that required to -contain the arguments. -This is an internal Xlib or server error. -.sp 3p -The length of a request exceeds the maximum length accepted by the server. -T} -.sp 3p -T{ -.PN BadMatch -T} T{ -In a graphics request, -the root and depth of the graphics context do not match those of the drawable. -.sp 3p -An -.PN InputOnly -window is used as a drawable. -.sp 3p -Some argument or pair of arguments has the correct type and range, -but it fails to match in some other way required by the request. -.sp 3p -An -.PN InputOnly -window lacks this attribute. -T} -.sp 3p -T{ -.PN BadName -T} T{ -A font or color of the specified name does not exist. -T} -.sp 3p -T{ -.PN BadPixmap -T} T{ -A value for a pixmap argument does not name a defined pixmap. -T} -.sp 3p -T{ -.PN BadRequest -T} T{ -The major or minor opcode does not specify a valid request. -This usually is an Xlib or server error. -T} -.sp 3p -T{ -.PN BadValue -T} T{ -Some numeric value falls outside of the range of values accepted -by the request. -Unless a specific range is specified for an argument, -the full range defined by the argument's type is accepted. -Any argument defined as a set of alternatives typically can generate -this error (due to the encoding). -T} -.sp 3p -T{ -.PN BadWindow -T} T{ -A value for a window argument does not name a defined window. -T} -.sp 6p -_ -.TE -.IN "BadImplementation" "" "@DEF@" -.IN "BadLength" "" "@DEF@" -.IN "BadMatch" "" "@DEF@" -.IN "BadName" "" "@DEF@" -.IN "BadPixmap" "" "@DEF@" -.IN "BadRequest" "" "@DEF@" -.IN "BadValue" "" "@DEF@" -.IN "BadWindow" "" "@DEF@" -.NT Note -The -.PN BadAtom , -.PN BadColor , -.PN BadCursor , -.PN BadDrawable , -.PN BadFont , -.PN BadGC , -.PN BadPixmap , -and -.PN BadWindow -errors are also used when the argument type is extended by a set of -fixed alternatives. -.NE -.sp -.LP -To obtain textual descriptions of the specified error code, use -.PN XGetErrorText . -.IN "XGetErrorText" "" "@DEF@" -.IN "Debugging" "error message strings" -.sM -.FD 0 -XGetErrorText\^(\^\fIdisplay\fP, \fIcode\fP, \fIbuffer_return\fP, \fIlength\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIcode\fP\^; -.br - char *\fIbuffer_return\fP\^; -.br - int \fIlength\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcode\fP 1i -Specifies the error code for which you want to obtain a description. -.IP \fIbuffer_return\fP 1i -Returns the error description. -.IP \fIlength\fP 1i -Specifies the size of the buffer. -.LP -.eM -The -.PN XGetErrorText -function copies a null-terminated string describing the specified error code -into the specified buffer. -The returned text is in the encoding of the current locale. -It is recommended that you use this function to obtain an error description -because extensions to Xlib may define their own error codes -and error strings. -.LP -.sp -To obtain error messages from the error database, use -.PN XGetErrorDatabaseText . -.IN "XGetErrorDatabaseText" "" "@DEF@" -.sM -.FD 0 -XGetErrorDatabaseText\^(\^\fIdisplay\fP, \fIname\fP, \fImessage\fP, \fIdefault_string\fP, \fIbuffer_return\fP, \fIlength\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - char *\fIname\fP, *\fImessage\fP\^; -.br - char *\fIdefault_string\fP\^; -.br - char *\fIbuffer_return\fP\^; -.br - int \fIlength\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIname\fP 1i -Specifies the name of the application. -.IP \fImessage\fP 1i -Specifies the type of the error message. -.IP \fIdefault_string\fP 1i -Specifies the default error message if none is found in the database. -.IP \fIbuffer_return\fP 1i -Returns the error description. -.IP \fIlength\fP 1i -Specifies the size of the buffer. -.LP -.eM -The -.PN XGetErrorDatabaseText -function returns a null-terminated message -(or the default message) from the error message -database. -Xlib uses this function internally to look up its error messages. -The text in the default_string argument is assumed -to be in the encoding of the current locale, -and the text stored in the buffer_return argument -is in the encoding of the current locale. -.LP -The name argument should generally be the name of your application. -The message argument should indicate which type of error message you want. -If the name and message are not in the Host Portable Character Encoding, -the result is implementation-dependent. -Xlib uses three predefined ``application names'' to report errors. -In these names, -uppercase and lowercase matter. -.IP XProtoError 1i -The protocol error number is used as a string for the message argument. -.IP XlibMessage 1i -These are the message strings that are used internally by the library. -.IP XRequest 1i -For a core protocol request, -the major request protocol number is used for the message argument. -For an extension request, -the extension name (as given by -.PN InitExtension ) -followed by a period (\.) and the minor request protocol number -is used for the message argument. -If no string is found in the error database, -the default_string is returned to the buffer argument. -.LP -.sp -To report an error to the user when the requested display does not exist, use -.PN XDisplayName . -.IN "XDisplayName" "" "@DEF@" -.sM -.FD 0 -char *XDisplayName\^(\^\fIstring\fP\^) -.br - char *\fIstring\fP\^; -.FN -.IP \fIstring\fP 1i -Specifies the character string. -.LP -.eM -The -.PN XDisplayName -function returns the name of the display that -.PN XOpenDisplay -would attempt to use. -If a NULL string is specified, -.PN XDisplayName -looks in the environment for the display and returns the display name that -.PN XOpenDisplay -would attempt to use. -This makes it easier to report to the user precisely which display the -program attempted to open when the initial connection attempt failed. -.LP -.sp -To handle fatal I/O errors, use -.PN XSetIOErrorHandler . -.IN "XSetIOErrorHandler" "" "@DEF@" -.sM -.FD 0 -int (*XSetIOErrorHandler\^(\^\fIhandler\fP\^)\^)\^(\^) -.br - int (\^*\^\fIhandler\fP\^)(Display *); -.FN -.IP \fIhandler\fP 1i -Specifies the program's supplied error handler. -.LP -.eM -The -.PN XSetIOErrorHandler -sets the fatal I/O error handler. -Xlib calls the program's supplied error handler if any sort of system call -error occurs (for example, the connection to the server was lost). -This is assumed to be a fatal condition, -and the called routine should not return. -If the I/O error handler does return, -the client process exits. -.LP -Note that the previous error handler is returned. -.bp |