diff options
Diffstat (limited to 'libX11/specs/libX11/CH01.xml')
| -rw-r--r-- | libX11/specs/libX11/CH01.xml | 1689 |
1 files changed, 846 insertions, 843 deletions
diff --git a/libX11/specs/libX11/CH01.xml b/libX11/specs/libX11/CH01.xml index a401b9a5b..21750aba1 100644 --- a/libX11/specs/libX11/CH01.xml +++ b/libX11/specs/libX11/CH01.xml @@ -1,843 +1,846 @@ -<?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 <citetitle>X Window System Protocol</citetitle> 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
-<function>XSync</function>,
-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,
-<function>XNextEvent</function>
-or
-<function>XWindowEvent</function>).
-In addition, some library
-functions (for example,
-<function>XRaiseWindow</function>)
-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
-<function>XSync</function>
-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 section 11.8.1). <!-- xref -->
-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 chapter 6. All functions, types, and symbols with the
-prefix "Xcms", <!-- xref -->
-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 14 and 16. <!-- xref -->
-<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 chapter 15.
-<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 his 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 chapter 14 <!-- xref -->
-and the <citetitle>Inter-Client Communication Conventions Manual</citetitle>.
- </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 section 11.8.2. <!-- xref -->
- </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>
+<?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 <citetitle>X Window System Protocol</citetitle> 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 +<function>XSync</function>, +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, +<function>XNextEvent</function> +or +<function>XWindowEvent</function>). +In addition, some library +functions (for example, +<function>XRaiseWindow</function>) +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 +<function>XSync</function> +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 his 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 <citetitle>Inter-Client Communication Conventions Manual</citetitle>. + </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> |