2053 lines
50 KiB
Plaintext
2053 lines
50 KiB
Plaintext
.\" 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.
|
|
.\"
|
|
.\" $XFree86$
|
|
\&
|
|
.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
|