James Gettys, Robert W. Scheifler, et al.

“ You should only attempt to resize or move top-level windows in direct response to a user request. If a request to change the size of a top-level window fails, you must be prepared to live with what you get. You are free to resize or move the children of top-level windows as necessary. (Toolkits often have facilities for automatic relayout.) If you do not use a toolkit that automatically sets standard window properties, you should set these properties for top-level windows before mapping them. ”

“ The design and implementation of the first 10 versions of X were primarily the work of three individuals: Robert Scheifler of the MIT Laboratory for Computer Science and Jim Gettys of Digital Equipment Corporation and Ron Newman of MIT, both at MIT Project Athena. X version 11, however, is the result of the efforts of dozens of individuals at almost as many locations and organizations. At the risk of offending some of the players by exclusion, we would like to acknowledge some of the people who deserve special credit and recognition for their work on Xlib. ”

“ In addition to the connection to the X server, an Xlib implementation may require connections to other kinds of servers (for example, to input method servers as described in chapter 13) . Toolkits and clients that use multiple displays, or that use displays in combination with other inputs, need to obtain these additional connections to correctly block until input is available and need to process that input when it is available. Simple clients that use a single display and block for input in an Xlib event function do not need to use these facilities. ”

“ An application may wish to create a window long before it is mapped to the screen. When a window is eventually mapped to the screen (using XMapWindow) , the X server generates an Expose event for the window if backing store has not been maintained.
A window manager can override your choice of size, border width, and position for a top-level window. Your program must be prepared to use the actual size and position of the top window. It is not acceptable for a client application to resize itself unless in direct response to a human command to do so. ”

“ The X server does this even if the save-set window was not an inferior of a window created by the client. It destroys all windows created by the client. It performs the appropriate free request on each nonwindow resource created by the client in the server (for example, Font, Pixmap, Cursor, Colormap, and GContext) . It frees all colors and colormap entries allocated by a client application. Additional processing occurs when the last connection to the X server closes. An X server goes through a cycle of having no connections and having some connections. ”

“ 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. ”

“ The border tile origin is always the same as the background tile origin.
You can also set the border-pixmap to a pixmap of any size (some may be faster than others) or to CopyFromParent (default) . You can set the border-pixel to any pixel value (no default) .
If you set a border-pixmap, it overrides the default. The border-pixmap and the window must have the same depth, or a BadMatch error results. If you set the border-pixmap to CopyFromParent, the parent window's border-pixmap is copied. Subsequent changes to the parent window's border attribute do not affect the child window. ”

“ In the X Window System, a window is a rectangular area on the screen that lets you view graphic output. Client applications can display overlapping and nested windows on one or more screens that are driven by X servers on one or more machines. Clients who want to create windows must first connect their program to the X server by calling XOpenDisplay. ”

“ All Xlib functions begin with a capital X. The beginnings of all function names and symbols are capitalized. All user-visible data structures begin with a capital X. More generally, anything that a user might dereference begins with a capital X. 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. All elements of or variables in a data structure are in lowercase. Compound words, where needed, are constructed with underscores (_) . The display argument, where used, is always first in the argument list. ”

“ The Xlib library provides a number of useful macros and corresponding functions that return data from the Display structure. The macros are used for C programming, and their corresponding function equivalents are for other language bindings. This section discusses the:
Display macros Image format functions and macros Screen information macros All other members of the Display structure (that is, those for which no macros are defined) are private to Xlib and must not be used. Applications must never directly modify or inspect these private members of the Display structure. ”

“ Windows have borders of a programmable width and pattern as well as a background pattern or tile. Pixel values can be used for solid colors. The background and border pixmaps can be destroyed immediately after creating the window if no further explicit references to them are to be made. The pattern can either be relative to the parent or absolute. If ParentRelative, the parent's background is used.
When windows are first created, they are not visible (not mapped) on the screen. Any output to a window that is not visible on the screen and that does not have backing store will be discarded. ”

“ 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. ”

“ A single X server can support any or all of these transport mechanisms simultaneously. A particular Xlib implementation can support many more of these transport mechanisms.
If successful, XOpenDisplay returns a pointer to a Display structure, which is defined in . If XOpenDisplay does not succeed, it returns NULL. After a successful call to XOpenDisplay, all of the screens in the display can be used by the client. The screen number specified in the display_name argument is returned by the DefaultScreen macro (or the XDefaultScreen function) . ”

“ For PseudoColor, a pixel value indexes a colormap to produce independent RGB values, and the RGB values can be changed dynamically. GrayScale is treated the same way as PseudoColor except that the primary that drives the screen is undefined. Thus, the client should always store the same value for red, green, and blue in the colormaps. For DirectColor, a pixel value is decomposed into separate RGB subfields, and each subfield separately indexes the colormap for the corresponding value. The RGB values can be changed dynamically. ”

“ The alpha and beta test participants deserve special recognition and thanks as well. It is signifi- cant that the bug reports (and many fixes) during alpha and beta test came almost exclusively from just a few of the alpha testers, mostly hardware vendors working on product implementations of X. The continued public contribution of vendors and universities is certainly to the bene- fit of the entire X community. ”

“ Except as contained in this notice, the name of The Open Group 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 Open Group. ”

“ Where the x, y, width, and height arguments are used together, the x and y arguments always precede the width and height arguments. Where a mask is accompanied with a structure, the mask always precedes the pointer to the structure in the argument list. ”

“ The XDestroySubwindows function destroys all inferior windows of the specified window, in bottom-to-top stacking order. It causes the X server to generate a DestroyNotify event for each window. If any mapped subwindows were actually destroyed, XDestroySubwindows causes the X server to generate Expose events on the specified window. This is much more efficient than deleting many windows one at a time because much of the work need be performed only once for all of the windows, rather than for each window. ”

“ Single protocol requests to the server can be no larger than this size unless an extended-length protocol encoding is supported by the server. The protocol guarantees the size to be no smaller than 4096 units (16384 bytes) . Xlib automatically breaks data up into multiple protocol requests as necessary for the following functions: XDrawPoints, XDrawRectangles, XDrawSegments, XFillArcs, XFillRectangles, and XPutImage.
Both extract the full serial number of the last request known by Xlib to have been processed by the X server. ”

“ If a window has a background (almost all do) , it obscures the other window for purposes of output.
Attempts to output to the obscured area do nothing, and no input events (for example, pointer motion) are generated for the obscured area.
Windows also have associated property lists (see section 4.3) . Both InputOutput and InputOnly windows have the following common attributes, which are the only attributes of an InputOnly window:
win-gravity event-mask do-not-propagate-mask override-redirect cursor If you specify any other attributes for an InputOnly window, a BadMatch error results. ”

“ Although a client usually runs on the same machine as the X server it is talking to, this need not be the case.
Xlib − C Language X Interface 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. Xlib − C Language X Interface assumes a basic understanding of a graphics window system and of the C programming language. ”

“ If Xlib has been initialized for threads, the procedure is called with the display locked and the result of a call by the procedure to any Xlib function that locks the display is not defined unless the executing thread has externally locked the display using XLockDisplay. ”

“ The work they have done will help many everywhere. We also would like to thank Hal Murray (Digital SRC) and Peter George (Digital VMS) who contributed much by proofreading the early drafts of this document.
Our thanks also goes to Jeff Dike (Digital UEG) , Tom Benson, Jackie Granfield, and Vince Orgovan (Digital VMS) who helped with the library utilities implementation; to Hania Gajewska (Digital UEG-WSL) who, along with Ellis Cohen (CMU and Siemens) , was instrumental in the semantic design of the window manager properties ”

“ Once you have established a connection, you then can use the Xlib macros and functions discussed in this chapter to return information about the display. This chapter discusses how to:
Open (connect to) the display Obtain information about the display, image formats, or screens Generate a NoOperation protocol request Free client-created data Close (disconnect from) a display Use X Server connection close operations Use Xlib with threads Use internal connections 2.1. Opening the Display
To open a connection to the X server that controls a display, use XOpenDisplay. ”

“ Others who have contributed to the architectural design or testing of the sample implementation of the internationalization facilities are: Hector Chan (Digital) , Michael Kung (IBM) , Joseph Kwok (Digital) , Hiroyuki Machida (Sony) , Nelson Ng (SunSoft) , Frank Rojas (IBM) , Yoshiyuki Segawa (Fujitsu OSSI) , Makiko Shimamura (Fujitsu) , Shoji Sugiyama (IBM) , Lining Sun (SGI) , Masaki Takeuchi (Sony) , Jinsoo Yoon (KAIST) and Akiyasu Zen (HP) . ”

“ InputOnly windows are used for controlling input events in situations where InputOutput windows are unnecessary. InputOnly windows are invisible; can only be used to control such things as cursors, input event generation, and grabbing ”

“ If the specified screen_number is valid and sufficient memory for the array can be allocated, XListDepths sets count_return to the number of available depths. Otherwise, it does not set count_return and returns NULL. To release the memory allocated for the array of depths, use XFree. ”

“ 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. 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 . This file declares all the functions, types, and symbols used for extensions, which are described in appendix C. This file automatically includes . ”