.\".U7
.\".UT "Introduction to Xlib" 1
.EH '\fBXlib \- C Library\fP''\fBX11, Release 2\fP'
.OH '\fBXlib \- C Library\fP''\fBX11, Release 2\fP'
.EF ''\fB % \fP''
.OF ''\fB % \fP''
\&
.sp 1
.ce 3
\s+1\fBChapter 1\fP\s-1

\s+1\fBIntroduction to Xlib\fP\s-1
.sp 2
.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 and that
runs under 4.3BSD UNIX,
ULTRIX-32, many other UNIX variants,
VAX/VMS, MS/DOS, as well as several other operating systems.
.LP
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
your 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
This manual 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 guide to programming to the X Window System.
Other high-level abstractions
(for example, those provided by the toolkits for X)
are built on top of the Xlib library.
For further information about these high-level libraries,
see the appropriate toolkit documentation.
For general information about the design of X,
see ``The X Window System.''
The \fIX Window System Protocol\fP provides the definitive word on the
behavior of X.
While additional information is provided by this manual,
the protocol document is the ruling document.
.LP
This manual assumes a basic understanding of a graphics window system and
of the C programming language.
To provide an introduction to X programming,
this chapter discusses:
.IP \(bu 5
Overview of the X Window System
.IP \(bu 5
Naming and argument conventions
.IP \(bu 5
Programming considerations
.IP \(bu 5
Documentation conventions
.LE
.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,
while other terms that are common to other window systems 
have different meanings in X.
You may find it helpful to refer to the glossary, 
located at the end of the book, when you are uncertain of
a term's meaning in the context of the X Window System.
.LP
The X Window System supports one or more screens containing
overlapping windows or subwindows.
A screen is a physical monitor and hardware,
which may be either color or black and white.
There can be multiple screens per display or workstation.
A single server can provide display services for any number of screens.
A set of screens for a single user with one keyboard and one mouse is
called a ``display''.
.LP
.IN "Screen" "" "@DEF@"
All the windows in an X server are arranged in a strict hierarchy.  At
the top of the hierarchy are the root windows,
which cover 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 per application program.
.IN "Child Window" "" "@DEF@"
.IN "Parent Window" "" "@DEF@"
Child windows  may in turn have their own children.
In this way, an application program can create a tree of arbitrary depth
on each screen.
.LP
A child window may be larger than its parent. 
That is, part or all of
the child window may extend beyond the boundaries of the parent.
However, all output to a window is clipped by the boundaries of its
parent window.
.IN "Stacking order" "" "@DEF@"
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, obscuring them.
Output to areas covered by other windows will be suppressed by the window
system.
If a window  is obscured by a second window, 
the second window will obscure only those ancestors of the second window,
which are also ancestors of the first window.
.LP
.IN "Window" "" "@DEF@"
A window has a border of 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.
Each window has its own coordinate system.
Child windows obscure their parents unless the child windows have no
background, and graphic operations in the parent window usually
are clipped by the children.
.LP
.IN "Event" "" "@DEF@"
Input from X takes the form of events.
Events may either be side effects of a command (for example, restacking windows
generates exposure events)
or completely asynchronous (for example, the keyboard).
A client program asks to be informed of events.
Programs must be prepared to handle (or ignore) events of all types,
because other applications can send events to your application.
.LP
X does not take responsibility for 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, and the client program is notified (by an exposure
event) 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" "" "@DEF@"
.IN "Drawable" "" "@DEF@"
.IN "Tiles" "" "@DEF@"
.IN "Bitmap" "" "@DEF@"
X also provides off screen storage of graphics objects,
called ``pixmaps.''
Single plane (depth 1) pixmaps are sometimes referred to as ``bitmaps.''
These can be used in most graphics functions interchangeably with
windows, and are used in various graphics operations to define patterns
also called ``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,
often referred to as display 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.
If a nonblocking  call results in an error, the error will
generally not be reported by a call to an optional error handler
until some later, blocking call is made.
.LP
.IN "XSync"
If it does not want a request to execute asynchronously, 
a client can follow it with a call to 
.PN XSync , 
which will block until all previously buffered
asynchronous events have been sent and acted on.
As an important side effect, 
.IN "XPending"
.IN "XNextEvent"
.IN "XWindowEvent"
.IN "XFlush"
.IN "XSync"
the output buffer is always flushed by a call to any function
which returns a value from the server or waits for input (for example,
.PN XPending , 
.PN XNextEvent , 
.PN XWindowEvent ,
.PN XFlush ,
or
.PN XSync ).
.LP
.IN "Resource ID" "" "@DEF@"
.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 Window, Font, Pixmap, Bitmap,
Cursor, and GContext,
as defined in the file
.Pn < X11/X.h >.
.FS
The <\|> has the meaning defined by the # include statement
of the C compiler and is a file relative to a well known directory.
On UNIX-based systems, this is
.PN /usr/include .
.FE
These resources are created by user requests, and destroyed
(or freed) by user requests or when connections 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 typically shared automatically
since the X server treats fonts specially,
loading and unloading font storage as needed.
GContexts should not be shared between applications.
.LP
Some functions return Status, an integer error indication.
If the function fails, it will return a zero.
If the function returns a status of zero,
it has not updated the return parameters.
.IN "Status" "" "@DEF@"
Because C does not provide multiple return values, many function must return
their results by writing into client-passed storage. 
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.
.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 will return NULL pointers if
the string does not exist.
.LP
Input events (for example, key pressed or mouse 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 of the library
.IN "XResizeWindow"
.IN "XRaiseWindow"
functions (for example,
.PN XResizeWindow
and
.PN XRaiseWindow )
generate exposure events (that is, requests to repaint sections of a 
window that do not have valid contents).  
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 which may generate exposure events.
.NH 2
Naming and Argument Conventions within Xlib
.XS
\*(SN Naming and Argument Conventions within Xlib
.XE
.LP
Throughout Xlib,
a number of conventions for naming and syntax of the Xlib functions
have been followed.
These conventions are intended to make the syntax of the functions more 
predictable, given that you remember what information the routine may require.
.LP
The major naming conventions are:
.IP \(bu 5
To better differentiate the X symbols from the user symbols,
the library uses mixed case for external symbols,
and leaves lower case for variables and all upper case for user macros,
per existing convention.
.IP \(bu 5
All Xlib functions begin with a capital X.
.IP \(bu 5
The beginnings of all procedure 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 an 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 lower case.
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 variable.
.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 an array occurs in an argument list accompanied with a count 
(number of elements in the array),
the array always precedes the count in the argument list.
.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 considerations are:
.IP \(bu 5
Keyboards are the greatest variable between different
manufacturer's 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.
There is more on this topic elsewhere in the book.
.IP \(bu 5
Coordinates and sizes in X are actually 16-bit quantities.
They usually are declared as an ``int'' in the interface
(int is 16-bits on some machines).
Values larger than 16 bits are truncated silently.
Sizes (width and height) are unsigned quantities.
This decision was taken to minimize the bandwidth required for a
given level of performance.
.NH 2
Conventions Used in this Manual
.XS
\*(SN Conventions Used in this Manual 
.XE
.LP
The major documentation conventions are:
.IP \(bu 5
Global symbols in this manual are printed in this 
.PN special 
font.
These can be either procedure names,
symbols defined in include files, or structure names.
Arguments, user-supplied variables, are printed in \fIitalics\fP.
.IP \(bu 5
Most procedures are introduced by a general discussion that may be
used to distinguish this procedure from other procedures and are
followed by the procedure declaration itself.
Each argument is then specifically explained.
General discussion of the procedure, if any is required,
follows the arguments.
Where applicable, 
the last paragraph of given explanation lists the possible 
Xlib error codes that can be generated by that function.
See Section 8.10.2 for a complete discussion of the
Xlib error codes.
.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 ``specifies''.
By contrast,
the explanations for all arguments that are returned to you start with the
word ``returns''.
.bp
