664 lines
23 KiB
Plaintext
664 lines
23 KiB
Plaintext
.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
|
|
.\"
|
|
.\" Permission is hereby granted, free of charge, to any person obtaining
|
|
.\" a copy of this software and associated documentation files (the
|
|
.\" "Software"), to deal in the Software without restriction, including
|
|
.\" without limitation the rights to use, copy, modify, merge, publish,
|
|
.\" distribute, sublicense, and/or sell copies of the Software, and to
|
|
.\" permit persons to whom the Software is furnished to do so, subject to
|
|
.\" the following conditions:
|
|
.\"
|
|
.\" The above copyright notice and this permission notice shall be included
|
|
.\" in all copies or substantial portions of the Software.
|
|
.\"
|
|
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
|
|
.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
|
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
|
.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
|
|
.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
|
|
.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
|
|
.\" OTHER DEALINGS IN THE SOFTWARE.
|
|
.\"
|
|
.\" Except as contained in this notice, the name of the X Consortium shall
|
|
.\" not be used in advertising or otherwise to promote the sale, use or
|
|
.\" other dealings in this Software without prior written authorization
|
|
.\" from the X Consortium.
|
|
.\"
|
|
.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
|
|
.\" Digital Equipment Corporation
|
|
.\"
|
|
.\" Portions Copyright \(co 1990, 1991 by
|
|
.\" Tektronix, Inc.
|
|
.\"
|
|
.\" Permission to use, copy, modify and distribute this documentation for
|
|
.\" any purpose and without fee is hereby granted, provided that the above
|
|
.\" copyright notice appears in all copies and that both that copyright notice
|
|
.\" and this permission notice appear in all copies, and that the names of
|
|
.\" Digital and Tektronix not be used in in advertising or publicity pertaining
|
|
.\" to this documentation without specific, written prior permission.
|
|
.\" Digital and Tektronix makes no representations about the suitability
|
|
.\" of this documentation for any purpose.
|
|
.\" It is provided ``as is'' without express or implied warranty.
|
|
.\"
|
|
.EH '\fBXlib \- C Library\fP''\fBX11, Release 6.8\fP'
|
|
.OH '\fBXlib \- C Library\fP''\fBX11, Release 6.8\fP'
|
|
.EF ''\fB % \fP''
|
|
.OF ''\fB % \fP''
|
|
.hw WM_NORMAL_HINTS
|
|
\&
|
|
.sp 1
|
|
.ce 3
|
|
\s+1\fBChapter 1\fP\s-1
|
|
|
|
\s+1\fBIntroduction to Xlib\fP\s-1
|
|
.sp 2
|
|
.if \n(GS .nr nh*hl 1
|
|
.nr H1 1
|
|
.nr H2 0
|
|
.nr H3 0
|
|
.nr H4 0
|
|
.nr H5 0
|
|
.na
|
|
.LP
|
|
.XS
|
|
Chapter 1: Introduction to Xlib
|
|
.XE
|
|
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.
|
|
.LP
|
|
\fIXlib \- C Language X Interface\fP 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.
|
|
\fIXlib \- C Language X Interface\fP 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 \fIX Window System Protocol\fP provides the definitive word on the
|
|
behavior of X.
|
|
Although additional information appears here,
|
|
the protocol document is the ruling document.
|
|
.LP
|
|
To provide an introduction to X programming,
|
|
this chapter discusses:
|
|
.IP \(bu 5
|
|
Overview of the X Window System
|
|
.IP \(bu 5
|
|
Errors
|
|
.IP \(bu 5
|
|
Standard header files
|
|
.IP \(bu 5
|
|
Generic values and types
|
|
.IP \(bu 5
|
|
Naming and argument conventions within Xlib
|
|
.IP \(bu 5
|
|
Programming considerations
|
|
.IP \(bu 5
|
|
Character sets and encodings
|
|
.IP \(bu 5
|
|
Formatting conventions
|
|
.NH 2
|
|
Overview of the X Window System
|
|
.XS
|
|
\*(SN Overview of the X Window System
|
|
.XE
|
|
.LP
|
|
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 the glossary,
|
|
which is located at the end of the book.
|
|
.LP
|
|
The X Window System supports one or more screens containing
|
|
overlapping windows or subwindows.
|
|
A screen 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 display.
|
|
.LP
|
|
.IN "Screen"
|
|
All the windows in an X server are arranged in strict hierarchies.
|
|
At the top of each hierarchy is a root window,
|
|
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.
|
|
.IN "Child window"
|
|
.IN "Parent Window"
|
|
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.
|
|
.LP
|
|
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.
|
|
.IN "Stacking order"
|
|
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.
|
|
.LP
|
|
.IN "Window" "" "@DEF@"
|
|
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.
|
|
.LP
|
|
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.
|
|
.LP
|
|
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
|
|
.PN Expose
|
|
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.
|
|
.LP
|
|
.IN "Pixmap"
|
|
.IN "Drawable"
|
|
.IN "Tile"
|
|
.IN "Bitmap"
|
|
X also provides off-screen storage of graphics objects,
|
|
called pixmaps.
|
|
Single plane (depth 1) pixmaps are sometimes referred to as bitmaps.
|
|
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.
|
|
.LP
|
|
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.
|
|
.LP
|
|
.IN "XSync"
|
|
If a client does not want a request to execute asynchronously,
|
|
it can follow the request with a call to
|
|
.PN XSync ,
|
|
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.
|
|
.LP
|
|
.IN "Resource IDs"
|
|
.IN "Resource IDs" "Window"
|
|
.IN "Resource IDs" "Font"
|
|
.IN "Resource IDs" "Pixmap"
|
|
.IN "Resource IDs" "Cursor"
|
|
.IN "Resource IDs" "GContext"
|
|
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
|
|
.PN Window ,
|
|
.PN Font ,
|
|
.PN Pixmap ,
|
|
.PN Colormap ,
|
|
.PN Cursor ,
|
|
and
|
|
.PN GContext ,
|
|
as defined in the file
|
|
.hN X11/X.h .
|
|
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.
|
|
.LP
|
|
.IN "Event"
|
|
Client programs are informed of events.
|
|
Events may either be side effects of a request (for example, restacking windows
|
|
generates
|
|
.PN Expose
|
|
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.
|
|
.LP
|
|
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,
|
|
.PN XNextEvent
|
|
or
|
|
.PN XWindowEvent ).
|
|
In addition, some library
|
|
functions (for example,
|
|
.PN XRaiseWindow )
|
|
generate
|
|
.PN Expose
|
|
and
|
|
.PN ConfigureRequest
|
|
events.
|
|
These events also arrive asynchronously, but the client may
|
|
.IN "XSync"
|
|
wish to explicitly wait for them by calling
|
|
.PN XSync
|
|
after calling a function that can cause the server to generate events.
|
|
.NH 2
|
|
Errors
|
|
.XS
|
|
\*(SN Errors
|
|
.XE
|
|
.LP
|
|
Some functions return
|
|
.PN Status ,
|
|
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.
|
|
.IN "Status"
|
|
Because C does not provide multiple return values,
|
|
many functions must return their results by writing into client-passed storage.
|
|
.IN "Error" "handling"
|
|
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.
|
|
.LP
|
|
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.
|
|
.LP
|
|
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).
|
|
When synchronization is enabled,
|
|
errors are reported as they are generated.
|
|
.LP
|
|
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.
|
|
.NH 2
|
|
Standard Header Files
|
|
.XS
|
|
\*(SN Standard Header Files
|
|
.XE
|
|
.LP
|
|
The following include files are part of the Xlib standard:
|
|
.IP \(bu 5
|
|
.hN X11/Xlib.h
|
|
.IP
|
|
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
|
|
.PN XlibSpecificationRelease .
|
|
.IN "XlibSpecificationRelease" "" "@DEF@"
|
|
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.)
|
|
.IP \(bu 5
|
|
.hN X11/X.h
|
|
.IP
|
|
This file declares types and constants for the X protocol that are
|
|
to be used by applications.
|
|
It is included automatically from
|
|
.hN X11/Xlib.h ,
|
|
so application code should never need to reference this file directly.
|
|
.IP \(bu 5
|
|
.hN X11/Xcms.h
|
|
.IP
|
|
This file contains symbols for much of the color management facilities
|
|
described in chapter 6.
|
|
All functions, types, and symbols with the prefix ``Xcms'',
|
|
plus the Color Conversion Contexts macros, are declared in this file.
|
|
.hN X11/Xlib.h
|
|
must be included before including this file.
|
|
.IP \(bu 5
|
|
.hN X11/Xutil.h
|
|
.IP
|
|
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.
|
|
.hN X11/Xlib.h
|
|
must be included before including this file.
|
|
.IP \(bu 5
|
|
.hN X11/Xresource.h
|
|
.IP
|
|
This file declares all functions, types, and symbols for the
|
|
resource manager facilities, which are described in chapter 15.
|
|
.hN X11/Xlib.h
|
|
must be included before including this file.
|
|
.IP \(bu 5
|
|
.hN X11/Xatom.h
|
|
.IP
|
|
This file declares all predefined atoms,
|
|
which are symbols with the prefix ``XA_''.
|
|
.IP \(bu 5
|
|
.hN X11/cursorfont.h
|
|
.IP
|
|
This file declares the cursor symbols for the standard cursor font,
|
|
which are listed in appendix B.
|
|
All cursor symbols have the prefix ``XC_''.
|
|
.IP \(bu 5
|
|
.hN X11/keysymdef.h
|
|
.IP
|
|
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 XK_MISCELLANY, XK_XKB_KEYS, XK_3270,
|
|
XK_LATIN1, XK_LATIN2,
|
|
XK_LATIN3, XK_LATIN4, XK_KATAKANA, XK_ARABIC, XK_CYRILLIC, XK_GREEK,
|
|
XK_TECHNICAL, XK_SPECIAL, XK_PUBLISHING, XK_APL, XK_HEBREW,
|
|
XK_THAI, and XK_KOREAN.
|
|
.IP \(bu 5
|
|
.hN X11/keysym.h
|
|
.IP
|
|
This file defines the preprocessor symbols
|
|
XK_MISCELLANY, XK_XKB_KEYS, XK_LATIN1, XK_LATIN2, XK_LATIN3,
|
|
XK_LATIN4, and XK_GREEK
|
|
and then includes
|
|
.hN X11/keysymdef.h .
|
|
.IP \(bu 5
|
|
.hN X11/Xlibint.h
|
|
.IP
|
|
This file declares all the functions, types, and symbols used for
|
|
extensions, which are described in appendix C.
|
|
This file automatically includes
|
|
.hN X11/Xlib.h .
|
|
.IP \(bu 5
|
|
.hN X11/Xproto.h
|
|
.IP
|
|
This file declares types and symbols for the basic X protocol,
|
|
for use in implementing extensions.
|
|
It is included automatically from
|
|
.hN X11/Xlibint.h ,
|
|
so application and extension code should never need to
|
|
reference this file directly.
|
|
.IP \(bu 5
|
|
.hN X11/Xprotostr.h
|
|
.IP
|
|
This file declares types and symbols for the basic X protocol,
|
|
for use in implementing extensions.
|
|
It is included automatically from
|
|
.hN X11/Xproto.h ,
|
|
so application and extension code should never need to
|
|
reference this file directly.
|
|
.IP \(bu 5
|
|
.hN X11/X10.h
|
|
.IP
|
|
This file declares all the functions, types, and symbols used for the
|
|
X10 compatibility functions, which are described in appendix D.
|
|
.NH 2
|
|
Generic Values and Types
|
|
.XS
|
|
\*(SN Generic Values and Types
|
|
.XE
|
|
.LP
|
|
The following symbols are defined by Xlib and used throughout the manual:
|
|
.IN "Bool" "" "@DEF@"
|
|
.IN "True" "" "@DEF@"
|
|
.IN "False" "" "@DEF@"
|
|
.IP \(bu 5
|
|
Xlib defines the type
|
|
.PN Bool
|
|
and the Boolean values
|
|
.PN True
|
|
and
|
|
.PN False .
|
|
.IN "None" "" "@DEF@"
|
|
.IP \(bu 5
|
|
.PN None
|
|
is the universal null resource ID or atom.
|
|
.IN "XID" "" "@DEF@"
|
|
.IP \(bu 5
|
|
The type
|
|
.PN XID
|
|
is used for generic resource IDs.
|
|
.IN "XPointer" "" "@DEF@"
|
|
.IP \(bu 5
|
|
The type
|
|
.PN XPointer
|
|
is defined to be char\^* and is used as a generic opaque pointer to data.
|
|
.NH 2
|
|
Naming and Argument Conventions within Xlib
|
|
.XS
|
|
\*(SN Naming and Argument Conventions within Xlib
|
|
.XE
|
|
.LP
|
|
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.
|
|
.LP
|
|
The major naming conventions are:
|
|
.IP \(bu 5
|
|
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.
|
|
.IP \(bu 5
|
|
All Xlib functions begin with a capital X.
|
|
.IP \(bu 5
|
|
The beginnings of all function names and symbols are capitalized.
|
|
.IP \(bu 5
|
|
All user-visible data structures begin with a capital X.
|
|
More generally,
|
|
anything that a user might dereference begins with a capital X.
|
|
.IP \(bu 5
|
|
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.
|
|
.IP \(bu 5
|
|
All elements of or variables in a data structure are in lowercase.
|
|
Compound words, where needed, are constructed with underscores (\^_\^).
|
|
.IP \(bu 5
|
|
The display argument, where used, is always first in the argument list.
|
|
.IP \(bu 5
|
|
All resource objects, where used, occur at the beginning of the argument list
|
|
immediately after the display argument.
|
|
.IP \(bu 5
|
|
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.
|
|
.IP \(bu 5
|
|
Source arguments always precede the destination arguments in the argument list.
|
|
.IP \(bu 5
|
|
The x argument always precedes the y argument in the argument list.
|
|
.IP \(bu 5
|
|
The width argument always precedes the height argument in the argument list.
|
|
.IP \(bu 5
|
|
Where the x, y, width, and height arguments are used together,
|
|
the x and y arguments always precede the width and height arguments.
|
|
.IP \(bu 5
|
|
Where a mask is accompanied with a structure,
|
|
the mask always precedes the pointer to the structure in the argument list.
|
|
.NH 2
|
|
Programming Considerations
|
|
.XS
|
|
\*(SN Programming Considerations
|
|
.XE
|
|
.LP
|
|
The major programming considerations are:
|
|
.IP \(bu 5
|
|
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
|
|
.PN int
|
|
in the interface.
|
|
Values larger than 16 bits are truncated silently.
|
|
Sizes (width and height) are declared as unsigned quantities.
|
|
.IP \(bu 5
|
|
Keyboards are the greatest variable between different
|
|
manufacturers' workstations.
|
|
If you want your program to be portable,
|
|
you should be particularly conservative here.
|
|
.IP \(bu 5
|
|
Many display systems have limited amounts of off-screen memory.
|
|
If you can, you should minimize use of pixmaps and backing
|
|
store.
|
|
.IP \(bu 5
|
|
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
|
|
and the \fIInter-Client Communication Conventions Manual\fP.
|
|
.NH 2
|
|
Character Sets and Encodings
|
|
.XS
|
|
\*(SN Character Sets and Encodings
|
|
.XE
|
|
.LP
|
|
Some of the Xlib functions make reference to specific character sets
|
|
and character encodings.
|
|
The following are the most common:
|
|
.IP \(bu 5
|
|
X Portable Character Set
|
|
.IP
|
|
A basic set of 97 characters,
|
|
which are assumed to exist in all locales supported by Xlib.
|
|
This set contains the following characters:
|
|
.IP
|
|
.Ds 0
|
|
.EQ
|
|
delim DD
|
|
.EN
|
|
a..z A..Z 0..9
|
|
!"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~
|
|
<space>, <tab>, and <newline>
|
|
.EQ
|
|
delim %%
|
|
.EN
|
|
.De
|
|
.IP
|
|
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.
|
|
.IP \(bu 5
|
|
Host Portable Character Encoding
|
|
.IP
|
|
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.
|
|
.IP \(bu 5
|
|
Latin-1
|
|
.IP
|
|
The coded character set defined by the ISO8859-1 standard.
|
|
.IP \(bu 5
|
|
Latin Portable Character Encoding
|
|
.IP
|
|
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.
|
|
.IP \(bu 5
|
|
STRING Encoding
|
|
.IP
|
|
Latin-1, plus tab and newline.
|
|
.IP \(bu 5
|
|
POSIX Portable Filename Character Set
|
|
.IP
|
|
The set of 65 characters,
|
|
which can be used in naming files on a POSIX-compliant host,
|
|
that are correctly processed in all locales.
|
|
The set is:
|
|
.IP
|
|
.Ds 0
|
|
a..z A..Z 0..9 ._-
|
|
.De
|
|
.NH 2
|
|
Formatting Conventions
|
|
.XS
|
|
\*(SN Formatting Conventions
|
|
.XE
|
|
.LP
|
|
\fIXlib \- C Language X Interface\fP uses the following conventions:
|
|
.IP \(bu 5
|
|
Global symbols are printed in
|
|
.PN this
|
|
.PN special
|
|
.PN font .
|
|
These can be either function names,
|
|
symbols defined in include files, or structure names.
|
|
When declared and defined,
|
|
function arguments are printed in \fIitalics\fP.
|
|
In the explanatory text that follows,
|
|
they usually are printed in regular type.
|
|
.IP \(bu 5
|
|
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.
|
|
.IP \(bu 5
|
|
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
|
|
\fIspecifies\fP or, in the case of multiple arguments, the word \fIspecify\^\fP.
|
|
The explanations for all arguments that are returned to you start with the
|
|
word \fIreturns\fP or, in the case of multiple arguments, the word \fIreturn\^\fP.
|
|
The explanations for all arguments that you can pass and are returned start
|
|
with the words \fIspecifies and returns\^\fP.
|
|
.IP \(bu 5
|
|
Any pointer to a structure that is used to return a value is designated as
|
|
such by the \fI_return\fP 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 \fI_in_out\fP suffix.
|
|
.bp
|