diff options
Diffstat (limited to 'libX11/specs/libX11/CH01')
| -rw-r--r-- | libX11/specs/libX11/CH01 | 663 |
1 files changed, 663 insertions, 0 deletions
diff --git a/libX11/specs/libX11/CH01 b/libX11/specs/libX11/CH01 new file mode 100644 index 000000000..765e4b5fb --- /dev/null +++ b/libX11/specs/libX11/CH01 @@ -0,0 +1,663 @@ +.\" 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''\fB\*(xV\fP' +.OH '\fBXlib \- C Library\fP''\fB\*(xV\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 |