mirror of
https://gitlab.freedesktop.org/xorg/lib/libx11.git
synced 2025-12-20 04:40:10 +01:00
8b77c86a06
Performed with: `git ls-files | xargs perl -i -p -e 's{[ \t]+$}{}'`
`git diff -w` & `git diff -b` show no diffs from this change
Signed-off-by: Alan Coopersmith <alan.coopersmith@oracle.com>
Part-of: <https://gitlab.freedesktop.org/xorg/lib/libx11/-/merge_requests/287>
3652 lines
101 KiB
XML
3652 lines
101 KiB
XML
<?xml version="1.0" encoding="UTF-8" ?>
|
|
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
|
|
<chapter id='Display_Functions'>
|
|
<title>Display Functions</title>
|
|
<para>
|
|
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:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
Open (connect to) the display
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Obtain information about the display, image formats, or screens
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Generate a
|
|
<systemitem>NoOperation</systemitem>
|
|
protocol request
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Free client-created data
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Close (disconnect from) a display
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Use X Server connection close operations
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Use Xlib with threads
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Use internal connections
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<sect1 id="Opening_the_Display">
|
|
<title>Opening the Display</title>
|
|
<!-- .XS -->
|
|
<!-- (SN Opening the Display -->
|
|
<!-- .XE -->
|
|
<para>
|
|
<!-- .LP -->
|
|
To open a connection to the X server that controls a display, use
|
|
<xref linkend='XOpenDisplay' xrefstyle='select: title'/>.
|
|
<indexterm significance="preferred"><primary>XOpenDisplay</primary></indexterm>
|
|
</para>
|
|
<funcsynopsis id='XOpenDisplay'>
|
|
<funcprototype>
|
|
<funcdef>Display *<function>XOpenDisplay</function></funcdef>
|
|
<paramdef>char *<parameter>display_name</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>display_name</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the hardware display name, which determines the display
|
|
and communications domain to be used.
|
|
On a <acronym>POSIX</acronym>-conformant system, if the display_name is NULL,
|
|
it defaults to the value of the DISPLAY environment variable.
|
|
<indexterm><primary>Environment</primary><secondary>DISPLAY</secondary></indexterm>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .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 <acronym>POSIX</acronym>-conformant systems,
|
|
the display name or DISPLAY environment variable can be a string in the format:
|
|
</para>
|
|
<!-- .LP -->
|
|
<!-- .sM -->
|
|
<literallayout class="monospaced">
|
|
<!-- .TA 1i -->
|
|
<!-- .ta 1i -->
|
|
<emphasis remap='I'>protocol</emphasis>/<emphasis remap='I'>hostname</emphasis>:<emphasis remap='I'>number</emphasis>.<emphasis remap='I'>screen_number</emphasis>
|
|
</literallayout>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>protocol</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>hostname</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
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 (::).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>number</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the number of the display server on that host machine.
|
|
You may optionally follow this display number with a period (.).
|
|
A single <acronym>CPU</acronym> can have more than one display.
|
|
Multiple displays are usually numbered starting with zero.
|
|
<indexterm><primary>Screen</primary></indexterm>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>screen_number</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
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
|
|
<function>DefaultScreen</function>
|
|
macro or the
|
|
<xref linkend='XDefaultScreen' xrefstyle='select: title'/>
|
|
function if you are using languages other than C
|
|
(see <link linkend='Display_Macros'>section 2.2.1</link>).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
For example, the following would specify screen 1 of display 0 on the
|
|
machine named ``dual-headed'':
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<literallayout class="monospaced">
|
|
dual-headed:0.1
|
|
</literallayout>
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
The
|
|
<xref linkend='XOpenDisplay' xrefstyle='select: title'/>
|
|
function returns a
|
|
<type>Display</type>
|
|
structure that serves as the
|
|
connection to the X server and that contains all the information
|
|
about that X server.
|
|
<xref linkend='XOpenDisplay' xrefstyle='select: title'/>
|
|
connects your application to the X server through <acronym>TCP</acronym>
|
|
or DECnet communications protocols,
|
|
or through some local inter-process communication protocol.
|
|
<indexterm><primary>Protocol</primary><secondary><acronym>TCP</acronym></secondary></indexterm>
|
|
<indexterm><primary>Protocol</primary><secondary>DECnet</secondary></indexterm>
|
|
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,
|
|
<xref linkend='XOpenDisplay' xrefstyle='select: title'/>
|
|
connects using <acronym>TCP</acronym> streams. (If the protocol is specified as "inet", <acronym>TCP</acronym> over
|
|
IPv4 is used. If the protocol is specified as "inet6", <acronym>TCP</acronym> over IPv6 is used.
|
|
Otherwise, the implementation determines which <acronym>IP</acronym> 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,
|
|
<xref linkend='XOpenDisplay' xrefstyle='select: title'/>
|
|
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.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<indexterm><primary>Display</primary></indexterm>
|
|
If successful,
|
|
<xref linkend='XOpenDisplay' xrefstyle='select: title'/>
|
|
returns a pointer to a
|
|
<type>Display</type>
|
|
structure,
|
|
which is defined in
|
|
<filename class="headerfile"><X11/Xlib.h></filename>.
|
|
<indexterm type="file"><primary><filename class="headerfile">X11/Xlib.h</filename></primary></indexterm>
|
|
<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/Xlib.h></filename></secondary></indexterm>
|
|
<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/Xlib.h></filename></secondary></indexterm>
|
|
If
|
|
<xref linkend='XOpenDisplay' xrefstyle='select: title'/>
|
|
does not succeed, it returns NULL.
|
|
After a successful call to
|
|
<xref linkend='XOpenDisplay' xrefstyle='select: title'/>,
|
|
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
|
|
<function>DefaultScreen</function>
|
|
macro (or the
|
|
<xref linkend='XDefaultScreen' xrefstyle='select: title'/>
|
|
function).
|
|
You can access elements of the
|
|
<type>Display</type>
|
|
and
|
|
<type>Screen</type>
|
|
structures only by using the information macros or functions.
|
|
For information about using macros and functions to obtain information from
|
|
the
|
|
<type>Display</type>
|
|
structure,
|
|
see <link linkend='Display_Macros'>section 2.2.1</link>.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
X servers may implement various types of access control mechanisms
|
|
(see <link linkend="Controlling_Host_Access">section 9.8</link>).
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="Obtaining_Information_about_the_Display_Image_Formats_or_Screens">
|
|
<title>Obtaining Information about the Display, Image Formats, or Screens</title>
|
|
<!-- .XS -->
|
|
<!-- (SN Obtaining Information about the Display, Image Formats, or Screens -->
|
|
<!-- .XE -->
|
|
<para>
|
|
<!-- .LP -->
|
|
The Xlib library provides a number of useful macros
|
|
and corresponding functions that return data from the
|
|
<type>Display</type>
|
|
structure.
|
|
The macros are used for C programming,
|
|
and their corresponding function equivalents are for other language bindings.
|
|
This section discusses the:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
Display macros
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Image format functions and macros
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Screen information macros
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<indexterm ><primary>Display</primary><secondary>data structure</secondary></indexterm>
|
|
All other members of the
|
|
<type>Display</type>
|
|
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
|
|
<type>Display</type>
|
|
structure.
|
|
<!-- .NT Note -->
|
|
The
|
|
<xref linkend='XDisplayWidth' xrefstyle='select: title'/>,
|
|
<xref linkend='XDisplayHeight' xrefstyle='select: title'/>,
|
|
<xref linkend='XDisplayCells' xrefstyle='select: title'/>,
|
|
<xref linkend='XDisplayPlanes' xrefstyle='select: title'/>,
|
|
<xref linkend='XDisplayWidthMM' xrefstyle='select: title'/>,
|
|
and
|
|
<xref linkend='XDisplayHeightMM' xrefstyle='select: title'/>
|
|
functions in the next sections are misnamed.
|
|
These functions really should be named Screen<emphasis remap='I'>whatever</emphasis>
|
|
and XScreen<emphasis remap='I'>whatever</emphasis>, not Display<emphasis remap='I'>whatever</emphasis> or XDisplay<emphasis remap='I'>whatever</emphasis>.
|
|
Our apologies for the resulting confusion.
|
|
<!-- .NE -->
|
|
</para>
|
|
<sect2 id='Display_Macros'>
|
|
<title>Display Macros</title>
|
|
<!-- .XS -->
|
|
<!-- (SN Display Macros -->
|
|
<!-- .XE -->
|
|
<para>
|
|
<!-- .LP -->
|
|
Applications should not directly modify any part of the
|
|
<type>Display</type>
|
|
and
|
|
<type>Screen</type>
|
|
structures.
|
|
The members should be considered read-only,
|
|
although they may change as the result of other operations on the display.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
The following lists the C language macros,
|
|
their corresponding function equivalents that are for other language bindings,
|
|
and what data both can return.
|
|
</para>
|
|
<synopsis id='AllPlanes' role='macro'><constant>AllPlanes</constant></synopsis>
|
|
<funcsynopsis id='XAllPlanes'>
|
|
<funcprototype>
|
|
<funcdef>unsigned long <function>XAllPlanes</function></funcdef>
|
|
<void />
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm significance="preferred"><primary>AllPlanes</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>XAllPlanes</primary></indexterm>
|
|
Both return a value with all bits set to 1 suitable for use in a plane argument to
|
|
a procedure.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<indexterm significance="preferred"><primary>BlackPixel</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>XBlackPixel</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>WhitePixel</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>XWhitePixel</primary></indexterm>
|
|
Both
|
|
<function>BlackPixel</function>
|
|
and
|
|
<function>WhitePixel</function>
|
|
can be used in implementing a monochrome application.
|
|
These pixel values are for permanently allocated entries in the default
|
|
colormap.
|
|
The actual <acronym>RGB</acronym> (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 -->
|
|
</para>
|
|
<funcsynopsis id='BlackPixel'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>BlackPixel</function></funcdef>
|
|
<paramdef><parameter>display</parameter></paramdef>
|
|
<paramdef><parameter>screen_number</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XBlackPixel'>
|
|
<funcprototype>
|
|
<funcdef>unsigned long <function>XBlackPixel</function></funcdef>
|
|
<paramdef>Display *<parameter>display</parameter></paramdef>
|
|
<paramdef>int <parameter>screen_number</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>display</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>screen_number</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the appropriate screen number on the host server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
Both return the black pixel value for the specified screen.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='WhitePixel'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>WhitePixel</function></funcdef>
|
|
<paramdef><parameter>display</parameter></paramdef>
|
|
<paramdef><parameter>screen_number</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XWhitePixel'>
|
|
<funcprototype>
|
|
<funcdef>unsigned long <function>XWhitePixel</function></funcdef>
|
|
<paramdef>Display *<parameter>display</parameter></paramdef>
|
|
<paramdef>int <parameter>screen_number</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>display</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>screen_number</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the appropriate screen number on the host server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
Both return the white pixel value for the specified screen.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='ConnectionNumber'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>ConnectionNumber</function></funcdef>
|
|
<paramdef><parameter>display</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XConnectionNumber'>
|
|
<funcprototype>
|
|
<funcdef>int <function>XConnectionNumber</function></funcdef>
|
|
<paramdef>Display *<parameter>display</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>display</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm significance="preferred"><primary>ConnectionNumber</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>XConnectionNumber</primary></indexterm>
|
|
Both return a connection number for the specified display.
|
|
On a <acronym>POSIX</acronym>-conformant system,
|
|
this is the file descriptor of the connection.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='DefaultColormap'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>DefaultColormap</function></funcdef>
|
|
<paramdef><parameter>display</parameter></paramdef>
|
|
<paramdef><parameter>screen_number</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XDefaultColormap'>
|
|
<funcprototype>
|
|
<funcdef>Colormap <function>XDefaultColormap</function></funcdef>
|
|
<paramdef>Display *<parameter>display</parameter></paramdef>
|
|
<paramdef>int <parameter>screen_number</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>display</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>screen_number</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the appropriate screen number on the host server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm significance="preferred"><primary>DefaultColormap</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>XDefaultColormap</primary></indexterm>
|
|
Both return the default colormap ID for allocation on the specified screen.
|
|
Most routine allocations of color should be made out of this colormap.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='DefaultDepth'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>DefaultDepth</function></funcdef>
|
|
<paramdef><parameter>display</parameter></paramdef>
|
|
<paramdef><parameter>screen_number</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XDefaultDepth'>
|
|
<funcprototype>
|
|
<funcdef>int <function>XDefaultDepth</function></funcdef>
|
|
<paramdef>Display *<parameter>display</parameter></paramdef>
|
|
<paramdef>int <parameter>screen_number</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>display</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>screen_number</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the appropriate screen number on the host server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm significance="preferred"><primary>DefaultDepth</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>XDefaultDepth</primary></indexterm>
|
|
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
|
|
<xref linkend='XMatchVisualInfo' xrefstyle='select: title'/>).
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<indexterm significance="preferred"><primary>XListDepths</primary></indexterm>
|
|
To determine the number of depths that are available on a given screen, use
|
|
<function>XListDepths</function>.
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='XListDepths'>
|
|
<funcprototype>
|
|
<funcdef>int *<function>XListDepths</function></funcdef>
|
|
<paramdef>Display *<parameter>display</parameter></paramdef>
|
|
<paramdef>int <parameter>screen_number</parameter></paramdef>
|
|
<paramdef>int *<parameter>count_return</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>display</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>screen_number</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the appropriate screen number on the host server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>count_return</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Returns the number of depths.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<function>XListDepths</function>
|
|
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,
|
|
<function>XListDepths</function>
|
|
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
|
|
<xref linkend='XFree' xrefstyle='select: title'/>.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='DefaultGC'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>DefaultGC</function></funcdef>
|
|
<paramdef><parameter>display</parameter></paramdef>
|
|
<paramdef><parameter>screen_number</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XDefaultGC'>
|
|
<funcprototype>
|
|
<funcdef>GC <function>XDefaultGC</function></funcdef>
|
|
<paramdef>Display *<parameter>display</parameter></paramdef>
|
|
<paramdef>int <parameter>screen_number</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>display</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>screen_number</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the appropriate screen number on the host server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm significance="preferred"><primary>DefaultGC</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>XDefaultGC</primary></indexterm>
|
|
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.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='DefaultRootWindow'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>DefaultRootWindow</function></funcdef>
|
|
<paramdef><parameter>display</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XDefaultRootWindow'>
|
|
<funcprototype>
|
|
<funcdef>Window <function>XDefaultRootWindow</function></funcdef>
|
|
<paramdef>Display *<parameter>display</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>display</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm significance="preferred"><primary>DefaultRootWindow</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>XDefaultRootWindow</primary></indexterm>
|
|
Both return the root window for the default screen.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='DefaultScreenOfDisplay'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>DefaultScreenOfDisplay</function></funcdef>
|
|
<paramdef><parameter>display</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XDefaultScreenOfDisplay'>
|
|
<funcprototype>
|
|
<funcdef>Screen *<function>XDefaultScreenOfDisplay</function></funcdef>
|
|
<paramdef>Display *<parameter>display</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>display</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm significance="preferred"><primary>DefaultScreenOfDisplay</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>XDefaultScreenOfDisplay</primary></indexterm>
|
|
Both return a pointer to the default screen.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='ScreenOfDisplay'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>ScreenOfDisplay</function></funcdef>
|
|
<paramdef><parameter>display</parameter></paramdef>
|
|
<paramdef><parameter>screen_number</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XScreenOfDisplay'>
|
|
<funcprototype>
|
|
<funcdef>Screen *<function>XScreenOfDisplay</function></funcdef>
|
|
<paramdef>Display *<parameter>display</parameter></paramdef>
|
|
<paramdef>int <parameter>screen_number</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>display</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>screen_number</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the appropriate screen number on the host server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm significance="preferred"><primary>ScreenOfDisplay</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>XScreenOfDisplay</primary></indexterm>
|
|
Both return a pointer to the indicated screen.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='DefaultScreen'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>DefaultScreen</function></funcdef>
|
|
<paramdef><parameter>display</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XDefaultScreen'>
|
|
<funcprototype>
|
|
<funcdef>int <function>XDefaultScreen</function></funcdef>
|
|
<paramdef>Display *<parameter>display</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>display</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm significance="preferred"><primary>DefaultScreen</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>XDefaultScreen</primary></indexterm>
|
|
Both return the default screen number referenced by the
|
|
<xref linkend='XOpenDisplay' xrefstyle='select: title'/>
|
|
function.
|
|
This macro or function should be used to retrieve the screen number
|
|
in applications that will use only a single screen.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='DefaultVisual'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>DefaultVisual</function></funcdef>
|
|
<paramdef><parameter>display</parameter></paramdef>
|
|
<paramdef><parameter>screen_number</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XDefaultVisual'>
|
|
<funcprototype>
|
|
<funcdef>Visual *<function>XDefaultVisual</function></funcdef>
|
|
<paramdef>Display *<parameter>display</parameter></paramdef>
|
|
<paramdef>int <parameter>screen_number</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>display</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>screen_number</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the appropriate screen number on the host server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm significance="preferred"><primary>DefaultVisual</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>XDefaultVisual</primary></indexterm>
|
|
Both return the default visual type for the specified screen.
|
|
For further information about visual types,
|
|
see <link linkend="Visual_Types">section 3.1</link>.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='DisplayCells'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>DisplayCells</function></funcdef>
|
|
<paramdef><parameter>display</parameter></paramdef>
|
|
<paramdef><parameter>screen_number</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XDisplayCells'>
|
|
<funcprototype>
|
|
<funcdef>int <function>XDisplayCells</function></funcdef>
|
|
<paramdef>Display *<parameter>display</parameter></paramdef>
|
|
<paramdef>int <parameter>screen_number</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>display</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>screen_number</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the appropriate screen number on the host server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm significance="preferred"><primary>DisplayCells</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>XDisplayCells</primary></indexterm>
|
|
Both return the number of entries in the default colormap.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='DisplayPlanes'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>DisplayPlanes</function></funcdef>
|
|
<paramdef><parameter>display</parameter></paramdef>
|
|
<paramdef><parameter>screen_number</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XDisplayPlanes'>
|
|
<funcprototype>
|
|
<funcdef>int <function>XDisplayPlanes</function></funcdef>
|
|
<paramdef>Display *<parameter>display</parameter></paramdef>
|
|
<paramdef>int <parameter>screen_number</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>display</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>screen_number</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the appropriate screen number on the host server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm significance="preferred"><primary>DisplayPlanes</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>XDisplayPlanes</primary></indexterm>
|
|
Both return the depth of the root window of the specified screen.
|
|
For an explanation of depth,
|
|
see the glossary.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='DisplayString'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>DisplayString</function></funcdef>
|
|
<paramdef><parameter>display</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XDisplayString'>
|
|
<funcprototype>
|
|
<funcdef>char *<function>XDisplayString</function></funcdef>
|
|
<paramdef>Display *<parameter>display</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>display</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm significance="preferred"><primary>DisplayString</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>XDisplayString</primary></indexterm>
|
|
Both return the string that was passed to
|
|
<xref linkend='XOpenDisplay' xrefstyle='select: title'/>
|
|
when the current display was opened.
|
|
On <acronym>POSIX</acronym>-conformant systems,
|
|
if the passed string was NULL, these return the value of
|
|
the DISPLAY environment variable when the current display was opened.
|
|
<indexterm><primary><acronym>POSIX</acronym> System Call</primary><secondary>fork</secondary></indexterm>
|
|
These are useful to applications that invoke the
|
|
<function>fork</function>
|
|
system call and want to open a new connection to the same display from the
|
|
child process as well as for printing error messages.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='XExtendedMaxRequestSize'>
|
|
<funcprototype>
|
|
<funcdef>long <function>XExtendedMaxRequestSize</function></funcdef>
|
|
<paramdef>Display *<parameter>display</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>display</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm significance="preferred"><primary>XExtendedMaxRequestSize</primary></indexterm>
|
|
The
|
|
<olink targetdoc='bigreq' targetptr='XExtendedMaxRequestSize'><function>XExtendedMaxRequestSize</function></olink>
|
|
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
|
|
<xref linkend='XDrawLines' xrefstyle='select: title'/>,
|
|
<xref linkend='XDrawArcs' xrefstyle='select: title'/>,
|
|
<xref linkend='XFillPolygon' xrefstyle='select: title'/>,
|
|
<xref linkend='XChangeProperty' xrefstyle='select: title'/>,
|
|
<xref linkend='XSetClipRectangles' xrefstyle='select: title'/>,
|
|
and
|
|
<xref linkend='XSetRegion' xrefstyle='select: title'/>
|
|
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,
|
|
<xref linkend='XDrawPoints' xrefstyle='select: title'/>,
|
|
<xref linkend='XDrawRectangles' xrefstyle='select: title'/>,
|
|
<xref linkend='XDrawSegments' xrefstyle='select: title'/>,
|
|
<xref linkend='XFillArcs' xrefstyle='select: title'/>,
|
|
<xref linkend='XFillRectangles' xrefstyle='select: title'/>,
|
|
<xref linkend='XPutImage' xrefstyle='select: title'/>)
|
|
is permitted but not required; an Xlib implementation may choose to
|
|
split the data across multiple smaller requests instead.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>long <function>XMaxRequestSize</function></funcdef>
|
|
<paramdef>Display *<parameter>display</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>display</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm significance="preferred"><primary>XMaxRequestSize</primary></indexterm>
|
|
The
|
|
<function>XMaxRequestSize</function>
|
|
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:
|
|
<xref linkend='XDrawPoints' xrefstyle='select: title'/>,
|
|
<xref linkend='XDrawRectangles' xrefstyle='select: title'/>,
|
|
<xref linkend='XDrawSegments' xrefstyle='select: title'/>,
|
|
<xref linkend='XFillArcs' xrefstyle='select: title'/>,
|
|
<xref linkend='XFillRectangles' xrefstyle='select: title'/>,
|
|
and
|
|
<xref linkend='XPutImage' xrefstyle='select: title'/>.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='LastKnownRequestProcessed'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>LastKnownRequestProcessed</function></funcdef>
|
|
<paramdef><parameter>display</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XLastKnownRequestProcessed'>
|
|
<funcprototype>
|
|
<funcdef>unsigned long <function>XLastKnownRequestProcessed</function></funcdef>
|
|
<paramdef>Display *<parameter>display</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>display</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm significance="preferred"><primary>LastKnownRequestProcessed</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>XLastKnownRequestProcessed</primary></indexterm>
|
|
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.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='NextRequest'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>NextRequest</function></funcdef>
|
|
<paramdef><parameter>display</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XNextRequest'>
|
|
<funcprototype>
|
|
<funcdef>unsigned long <function>XNextRequest</function></funcdef>
|
|
<paramdef>Display *<parameter>display</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>display</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm significance="preferred"><primary>NextRequest</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>XNextRequest</primary></indexterm>
|
|
Both extract the full serial number that is to be used for the next
|
|
request.
|
|
Serial numbers are maintained separately for each display connection.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='ProtocolVersion'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>ProtocolVersion</function></funcdef>
|
|
<paramdef><parameter>display</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XProtocolVersion'>
|
|
<funcprototype>
|
|
<funcdef>int <function>XProtocolVersion</function></funcdef>
|
|
<paramdef>Display *<parameter>display</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>display</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm significance="preferred"><primary>ProtocolVersion</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>XProtocolVersion</primary></indexterm>
|
|
Both return the major version number (11) of the X protocol associated with
|
|
the connected display.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='ProtocolRevision'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>ProtocolRevision</function></funcdef>
|
|
<paramdef><parameter>display</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XProtocolRevision'>
|
|
<funcprototype>
|
|
<funcdef>int <function>XProtocolRevision</function></funcdef>
|
|
<paramdef>Display *<parameter>display</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>display</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm significance="preferred"><primary>ProtocolRevision</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>XProtocolRevision</primary></indexterm>
|
|
Both return the minor protocol revision number of the X server.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='QLength'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>QLength</function></funcdef>
|
|
<paramdef><parameter>display</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XQLength'>
|
|
<funcprototype>
|
|
<funcdef>int <function>XQLength</function></funcdef>
|
|
<paramdef>Display *<parameter>display</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>display</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm significance="preferred"><primary>QLength</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>XQLength</primary></indexterm>
|
|
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
|
|
<xref linkend='XEventsQueued' xrefstyle='select: title'/>).
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='RootWindow'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>RootWindow</function></funcdef>
|
|
<paramdef><parameter>display</parameter></paramdef>
|
|
<paramdef><parameter>screen_number</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XRootWindow'>
|
|
<funcprototype>
|
|
<funcdef>Window <function>XRootWindow</function></funcdef>
|
|
<paramdef>Display *<parameter>display</parameter></paramdef>
|
|
<paramdef>int <parameter>screen_number</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>display</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>screen_number</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the appropriate screen number on the host server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm><primary>Window</primary><secondary>RootWindow</secondary></indexterm>
|
|
<indexterm significance="preferred"><primary>RootWindow</primary></indexterm>
|
|
<indexterm><primary>Window</primary><secondary>XRootWindow</secondary></indexterm>
|
|
<indexterm significance="preferred"><primary>XRootWindow</primary></indexterm>
|
|
Both return the root window.
|
|
These are useful with functions that need a drawable of a particular screen
|
|
and for creating top-level windows.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='ScreenCount'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>ScreenCount</function></funcdef>
|
|
<paramdef><parameter>display</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XScreenCount'>
|
|
<funcprototype>
|
|
<funcdef>int <function>XScreenCount</function></funcdef>
|
|
<paramdef>Display *<parameter>display</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>display</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm significance="preferred"><primary>ScreenCount</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>XScreenCount</primary></indexterm>
|
|
Both return the number of available screens.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='ServerVendor'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>ServerVendor</function></funcdef>
|
|
<paramdef><parameter>display</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XServerVendor'>
|
|
<funcprototype>
|
|
<funcdef>char *<function>XServerVendor</function></funcdef>
|
|
<paramdef>Display *<parameter>display</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>display</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm significance="preferred"><primary>ServerVendor</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>XServerVendor</primary></indexterm>
|
|
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.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='VendorRelease'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>VendorRelease</function></funcdef>
|
|
<paramdef><parameter>display</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XVendorRelease'>
|
|
<funcprototype>
|
|
<funcdef>int <function>XVendorRelease</function></funcdef>
|
|
<paramdef>Display *<parameter>display</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>display</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm significance="preferred"><primary>VendorRelease</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>XVendorRelease</primary></indexterm>
|
|
Both return a number related to a vendor's release of the X server.
|
|
</para>
|
|
</sect2>
|
|
<sect2 id="Image_Format_Functions_and_Macros">
|
|
<title>Image Format Functions and Macros</title>
|
|
<!-- .XS -->
|
|
<!-- (SN Image Format Functions and Macros -->
|
|
<!-- .XE -->
|
|
<para>
|
|
<!-- .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
|
|
<link linkend="Transferring_Images_between_Client_and_Server">8.7</link> and
|
|
<link linkend="Manipulating_Images">16.8</link>).
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<indexterm significance="preferred"><primary>XPixmapFormatValues</primary></indexterm>
|
|
The
|
|
<structname>XPixmapFormatValues</structname>
|
|
structure provides an interface to the pixmap format information
|
|
that is returned at the time of a connection setup.
|
|
It contains:
|
|
<synopsis id='XPixmapFormatValues'>
|
|
typedef struct {
|
|
<type>int</type> <structfield>depth</structfield>;
|
|
<type>int</type> <structfield>bits_per_pixel</structfield>;
|
|
<type>int</type> <structfield>scanline_pad</structfield>;
|
|
} <structname>XPixmapFormatValues</structname>;
|
|
</synopsis>
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<!-- .sp -->
|
|
To obtain the pixmap format information for a given display, use
|
|
<function>XListPixmapFormats</function>.
|
|
<indexterm significance="preferred"><primary>XListPixmapFormats</primary></indexterm>
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='XListPixmapFormats'>
|
|
<funcprototype>
|
|
<funcdef>XPixmapFormatValues *<function>XListPixmapFormats</function></funcdef>
|
|
<paramdef>Display *<parameter>display</parameter></paramdef>
|
|
<paramdef>int *<parameter>count_return</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>display</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>count_return</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Returns the number of pixmap formats that are supported by the display.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<function>XListPixmapFormats</function>
|
|
function returns an array of
|
|
<structname>XPixmapFormatValues</structname>
|
|
structures that describe the types of Z format images supported
|
|
by the specified display.
|
|
If insufficient memory is available,
|
|
<function>XListPixmapFormats</function>
|
|
returns NULL.
|
|
To free the allocated storage for the
|
|
<structname>XPixmapFormatValues</structname>
|
|
structures, use
|
|
<xref linkend='XFree' xrefstyle='select: title'/>.
|
|
</para>
|
|
<para>
|
|
<!-- .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.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='ImageByteOrder'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>ImageByteOrder</function></funcdef>
|
|
<paramdef><parameter>display</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XImageByteOrder'>
|
|
<funcprototype>
|
|
<funcdef>int <function>XImageByteOrder</function></funcdef>
|
|
<paramdef>Display *<parameter>display</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>display</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm significance="preferred"><primary>ImageByteOrder</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>XImageByteOrder</primary></indexterm>
|
|
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
|
|
<symbol>LSBFirst</symbol>
|
|
or
|
|
<symbol>MSBFirst</symbol>.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='BitmapUnit'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>XBitmapUnit</function></funcdef>
|
|
<paramdef><parameter>display</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XBitmapUnit'>
|
|
<funcprototype>
|
|
<funcdef>int <function>XBitmapUnit</function></funcdef>
|
|
<paramdef>Display *<parameter>display</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>display</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm significance="preferred"><primary>BitmapUnit</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>XBitmapUnit</primary></indexterm>
|
|
Both return the size of a bitmap's scanline unit in bits.
|
|
The scanline is calculated in multiples of this value.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='BitmapBitOrder'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>BitmapBitOrder</function></funcdef>
|
|
<paramdef><parameter>display</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XBitmapBitOrder'>
|
|
<funcprototype>
|
|
<funcdef>int <function>XBitmapBitOrder</function></funcdef>
|
|
<paramdef>Display *<parameter>display</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>display</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm significance="preferred"><primary>BitmapBitOrder</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>XBitmapBitOrder</primary></indexterm>
|
|
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
|
|
<symbol>LSBFirst</symbol>
|
|
or
|
|
<symbol>MSBFirst</symbol>.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='BitmapPad'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>BitmapPad</function></funcdef>
|
|
<paramdef><parameter>display</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XBitmapPad'>
|
|
<funcprototype>
|
|
<funcdef>int <function>XBitmapPad</function></funcdef>
|
|
<paramdef>Display *<parameter>display</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>display</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm significance="preferred"><primary>BitmapPad</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>XBitmapPad</primary></indexterm>
|
|
Each scanline must be padded to a multiple of bits returned
|
|
by this macro or function.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='DisplayHeight'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>DisplayHeight</function></funcdef>
|
|
<paramdef><parameter>display</parameter></paramdef>
|
|
<paramdef><parameter>screen_number</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XDisplayHeight'>
|
|
<funcprototype>
|
|
<funcdef>int <function>XDisplayHeight</function></funcdef>
|
|
<paramdef>Display *<parameter>display</parameter></paramdef>
|
|
<paramdef>int <parameter>screen_number</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>display</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>screen_number</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the appropriate screen number on the host server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm significance="preferred"><primary>DisplayHeight</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>XDisplayHeight</primary></indexterm>
|
|
Both return an integer that describes the height of the screen
|
|
in pixels.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='DisplayHeightMM'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>DisplayHeightMM</function></funcdef>
|
|
<paramdef><parameter>display</parameter></paramdef>
|
|
<paramdef><parameter>screen_number</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XDisplayHeightMM'>
|
|
<funcprototype>
|
|
<funcdef>int <function>XDisplayHeightMM</function></funcdef>
|
|
<paramdef>Display *<parameter>display</parameter></paramdef>
|
|
<paramdef>int <parameter>screen_number</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>display</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>screen_number</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the appropriate screen number on the host server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm significance="preferred"><primary>DisplayHeightMM</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>XDisplayHeightMM</primary></indexterm>
|
|
Both return the height of the specified screen in millimeters.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='DisplayWidth'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>DisplayWidth</function></funcdef>
|
|
<paramdef><parameter>display</parameter></paramdef>
|
|
<paramdef><parameter>screen_number</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XDisplayWidth'>
|
|
<funcprototype>
|
|
<funcdef>int <function>XDisplayWidth</function></funcdef>
|
|
<paramdef>Display *<parameter>display</parameter></paramdef>
|
|
<paramdef>int <parameter>screen_number</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>display</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>screen_number</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the appropriate screen number on the host server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm significance="preferred"><primary>DisplayWidth</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>XDisplayWidth</primary></indexterm>
|
|
Both return the width of the screen in pixels.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='DisplayWidthMM'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>DisplayWidthMM</function></funcdef>
|
|
<paramdef><parameter>display</parameter></paramdef>
|
|
<paramdef><parameter>screen_number</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XDisplayWidthMM'>
|
|
<funcprototype>
|
|
<funcdef>int <function>XDisplayWidthMM</function></funcdef>
|
|
<paramdef>Display *<parameter>display</parameter></paramdef>
|
|
<paramdef>int <parameter>screen_number</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>display</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>screen_number</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the appropriate screen number on the host server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm significance="preferred"><primary>DisplayWidthMM</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>XDisplayWidthMM</primary></indexterm>
|
|
Both return the width of the specified screen in millimeters.
|
|
</para>
|
|
</sect2>
|
|
<sect2 id="Screen_Information_Macros">
|
|
<title>Screen Information Macros</title>
|
|
<!-- .XS -->
|
|
<!-- (SN Screen Information Macros -->
|
|
<!-- .XE -->
|
|
<para>
|
|
<!-- .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.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='BlackPixelOfScreen'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>BlackPixelOfScreen</function></funcdef>
|
|
<paramdef><parameter>screen</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XBlackPixelOfScreen'>
|
|
<funcprototype>
|
|
<funcdef>unsigned long <function>XBlackPixelOfScreen</function></funcdef>
|
|
<paramdef>Screen *<parameter>screen</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>screen</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the appropriate
|
|
<type>Screen</type>
|
|
structure.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm significance="preferred"><primary>BlackPixelOfScreen</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>XBlackPixelOfScreen</primary></indexterm>
|
|
Both return the black pixel value of the specified screen.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='WhitePixelOfScreen'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>XWhitePixelOfScreen</function></funcdef>
|
|
<paramdef><parameter>screen</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XWhitePixelOfScreen'>
|
|
<funcprototype>
|
|
<funcdef>unsigned long <function>XWhitePixelOfScreen</function></funcdef>
|
|
<paramdef>Screen *<parameter>screen</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>screen</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the appropriate
|
|
<type>Screen</type>
|
|
structure.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm significance="preferred"><primary>WhitePixelOfScreen</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>XWhitePixelOfScreen</primary></indexterm>
|
|
Both return the white pixel value of the specified screen.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='CellsOfScreen'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>CellsOfScreen</function></funcdef>
|
|
<paramdef><parameter>screen</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XCellsOfScreen'>
|
|
<funcprototype>
|
|
<funcdef>int <function>XCellsOfScreen</function></funcdef>
|
|
<paramdef>Screen *<parameter>screen</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>screen</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the appropriate
|
|
<type>Screen</type>
|
|
structure.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm significance="preferred"><primary>CellsOfScreen</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>XCellsOfScreen</primary></indexterm>
|
|
Both return the number of colormap cells in the default colormap
|
|
of the specified screen.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='DefaultColormapOfScreen'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>DefaultColormapOfScreen</function></funcdef>
|
|
<paramdef><parameter>screen</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XDefaultColormapOfScreen'>
|
|
<funcprototype>
|
|
<funcdef>Colormap <function>XDefaultColormapOfScreen</function></funcdef>
|
|
<paramdef>Screen *<parameter>screen</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>screen</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the appropriate
|
|
<type>Screen</type>
|
|
structure.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm significance="preferred"><primary>DefaultColormapOfScreen</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>XDefaultColormapOfScreen</primary></indexterm>
|
|
Both return the default colormap of the specified screen.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='DefaultDepthOfScreen'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>DefaultDepthOfScreen</function></funcdef>
|
|
<paramdef><parameter>screen</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XDefaultDepthOfScreen'>
|
|
<funcprototype>
|
|
<funcdef>int <function>XDefaultDepthOfScreen</function></funcdef>
|
|
<paramdef>Screen *<parameter>screen</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>screen</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the appropriate
|
|
<type>Screen</type>
|
|
structure.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm significance="preferred"><primary>DefaultDepthOfScreen</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>XDefaultDepthOfScreen</primary></indexterm>
|
|
Both return the depth of the root window.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='DefaultGCOfScreen'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>DefaultGCOfScreen</function></funcdef>
|
|
<paramdef><parameter>screen</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XDefaultGCOfScreen'>
|
|
<funcprototype>
|
|
<funcdef>GC <function>XDefaultGCOfScreen</function></funcdef>
|
|
<paramdef>Screen *<parameter>screen</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>screen</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the appropriate
|
|
<type>Screen</type>
|
|
structure.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm significance="preferred"><primary>DefaultGCOfScreen</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>XDefaultGCOfScreen</primary></indexterm>
|
|
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.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='DefaultVisualOfScreen'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>XDefaultVisualOfScreen</function></funcdef>
|
|
<paramdef><parameter>screen</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XDefaultVisualOfScreen'>
|
|
<funcprototype>
|
|
<funcdef>Visual *<function>XDefaultVisualOfScreen</function></funcdef>
|
|
<paramdef>Screen *<parameter>screen</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>screen</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the appropriate
|
|
<type>Screen</type>
|
|
structure.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm significance="preferred"><primary>DefaultVisualOfScreen</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>XDefaultVisualOfScreen</primary></indexterm>
|
|
Both return the default visual of the specified screen.
|
|
For information on visual types,
|
|
see <link linkend="Visual_Types">section 3.1</link>.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='DoesBackingStore'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>DoesBackingStore</function></funcdef>
|
|
<paramdef><parameter>screen</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XDoesBackingStore'>
|
|
<funcprototype>
|
|
<funcdef>int <function>XDoesBackingStore</function></funcdef>
|
|
<paramdef>Screen *<parameter>screen</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>screen</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the appropriate
|
|
<type>Screen</type>
|
|
structure.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm significance="preferred"><primary>DoesBackingStore</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>XDoesBackingStore</primary></indexterm>
|
|
Both return a value indicating whether the screen supports backing
|
|
stores.
|
|
The value returned can be one of
|
|
<symbol>WhenMapped</symbol>,
|
|
<symbol>NotUseful</symbol>,
|
|
or
|
|
<symbol>Always</symbol>
|
|
(see <link linkend="Backing_Store_Attribute">section 3.2.4</link>).
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='DoesSaveUnders'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>DoesSaveUnders</function></funcdef>
|
|
<paramdef><parameter>screen</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XDoesSaveUnders'>
|
|
<funcprototype>
|
|
<funcdef>Bool <function>XDoesSaveUnders</function></funcdef>
|
|
<paramdef>Screen *<parameter>screen</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>screen</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the appropriate
|
|
<type>Screen</type>
|
|
structure.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm significance="preferred"><primary>DoesSaveUnders</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>XDoesSaveUnders</primary></indexterm>
|
|
Both return a Boolean value indicating whether the
|
|
screen supports save unders.
|
|
If
|
|
<symbol>True</symbol>,
|
|
the screen supports save unders.
|
|
If
|
|
<symbol>False</symbol>,
|
|
the screen does not support save unders
|
|
(see <link linkend="Save_Under_Flag">section 3.2.5</link>).
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='DisplayOfScreen'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>DisplayOfScreen</function></funcdef>
|
|
<paramdef><parameter>screen</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XDisplayOfScreen'>
|
|
<funcprototype>
|
|
<funcdef>Display *<function>XDisplayOfScreen</function></funcdef>
|
|
<paramdef>Screen *<parameter>screen</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>screen</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the appropriate
|
|
<type>Screen</type>
|
|
structure.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm significance="preferred"><primary>DisplayOfScreen</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>XDisplayOfScreen</primary></indexterm>
|
|
Both return the display of the specified screen.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
<indexterm significance="preferred"><primary>XScreenNumberOfScreen</primary></indexterm>
|
|
</para>
|
|
<funcsynopsis id='ScreenNumberOfScreen'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>ScreenNumberOfScreen</function></funcdef>
|
|
<paramdef><parameter>screen</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XScreenNumberOfScreen'>
|
|
<funcprototype>
|
|
<funcdef>long <function>XScreenNumberOfScreen</function></funcdef>
|
|
<paramdef>Screen *<parameter>screen</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>screen</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the appropriate
|
|
<type>Screen</type>
|
|
structure.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<function>XScreenNumberOfScreen</function>
|
|
function returns the screen index number of the specified screen.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='EventMaskOfScreen'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>EventMaskOfScreen</function></funcdef>
|
|
<paramdef><parameter>screen</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XEventMaskOfScreen'>
|
|
<funcprototype>
|
|
<funcdef>long <function>XEventMaskOfScreen</function></funcdef>
|
|
<paramdef>Screen *<parameter>screen</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>screen</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the appropriate
|
|
<type>Screen</type>
|
|
structure.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm significance="preferred"><primary>EventMaskOfScreen</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>XEventMaskOfScreen</primary></indexterm>
|
|
Both return the event mask of the root window for the specified screen
|
|
at connection setup time.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='WidthOfScreen'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>WidthOfScreen</function></funcdef>
|
|
<paramdef><parameter>screen</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XWidthOfScreen'>
|
|
<funcprototype>
|
|
<funcdef>int <function>XWidthOfScreen</function></funcdef>
|
|
<paramdef>Screen *<parameter>screen</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>screen</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the appropriate
|
|
<type>Screen</type>
|
|
structure.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm significance="preferred"><primary>WidthOfScreen</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>XWidthOfScreen</primary></indexterm>
|
|
Both return the width of the specified screen in pixels.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='HeightOfScreen'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>HeightOfScreen</function></funcdef>
|
|
<paramdef><parameter>screen</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XHeightOfScreen'>
|
|
<funcprototype>
|
|
<funcdef>int <function>XHeightOfScreen</function></funcdef>
|
|
<paramdef>Screen *<parameter>screen</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>screen</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the appropriate
|
|
<type>Screen</type>
|
|
structure.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm significance="preferred"><primary>HeightOfScreen</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>XHeightOfScreen</primary></indexterm>
|
|
Both return the height of the specified screen in pixels.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='WidthMMOfScreen'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>WidthMMOfScreen</function></funcdef>
|
|
<paramdef><parameter>screen</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XWidthMMOfScreen'>
|
|
<funcprototype>
|
|
<funcdef>int <function>XWidthMMOfScreen</function></funcdef>
|
|
<paramdef>Screen *<parameter>screen</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>screen</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the appropriate
|
|
<type>Screen</type>
|
|
structure.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm significance="preferred"><primary>WidthMMOfScreen</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>XWidthMMOfScreen</primary></indexterm>
|
|
Both return the width of the specified screen in millimeters.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='HeightMMOfScreen'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>HeightMMOfScreen</function></funcdef>
|
|
<paramdef><parameter>screen</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XHeightMMOfScreen'>
|
|
<funcprototype>
|
|
<funcdef>int <function>XHeightMMOfScreen</function></funcdef>
|
|
<paramdef>Screen *<parameter>screen</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>screen</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the appropriate
|
|
<type>Screen</type>
|
|
structure.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm significance="preferred"><primary>HeightMMOfScreen</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>XHeightMMOfScreen</primary></indexterm>
|
|
Both return the height of the specified screen in millimeters.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='MaxCmapsOfScreen'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>MaxCmapsOfScreen</function></funcdef>
|
|
<paramdef><parameter>screen</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XMaxCmapsOfScreen'>
|
|
<funcprototype>
|
|
<funcdef>int <function>XMaxCmapsOfScreen</function></funcdef>
|
|
<paramdef>Screen *<parameter>screen</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>screen</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the appropriate
|
|
<type>Screen</type>
|
|
structure.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm significance="preferred"><primary>MaxCmapsOfScreen</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>XMaxCmapsOfScreen</primary></indexterm>
|
|
Both return the maximum number of installed colormaps supported
|
|
by the specified screen
|
|
(see <link linkend="Managing_Installed_Colormaps">section 9.3</link>).
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='MinCmapsOfScreen'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>MinCmapsOfScreen</function></funcdef>
|
|
<paramdef><parameter>screen</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XMinCmapsOfScreen'>
|
|
<funcprototype>
|
|
<funcdef>int <function>XMinCmapsOfScreen</function></funcdef>
|
|
<paramdef>Screen *<parameter>screen</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>screen</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the appropriate
|
|
<type>Screen</type>
|
|
structure.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm significance="preferred"><primary>MinCmapsOfScreen</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>XMinCmapsOfScreen</primary></indexterm>
|
|
Both return the minimum number of installed colormaps supported
|
|
by the specified screen
|
|
(see <link linkend="Managing_Installed_Colormaps">section 9.3</link>).
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='PlanesOfScreen'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>PlanesOfScreen</function></funcdef>
|
|
<paramdef><parameter>screen</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XPlanesOfScreen'>
|
|
<funcprototype>
|
|
<funcdef>int <function>XPlanesOfScreen</function></funcdef>
|
|
<paramdef>Screen *<parameter>screen</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>screen</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the appropriate
|
|
<type>Screen</type>
|
|
structure.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm significance="preferred"><primary>PlanesOfScreen</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>XPlanesOfScreen</primary></indexterm>
|
|
Both return the depth of the root window.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='RootWindowOfScreen'>
|
|
<funcprototype role='macro'>
|
|
<funcdef><function>RootWindowOfScreen</function></funcdef>
|
|
<paramdef><parameter>screen</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis id='XRootWindowOfScreen'>
|
|
<funcprototype>
|
|
<funcdef>Window <function>XRootWindowOfScreen</function></funcdef>
|
|
<paramdef>Screen *<parameter>screen</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>screen</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the appropriate
|
|
<type>Screen</type>
|
|
structure.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
<indexterm significance="preferred"><primary>RootWindowOfScreen</primary></indexterm>
|
|
<indexterm significance="preferred"><primary>XRootWindowOfScreen</primary></indexterm>
|
|
Both return the root window of the specified screen.
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
<sect1 id="Generating_a_NoOperation_Protocol_Request">
|
|
<title>Generating a NoOperation Protocol Request</title>
|
|
<!-- .XS -->
|
|
<!-- (SN Generating a NoOperation Protocol Request -->
|
|
<!-- .XE -->
|
|
<para>
|
|
<!-- .LP -->
|
|
To execute a
|
|
<systemitem>NoOperation</systemitem>
|
|
protocol request, use
|
|
<xref linkend='XNoOp' xrefstyle='select: title'/>.
|
|
<indexterm significance="preferred"><primary>XNoOp</primary></indexterm>
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='XNoOp'>
|
|
<funcprototype>
|
|
<funcdef><function>XNoOp</function></funcdef>
|
|
<paramdef>Display *<parameter>display</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><emphasis remap='I'>display</emphasis></term>
|
|
<listitem>
|
|
<para>Specifies the connection to the X server.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XNoOp' xrefstyle='select: title'/>
|
|
function sends a
|
|
<systemitem>NoOperation</systemitem>
|
|
protocol request to the X server,
|
|
thereby exercising the connection.
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="Freeing_Client_Created_Data">
|
|
<title>Freeing Client-Created Data</title>
|
|
<!-- .XS -->
|
|
<!-- (SN Freeing Client-Created Data -->
|
|
<!-- .XE -->
|
|
<para>
|
|
<!-- .LP -->
|
|
To free in-memory data that was created by an Xlib function, use
|
|
<xref linkend='XFree' xrefstyle='select: title'/>.
|
|
<indexterm significance="preferred"><primary>XFree</primary></indexterm>
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='XFree'>
|
|
<funcprototype>
|
|
<funcdef><function>XFree</function></funcdef>
|
|
<paramdef>void *<parameter>data</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>data</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the data that is to be freed.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XFree' xrefstyle='select: title'/>
|
|
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.
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="Closing_the_Display">
|
|
<title>Closing the Display</title>
|
|
<!-- .XS -->
|
|
<!-- (SN Closing the Display -->
|
|
<!-- .XE -->
|
|
<para>
|
|
<!-- .LP -->
|
|
To close a display or disconnect from the X server, use
|
|
<function>XCloseDisplay</function>.
|
|
<indexterm significance="preferred"><primary>XCloseDisplay</primary></indexterm>
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='xclosedisplay'>
|
|
<funcprototype>
|
|
<funcdef><function>XCloseDisplay</function></funcdef>
|
|
<paramdef>Display *<parameter>display</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>display</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<function>XCloseDisplay</function>
|
|
function closes the connection to the X server for the display specified in the
|
|
<type>Display</type>
|
|
structure and destroys all windows, resource IDs
|
|
(<type>Window</type>,
|
|
<type>Font</type>,
|
|
<type>Pixmap</type>,
|
|
<type>Colormap</type>,
|
|
<type>Cursor</type>,
|
|
and
|
|
<type>GContext</type>),
|
|
or other resources that the client has created
|
|
on this display, unless the close-down mode of the client has been changed
|
|
(see
|
|
<xref linkend='XSetCloseDownMode' xrefstyle='select: title'/>).
|
|
Therefore, these windows, resource IDs, and other resources should never be
|
|
referenced again or an error will be generated.
|
|
Before exiting, you should call
|
|
<function>XCloseDisplay</function>
|
|
explicitly so that any pending errors are reported as
|
|
<function>XCloseDisplay</function>
|
|
performs a final
|
|
<xref linkend='XSync' xrefstyle='select: title'/>
|
|
operation.
|
|
<indexterm><primary>Resource IDs</primary></indexterm>
|
|
<indexterm><primary>XCloseDisplay</primary></indexterm>
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<function>XCloseDisplay</function>
|
|
can generate a
|
|
<errorname>BadGC</errorname>
|
|
error.
|
|
<!-- .sp -->
|
|
</para>
|
|
<para>
|
|
<!-- .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
|
|
<xref linkend='XSetCloseDownMode' xrefstyle='select: title'/>.
|
|
<indexterm significance="preferred"><primary>XSetCloseDownMode</primary></indexterm>
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='XSetCloseDownMode'>
|
|
<funcprototype>
|
|
<funcdef><function>XSetCloseDownMode</function></funcdef>
|
|
<paramdef>Display *<parameter>display</parameter></paramdef>
|
|
<paramdef>int <parameter>close_mode</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>display</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>close_mode</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the client close-down mode.
|
|
You can pass
|
|
<symbol>DestroyAll</symbol>,
|
|
<symbol>RetainPermanent</symbol>,
|
|
or
|
|
<symbol>RetainTemporary</symbol>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XSetCloseDownMode' xrefstyle='select: title'/> function
|
|
defines what will happen to the client's resources at connection close.
|
|
A connection starts in
|
|
<symbol>DestroyAll</symbol>
|
|
mode.
|
|
For information on what happens to the client's resources when the
|
|
close_mode argument is
|
|
<symbol>RetainPermanent</symbol>
|
|
or
|
|
<symbol>RetainTemporary</symbol>,
|
|
see <link linkend='Using_X_Server_Connection_Close_Operations'>section 2.6</link>.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<xref linkend='XSetCloseDownMode' xrefstyle='select: title'/>
|
|
can generate a
|
|
<errorname>BadValue</errorname>
|
|
error.
|
|
</para>
|
|
</sect1>
|
|
<sect1 id='Using_X_Server_Connection_Close_Operations'>
|
|
<title>Using X Server Connection Close Operations</title>
|
|
<!-- .XS -->
|
|
<!-- (SN Using X Server Connection Close Operations -->
|
|
<!-- .XE -->
|
|
<para>
|
|
<!-- .LP -->
|
|
When the X server's connection to a client is closed
|
|
either by an explicit call to
|
|
<function>XCloseDisplay</function>
|
|
or by a process that exits, the X server performs the following
|
|
automatic operations:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
It disowns all selections owned by the client
|
|
(see
|
|
<xref linkend='XSetSelectionOwner' xrefstyle='select: title'/>).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
It performs an
|
|
<xref linkend='XUngrabPointer' xrefstyle='select: title'/>
|
|
and
|
|
<xref linkend='XUngrabKeyboard' xrefstyle='select: title'/>
|
|
if the client has actively grabbed the pointer
|
|
or the keyboard.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
It performs an
|
|
<xref linkend='XUngrabServer' xrefstyle='select: title'/>
|
|
if the client has grabbed the server.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
It releases all passive grabs made by the client.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
It marks all resources (including colormap entries) allocated
|
|
by the client either as permanent or temporary,
|
|
depending on whether the close-down mode is
|
|
<symbol>RetainPermanent</symbol>
|
|
or
|
|
<symbol>RetainTemporary</symbol>.
|
|
However, this does not prevent other client applications from explicitly
|
|
destroying the resources (see
|
|
<xref linkend='XSetCloseDownMode' xrefstyle='select: title'/>).
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
<!-- .LP -->
|
|
When the close-down mode is
|
|
<symbol>DestroyAll</symbol>,
|
|
the X server destroys all of a client's resources as follows:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
It performs a
|
|
<systemitem>MapWindow</systemitem>
|
|
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.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
It destroys all windows created by the client.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
It performs the appropriate free request on each nonwindow resource created by
|
|
the client in the server (for example,
|
|
<type>Font</type>,
|
|
<type>Pixmap</type>,
|
|
<type>Cursor</type>,
|
|
<type>Colormap</type>,
|
|
and
|
|
<type>GContext</type>).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
It frees all colors and colormap entries allocated by a client application.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
<!-- .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
|
|
<symbol>DestroyAll</symbol>,
|
|
the X server does the following:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
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
|
|
<symbol>RetainPermanent</symbol>
|
|
or
|
|
<symbol>RetainTemporary</symbol>
|
|
mode.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
It deletes all but the predefined atom identifiers.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
It deletes all properties on all root windows
|
|
(see <link linkend="Properties_and_Atoms">section 4.3</link>).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
It resets all device maps and attributes
|
|
(for example, key click, bell volume, and acceleration)
|
|
as well as the access control list.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
It restores the standard root tiles and cursors.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
It restores the default font path.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
It restores the input focus to state
|
|
<symbol>PointerRoot</symbol>.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
<!-- .LP -->
|
|
However, the X server does not reset if you close a connection with a close-down
|
|
mode set to
|
|
<symbol>RetainPermanent</symbol>
|
|
or
|
|
<symbol>RetainTemporary</symbol>.
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="Using_Xlib_with_Threads">
|
|
<title>Using Xlib with Threads</title>
|
|
<!-- .XS -->
|
|
<!-- (SN Using Xlib with Threads -->
|
|
<!-- .XE -->
|
|
<para>
|
|
<!-- .LP -->
|
|
On systems that have threads, support may be provided to permit
|
|
multiple threads to use Xlib concurrently.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
To initialize support for concurrent threads, use
|
|
<function>XInitThreads</function>.
|
|
<indexterm significance="preferred"><primary>XInitThreads</primary></indexterm>
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='XInitThreads'>
|
|
<funcprototype>
|
|
<funcdef>Status <function>XInitThreads</function></funcdef>
|
|
<void />
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<function>XInitThreads</function>
|
|
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.
|
|
</para>
|
|
<para>
|
|
<!-- .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.
|
|
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
To lock a display across several Xlib calls, use
|
|
<function>XLockDisplay</function>.
|
|
<indexterm significance="preferred"><primary>XLockDisplay</primary></indexterm>
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='xlockdisplay'>
|
|
<funcprototype>
|
|
<funcdef><function>XLockDisplay</function></funcdef>
|
|
<paramdef>Display *<parameter>display</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>display</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<function>XLockDisplay</function>
|
|
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
|
|
<function>XLockDisplay</function>
|
|
work correctly; the display will not actually be unlocked until
|
|
<xref linkend='XUnlockDisplay' xrefstyle='select: title'/>
|
|
has been called the same number of times as
|
|
<function>XLockDisplay</function>.
|
|
This function has no effect unless Xlib was successfully initialized
|
|
for threads using
|
|
<function>XInitThreads</function>.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
To unlock a display, use
|
|
<xref linkend='XUnlockDisplay' xrefstyle='select: title'/>.
|
|
<indexterm significance="preferred"><primary>XUnlockDisplay</primary></indexterm>
|
|
<!-- .sM -->
|
|
</para>
|
|
<funcsynopsis id='XUnlockDisplay'>
|
|
<funcprototype>
|
|
<funcdef><function>XUnlockDisplay</function></funcdef>
|
|
<paramdef>Display *<parameter>display</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>display</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XUnlockDisplay' xrefstyle='select: title'/>
|
|
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
|
|
<function>XLockDisplay</function>
|
|
has been called multiple times by a thread, then
|
|
<xref linkend='XUnlockDisplay' xrefstyle='select: title'/>
|
|
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
|
|
<function>XInitThreads</function>.
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="Using_Internal_Connections">
|
|
<title>Using Internal Connections</title>
|
|
<!-- .XS -->
|
|
<!-- (SN Using Internal Connections -->
|
|
<!-- .XE -->
|
|
<para>
|
|
<!-- .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
|
|
<link linkend='Locales_and_Internationalized_Text_Functions'>chapter 13</link>).
|
|
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.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
To track internal connections for a display, use
|
|
<xref linkend='XAddConnectionWatch' xrefstyle='select: title'/>.
|
|
</para>
|
|
<funcsynopsis id='xconnectionwatch'>
|
|
<funcprototype>
|
|
<funcdef>typedef void (*XConnectionWatchProc)</funcdef>
|
|
<paramdef>Display *<parameter>display</parameter></paramdef>
|
|
<paramdef>XPointer <parameter>client_data</parameter></paramdef>
|
|
<paramdef>int <parameter>fd</parameter></paramdef>
|
|
<paramdef>Bool <parameter>opening</parameter></paramdef>
|
|
<paramdef>XPointer *<parameter>watch_data</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
|
|
<funcsynopsis id='XAddConnectionWatch'>
|
|
<funcprototype>
|
|
<funcdef>Status <function>XAddConnectionWatch</function></funcdef>
|
|
<paramdef>Display *<parameter>display</parameter></paramdef>
|
|
<paramdef>XConnectionWatchProc <parameter>procedure</parameter></paramdef>
|
|
<paramdef>XPointer <parameter>client_data</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>display</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>procedure</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the procedure to be called.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>client_data</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the additional client data.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XAddConnectionWatch' xrefstyle='select: title'/>
|
|
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
|
|
<symbol>True</symbol>,
|
|
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
|
|
<symbol>False</symbol>,
|
|
the location pointed to by watch_data will hold this same private data pointer.
|
|
</para>
|
|
<para>
|
|
<!-- .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
|
|
<xref linkend='XAddConnectionWatch' xrefstyle='select: title'/>
|
|
returns.
|
|
<xref linkend='XAddConnectionWatch' xrefstyle='select: title'/>
|
|
returns a nonzero status if the procedure is successfully registered;
|
|
otherwise, it returns zero.
|
|
</para>
|
|
<para>
|
|
<!-- .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
|
|
<function>XLockDisplay</function>.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
To stop tracking internal connections for a display, use
|
|
<function>XRemoveConnectionWatch</function>.
|
|
<indexterm significance="preferred"><primary>XRemoveConnectionWatch</primary></indexterm>
|
|
<!-- .sM -->
|
|
</para>
|
|
<para>
|
|
</para>
|
|
<funcsynopsis id='xremoveconnectionwatch'>
|
|
<funcprototype>
|
|
<funcdef>Status <function>XRemoveConnectionWatch</function></funcdef>
|
|
<paramdef>Display *<parameter>display</parameter></paramdef>
|
|
<paramdef>XConnectionWatchProc <parameter>procedure</parameter></paramdef>
|
|
<paramdef>XPointer <parameter>client_data</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>display</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>procedure</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the procedure to be called.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>client_data</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the additional client data.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<function>XRemoveConnectionWatch</function>
|
|
function removes a previously registered connection watch procedure.
|
|
The client_data must match the client_data used when the procedure
|
|
was initially registered.
|
|
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
To process input on an internal connection, use
|
|
<xref linkend='XProcessInternalConnection' xrefstyle='select: title'/>.
|
|
<indexterm significance="preferred"><primary>XProcessInternalConnection</primary></indexterm>
|
|
<!-- .sM -->
|
|
</para>
|
|
<para>
|
|
</para>
|
|
<funcsynopsis id='XProcessInternalConnection'>
|
|
<funcprototype>
|
|
<funcdef>void <function>XProcessInternalConnection</function></funcdef>
|
|
<paramdef>Display *<parameter>display</parameter></paramdef>
|
|
<paramdef>int <parameter>fd</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>display</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>fd</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the file descriptor.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XProcessInternalConnection' xrefstyle='select: title'/>
|
|
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,
|
|
<function>select</function>
|
|
or
|
|
<function>poll</function>)
|
|
has indicated that input is available; otherwise,
|
|
the effect is not defined.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
To obtain all of the current internal connections for a display, use
|
|
<xref linkend='XInternalConnectionNumbers' xrefstyle='select: title'/>.
|
|
<indexterm significance="preferred"><primary>XInternalConnectionNumbers</primary></indexterm>
|
|
<!-- .sM -->
|
|
</para>
|
|
<para>
|
|
</para>
|
|
<funcsynopsis id='XInternalConnectionNumbers'>
|
|
<funcprototype>
|
|
<funcdef>Status <function>XInternalConnectionNumbers</function></funcdef>
|
|
<paramdef>Display *<parameter>display</parameter></paramdef>
|
|
<paramdef>int ** <parameter>fd</parameter></paramdef>
|
|
<paramdef>int * <parameter>count_return</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<!-- .FN -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>display</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>fd_return</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Returns the file descriptors.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>count_return</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Returns the number of file descriptors.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XInternalConnectionNumbers' xrefstyle='select: title'/>
|
|
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
|
|
<xref linkend='XFree' xrefstyle='select: title'/>.
|
|
This functions returns a nonzero status if the list is successfully allocated;
|
|
otherwise, it returns zero.
|
|
</para>
|
|
</sect1>
|
|
</chapter>
|