mirror of
https://gitlab.freedesktop.org/xorg/lib/libx11.git
synced 2026-05-26 13:38:17 +02:00
847 lines
34 KiB
XML
847 lines
34 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="Introduction_to_Xlib"><title>Introduction to Xlib</title>
|
||
|
||
<para>
|
||
The X Window System is a network-transparent window system that was
|
||
designed at MIT. X display servers run on computers with either
|
||
monochrome or color bitmap display hardware. The server distributes
|
||
user input to and accepts output requests from various client programs
|
||
located either on the same machine or elsewhere in the network. Xlib
|
||
is a C subroutine library that application programs (clients) use to
|
||
interface with the window system by means of a stream connection.
|
||
Although a client usually runs on the same machine as the X server
|
||
it is talking to, this need not be the case.
|
||
</para>
|
||
<para>
|
||
<citetitle>Xlib − C Language X Interface</citetitle> is a reference
|
||
guide to the low-level C language interface to the X Window System
|
||
protocol. It is neither a tutorial nor a user’s guide to programming
|
||
the X Window System. Rather, it provides a detailed description of
|
||
each function in the library as well as a discussion of the related
|
||
background information. <citetitle>Xlib − C Language X Interface</citetitle>
|
||
assumes a basic understanding of a graphics window system and of the C
|
||
programming language. Other higher-level abstractions (for example,
|
||
those provided by the toolkits for X) are built on top of the Xlib
|
||
library. For further information about these higher-level libraries,
|
||
see the appropriate toolkit documentation.
|
||
The <olink targetdoc='x11protocol' targetptr='x11protocol'
|
||
><citetitle>X Window System Protocol</citetitle></olink> provides the
|
||
definitive word on the behavior of X.
|
||
Although additional information appears here, the protocol document is
|
||
the ruling document.
|
||
</para>
|
||
<para>
|
||
To provide an introduction to X programming, this chapter discusses:
|
||
|
||
<itemizedlist>
|
||
<listitem><para><link linkend="Overview_of_the_X_Window_System">Overview of the X Window System</link></para></listitem>
|
||
<listitem><para><link linkend="Errors">Errors</link></para></listitem>
|
||
<listitem><para><link linkend="Standard_Header_Files">Standard header files</link></para></listitem>
|
||
<listitem><para><link linkend="Generic_Values_and_Types">Generic values and types</link></para></listitem>
|
||
<listitem><para><link linkend="Naming_and_Argument_Conventions_within_Xlib">Naming and argument conventions within Xlib</link></para></listitem>
|
||
<listitem><para><link linkend="Programming_Considerations">Programming considerations</link></para></listitem>
|
||
<listitem><para><link linkend="Character_Sets_and_Encodings">Character sets and encodings</link></para></listitem>
|
||
<listitem><para><link linkend="Formatting_Conventions">Formatting conventions</link></para></listitem>
|
||
</itemizedlist>
|
||
</para>
|
||
|
||
<sect1 id="Overview_of_the_X_Window_System">
|
||
<title>Overview of the X Window System</title>
|
||
<para>
|
||
Some of the terms used in this book are unique to X,
|
||
and other terms that are common to other window systems
|
||
have different meanings in X. You may find it helpful to refer to
|
||
<link linkend="glossary">the glossary</link>,
|
||
which is located at the end of the book.
|
||
</para>
|
||
<para>
|
||
The X Window System supports one or more screens containing
|
||
overlapping windows or subwindows.
|
||
<indexterm><primary>Screen</primary></indexterm>
|
||
A <firstterm>screen</firstterm> is a physical monitor and hardware
|
||
that can be color, grayscale, or monochrome.
|
||
There can be multiple screens for each display or workstation.
|
||
A single X server can provide display services for any number of screens.
|
||
A set of screens for a single user with one keyboard and one pointer
|
||
(usually a mouse) is called a <firstterm>display</firstterm>.
|
||
</para>
|
||
<para>
|
||
All the windows in an X server are arranged in strict hierarchies.
|
||
At the top of each hierarchy is a <firstterm>root window</firstterm>,
|
||
which covers each of the display screens.
|
||
Each root window is partially or completely covered by child windows.
|
||
All windows, except for root windows, have parents.
|
||
There is usually at least one window for each application program.
|
||
<indexterm><primary>Child window</primary></indexterm>
|
||
<indexterm><primary>Parent Window</primary></indexterm>
|
||
Child windows may in turn have their own children.
|
||
In this way,
|
||
an application program can create an arbitrarily deep tree
|
||
on each screen.
|
||
X provides graphics, text, and raster operations for windows.
|
||
</para>
|
||
<para>
|
||
A child window can be larger than its parent.
|
||
That is, part or all of
|
||
the child window can extend beyond the boundaries of the parent,
|
||
but all output to a window is clipped by its parent.
|
||
<indexterm><primary>Stacking order</primary></indexterm>
|
||
If several children of a window have overlapping locations,
|
||
one of the children is considered to be on top of or raised over the
|
||
others, thus obscuring them.
|
||
Output to areas covered by other windows is suppressed by the window
|
||
system unless the window has backing store.
|
||
If a window is obscured by a second window,
|
||
the second window obscures only those ancestors of the second window
|
||
that are also ancestors of the first window.
|
||
</para>
|
||
<para>
|
||
<indexterm significance="preferred"><primary>Window</primary></indexterm>
|
||
A window has a border zero or more pixels in width, which can
|
||
be any pattern (pixmap) or solid color you like.
|
||
A window usually but not always has a background pattern,
|
||
which will be repainted by the window system when uncovered.
|
||
Child windows obscure their parents,
|
||
and graphic operations in the parent window usually
|
||
are clipped by the children.
|
||
</para>
|
||
<para>
|
||
Each window and pixmap has its own coordinate system.
|
||
The coordinate system has the X axis horizontal and the Y axis vertical
|
||
with the origin [0, 0] at the upper-left corner.
|
||
Coordinates are integral,
|
||
in terms of pixels,
|
||
and coincide with pixel centers.
|
||
For a window,
|
||
the origin is inside the border at the inside, upper-left corner.
|
||
</para>
|
||
<para>
|
||
X does not guarantee to preserve the contents of windows.
|
||
When part or all of a window is hidden and then brought back onto the screen,
|
||
its contents may be lost.
|
||
The server then sends the client program an
|
||
<systemitem class="event">Expose</systemitem>
|
||
event to notify it that part or all of the window needs to be repainted.
|
||
Programs must be prepared to regenerate the contents of windows on demand.
|
||
</para>
|
||
<para>
|
||
<indexterm><primary>Pixmap</primary></indexterm>
|
||
<indexterm><primary>Drawable</primary></indexterm>
|
||
<indexterm><primary>Tile</primary></indexterm>
|
||
<indexterm><primary>Bitmap</primary></indexterm>
|
||
X also provides off-screen storage of graphics objects,
|
||
called <firstterm linkend="glossary:Pixmap">pixmaps</firstterm>.
|
||
Single plane (depth 1) pixmaps are sometimes referred to as
|
||
<firstterm>bitmaps</firstterm>.
|
||
Pixmaps can be used in most graphics functions interchangeably with
|
||
windows and are used in various graphics operations to define patterns or tiles.
|
||
Windows and pixmaps together are referred to as drawables.
|
||
</para>
|
||
<para>
|
||
Most of the functions in Xlib just add requests to an output buffer.
|
||
These requests later execute asynchronously on the X server.
|
||
Functions that return values of information stored in
|
||
the server do not return (that is, they block)
|
||
until an explicit reply is received or an error occurs.
|
||
You can provide an error handler,
|
||
which will be called when the error is reported.
|
||
</para>
|
||
<para>
|
||
<indexterm><primary>XSync</primary></indexterm>
|
||
If a client does not want a request to execute asynchronously,
|
||
it can follow the request with a call to
|
||
<xref linkend='XSync' xrefstyle='select: title'/>,
|
||
which blocks until all previously buffered
|
||
asynchronous events have been sent and acted on.
|
||
As an important side effect,
|
||
the output buffer in Xlib is always flushed by a call to any function
|
||
that returns a value from the server or waits for input.
|
||
</para>
|
||
<para>
|
||
<indexterm><primary>Resource IDs</primary></indexterm>
|
||
<indexterm><primary>Resource IDs</primary><secondary>Window</secondary></indexterm>
|
||
<indexterm><primary>Resource IDs</primary><secondary>Font</secondary></indexterm>
|
||
<indexterm><primary>Resource IDs</primary><secondary>Pixmap</secondary></indexterm>
|
||
<indexterm><primary>Resource IDs</primary><secondary>Colormap</secondary></indexterm>
|
||
<indexterm><primary>Resource IDs</primary><secondary>Cursor</secondary></indexterm>
|
||
<indexterm><primary>Resource IDs</primary><secondary>GContext</secondary></indexterm>
|
||
Many Xlib functions will return an integer resource ID,
|
||
which allows you to refer to objects stored on the X server.
|
||
These can be of type
|
||
<type>Window</type>,
|
||
<type>Font</type>,
|
||
<type>Pixmap</type>,
|
||
<type>Colormap</type>,
|
||
<type>Cursor</type>,
|
||
and
|
||
<type>GContext</type>,
|
||
as defined in the file
|
||
<filename class="headerfile"><X11/X.h></filename>.
|
||
<indexterm type="file"><primary><filename class="headerfile">X11/X.h</filename></primary></indexterm>
|
||
<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/X.h></filename></secondary></indexterm>
|
||
<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/X.h></filename></secondary></indexterm>
|
||
These resources are created by requests and are destroyed
|
||
(or freed) by requests or when connections are closed.
|
||
Most of these resources are potentially sharable between
|
||
applications, and in fact, windows are manipulated explicitly by
|
||
window manager programs.
|
||
Fonts and cursors are shared automatically across multiple screens.
|
||
Fonts are loaded and unloaded as needed and are shared by multiple clients.
|
||
Fonts are often cached in the server.
|
||
Xlib provides no support for sharing graphics contexts between applications.
|
||
</para>
|
||
<para>
|
||
<indexterm><primary>Event</primary></indexterm>
|
||
Client programs are informed of events.
|
||
Events may either be side effects of a request (for example, restacking windows
|
||
generates
|
||
<systemitem class="event">Expose</systemitem>
|
||
events) or completely asynchronous (for example, from the keyboard).
|
||
A client program asks to be informed of events.
|
||
Because other applications can send events to your application,
|
||
programs must be prepared to handle (or ignore) events of all types.
|
||
</para>
|
||
<para>
|
||
Input events (for example, a key pressed or the pointer moved)
|
||
arrive asynchronously from the server and are queued until they are
|
||
requested by an explicit call (for example,
|
||
<xref linkend='XNextEvent' xrefstyle='select: title'/>
|
||
or
|
||
<xref linkend='XWindowEvent' xrefstyle='select: title'/>).
|
||
In addition, some library
|
||
functions (for example,
|
||
<xref linkend='XRaiseWindow' xrefstyle='select: title'/>)
|
||
generate
|
||
<symbol>Expose</symbol>
|
||
and
|
||
<symbol>ConfigureRequest</symbol>
|
||
events.
|
||
These events also arrive asynchronously, but the client may
|
||
<indexterm><primary>XSync</primary></indexterm>
|
||
wish to explicitly wait for them by calling
|
||
<xref linkend='XSync' xrefstyle='select: title'/>
|
||
after calling a function that can cause the server to generate events.
|
||
</para>
|
||
</sect1>
|
||
|
||
<sect1 id="Errors">
|
||
<title>Errors</title>
|
||
|
||
<para>
|
||
Some functions return
|
||
<type>Status</type>,
|
||
an integer error indication.
|
||
If the function fails, it returns a zero.
|
||
If the function returns a status of zero,
|
||
it has not updated the return arguments.
|
||
<indexterm><primary>Status</primary></indexterm>
|
||
Because C does not provide multiple return values,
|
||
many functions must return their results by writing into client-passed storage.
|
||
<indexterm><primary>Error</primary><secondary>handling</secondary></indexterm>
|
||
By default, errors are handled either by a standard library function
|
||
or by one that you provide.
|
||
Functions that return pointers to strings return NULL pointers if
|
||
the string does not exist.
|
||
</para>
|
||
<para>
|
||
The X server reports protocol errors at the time that it detects them.
|
||
If more than one error could be generated for a given request,
|
||
the server can report any of them.
|
||
</para>
|
||
<para>
|
||
Because Xlib usually does not transmit requests to the server immediately
|
||
(that is, it buffers them), errors can be reported much later than they
|
||
actually occur.
|
||
For debugging purposes, however,
|
||
Xlib provides a mechanism for forcing synchronous behavior
|
||
(see <link linkend="Enabling_or_Disabling_Synchronization">section 11.8.1</link>).
|
||
When synchronization is enabled,
|
||
errors are reported as they are generated.
|
||
</para>
|
||
<para>
|
||
When Xlib detects an error,
|
||
it calls an error handler,
|
||
which your program can provide.
|
||
If you do not provide an error handler,
|
||
the error is printed, and your program terminates.
|
||
</para>
|
||
</sect1>
|
||
|
||
<sect1 id="Standard_Header_Files">
|
||
<title>Standard Header Files</title>
|
||
|
||
<para>
|
||
The following include files are part of the Xlib standard:
|
||
<indexterm><primary>Headers</primary></indexterm>
|
||
|
||
<variablelist>
|
||
<varlistentry id="Standard_Header_Files:Xlib.h">
|
||
<term><filename class="headerfile"><X11/Xlib.h></filename></term>
|
||
<listitem>
|
||
<indexterm type="file"><primary><filename class="headerfile">X11/Xlib.h</filename></primary></indexterm>
|
||
<indexterm><primary>Files</primary><secondary><X11/Xlib.h></secondary></indexterm>
|
||
<indexterm><primary>Headers</primary><secondary><X11/Xlib.h></secondary></indexterm>
|
||
<para>
|
||
This is the main header file for Xlib.
|
||
The majority of all Xlib symbols are declared by including this file.
|
||
This file also contains the preprocessor symbol
|
||
<symbol>XlibSpecificationRelease</symbol>.
|
||
<indexterm significance="preferred"><primary>XlibSpecificationRelease</primary></indexterm>
|
||
This symbol is defined to have the 6 in this release of the standard.
|
||
(Release 5 of Xlib was the first release to have this symbol.)
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry id="Standard_Header_Files:X.h">
|
||
<term><filename class="headerfile"><X11/X.h></filename></term>
|
||
<listitem>
|
||
<indexterm type="file"><primary><filename class="headerfile">X11/X.h</filename></primary></indexterm>
|
||
<indexterm><primary>Files</primary><secondary><X11/X.h></secondary></indexterm>
|
||
<indexterm><primary>Headers</primary><secondary><X11/X.h></secondary></indexterm>
|
||
<para>
|
||
This file declares types and constants for the X protocol that are
|
||
to be used by applications. It is included automatically from
|
||
<filename class="headerfile"><X11/Xlib.h></filename>
|
||
so application code should never need to
|
||
reference this file directly.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry id="Standard_Header_Files:Xcms.h">
|
||
<term><filename class="headerfile"><X11/Xcms.h></filename></term>
|
||
<listitem>
|
||
<indexterm type="file"><primary><filename class="headerfile">X11/Xcms.h</filename></primary></indexterm>
|
||
<indexterm><primary>Files</primary><secondary><X11/Xcms.h></secondary></indexterm>
|
||
<indexterm><primary>Headers</primary><secondary><X11/Xcms.h></secondary></indexterm>
|
||
<para>
|
||
This file contains symbols for much of the color management facilities
|
||
described in <link linkend='Color_Management_Functions'>chapter 6</link>.
|
||
All functions, types, and symbols with the prefix "Xcms",
|
||
plus the Color Conversion Contexts macros, are declared in this file.
|
||
<filename class="headerfile"><X11/Xlib.h></filename>
|
||
must be included before including this file.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry id="Standard_Header_Files:Xutil.h">
|
||
<term><filename class="headerfile"><X11/Xutil.h></filename></term>
|
||
<listitem>
|
||
<indexterm type="file"><primary><filename class="headerfile">X11/Xutil.h</filename></primary></indexterm>
|
||
<indexterm><primary>Files</primary><secondary><X11/Xutil.h></secondary></indexterm>
|
||
<indexterm><primary>Headers</primary><secondary><X11/Xutil.h></secondary></indexterm>
|
||
<para>
|
||
This file declares various functions, types, and symbols used for
|
||
inter-client communication and application utility functions,
|
||
which are described in chapters
|
||
<link linkend='Inter_Client_Communication_Functions'>14</link> and
|
||
<link linkend='Application_Utility_Functions'>16</link>.
|
||
<filename class="headerfile"><X11/Xlib.h></filename> must be included before including this file.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry id="Standard_Header_Files:Xresource.h">
|
||
<term><filename class="headerfile"><X11/Xresource.h></filename></term>
|
||
<listitem>
|
||
<indexterm type="file"><primary><filename class="headerfile">X11/Xresource.h</filename></primary></indexterm>
|
||
<indexterm><primary>Files</primary><secondary><X11/Xresource.h></secondary></indexterm>
|
||
<indexterm><primary>Headers</primary><secondary><X11/Xresource.h></secondary></indexterm>
|
||
<para>
|
||
This file declares all functions, types, and symbols for the
|
||
resource manager facilities, which are described in
|
||
<link linkend='Resource_Manager_Functions'>chapter 15</link>.
|
||
<filename class="headerfile"><X11/Xlib.h></filename> <!-- xref -->
|
||
must be included before including this file.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry id="Standard_Header_Files:Xatom.h">
|
||
<term><filename class="headerfile"><X11/Xatom.h></filename></term>
|
||
<listitem>
|
||
<indexterm type="file"><primary><filename class="headerfile">X11/Xatom.h</filename></primary></indexterm>
|
||
<indexterm><primary>Files</primary><secondary><X11/Xatom.h></secondary></indexterm>
|
||
<indexterm><primary>Headers</primary><secondary><X11/Xatom.h></secondary></indexterm>
|
||
<para>
|
||
This file declares all predefined atoms,
|
||
which are symbols with the prefix "XA_".
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry id="Standard_Header_Files:cursorfont.h">
|
||
<term><filename class="headerfile"><X11/cursorfont.h></filename></term>
|
||
<listitem>
|
||
<indexterm type="file"><primary><filename class="headerfile">X11/cursorfont.h</filename></primary></indexterm>
|
||
<indexterm><primary>Files</primary><secondary><X11/cursorfont.h></secondary></indexterm>
|
||
<indexterm><primary>Headers</primary><secondary><X11/cursorfont.h></secondary></indexterm>
|
||
<para>
|
||
This file declares the cursor symbols for the standard cursor font,
|
||
which are listed in <link linkend="x_font_cursors">Appendix B</link>.
|
||
All cursor symbols have the prefix "XC_".
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry id="Standard_Header_Files:keysymdef.h">
|
||
<term><filename class="headerfile"><X11/keysymdef.h></filename></term>
|
||
<listitem>
|
||
<indexterm type="file"><primary><filename class="headerfile">X11/keysymdef.h</filename></primary></indexterm>
|
||
<indexterm><primary>Files</primary><secondary><X11/keysymdef.h></secondary></indexterm>
|
||
<indexterm><primary>Headers</primary><secondary><X11/keysymdef.h></secondary></indexterm>
|
||
<para>
|
||
This file declares all standard KeySym values,
|
||
which are symbols with the prefix "XK_".
|
||
The KeySyms are arranged in groups, and a preprocessor symbol controls
|
||
inclusion of each group. The preprocessor symbol must be defined
|
||
prior to inclusion of the file to obtain the associated values.
|
||
The preprocessor symbols are
|
||
<symbol>XK_MISCELLANY</symbol>,
|
||
<symbol>XK_XKB_KEYS</symbol>,
|
||
<symbol>XK_3270</symbol>,
|
||
<symbol>XK_LATIN1</symbol>,
|
||
<symbol>XK_LATIN2</symbol>,
|
||
<symbol>XK_LATIN3</symbol>,
|
||
<symbol>XK_LATIN4</symbol>,
|
||
<symbol>XK_KATAKANA</symbol>,
|
||
<symbol>XK_ARABIC</symbol>,
|
||
<symbol>XK_CYRILLIC</symbol>,
|
||
<symbol>XK_GREEK</symbol>,
|
||
<symbol>XK_TECHNICAL</symbol>,
|
||
<symbol>XK_SPECIAL</symbol>,
|
||
<symbol>XK_PUBLISHING</symbol>,
|
||
<symbol>XK_APL</symbol>,
|
||
<symbol>XK_HEBREW</symbol>,
|
||
<symbol>XK_THAI</symbol>, and
|
||
<symbol>XK_KOREAN</symbol>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry id="Standard_Header_Files:keysym.h">
|
||
<term><filename class="headerfile"><X11/keysym.h></filename></term>
|
||
<listitem>
|
||
<indexterm type="file"><primary><filename class="headerfile">X11/keysym.h</filename></primary></indexterm>
|
||
<indexterm><primary>Files</primary><secondary><X11/keysym.h></secondary></indexterm>
|
||
<indexterm><primary>Headers</primary><secondary><X11/keysym.h></secondary></indexterm>
|
||
<para>
|
||
This file defines the preprocessor symbols
|
||
<symbol>XK_MISCELLANY</symbol>,
|
||
<symbol>XK_XKB_KEYS</symbol>,
|
||
<symbol>XK_LATIN1</symbol>,
|
||
<symbol>XK_LATIN2</symbol>,
|
||
<symbol>XK_LATIN3</symbol>,
|
||
<symbol>XK_LATIN4</symbol>, and
|
||
<symbol>XK_GREEK</symbol>
|
||
and then includes <filename class="headerfile"><X11/keysymdef.h></filename>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry id="Standard_Header_Files:Xlibint.h">
|
||
<term><filename class="headerfile"><X11/Xlibint.h></filename></term>
|
||
<listitem>
|
||
<indexterm type="file"><primary><filename class="headerfile">X11/Xlibint.h</filename></primary></indexterm>
|
||
<indexterm><primary>Files</primary><secondary><X11/Xlibint.h></secondary></indexterm>
|
||
<indexterm><primary>Headers</primary><secondary><X11/Xlibint.h></secondary></indexterm>
|
||
<para>
|
||
This file declares all the functions, types, and symbols used for
|
||
extensions, which are described in <link linkend="extensions">Appendix C</link>.
|
||
This file automatically includes
|
||
<filename class="headerfile"><X11/Xlib.h></filename>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry id="Standard_Header_Files:Xproto.h">
|
||
<term><filename class="headerfile"><X11/Xproto.h></filename></term>
|
||
<listitem>
|
||
<indexterm type="file"><primary><filename class="headerfile">X11/Xproto.h</filename></primary></indexterm>
|
||
<indexterm><primary>Files</primary><secondary><X11/Xproto.h></secondary></indexterm>
|
||
<indexterm><primary>Headers</primary><secondary><X11/Xproto.h></secondary></indexterm>
|
||
<para>
|
||
This file declares types and symbols for the basic X protocol,
|
||
for use in implementing extensions.
|
||
It is included automatically from
|
||
<filename class="headerfile"><X11/Xlibint.h></filename>,
|
||
so application and extension code should never need to
|
||
reference this file directly.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry id="Standard_Header_Files:Xprotostr.h">
|
||
<term><filename class="headerfile"><X11/Xprotostr.h></filename></term>
|
||
<listitem>
|
||
<indexterm type="file"><primary><filename class="headerfile">X11/Xprotostr.h</filename></primary></indexterm>
|
||
<indexterm><primary>Files</primary><secondary><X11/Xprotostr.h></secondary></indexterm>
|
||
<indexterm><primary>Headers</primary><secondary><X11/Xprotostr.h></secondary></indexterm>
|
||
<para>
|
||
This file declares types and symbols for the basic X protocol,
|
||
for use in implementing extensions.
|
||
It is included automatically from
|
||
<filename class="headerfile"><X11/Xproto.h></filename>,
|
||
so application and extension code should never need to
|
||
reference this file directly.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry id="Standard_Header_Files:X10.h">
|
||
<term><filename class="headerfile"><X11/X10.h></filename></term>
|
||
<listitem>
|
||
<indexterm type="file"><primary><filename class="headerfile">X11/X10.h</filename></primary></indexterm>
|
||
<indexterm><primary>Files</primary><secondary><X11/X10.h></secondary></indexterm>
|
||
<indexterm><primary>Headers</primary><secondary><X11/X10.h></secondary></indexterm>
|
||
<para>
|
||
This file declares all the functions, types, and symbols used for the
|
||
X10 compatibility functions, which are described in
|
||
<link linkend="X_Version_10_Compatibility_Functions">Appendix D</link>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</para>
|
||
</sect1>
|
||
|
||
<sect1 id="Generic_Values_and_Types">
|
||
<title>Generic Values and Types</title>
|
||
|
||
<para>
|
||
The following symbols are defined by Xlib and used throughout the manual:
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
<indexterm significance="preferred"><primary>Bool</primary></indexterm>
|
||
<indexterm significance="preferred"><primary>True</primary></indexterm>
|
||
<indexterm significance="preferred"><primary>False</primary></indexterm>
|
||
Xlib defines the type
|
||
<type>Bool</type>
|
||
and the Boolean values
|
||
<symbol>True</symbol>
|
||
and
|
||
<symbol>False</symbol>.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
<indexterm significance="preferred"><primary>None</primary></indexterm>
|
||
<symbol>None</symbol>
|
||
is the universal null resource ID or atom.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
<indexterm significance="preferred"><primary>XID</primary></indexterm>
|
||
The type
|
||
<type>XID</type>
|
||
is used for generic resource IDs.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
<indexterm significance="preferred"><primary>XPointer</primary></indexterm>
|
||
The type <type>XPointer</type> is defined to be <type>char *</type>
|
||
and is used as a generic opaque pointer to data.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</para>
|
||
</sect1>
|
||
|
||
<sect1 id="Naming_and_Argument_Conventions_within_Xlib">
|
||
<title>Naming and Argument Conventions within Xlib</title>
|
||
|
||
<para>
|
||
Xlib follows a number of conventions for the naming and syntax of the functions.
|
||
Given that you remember what information the function requires,
|
||
these conventions are intended to make the syntax of the functions more
|
||
predictable.
|
||
</para>
|
||
<para>
|
||
The major naming conventions are:
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
To differentiate the X symbols from the other symbols,
|
||
the library uses mixed case for external symbols.
|
||
It leaves lowercase for variables and all uppercase for user macros,
|
||
as per existing convention.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
All Xlib functions begin with a capital X.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
The beginnings of all function names and symbols are capitalized.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
All user-visible data structures begin with a capital X.
|
||
More generally,
|
||
anything that a user might dereference begins with a capital X.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Macros and other symbols do not begin with a capital X.
|
||
To distinguish them from all user symbols,
|
||
each word in the macro is capitalized.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
All elements of or variables in a data structure are in lowercase.
|
||
Compound words, where needed, are constructed with underscores (_).
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
The display argument, where used, is always first in the argument list.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
All resource objects, where used, occur at the beginning of the argument list
|
||
immediately after the display argument.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
When a graphics context is present together with
|
||
another type of resource (most commonly, a drawable), the
|
||
graphics context occurs in the argument list after the other
|
||
resource.
|
||
Drawables outrank all other resources.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Source arguments always precede the destination arguments in the argument list.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
The x argument always precedes the y argument in the argument list.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
The width argument always precedes the height argument in the argument list.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Where the x, y, width, and height arguments are used together,
|
||
the x and y arguments always precede the width and height arguments.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Where a mask is accompanied with a structure,
|
||
the mask always precedes the pointer to the structure in the argument list.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</para>
|
||
</sect1>
|
||
|
||
<sect1 id="Programming_Considerations">
|
||
<title>Programming Considerations</title>
|
||
|
||
<para>
|
||
The major programming considerations are:
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
Coordinates and sizes in X are actually 16-bit quantities.
|
||
This decision was made to minimize the bandwidth required for a
|
||
given level of performance.
|
||
Coordinates usually are declared as an
|
||
<type>int</type>
|
||
in the interface.
|
||
Values larger than 16 bits are truncated silently.
|
||
Sizes (width and height) are declared as unsigned quantities.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Keyboards are the greatest variable between different
|
||
manufacturers' workstations.
|
||
If you want your program to be portable,
|
||
you should be particularly conservative here.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Many display systems have limited amounts of off-screen memory.
|
||
If you can, you should minimize use of pixmaps and backing
|
||
store.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
The user should have control of their screen real estate.
|
||
Therefore, you should write your applications to react to window management
|
||
rather than presume control of the entire screen.
|
||
What you do inside of your top-level window, however,
|
||
is up to your application.
|
||
For further information,
|
||
see <link linkend='Inter_Client_Communication_Functions'>chapter 14</link>
|
||
and the <olink targetdoc='icccm' targetptr='icccm'><citetitle>Inter-Client Communication Conventions Manual</citetitle></olink>.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</para>
|
||
</sect1>
|
||
|
||
<sect1 id="Character_Sets_and_Encodings">
|
||
<title>Character Sets and Encodings</title>
|
||
|
||
<para>
|
||
Some of the Xlib functions make reference to specific character sets
|
||
and character encodings.
|
||
The following are the most common:
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term><firstterm>X Portable Character Set</firstterm></term>
|
||
<listitem><para>
|
||
A basic set of 97 characters,
|
||
which are assumed to exist in all locales supported by Xlib.
|
||
This set contains the following characters:
|
||
<literallayout>
|
||
a..z A..Z 0..9 !"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~ <space>, <tab>, and <newline>
|
||
</literallayout>
|
||
</para>
|
||
<para>
|
||
This set is the left/lower half
|
||
of the graphic character set of ISO8859-1 plus space, tab, and newline.
|
||
It is also the set of graphic characters in 7-bit ASCII plus the same
|
||
three control characters.
|
||
The actual encoding of these characters on the host is system dependent.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><firstterm>Host Portable Character Encoding</firstterm></term>
|
||
<listitem>
|
||
<para>
|
||
The encoding of the X Portable Character Set on the host.
|
||
The encoding itself is not defined by this standard,
|
||
but the encoding must be the same in all locales supported by Xlib on the host.
|
||
If a string is said to be in the Host Portable Character Encoding,
|
||
then it only contains characters from the X Portable Character Set,
|
||
in the host encoding.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><firstterm>Latin-1</firstterm></term>
|
||
<listitem>
|
||
<para>
|
||
The coded character set defined by the ISO8859-1 standard.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><firstterm>Latin Portable Character Encoding</firstterm></term>
|
||
<listitem>
|
||
<para>
|
||
The encoding of the X Portable Character Set using the Latin-1 codepoints
|
||
plus ASCII control characters.
|
||
If a string is said to be in the Latin Portable Character Encoding,
|
||
then it only contains characters from the X Portable Character Set,
|
||
not all of Latin-1.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><firstterm>STRING Encoding</firstterm></term>
|
||
<listitem>
|
||
<para>
|
||
Latin-1, plus tab and newline.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><firstterm><acronym>POSIX</acronym> Portable Filename Character Set</firstterm></term>
|
||
<listitem>
|
||
<para>
|
||
The set of 65 characters,
|
||
which can be used in naming files on a <acronym>POSIX</acronym>-compliant host,
|
||
that are correctly processed in all locales.
|
||
The set is:
|
||
<literallayout>
|
||
a..z A..Z 0..9 ._-
|
||
</literallayout>
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</para>
|
||
</sect1>
|
||
|
||
<sect1 id="Formatting_Conventions">
|
||
<title>Formatting Conventions</title>
|
||
|
||
<para>
|
||
<citetitle>Xlib − C Language X Interface</citetitle> uses the
|
||
following conventions:
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
Global symbols are printed in
|
||
<function>this</function>
|
||
<function>special</function>
|
||
<function>font</function>.
|
||
These can be either function names,
|
||
symbols defined in include files, or structure names.
|
||
When declared and defined,
|
||
function arguments are printed in <emphasis remap='I'>italics</emphasis>.
|
||
In the explanatory text that follows,
|
||
they usually are printed in regular type.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Each function is introduced by a general discussion that
|
||
distinguishes it from other functions.
|
||
The function declaration itself follows,
|
||
and each argument is specifically explained.
|
||
Although ANSI C function prototype syntax is not used,
|
||
Xlib header files normally declare functions using function prototypes
|
||
in ANSI C environments.
|
||
General discussion of the function, if any is required,
|
||
follows the arguments.
|
||
Where applicable,
|
||
the last paragraph of the explanation lists the possible
|
||
Xlib error codes that the function can generate.
|
||
For a complete discussion of the Xlib error codes,
|
||
see <link linkend="Using_the_Default_Error_Handlers">section 11.8.2</link>.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
To eliminate any ambiguity between those arguments that you pass and those that
|
||
a function returns to you,
|
||
the explanations for all arguments that you pass start with the word
|
||
<emphasis remap='I'>specifies</emphasis> or, in the case of multiple arguments, the word <emphasis remap='I'>specify</emphasis>.
|
||
The explanations for all arguments that are returned to you start with the
|
||
word <emphasis remap='I'>returns</emphasis> or, in the case of multiple arguments, the word <emphasis remap='I'>return</emphasis>.
|
||
The explanations for all arguments that you can pass and are returned start
|
||
with the words <emphasis remap='I'>specifies and returns</emphasis>.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Any pointer to a structure that is used to return a value is designated as
|
||
such by the <emphasis remap='I'>_return</emphasis> suffix as part of its name.
|
||
All other pointers passed to these functions are
|
||
used for reading only.
|
||
A few arguments use pointers to structures that are used for
|
||
both input and output and are indicated by using the <emphasis remap='I'>_in_out</emphasis> suffix.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</para>
|
||
</sect1>
|
||
</chapter>
|