home *** CD-ROM | disk | FTP | other *** search
- .EH '\fBXlib \- C Library\fP''\fBX11, Release 5\fP'
- .OH '\fBXlib \- C Library\fP''\fBX11, Release 5\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.
- 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
- Naming and argument conventions
- .IP \(bu 5
- Programming considerations
- .IP \(bu 5
- Formatting 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,
- 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,
- which can be either 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,
- which 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.
- 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.
- .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
- .Pn < 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.
- .LP
- .Pn < 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 ``5'' in this release of the standard.
- (Earlier releases of Xlib did not have this symbol.)
- .LP
- .Pn < 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
- .Pn < X11/Xlib.h >,
- so application code should never need to reference this file directly.
- .LP
- .Pn < 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.
- .Pn < X11/Xlib.h >
- must be included before including this file.
- .LP
- .Pn < X11/Xutil.h >
- .IP
- This file declares various functions, types, and symbols used for
- inter-client communication and application utility functions,
- described in chapters 14 and 16.
- .Pn < X11/Xlib.h >
- must be included before including this file.
- .LP
- .Pn < X11/Xresource.h >
- .IP
- This file declares all functions, types, and symbols for the
- resource manager facilities, described in chapter 15.
- .Pn < X11/Xlib.h >
- must be included before including this file.
- .LP
- .Pn < X11/Xatom.h >
- .IP
- This file declares all predefined atoms, symbols with prefix ``XA_''.
- .LP
- .Pn < X11/cursorfont.h >
- .IP
- This file declares the cursor symbols for the standard cursor font,
- listed in appendix B. All symbols have the prefix ``XC_''.
- .LP
- .Pn < X11/keysymdef.h >
- .IP
- This file declares all standard KeySym values, symbols with 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_LATIN1, XK_LATIN2,
- XK_LATIN3, XK_LATIN4, XK_KATAKANA, XK_ARABIC, XK_CYRILLIC, XK_GREEK,
- XK_TECHNICAL, XK_SPECIAL, XK_PUBLISHING, XK_APL, and XK_HEBREW.
- .LP
- .Pn < X11/keysym.h >
- .IP
- This file defines the preprocessor symbols
- XK_MISCELLANY, XK_LATIN1, XK_LATIN2, XK_LATIN3, XK_LATIN4, and XK_GREEK,
- and then includes
- .Pn < X11/keysymdef.h >.
- .LP
- .Pn < X11/Xlibint.h >
- .IP
- This file declares all the functions, types, and symbols used for
- extensions, described in appendix C.
- This file automatically includes
- .Pn < X11/Xlib.h >.
- .LP
- .Pn < 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
- .Pn < X11/Xlibint.h >,
- so application and extension code should never need to
- reference this file directly.
- .LP
- .Pn < 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
- .Pn < X11/Xproto.h >,
- so application and extension code should never need to
- reference this file directly.
- .LP
- .Pn < X11/X10.h >
- .IP
- This file declares all the functions, types, and symbols used for the
- X10 compatibility functions, 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 taken to minimize the bandwidth required for a
- given level of performance.
- Coordinates usually are declared as an ``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 ones are the most common:
- .LP
- \fBX Portable Character Set\fP
- .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 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.
- .LP
- \fBHost Portable Character Encoding\fP
- .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.
- .LP
- \fBLatin-1\fP
- .IP
- The coded character set defined by the ISO8859-1 standard.
- .LP
- \fBSTRING encoding\fP
- .IP
- Latin-1, plus tab and newline.
- .LP
- \fBPOSIX Portable Filename Character Set\fP
- .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.
- Arguments are printed in \fIitalics\fP.
- .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
-