diff options
Diffstat (limited to 'libX11/specs/libX11/CH02')
| -rw-r--r-- | libX11/specs/libX11/CH02 | 2051 |
1 files changed, 0 insertions, 2051 deletions
diff --git a/libX11/specs/libX11/CH02 b/libX11/specs/libX11/CH02 deleted file mode 100644 index dbf0b4850..000000000 --- a/libX11/specs/libX11/CH02 +++ /dev/null @@ -1,2051 +0,0 @@ -.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996, 2000 The Open Group -.\" -.\" 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 Open Group 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 Open Group. -.\" -.\" 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 2\fP\s-1 - -\s+1\fBDisplay Functions\fP\s-1 -.sp 2 -.nr H1 2 -.nr H2 0 -.nr H3 0 -.nr H4 0 -.nr H5 0 -.na -.LP -.XS -Chapter 2: Display Functions -.XE -Before your program can use a display, you must establish a connection -to the X server. -Once you have established a connection, -you then can use the Xlib macros and functions discussed in this chapter -to return information about the display. -This chapter discusses how to: -.IP \(bu 5 -Open (connect to) the display -.IP \(bu 5 -Obtain information about the display, image formats, or screens -.IP \(bu 5 -Generate a -.PN NoOperation -protocol request -.IP \(bu 5 -Free client-created data -.IP \(bu 5 -Close (disconnect from) a display -.IP \(bu 5 -Use X Server connection close operations -.IP \(bu 5 -Use Xlib with threads -.IP \(bu 5 -Use internal connections -.NH 2 -Opening the Display -.XS -\*(SN Opening the Display -.XE -.LP -To open a connection to the X server that controls a display, use -.PN XOpenDisplay . -.IN "XOpenDisplay" "" "@DEF@" -.LP -.sM -.FD 0 -Display *XOpenDisplay\^(\^\fIdisplay_name\fP\^) -.br - char *\fIdisplay_name\fP\^; -.FN -.IP \fIdisplay_name\fP 1i -Specifies the hardware display name, which determines the display -and communications domain to be used. -On a POSIX-conformant system, if the display_name is NULL, -it defaults to the value of the DISPLAY environment variable. -.IN "Environment" "DISPLAY" -.LP -.eM -The encoding and interpretation of the display name are -implementation-dependent. -Strings in the Host Portable Character Encoding are supported; -support for other characters is implementation-dependent. -On POSIX-conformant systems, -the display name or DISPLAY environment variable can be a string in the format: -.LP -.sM -.Ds 0 -.TA 1i -.ta 1i - \fIprotocol\fP\^/\^\fIhostname\fP\^:\^\fInumber\fP\^.\^\fIscreen_number\fP -.De -.IP \fIprotocol\fP 1i -Specifies a protocol family or an alias for a protocol family. Supported -protocol families are implementation dependent. The protocol entry is -optional. If protocol is not specified, the / separating protocol and -hostname must also not be specified. -.IP \fIhostname\fP 1i -Specifies the name of the host machine on which the display is physically -attached. -You follow the hostname with either a single colon (:) or a double colon (::). -.IP \fInumber\fP 1i -Specifies the number of the display server on that host machine. -You may optionally follow this display number with a period (.). -A single CPU can have more than one display. -Multiple displays are usually numbered starting with zero. -.IN "Screen" -.IP \fIscreen_number\fP 1i -Specifies the screen to be used on that server. -Multiple screens can be controlled by a single X server. -The screen_number sets an internal variable that can be accessed by -using the -.PN DefaultScreen -macro or the -.PN XDefaultScreen -function if you are using languages other than C (see section 2.2.1). -.LP -.eM -For example, the following would specify screen 1 of display 0 on the -machine named ``dual-headed'': -.LP -.Ds -dual-headed:0.1 -.De -.LP -The -.PN XOpenDisplay -function returns a -.PN Display -structure that serves as the -connection to the X server and that contains all the information -about that X server. -.PN XOpenDisplay -connects your application to the X server through TCP -or DECnet communications protocols, -or through some local inter-process communication protocol. -.IN "Protocol" "TCP" -.IN "Protocol" "DECnet" -If the protocol is specified as "tcp", "inet", or "inet6", or -if no protocol is specified and the hostname is a host machine name and a single colon (:) -separates the hostname and display number, -.PN XOpenDisplay -connects using TCP streams. (If the protocol is specified as "inet", TCP over -IPv4 is used. If the protocol is specified as "inet6", TCP over IPv6 is used. -Otherwise, the implementation determines which IP version is used.) -If the hostname and protocol are both not specified, -Xlib uses whatever it believes is the fastest transport. -If the hostname is a host machine name and a double colon (::) -separates the hostname and display number, -.PN XOpenDisplay -connects using DECnet. -A single X server can support any or all of these transport mechanisms -simultaneously. -A particular Xlib implementation can support many more of these transport -mechanisms. -.LP -.IN "Display" -If successful, -.PN XOpenDisplay -returns a pointer to a -.PN Display -structure, -which is defined in -.hN X11/Xlib.h . -If -.PN XOpenDisplay -does not succeed, it returns NULL. -After a successful call to -.PN XOpenDisplay , -all of the screens in the display can be used by the client. -The screen number specified in the display_name argument is returned -by the -.PN DefaultScreen -macro (or the -.PN XDefaultScreen -function). -You can access elements of the -.PN Display -and -.PN Screen -structures only by using the information macros or functions. -For information about using macros and functions to obtain information from -the -.PN Display -structure, -see section 2.2.1. -.LP -X servers may implement various types of access control mechanisms -(see section 9.8). -.NH 2 -Obtaining Information about the Display, Image Formats, or Screens -.XS -\*(SN Obtaining Information about the Display, Image Formats, or Screens -.XE -.LP -The Xlib library provides a number of useful macros -and corresponding functions that return data from the -.PN Display -structure. -The macros are used for C programming, -and their corresponding function equivalents are for other language bindings. -This section discusses the: -.IP \(bu 5 -Display macros -.IP \(bu 5 -Image format functions and macros -.IP \(bu 5 -Screen information macros -.LP -.IN "Display" "data structure" -All other members of the -.PN Display -structure (that is, those for which no macros are defined) are private to Xlib -and must not be used. -Applications must never directly modify or inspect these private members of the -.PN Display -structure. -.NT Note -The -.PN XDisplayWidth , -.PN XDisplayHeight , -.PN XDisplayCells , -.PN XDisplayPlanes , -.PN XDisplayWidthMM , -and -.PN XDisplayHeightMM -functions in the next sections are misnamed. -These functions really should be named Screen\fIwhatever\fP -and XScreen\fIwhatever\fP, not Display\fIwhatever\fP or XDisplay\fIwhatever\fP. -Our apologies for the resulting confusion. -.NE -.NH 3 -Display Macros -.XS -\*(SN Display Macros -.XE -.LP -Applications should not directly modify any part of the -.PN Display -and -.PN Screen -structures. -The members should be considered read-only, -although they may change as the result of other operations on the display. -.LP -The following lists the C language macros, -their corresponding function equivalents that are for other language bindings, -and what data both can return. -.LP -.sp -.sM -.FD 0 -AllPlanes -.sp -unsigned long XAllPlanes(\^) -.FN -.LP -.eM -.IN "AllPlanes" "" "@DEF@" -.IN "XAllPlanes" "" "@DEF@" -Both return a value with all bits set to 1 suitable for use in a plane argument to -a procedure. -.LP -.sp -Both -.PN BlackPixel -and -.PN WhitePixel -can be used in implementing a monochrome application. -These pixel values are for permanently allocated entries in the default -colormap. -The actual RGB (red, green, and blue) values are settable on some screens -and, in any case, may not actually be black or white. -The names are intended to convey the expected relative intensity of the colors. -.sM -.FD 0 -BlackPixel\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.sp -unsigned long XBlackPixel\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIscreen_number\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIscreen_number\fP 1i -Specifies the appropriate screen number on the host server. -.LP -.eM -.IN "BlackPixel" "" "@DEF@" -.IN "XBlackPixel" "" "@DEF@" -Both return the black pixel value for the specified screen. -.LP -.sp -.sM -.FD 0 -WhitePixel\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.sp -unsigned long XWhitePixel\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIscreen_number\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIscreen_number\fP 1i -Specifies the appropriate screen number on the host server. -.LP -.eM -.IN "WhitePixel" "" "@DEF@" -.IN "XWhitePixel" "" "@DEF@" -Both return the white pixel value for the specified screen. -.LP -.sp -.sM -.FD 0 -ConnectionNumber\^(\^\fIdisplay\fP\^) -.sp -int XConnectionNumber\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -.IN "ConnectionNumber" "" "@DEF@" -.IN "XConnectionNumber" "" "@DEF@" -Both return a connection number for the specified display. -On a POSIX-conformant system, -this is the file descriptor of the connection. -.LP -.sp -.sM -.FD 0 -DefaultColormap\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.sp -Colormap XDefaultColormap\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIscreen_number\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIscreen_number\fP 1i -Specifies the appropriate screen number on the host server. -.LP -.eM -.IN "DefaultColormap" "" "@DEF@" -.IN "XDefaultColormap" "" "@DEF@" -Both return the default colormap ID for allocation on the specified screen. -Most routine allocations of color should be made out of this colormap. -.LP -.sp -.sM -.FD 0 -DefaultDepth\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.sp -int XDefaultDepth\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIscreen_number\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIscreen_number\fP 1i -Specifies the appropriate screen number on the host server. -.LP -.eM -.IN "DefaultDepth" "" "@DEF@" -.IN "XDefaultDepth" "" "@DEF@" -Both return the depth (number of planes) of the default root window for the -specified screen. -Other depths may also be supported on this screen (see -.PN XMatchVisualInfo ). -.LP -.sp -.IN "XListDepths" "" "@DEF@" -To determine the number of depths that are available on a given screen, use -.PN XListDepths . -.sM -.FD 0 -int *XListDepths\^(\^\fIdisplay\fP, \fIscreen_number\fP, \fIcount_return\fP\^) -.br - Display *\fIdisplay\fP; -.br - int \fIscreen_number\fP; -.br - int *\fIcount_return\fP; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIscreen_number\fP 1i -Specifies the appropriate screen number on the host server. -.ds Cn depths -.IP \fIcount_return\fP 1i -Returns the number of \*(Cn. -.LP -.eM -The -.PN XListDepths -function returns the array of depths -that are available on the specified screen. -If the specified screen_number is valid and sufficient memory for the array -can be allocated, -.PN XListDepths -sets count_return to the number of available depths. -Otherwise, it does not set count_return and returns NULL. -To release the memory allocated for the array of depths, use -.PN XFree . -.LP -.sp -.sM -.FD 0 -DefaultGC\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.sp -GC XDefaultGC\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIscreen_number\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIscreen_number\fP 1i -Specifies the appropriate screen number on the host server. -.LP -.eM -.IN "DefaultGC" "" "@DEF@" -.IN "XDefaultGC" "" "@DEF@" -Both return the default graphics context for the root window of the -specified screen. -This GC is created for the convenience of simple applications -and contains the default GC components with the foreground and -background pixel values initialized to the black and white -pixels for the screen, respectively. -You can modify its contents freely because it is not used in any Xlib -function. -This GC should never be freed. -.LP -.sp -.sM -.FD 0 -DefaultRootWindow\^(\^\fIdisplay\fP\^) -.sp -Window XDefaultRootWindow\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -.IN "DefaultRootWindow" "" "@DEF@" -.IN "XDefaultRootWindow" "" "@DEF@" -Both return the root window for the default screen. -.LP -.sp -.sM -.FD 0 -DefaultScreenOfDisplay\^(\^\fIdisplay\fP\^) -.sp -Screen *XDefaultScreenOfDisplay\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -.IN "DefaultScreenOfDisplay" "" "@DEF@" -.IN "XDefaultScreenOfDisplay" "" "@DEF@" -Both return a pointer to the default screen. -.LP -.sp -.sM -.FD 0 -ScreenOfDisplay\^(\^\fIdisplay\fP, \fIscreen_number\fP\^) -.sp -Screen *XScreenOfDisplay\^(\^\fIdisplay\fP, \fIscreen_number\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIscreen_number\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIscreen_number\fP 1i -Specifies the appropriate screen number on the host server. -.LP -.eM -.IN "ScreenOfDisplay" "" "@DEF@" -.IN "XScreenOfDisplay" "" "@DEF@" -Both return a pointer to the indicated screen. -.LP -.sp -.sM -.FD 0 -DefaultScreen\^(\^\fIdisplay\fP\^) -.sp -int XDefaultScreen\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -.IN "DefaultScreen" "" "@DEF@" -.IN "XDefaultScreen" "" "@DEF@" -Both return the default screen number referenced by the -.PN XOpenDisplay -function. -This macro or function should be used to retrieve the screen number -in applications that will use only a single screen. -.LP -.sp -.sM -.FD 0 -DefaultVisual\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.sp -Visual *XDefaultVisual\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIscreen_number\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIscreen_number\fP 1i -Specifies the appropriate screen number on the host server. -.LP -.eM -.IN "DefaultVisual" "" "@DEF@" -.IN "XDefaultVisual" "" "@DEF@" -Both return the default visual type for the specified screen. -For further information about visual types, -see section 3.1. -.LP -.sp -.sM -.FD 0 -DisplayCells\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.sp -int XDisplayCells\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIscreen_number\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIscreen_number\fP 1i -Specifies the appropriate screen number on the host server. -.LP -.eM -.IN "DisplayCells" "" "@DEF@" -.IN "XDisplayCells" "" "@DEF@" -Both return the number of entries in the default colormap. -.LP -.sp -.sM -.FD 0 -DisplayPlanes\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.sp -int XDisplayPlanes\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIscreen_number\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIscreen_number\fP 1i -Specifies the appropriate screen number on the host server. -.LP -.eM -.IN "DisplayPlanes" "" "@DEF@" -.IN "XDisplayPlanes" "" "@DEF@" -Both return the depth of the root window of the specified screen. -For an explanation of depth, -see the glossary. -.LP -.sp -.sM -.FD 0 -DisplayString\^(\^\fIdisplay\fP\^) -.sp -char *XDisplayString\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -.IN "DisplayString" "" "@DEF@" -.IN "XDisplayString" "" "@DEF@" -Both return the string that was passed to -.PN XOpenDisplay -when the current display was opened. -On POSIX-conformant systems, -if the passed string was NULL, these return the value of -the DISPLAY environment variable when the current display was opened. -.IN "POSIX System Call" "fork" -These are useful to applications that invoke the -.PN fork -system call and want to open a new connection to the same display from the -child process as well as for printing error messages. -.LP -.sp -.sM -.FD 0 -long XExtendedMaxRequestSize(\^\fIdisplay\fP\^) - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -.IN "XExtendedMaxRequestSize" "" "@DEF@" -The -.PN XExtendedMaxRequestSize -function returns zero if the specified display does not support an -extended-length protocol encoding; otherwise, -it returns the maximum request size (in 4-byte units) supported -by the server using the extended-length encoding. -The Xlib functions -.PN XDrawLines , -.PN XDrawArcs , -.PN XFillPolygon , -.PN XChangeProperty , -.PN XSetClipRectangles , -and -.PN XSetRegion -will use the extended-length encoding as necessary, if supported -by the server. Use of the extended-length encoding in other Xlib -functions (for example, -.PN XDrawPoints , -.PN XDrawRectangles , -.PN XDrawSegments , -.PN XFillArcs , -.PN XFillRectangles , -.PN XPutImage ) -is permitted but not required; an Xlib implementation may choose to -split the data across multiple smaller requests instead. -.LP -.sp -.sM -.FD 0 -long XMaxRequestSize(\^\fIdisplay\fP\^) - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -.IN "XMaxRequestSize" "" "@DEF@" -The -.PN XMaxRequestSize -function returns the maximum request size (in 4-byte units) supported -by the server without using an extended-length protocol encoding. -Single protocol requests to the server can be no larger than this size -unless an extended-length protocol encoding is supported by the server. -The protocol guarantees the size to be no smaller than 4096 units -(16384 bytes). -Xlib automatically breaks data up into multiple protocol requests -as necessary for the following functions: -.PN XDrawPoints , -.PN XDrawRectangles , -.PN XDrawSegments , -.PN XFillArcs , -.PN XFillRectangles , -and -.PN XPutImage . -.LP -.sp -.sM -.FD 0 -LastKnownRequestProcessed\^(\^\fIdisplay\fP\^) -.sp -unsigned long XLastKnownRequestProcessed\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -.IN "LastKnownRequestProcessed" "" "@DEF@" -.IN "XLastKnownRequestProcessed" "" "@DEF@" -Both extract the full serial number of the last request known by Xlib -to have been processed by the X server. -Xlib automatically sets this number when replies, events, and errors -are received. -.LP -.sp -.sM -.FD 0 -NextRequest\^(\^\fIdisplay\fP\^) -.sp -unsigned long XNextRequest\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -.IN "NextRequest" "" "@DEF@" -.IN "XNextRequest" "" "@DEF@" -Both extract the full serial number that is to be used for the next -request. -Serial numbers are maintained separately for each display connection. -.LP -.sp -.sM -.FD 0 -ProtocolVersion\^(\^\fIdisplay\fP\^) -.sp -int XProtocolVersion\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -.IN "ProtocolVersion" "" "@DEF@" -.IN "XProtocolVersion" "" "@DEF@" -Both return the major version number (11) of the X protocol associated with -the connected display. -.LP -.sp -.sM -.FD 0 -ProtocolRevision\^(\^\fIdisplay\fP\^) -.sp -int XProtocolRevision\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -.IN "ProtocolRevision" "" "@DEF@" -.IN "XProtocolRevision" "" "@DEF@" -Both return the minor protocol revision number of the X server. -.LP -.sp -.sM -.FD 0 -QLength\^(\^\fIdisplay\fP\^) -.sp -int XQLength\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -.IN "QLength" "" "@DEF@" -.IN "XQLength" "" "@DEF@" -Both return the length of the event queue for the connected display. -Note that there may be more events that have not been read into -the queue yet (see -.PN XEventsQueued ). -.LP -.sp -.sM -.FD 0 -RootWindow\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.sp -Window XRootWindow\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIscreen_number\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIscreen_number\fP 1i -Specifies the appropriate screen number on the host server. -.LP -.eM -.IN "Window" "RootWindow" -.IN "RootWindow" "" "@DEF@" -.IN "Window" "XRootWindow" -.IN "XRootWindow" "" "@DEF@" -Both return the root window. -These are useful with functions that need a drawable of a particular screen -and for creating top-level windows. -.LP -.sp -.sM -.FD 0 -ScreenCount\^(\^\fIdisplay\fP\^) -.sp -int XScreenCount\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -.IN "ScreenCount" "" "@DEF@" -.IN "XScreenCount" "" "@DEF@" -Both return the number of available screens. -.LP -.sp -.sM -.FD 0 -ServerVendor\^(\^\fIdisplay\fP\^) -.sp -char *XServerVendor\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -.IN "ServerVendor" "" "@DEF@" -.IN "XServerVendor" "" "@DEF@" -Both return a pointer to a null-terminated string that provides -some identification of the owner of the X server implementation. -If the data returned by the server is in the Latin Portable Character Encoding, -then the string is in the Host Portable Character Encoding. -Otherwise, the contents of the string are implementation-dependent. -.LP -.sp -.sM -.FD 0 -VendorRelease\^(\^\fIdisplay\fP\^) -.sp -int XVendorRelease\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -.IN "VendorRelease" "" "@DEF@" -.IN "XVendorRelease" "" "@DEF@" -Both return a number related to a vendor's release of the X server. -.NH 3 -Image Format Functions and Macros -.XS -\*(SN Image Format Functions and Macros -.XE -.LP -Applications are required to present data to the X server -in a format that the server demands. -To help simplify applications, -most of the work required to convert the data is provided by Xlib -(see sections 8.7 and 16.8). -.LP -The -.PN XPixmapFormatValues -structure provides an interface to the pixmap format information -that is returned at the time of a connection setup. -It contains: -.LP -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct { - int depth; - int bits_per_pixel; - int scanline_pad; -} XPixmapFormatValues; -.De -.LP -.eM -.sp -To obtain the pixmap format information for a given display, use -.PN XListPixmapFormats . -.IN "XListPixmapFormats" "" "@DEF@" -.sM -.FD 0 -XPixmapFormatValues *XListPixmapFormats\^(\^\fIdisplay\fP, \fIcount_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int *\fIcount_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.ds Cn pixmap formats that are supported by the display -.IP \fIcount_return\fP 1i -Returns the number of \*(Cn. -.LP -.eM -The -.PN XListPixmapFormats -function returns an array of -.PN XPixmapFormatValues -structures that describe the types of Z format images supported -by the specified display. -If insufficient memory is available, -.PN XListPixmapFormats -returns NULL. -To free the allocated storage for the -.PN XPixmapFormatValues -structures, use -.PN XFree . -.LP -The following lists the C language macros, -their corresponding function equivalents that are for other language bindings, -and what data they both return for the specified server and screen. -These are often used by toolkits as well as by simple applications. -.LP -.sp -.sM -.FD 0 -ImageByteOrder\^(\^\fIdisplay\fP\^) -.sp -int XImageByteOrder\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -.IN "ImageByteOrder" "" "@DEF@" -.IN "XImageByteOrder" "" "@DEF@" -Both specify the required byte order for images for each scanline unit in -XY format (bitmap) or for each pixel value in -Z format. -The macro or function can return either -.PN LSBFirst -or -.PN MSBFirst . -.LP -.sp -.sM -.FD 0 -BitmapUnit\^(\^\fIdisplay\fP\^) -.sp -int XBitmapUnit\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -.IN "BitmapUnit" "" "@DEF@" -.IN "XBitmapUnit" "" "@DEF@" -Both return the size of a bitmap's scanline unit in bits. -The scanline is calculated in multiples of this value. -.LP -.sp -.sM -.FD 0 -BitmapBitOrder\^(\^\fIdisplay\fP\^) -.sp -int XBitmapBitOrder\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -.IN "BitmapBitOrder" "" "@DEF@" -.IN "XBitmapBitOrder" "" "@DEF@" -Within each bitmap unit, the left-most bit in the bitmap as displayed -on the screen is either the least significant or most significant bit in the -unit. -This macro or function can return -.PN LSBFirst -or -.PN MSBFirst . -.LP -.sp -.sM -.FD 0 -BitmapPad\^(\^\fIdisplay\fP\^) -.sp -int XBitmapPad\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -.IN "BitmapPad" "" "@DEF@" -.IN "XBitmapPad" "" "@DEF@" -Each scanline must be padded to a multiple of bits returned -by this macro or function. -.LP -.sp -.sM -.FD 0 -DisplayHeight\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.sp -int XDisplayHeight\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIscreen_number\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIscreen_number\fP 1i -Specifies the appropriate screen number on the host server. -.LP -.eM -.IN "DisplayHeight" "" "@DEF@" -.IN "XDisplayHeight" "" "@DEF@" -Both return an integer that describes the height of the screen -in pixels. -.LP -.sp -.sM -.FD 0 -DisplayHeightMM\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.sp -int XDisplayHeightMM\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIscreen_number\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIscreen_number\fP 1i -Specifies the appropriate screen number on the host server. -.LP -.eM -.IN "DisplayHeightMM" "" "@DEF@" -.IN "XDisplayHeightMM" "" "@DEF@" -Both return the height of the specified screen in millimeters. -.LP -.sp -.sM -.FD 0 -DisplayWidth\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.sp -int XDisplayWidth\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIscreen_number\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIscreen_number\fP 1i -Specifies the appropriate screen number on the host server. -.LP -.eM -.IN "DisplayWidth" "" "@DEF@" -.IN "XDisplayWidth" "" "@DEF@" -Both return the width of the screen in pixels. -.LP -.sp -.sM -.FD 0 -DisplayWidthMM\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.sp -int XDisplayWidthMM\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIscreen_number\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIscreen_number\fP 1i -Specifies the appropriate screen number on the host server. -.LP -.eM -.IN "DisplayWidthMM" "" "@DEF@" -.IN "XDisplayWidthMM" "" "@DEF@" -Both return the width of the specified screen in millimeters. -.NH 3 -Screen Information Macros -.XS -\*(SN Screen Information Macros -.XE -.LP -The following lists the C language macros, -their corresponding function equivalents that are for other language bindings, -and what data they both can return. -These macros or functions all take a pointer to the appropriate screen -structure. -.LP -.sp -.sM -.FD 0 -BlackPixelOfScreen\^(\^\fIscreen\fP\^) -.sp -unsigned long XBlackPixelOfScreen\^(\^\fIscreen\fP\^) -.br - Screen *\fIscreen\fP\^; -.FN -.IP \fIscreen\fP 1i -Specifies the appropriate -.PN Screen -structure. -.LP -.eM -.IN "BlackPixelOfScreen" "" "@DEF@" -.IN "XBlackPixelOfScreen" "" "@DEF@" -Both return the black pixel value of the specified screen. -.LP -.sp -.sM -.FD 0 -WhitePixelOfScreen\^(\^\fIscreen\fP\^) -.sp -unsigned long XWhitePixelOfScreen\^(\^\fIscreen\fP\^) -.br - Screen *\fIscreen\fP\^; -.FN -.IP \fIscreen\fP 1i -Specifies the appropriate -.PN Screen -structure. -.LP -.eM -.IN "WhitePixelOfScreen" "" "@DEF@" -.IN "XWhitePixelOfScreen" "" "@DEF@" -Both return the white pixel value of the specified screen. -.LP -.sp -.sM -.FD 0 -CellsOfScreen\^(\^\fIscreen\fP\^) -.sp -int XCellsOfScreen\^(\^\fIscreen\fP\^) -.br - Screen *\fIscreen\fP\^; -.FN -.IP \fIscreen\fP 1i -Specifies the appropriate -.PN Screen -structure. -.LP -.eM -.IN "CellsOfScreen" "" "@DEF@" -.IN "XCellsOfScreen" "" "@DEF@" -Both return the number of colormap cells in the default colormap -of the specified screen. -.LP -.sp -.sM -.FD 0 -DefaultColormapOfScreen\^(\^\fIscreen\fP\^) -.sp -Colormap XDefaultColormapOfScreen\^(\^\fIscreen\fP\^) -.br - Screen *\fIscreen\fP\^; -.FN -.IP \fIscreen\fP 1i -Specifies the appropriate -.PN Screen -structure. -.LP -.eM -.IN "DefaultColormapOfScreen" "" "@DEF@" -.IN "XDefaultColormapOfScreen" "" "@DEF@" -Both return the default colormap of the specified screen. -.LP -.sp -.sM -.FD 0 -DefaultDepthOfScreen\^(\^\fIscreen\fP\^) -.sp -int XDefaultDepthOfScreen\^(\^\fIscreen\fP\^) -.br - Screen *\fIscreen\fP\^; -.FN -.IP \fIscreen\fP 1i -Specifies the appropriate -.PN Screen -structure. -.LP -.eM -.IN "DefaultDepthOfScreen" "" "@DEF@" -.IN "XDefaultDepthOfScreen" "" "@DEF@" -Both return the depth of the root window. -.LP -.sp -.sM -.FD 0 -DefaultGCOfScreen\^(\^\fIscreen\fP\^) -.sp -GC XDefaultGCOfScreen\^(\^\fIscreen\fP\^) -.br - Screen *\fIscreen\fP\^; -.FN -.IP \fIscreen\fP 1i -Specifies the appropriate -.PN Screen -structure. -.LP -.eM -.IN "DefaultGCOfScreen" "" "@DEF@" -.IN "XDefaultGCOfScreen" "" "@DEF@" -Both return a default graphics context (GC) of the specified screen, -which has the same depth as the root window of the screen. -The GC must never be freed. -.LP -.sp -.sM -.FD 0 -DefaultVisualOfScreen\^(\^\fIscreen\fP\^) -.sp -Visual *XDefaultVisualOfScreen\^(\^\fIscreen\fP\^) -.br - Screen *\fIscreen\fP\^; -.FN -.IP \fIscreen\fP 1i -Specifies the appropriate -.PN Screen -structure. -.LP -.eM -.IN "DefaultVisualOfScreen" "" "@DEF@" -.IN "XDefaultVisualOfScreen" "" "@DEF@" -Both return the default visual of the specified screen. -For information on visual types, -see section 3.1. -.LP -.sp -.sM -.FD 0 -DoesBackingStore\^(\^\fIscreen\fP\^) -.sp -int XDoesBackingStore\^(\^\fIscreen\fP\^) -.br - Screen *\fIscreen\fP\^; -.FN -.IP \fIscreen\fP 1i -Specifies the appropriate -.PN Screen -structure. -.LP -.eM -.IN "DoesBackingStore" "" "@DEF@" -.IN "XDoesBackingStore" "" "@DEF@" -Both return a value indicating whether the screen supports backing -stores. -The value returned can be one of -.PN WhenMapped , -.PN NotUseful , -or -.PN Always -(see section 3.2.4). -.LP -.sp -.sM -.FD 0 -DoesSaveUnders\^(\^\fIscreen\fP\^) -.sp -Bool XDoesSaveUnders\^(\^\fIscreen\fP\^) -.br - Screen *\fIscreen\fP\^; -.FN -.IP \fIscreen\fP 1i -Specifies the appropriate -.PN Screen -structure. -.LP -.eM -.IN "DoesSaveUnders" "" "@DEF@" -.IN "XDoesSaveUnders" "" "@DEF@" -Both return a Boolean value indicating whether the -screen supports save unders. -If -.PN True , -the screen supports save unders. -If -.PN False , -the screen does not support save unders (see section 3.2.5). -.LP -.sp -.sM -.FD 0 -DisplayOfScreen\^(\^\fIscreen\fP\^) -.sp -Display *XDisplayOfScreen\^(\^\fIscreen\fP\^) -.br - Screen *\fIscreen\fP\^; -.FN -.IP \fIscreen\fP 1i -Specifies the appropriate -.PN Screen -structure. -.LP -.eM -.IN "DisplayOfScreen" "" "@DEF@" -.IN "XDisplayOfScreen" "" "@DEF@" -Both return the display of the specified screen. -.LP -.sp -.sM -.IN "XScreenNumberOfScreen" "" "@DEF@" -.FD 0 -int XScreenNumberOfScreen\^(\^\fIscreen\fP\^) -.br - Screen *\fIscreen\fP\^; -.FN -.IP \fIscreen\fP 1i -Specifies the appropriate -.PN Screen -structure. -.LP -.eM -The -.PN XScreenNumberOfScreen -function returns the screen index number of the specified screen. -.LP -.sp -.sM -.FD 0 -EventMaskOfScreen\^(\^\fIscreen\fP\^) -.sp -long XEventMaskOfScreen\^(\^\fIscreen\fP\^) -.br - Screen *\fIscreen\fP\^; -.FN -.IP \fIscreen\fP 1i -Specifies the appropriate -.PN Screen -structure. -.LP -.eM -.IN "EventMaskOfScreen" "" "@DEF@" -.IN "XEventMaskOfScreen" "" "@DEF@" -Both return the event mask of the root window for the specified screen -at connection setup time. -.LP -.sp -.sM -.FD 0 -WidthOfScreen\^(\^\fIscreen\fP\^) -.sp -int XWidthOfScreen\^(\^\fIscreen\fP\^) -.br - Screen *\fIscreen\fP\^; -.FN -.IP \fIscreen\fP 1i -Specifies the appropriate -.PN Screen -structure. -.LP -.eM -.IN "WidthOfScreen" "" "@DEF@" -.IN "XWidthOfScreen" "" "@DEF@" -Both return the width of the specified screen in pixels. -.LP -.sp -.sM -.FD 0 -HeightOfScreen\^(\^\fIscreen\fP\^) -.sp -int XHeightOfScreen\^(\^\fIscreen\fP\^) -.br - Screen *\fIscreen\fP\^; -.FN -.IP \fIscreen\fP 1i -Specifies the appropriate -.PN Screen -structure. -.LP -.eM -.IN "HeightOfScreen" "" "@DEF@" -.IN "XHeightOfScreen" "" "@DEF@" -Both return the height of the specified screen in pixels. -.LP -.sp -.sM -.FD 0 -WidthMMOfScreen\^(\^\fIscreen\fP\^) -.sp -int XWidthMMOfScreen\^(\^\fIscreen\fP\^) -.br - Screen *\fIscreen\fP\^; -.FN -.IP \fIscreen\fP 1i -Specifies the appropriate -.PN Screen -structure. -.LP -.eM -.IN "WidthMMOfScreen" "" "@DEF@" -.IN "XWidthMMOfScreen" "" "@DEF@" -Both return the width of the specified screen in millimeters. -.LP -.sp -.sM -.FD 0 -HeightMMOfScreen\^(\^\fIscreen\fP\^) -.sp -int XHeightMMOfScreen\^(\^\fIscreen\fP\^) -.br - Screen *\fIscreen\fP\^; -.FN -.IP \fIscreen\fP 1i -Specifies the appropriate -.PN Screen -structure. -.LP -.eM -.IN "HeightMMOfScreen" "" "@DEF@" -.IN "XHeightMMOfScreen" "" "@DEF@" -Both return the height of the specified screen in millimeters. -.LP -.sp -.sM -.FD 0 -MaxCmapsOfScreen\^(\^\fIscreen\fP\^) -.sp -int XMaxCmapsOfScreen\^(\^\fIscreen\fP\^) -.br - Screen *\fIscreen\fP\^; -.FN -.IP \fIscreen\fP 1i -Specifies the appropriate -.PN Screen -structure. -.LP -.eM -.IN "MaxCmapsOfScreen" "" "@DEF@" -.IN "XMaxCmapsOfScreen" "" "@DEF@" -Both return the maximum number of installed colormaps supported -by the specified screen (see section 9.3). -.LP -.sp -.sM -.FD 0 -MinCmapsOfScreen\^(\^\fIscreen\fP\^) -.sp -int XMinCmapsOfScreen\^(\^\fIscreen\fP\^) -.br - Screen *\fIscreen\fP\^; -.FN -.IP \fIscreen\fP 1i -Specifies the appropriate -.PN Screen -structure. -.LP -.eM -.IN "MinCmapsOfScreen" "" "@DEF@" -.IN "XMinCmapsOfScreen" "" "@DEF@" -Both return the minimum number of installed colormaps supported -by the specified screen (see section 9.3). -.LP -.sp -.sM -.FD 0 -PlanesOfScreen\^(\^\fIscreen\fP\^) -.sp -int XPlanesOfScreen\^(\^\fIscreen\fP\^) -.br - Screen *\fIscreen\fP\^; -.FN -.IP \fIscreen\fP 1i -Specifies the appropriate -.PN Screen -structure. -.LP -.eM -.IN "PlanesOfScreen" "" "@DEF@" -.IN "XPlanesOfScreen" "" "@DEF@" -Both return the depth of the root window. -.LP -.sp -.sM -.FD 0 -RootWindowOfScreen\^(\^\fIscreen\fP\^) -.sp -Window XRootWindowOfScreen\^(\^\fIscreen\fP\^) -.br - Screen *\fIscreen\fP\^; -.FN -.IP \fIscreen\fP 1i -Specifies the appropriate -.PN Screen -structure. -.LP -.eM -.IN "RootWindowOfScreen" "" "@DEF@" -.IN "XRootWindowOfScreen" "" "@DEF@" -Both return the root window of the specified screen. -.NH 2 -Generating a NoOperation Protocol Request -.XS -\*(SN Generating a NoOperation Protocol Request -.XE -.LP -To execute a -.PN NoOperation -protocol request, use -.PN XNoOp . -.IN "XNoOp" "" "@DEF@" -.sM -.FD 0 -XNoOp\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -The -.PN XNoOp -function sends a -.PN NoOperation -protocol request to the X server, -thereby exercising the connection. -.NH 2 -Freeing Client-Created Data -.XS -\*(SN Freeing Client-Created Data -.XE -.LP -To free in-memory data that was created by an Xlib function, use -.PN XFree . -.IN "XFree" "" "@DEF@" -.sM -.FD 0 -XFree\^(\^\fIdata\fP\^) -.br - void *\fIdata\fP\^; -.FN -.IP \fIdata\fP 1i -Specifies the data that is to be freed. -.LP -.eM -The -.PN XFree -function is a general-purpose Xlib routine that frees the specified data. -You must use it to free any objects that were allocated by Xlib, -unless an alternate function is explicitly specified for the object. -A NULL pointer cannot be passed to this function. -.NH 2 -Closing the Display -.XS -\*(SN Closing the Display -.XE -.LP -To close a display or disconnect from the X server, use -.PN XCloseDisplay . -.IN "XCloseDisplay" "" "@DEF@" -.LP -.sM -.FD 0 -XCloseDisplay\^(\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -The -.PN XCloseDisplay -function closes the connection to the X server for the display specified in the -.PN Display -structure and destroys all windows, resource IDs -.Pn ( Window , -.PN Font , -.PN Pixmap , -.PN Colormap , -.PN Cursor , -and -.PN GContext ), -or other resources that the client has created -on this display, unless the close-down mode of the resource has been changed -(see -.PN XSetCloseDownMode ). -Therefore, these windows, resource IDs, and other resources should never be -referenced again or an error will be generated. -Before exiting, you should call -.PN XCloseDisplay -explicitly so that any pending errors are reported as -.PN XCloseDisplay -performs a final -.PN XSync -operation. -.IN "Resource IDs" -.IN "XCloseDisplay" -.LP -.PN XCloseDisplay -can generate a -.PN BadGC -error. -.sp -.LP -Xlib provides a function to permit the resources owned by a client -to survive after the client's connection is closed. -To change a client's close-down mode, use -.PN XSetCloseDownMode . -.IN "XSetCloseDownMode" "" "@DEF@" -.sM -.FD 0 -XSetCloseDownMode\^(\^\fIdisplay\fP, \fIclose_mode\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIclose_mode\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIclose_mode\fP 1i -Specifies the client close-down mode. -You can pass -.PN DestroyAll , -.PN RetainPermanent , -or -.PN RetainTemporary . -.LP -.eM -The -.PN XSetCloseDownMode -defines what will happen to the client's resources at connection close. -A connection starts in -.PN DestroyAll -mode. -For information on what happens to the client's resources when the -close_mode argument is -.PN RetainPermanent -or -.PN RetainTemporary , -see section 2.6. -.LP -.PN XSetCloseDownMode -can generate a -.PN BadValue -error. -.NH 2 -Using X Server Connection Close Operations -.XS -\*(SN Using X Server Connection Close Operations -.XE -.LP -When the X server's connection to a client is closed -either by an explicit call to -.PN XCloseDisplay -or by a process that exits, the X server performs the following -automatic operations: -.IP \(bu 5 -It disowns all selections owned by the client -(see -.PN XSetSelectionOwner ). -.IP \(bu 5 -It performs an -.PN XUngrabPointer -and -.PN XUngrabKeyboard -if the client has actively grabbed the pointer -or the keyboard. -.IP \(bu 5 -It performs an -.PN XUngrabServer -if the client has grabbed the server. -.IP \(bu 5 -It releases all passive grabs made by the client. -.IP \(bu 5 -It marks all resources (including colormap entries) allocated -by the client either as permanent or temporary, -depending on whether the close-down mode is -.PN RetainPermanent -or -.PN RetainTemporary . -However, this does not prevent other client applications from explicitly -destroying the resources (see -.PN XSetCloseDownMode ). -.LP -When the close-down mode is -.PN DestroyAll , -the X server destroys all of a client's resources as follows: -.IP \(bu 5 -It examines each window in the client's save-set to determine if it is an inferior -(subwindow) of a window created by the client. -(The save-set is a list of other clients' windows -that are referred to as save-set windows.) -If so, the X server reparents the save-set window to the closest ancestor so -that the save-set window is not an inferior of a window created by the client. -The reparenting leaves unchanged the absolute coordinates (with respect to -the root window) of the upper-left outer corner of the save-set -window. -.IP \(bu 5 -It performs a -.PN MapWindow -request on the save-set window if the save-set window is unmapped. -The X server does this even if the save-set window was not an inferior of -a window created by the client. -.IP \(bu 5 -It destroys all windows created by the client. -.IP \(bu 5 -It performs the appropriate free request on each nonwindow resource created by -the client in the server (for example, -.PN Font , -.PN Pixmap , -.PN Cursor , -.PN Colormap , -and -.PN GContext ). -.IP \(bu 5 -It frees all colors and colormap entries allocated by a client application. -.LP -Additional processing occurs when the last connection to the X server closes. -An X server goes through a cycle of having no connections and having some -connections. -When the last connection to the X server closes as a result of a connection -closing with the close_mode of -.PN DestroyAll , -the X server does the following: -.IP \(bu 5 -It resets its state as if it had just been -started. -The X server begins by destroying all lingering resources from -clients that have terminated in -.PN RetainPermanent -or -.PN RetainTemporary -mode. -.IP \(bu 5 -It deletes all but the predefined atom identifiers. -.IP \(bu 5 -It deletes all properties on all root windows (see section 4.3). -.IP \(bu 5 -It resets all device maps and attributes -(for example, key click, bell volume, and acceleration) -as well as the access control list. -.IP \(bu 5 -It restores the standard root tiles and cursors. -.IP \(bu 5 -It restores the default font path. -.IP \(bu 5 -It restores the input focus to state -.PN PointerRoot . -.LP -However, the X server does not reset if you close a connection with a close-down -mode set to -.PN RetainPermanent -or -.PN RetainTemporary . -.NH 2 -Using Xlib with Threads -.XS -\*(SN Using Xlib with Threads -.XE -.LP -On systems that have threads, support may be provided to permit -multiple threads to use Xlib concurrently. -.LP -.sp -To initialize support for concurrent threads, use -.PN XInitThreads . -.IN "XInitThreads" "" "@DEF@" -.sM -.FD 0 -Status XInitThreads\^(\|); -.FN -.LP -.eM -The -.PN XInitThreads -function initializes Xlib support for concurrent threads. -This function must be the first Xlib function a -multi-threaded program calls, and it must complete -before any other Xlib call is made. -This function returns a nonzero status if initialization was -successful; otherwise, it returns zero. -On systems that do not support threads, this function always returns zero. -.LP -It is only necessary to call this function if multiple threads -might use Xlib concurrently. If all calls to Xlib functions -are protected by some other access mechanism (for example, -a mutual exclusion lock in a toolkit or through explicit client -programming), Xlib thread initialization is not required. -It is recommended that single-threaded programs not call this function. - -.LP -.sp -To lock a display across several Xlib calls, use -.PN XLockDisplay . -.IN "XLockDisplay" "" "@DEF@" -.sM -.FD 0 -void XLockDisplay\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -The -.PN XLockDisplay -function locks out all other threads from using the specified display. -Other threads attempting to use the display will block until -the display is unlocked by this thread. -Nested calls to -.PN XLockDisplay -work correctly; the display will not actually be unlocked until -.PN XUnlockDisplay -has been called the same number of times as -.PN XLockDisplay . -This function has no effect unless Xlib was successfully initialized -for threads using -.PN XInitThreads . -.LP -.sp -To unlock a display, use -.PN XUnlockDisplay . -.IN "XUnlockDisplay" "" "@DEF@" -.sM -.FD 0 -void XUnlockDisplay\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -The -.PN XUnlockDisplay -function allows other threads to use the specified display again. -Any threads that have blocked on the display are allowed to continue. -Nested locking works correctly; if -.PN XLockDisplay -has been called multiple times by a thread, then -.PN XUnlockDisplay -must be called an equal number of times before the display is -actually unlocked. -This function has no effect unless Xlib was successfully initialized -for threads using -.PN XInitThreads . -.NH 2 -Using Internal Connections -.XS -\*(SN Using Internal Connections -.XE -.LP -In addition to the connection to the X server, an Xlib implementation -may require connections to other kinds of servers (for example, to -input method servers as described in chapter 13). Toolkits and clients -that use multiple displays, or that use displays in combination with -other inputs, need to obtain these additional connections to correctly -block until input is available and need to process that input -when it is available. Simple clients that use a single display and -block for input in an Xlib event function do not need to use these -facilities. -.LP -To track internal connections for a display, use -.PN XAddConnectionWatch . -.LP -.IN "XWatchProc" "" "@DEF@" -.IN "XAddConnectionWatch" "" "@DEF@" -.sM -.FD 0 -typedef void (*XConnectionWatchProc)\^(\^\fIdisplay\fP, \fIclient_data\fP, \fIfd\fP, \fIopening\fP, \fIwatch_data\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XPointer \fIclient_data\fP\^; -.br - int \fIfd\fP\^; -.br - Bool \fIopening\fP\^; -.br - XPointer *\fIwatch_data\fP\^; -.sp -Status XAddConnectionWatch\^(\^\fIdisplay\fP, \fIprocedure\fP\^, \fIclient_data\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XWatchProc \fIprocedure\fP\^; -.br - XPointer \fIclient_data\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIprocedure\fP 1i -Specifies the procedure to be called. -.IP \fIclient_data\fP 1i -Specifies the additional client data. -.LP -.eM -The -.PN XAddConnectionWatch -function registers a procedure to be called each time Xlib opens or closes an -internal connection for the specified display. The procedure is passed the -display, the specified client_data, the file descriptor for the connection, -a Boolean indicating whether the connection is being opened or closed, and a -pointer to a location for private watch data. If opening is -.PN True , -the procedure can store a pointer to private data in the location pointed -to by watch_data; -when the procedure is later called for this same connection and opening is -.PN False , -the location pointed to by watch_data will hold this same private data pointer. -.LP -This function can be called at any time after a display is opened. -If internal connections already exist, the registered procedure will -immediately be called for each of them, before -.PN XAddConnectionWatch -returns. -.PN XAddConnectionWatch -returns a nonzero status if the procedure is successfully registered; -otherwise, it returns zero. -.LP -The registered procedure should not call any Xlib functions. -If the procedure directly or indirectly causes the state of internal -connections or watch procedures to change, the result is not defined. -If Xlib has been initialized for threads, the procedure is called with -the display locked and the result of a call by the procedure to any -Xlib function that locks the display is not defined unless the executing -thread has externally locked the display using -.PN XLockDisplay . -.LP -.sp -To stop tracking internal connections for a display, use -.PN XRemoveConnectionWatch . -.IN "XRemoveConnectionWatch" "" "@DEF@" -.sM -.FD 0 -Status XRemoveConnectionWatch\^(\^\fIdisplay\fP, \fIprocedure\fP\^, \fIclient_data\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XWatchProc \fIprocedure\fP\^; -.br - XPointer \fIclient_data\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIprocedure\fP 1i -Specifies the procedure to be called. -.IP \fIclient_data\fP 1i -Specifies the additional client data. -.LP -.eM -The -.PN XRemoveConnectionWatch -function removes a previously registered connection watch procedure. -The client_data must match the client_data used when the procedure -was initially registered. - -.LP -.sp -To process input on an internal connection, use -.PN XProcessInternalConnection . -.IN "XProcessInternalConnection" "" "@DEF@" -.sM -.FD 0 -void XProcessInternalConnection\^(\^\fIdisplay\fP, \fIfd\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIfd\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIfd\fP 1i -Specifies the file descriptor. -.LP -.eM -The -.PN XProcessInternalConnection -function processes input available on an internal connection. -This function should be called for an internal connection only -after an operating system facility (for example, -.PN select -or -.PN poll ) -has indicated that input is available; otherwise, -the effect is not defined. -.LP -.sp -To obtain all of the current internal connections for a display, use -.PN XInternalConnectionNumbers . -.IN "XInternalConnectionNumbers" "" "@DEF@" -.sM -.FD 0 -Status XInternalConnectionNumbers\^(\^\fIdisplay\fP, \fIfd_return\fP\^, \fIcount_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int **\fIfd_return\fP\^; -.br - int *\fIcount_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIfd_return\fP 1i -Returns the file descriptors. -.ds Cn file descriptors -.IP \fIcount_return\fP 1i -Returns the number of \*(Cn. -.LP -.eM -The -.PN XInternalConnectionNumbers -function returns a list of the file descriptors for all internal -connections currently open for the specified display. -When the allocated list is no longer needed, -free it by using -.PN XFree . -This functions returns a nonzero status if the list is successfully allocated; -otherwise, it returns zero. -.LP -.bp |