Xlib − C Language X Interface

X Window System Standard

X Version 11, Release 7

libX11 1.3.2

James Gettys
Cambridge Research Laboratory Digital Equipment Corporation

Robert W. Scheifler
Laboratory for Computer Science Massachusetts Institute of Technology

with contributions from

Chuck Adams, Tektronix, Inc.

Vania Joloboff, Open Software Foundation

Hideki Hiura, Sun Microsystems, Inc.

Bill McMahon, Hewlett-Packard Company

Ron Newman, Massachusetts Institute of Technology

Al Tabayoyon, Tektronix, Inc.

Glenn Widener, Tektronix, Inc.

Shigeru Yamada, Fujitsu OSSI

The X Window System is a trademark of The Open Group.

TekHVC is a trademark of Tektronix, Inc.

Copyright © 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996, 2002 The Open Group

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

Copyright © 1985, 1986, 1987, 1988, 1989, 1990, 1991 by Digital Equipment Corporation

Portions Copyright © 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.

Acknowledgments

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. Our apologies to anyone inadvertently overlooked.

Release 1

Our thanks does to Ron Newman (MIT Project Athena), who contributed substantially to the design and implementation of the Version 11 Xlib interface.

Our thanks also goes to Ralph Swick (Project Athena and Digital) who kept it all together for us during the early releases. He handled literally thousands of requests from people everywhere and saved the sanity of at least one of us. His calm good cheer was a foundation on which we could build.

Our thanks also goes to Todd Brunhoff (Tektronix) who was ‘‘loaned’’ to Project Athena at exactly the right moment to provide very capable and much-needed assistance during the alpha and beta releases. He was responsible for the successful integration of sources from multiple sites; we would not have had a release without him.

Our thanks also goes to Al Mento and Al Wojtas of Digital’s ULTRIX Documentation Group. With good humor and cheer, they took a rough draft and made it an infinitely better and more useful document. 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; and to Dave Rosenthal (Sun Microsystems) who also contributed to the protocol and provided the sample generic color frame buffer device-dependent code.

The alpha and beta test participants deserve special recognition and thanks as well. It is significant 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 benefit of the entire X community.

Our special thanks must go to Sam Fuller, Vice-President of Corporate Research at Digital, who has remained committed to the widest public availability of X and who made it possible to greatly supplement MIT’s resources with the Digital staff in order to make version 11 a reality. Many of the people mentioned here are part of the Western Software Laboratory (Digital UEG-WSL) of the ULTRIX Engineering group and work for Smokey Wallace, who has been vital to the project’s success. Others not mentioned here worked on the toolkit and are acknowledged in the X Toolkit documentation.

Of course, we must particularly thank Paul Asente, formerly of Stanford University and now of Digital UEG-WSL, who wrote W, the predecessor to X, and Brian Reid, formerly of Stanford University and now of Digital WRL, who had much to do with W’s design.

Finally, our thanks goes to MIT, Digital Equipment Corporation, and IBM for providing the environment where it could happen.

Release 4

Our thanks go to Jim Fulton (MIT X Consortium) for designing and specifying the new Xlib functions for Inter-Client Communication Conventions (ICCCM) support.

We also thank Al Mento of Digital for his continued effort in maintaining this document and Jim Fulton and Donna Converse (MIT X Consortium) for their much-appreciated efforts in reviewing the changes.

Release 5

The principal authors of the Input Method facilities are Vania Joloboff (Open Software Foundation) and Bill McMahon (Hewlett-Packard). The principal author of the rest of the internationalization facilities is Glenn Widener (Tektronix). Our thanks to them for keeping their sense of humor through a long and sometimes difficult design process. Although the words and much of the design are due to them, many others have contributed substantially to the design and implementation. Tom McFarland (HP) and Frank Rojas (IBM) deserve particular recognition for their contributions. Other contributors were: Tim Anderson (Motorola), Alka Badshah (OSF), Gabe Beged-Dov (HP), Chih-Chung Ko (III), Vera Cheng (III), Michael Collins (Digital), Walt Daniels (IBM), Noritoshi Demizu (OMRON), Keisuke Fukui (Fujitsu), Hitoshoi Fukumoto (Nihon Sun), Tim Greenwood (Digital), John Harvey (IBM), Hideki Hiura (Sun), Fred Horman (AT&T), Norikazu Kaiya (Fujitsu), Yuji Kamata (IBM), Yutaka Kataoka (Waseda University), Ranee Khubchandani (Sun), Akira Kon (NEC), Hiroshi Kuribayashi (OMRON), Teruhiko Kurosaka (Sun), Seiji Kuwari (OMRON), Sandra Martin (OSF), Narita Masahiko (Fujitsu), Masato Morisaki (NTT), Nelson Ng (Sun), Takashi Nishimura (NTT America), Makato Nishino (IBM), Akira Ohsone (Nihon Sun), Chris Peterson (MIT), Sam Shteingart (AT&T), Manish Sheth (AT&T), Muneiyoshi Suzuki (NTT), Cori Mehring (Digital), Shoji Sugiyama (IBM), and Eiji Tosa (IBM).

We are deeply indebted to Tatsuya Kato (NTT), Hiroshi Kuribayashi (OMRON), Seiji Kuwari (OMRON), Muneiyoshi Suzuki (NTT), and Li Yuhong (OMRON) for producing one of the first complete sample implementation of the internationalization facilities, and Hiromu Inukai (Nihon Sun), Takashi Fujiwara (Fujitsu), Hideki Hiura (Sun), Yasuhiro Kawai (Oki Technosystems Laboratory), Kazunori Nishihara (Fuji Xerox), Masaki Takeuchi (Sony), Katsuhisa Yano (Toshiba), Makoto Wakamatsu (Sony Corporation) for producing the another complete sample implementation of the internationalization facilities.

The principal authors (design and implementation) of the Xcms color management facilities are Al Tabayoyon (Tektronix) and Chuck Adams (Tektronix). Joann Taylor (Tektronix), Bob Toole (Tektronix), and Keith Packard (MIT X Consortium) also contributed significantly to the design. Others who contributed are: Harold Boll (Kodak), Ken Bronstein (HP), Nancy Cam (SGI), Donna Converse (MIT X Consortium), Elias Israel (ISC), Deron Johnson (Sun), Jim King (Adobe), Ricardo Motta (HP), Chuck Peek (IBM), Wil Plouffe (IBM), Dave Sternlicht (MIT X Consortium), Kumar Talluri (AT&T), and Richard Verberg (IBM).

We also once again thank Al Mento of Digital for his work in formatting and reformatting text for this manual, and for producing man pages. Thanks also to Clive Feather (IXI) for proof-reading and finding a number of small errors.

Release 6

Stephen Gildea (X Consortium) authored the threads support. Ovais Ashraf (Sun) and Greg Olsen (Sun) contributed substantially by testing the facilities and reporting bugs in a timely fashion.

The principal authors of the internationalization facilities, including Input and Output Methods, are Hideki Hiura (SunSoft) and Shigeru Yamada (Fujitsu OSSI). Although the words and much of the design are due to them, many others have contributed substantially to the design and implementation. They are: Takashi Fujiwara (Fujitsu), Yoshio Horiuchi (IBM), Makoto Inada (Digital), Hiromu Inukai (Nihon SunSoft), Song JaeKyung (KAIST), Franky Ling (Digital), Tom McFarland (HP), Hiroyuki Miyamoto (Digital), Masahiko Narita (Fujitsu), Frank Rojas (IBM), Hidetoshi Tajima (HP), Masaki Takeuchi (Sony), Makoto Wakamatsu (Sony), Masaki Wakao (IBM), Katsuhisa Yano(Toshiba) and Jinsoo Yoon (KAIST).

The principal producers of the sample implementation of the internationalization facilities are: Jeffrey Bloomfield (Fujitsu OSSI), Takashi Fujiwara (Fujitsu), Hideki Hiura (SunSoft), Yoshio Horiuchi (IBM), Makoto Inada (Digital), Hiromu Inukai (Nihon SunSoft), Song JaeKyung (KAIST), Riki Kawaguchi (Fujitsu), Franky Ling (Digital), Hiroyuki Miyamoto (Digital), Hidetoshi Tajima (HP), Toshimitsu Terazono (Fujitsu), Makoto Wakamatsu (Sony), Masaki Wakao (IBM), Shigeru Yamada (Fujitsu OSSI) and Katsuhisa Yano (Toshiba).

The coordinators of the integration, testing, and release of this implementation of the internationalization facilities are Nobuyuki Tanaka (Sony) and Makoto Wakamatsu (Sony).

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).

Jim Gettys
Cambridge Research Laboratory
Digital Equipment Corporation

Robert W. Scheifler
Laboratory for Computer Science
Massachusetts Institute of Technology

Chapter 1

Introduction to Xlib

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.

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. 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 X Window System Protocol provides the definitive word on the behavior of X. Although additional information appears here, the protocol document is the ruling document.

To provide an introduction to X programming, this chapter discusses:

1.1. Overview of the X Window System

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.

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.

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

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

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.

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.

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

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.

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.

If a client does not want a request to execute asynchronously, it can follow the request with a call to 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.

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, Colormap, Cursor, and GContext, as defined in the file <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.

Client programs are informed of events. Events may either be side effects of a request (for example, restacking windows generates 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.

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, XNextEvent or XWindowEvent). In addition, some library functions (for example, XRaiseWindow) generate Expose and ConfigureRequest events. These events also arrive asynchronously, but the client may wish to explicitly wait for them by calling XSync after calling a function that can cause the server to generate events.

1.2. Errors

Some functions return 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. Because C does not provide multiple return values, many functions must return their results by writing into client-passed storage. 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.

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.

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.

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.

1.3. Standard Header Files

The following include files are part of the Xlib standard:

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 XlibSpecificationRelease. 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.)

This file declares types and constants for the X protocol that are to be used by applications. It is included automatically from <X11/Xlib.h>, so application code should never need to reference this file directly.

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. <X11/Xlib.h> must be included before including this file.

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. <X11/Xlib.h> must be included before including this file.

This file declares all functions, types, and symbols for the resource manager facilities, which are described in chapter 15. <X11/Xlib.h> must be included before including this file.

This file declares all predefined atoms, which are symbols with the prefix ‘‘XA_’’.

This file declares the cursor symbols for the standard cursor font, which are listed in appendix B. All cursor symbols have the prefix ‘‘XC_’’.

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.

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 <X11/keysymdef.h>.

This file declares all the functions, types, and symbols used for extensions, which are described in appendix C. This file automatically includes <X11/Xlib.h>.

This file declares types and symbols for the basic X protocol, for use in implementing extensions. It is included automatically from <X11/Xlibint.h>, so application and extension code should never need to reference this file directly.

This file declares types and symbols for the basic X protocol, for use in implementing extensions. It is included automatically from <X11/Xproto.h>, so application and extension code should never need to reference this file directly.

This file declares all the functions, types, and symbols used for the X10 compatibility functions, which are described in appendix D.

1.4. Generic Values and Types

The following symbols are defined by Xlib and used throughout the manual:

1.5. Naming and Argument Conventions within Xlib

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.

The major naming conventions are:

1.6. Programming Considerations

The major programming considerations are:

1.7. Character Sets and Encodings

Some of the Xlib functions make reference to specific character sets and character encodings. The following are the most common:

A basic set of 97 characters, which are assumed to exist in all locales supported by Xlib. This set contains the following characters:

a..z A..Z 0..9
!"#$%&’()*+,-./:;<=>?@[\]^_‘{|}~
<space>, <tab>, and <newline>

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.

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.

The coded character set defined by the ISO8859-1 standard.

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.

Latin-1, plus tab and newline.

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:

a..z A..Z 0..9 ._-

1.8. Formatting Conventions

Xlib − C Language X Interface uses the following conventions:

1

Xlib − C Library libX11 1.3.2

Chapter 2

Display Functions

Before your program can use a display, you must establish a connection to the X server. 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:

2.1. Opening the Display

To open a connection to the X server that controls a display, use XOpenDisplay. __ │

Display *XOpenDisplay(display_name)
char *display_name;

display_name
Specifies the hardware display name, which deter-
mines the display and communications domain to be
used. On a POSIX-conformant system, if the dis-
play_name is NULL, it defaults to the value of the
DISPLAY environment variable. │__

The encoding and interpretation of the display name are implementation-dependent. Strings in the Host Portable Character Encoding are supported; support for other characters is implementation-dependent. On POSIX-conformant systems, the display name or DISPLAY environment variable can be a string in the format: __ │

screen_number
Specifies the screen to be used on that server. Multiple screens can be controlled by a single X server. The screen_number sets an internal variable that can be accessed by using the DefaultScreen macro or the XDefaultScreen function if you are using languages other than C (see section 2.2.1). │__

For example, the following would specify screen 1 of display 0 on the machine named ‘‘dual-headed’’:

dual-headed:0.1

The XOpenDisplay function returns a Display structure that serves as the connection to the X server and that contains all the information about that X server. XOpenDisplay connects your application to the X server through TCP or DECnet communications protocols, or through some local inter-process communication protocol. If the protocol is specified as "tcp", "inet", or "inet6", or if no protocol is specified and the hostname is a host machine name and a single colon (:) separates the hostname and display number, XOpenDisplay connects using TCP streams. (If the protocol is specified as "inet", TCP over IPv4 is used. If the protocol is specified as "inet6", TCP over IPv6 is used. Otherwise, the implementation determines which IP version is used.) If the hostname and protocol are both not specified, Xlib uses whatever it believes is the fastest transport. If the hostname is a host machine name and a double colon (::) separates the hostname and display number, XOpenDisplay connects using DECnet. 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 <X11/Xlib.h>. 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). You can access elements of the Display and Screen structures only by using the information macros or functions. For information about using macros and functions to obtain information from the Display structure, see section 2.2.1.

X servers may implement various types of access control mechanisms (see section 9.8).

2.2. Obtaining Information about the Display, Image Formats, or Screens

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.

Note

The XDisplayWidth, XDisplayHeight, XDisplayCells, XDisplayPlanes, XDisplayWidthMM, and XDisplayHeightMM functions in the next sections are misnamed. These functions really should be named Screenwhatever and XScreenwhatever, not Displaywhatever or XDisplaywhatever. Our apologies for the resulting confusion.

2.2.1. Display Macros

Applications should not directly modify any part of the Display and Screen structures. The members should be considered read-only, although they may change as the result of other operations on the display.

The following lists the C language macros, their corresponding function equivalents that are for other language bindings, and what data both can return. __ │

AllPlanes

unsigned long XAllPlanes() │__

Both return a value with all bits set to 1 suitable for use in a plane argument to a procedure.

Both BlackPixel and WhitePixel can be used in implementing a monochrome application. These pixel values are for permanently allocated entries in the default colormap. The actual RGB (red, green, and blue) values are settable on some screens and, in any case, may not actually be black or white. The names are intended to convey the expected relative intensity of the colors. __ │

BlackPixel(display, screen_number)

unsigned long XBlackPixel(display, screen_number)
Display *display;
int screen_number;

screen_number
Specifies the appropriate screen number on the
host server. │__

Both return the black pixel value for the specified screen. __ │

WhitePixel(display, screen_number)

unsigned long XWhitePixel(display, screen_number)
Display *display;
int screen_number;

screen_number
Specifies the appropriate screen number on the
host server. │__

Both return the white pixel value for the specified screen. __ │

ConnectionNumber(display)

int XConnectionNumber(display)
Display *display;

Both return a connection number for the specified display. On a POSIX-conformant system, this is the file descriptor of the connection. __ │

DefaultColormap(display, screen_number)

Colormap XDefaultColormap(display, screen_number)
Display *display;
int screen_number;

screen_number
Specifies the appropriate screen number on the
host server. │__

Both return the default colormap ID for allocation on the specified screen. Most routine allocations of color should be made out of this colormap. __ │

DefaultDepth(display, screen_number)

int XDefaultDepth(display, screen_number)
Display *display;
int screen_number;

screen_number
Specifies the appropriate screen number on the
host server. │__

Both return the depth (number of planes) of the default root window for the specified screen. Other depths may also be supported on this screen (see XMatchVisualInfo).

To determine the number of depths that are available on a given screen, use XListDepths. __ │

int *XListDepths(display, screen_number, count_return)
Display *display;
int screen_number;
int *count_return;

screen_number
Specifies the appropriate screen number on the
host server.

count_return
Returns the number of depths. │__

The XListDepths function returns the array of depths that are available on the specified screen. 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. __ │

DefaultGC(display, screen_number)

GC XDefaultGC(display, screen_number)
Display *display;
int screen_number;

screen_number
Specifies the appropriate screen number on the
host server. │__

Both return the default graphics context for the root window of the specified screen. This GC is created for the convenience of simple applications and contains the default GC components with the foreground and background pixel values initialized to the black and white pixels for the screen, respectively. You can modify its contents freely because it is not used in any Xlib function. This GC should never be freed. __ │

DefaultRootWindow(display)

Window XDefaultRootWindow(display)
Display *display;

Both return the root window for the default screen. __ │

DefaultScreenOfDisplay(display)

Screen *XDefaultScreenOfDisplay(display)
Display *display;

Both return a pointer to the default screen. __ │

ScreenOfDisplay(display, screen_number)

Screen *XScreenOfDisplay(display, screen_number)
Display *display;
int screen_number;

screen_number
Specifies the appropriate screen number on the
host server. │__

Both return a pointer to the indicated screen. __ │

DefaultScreen(display)

int XDefaultScreen(display)
Display *display;

Both return the default screen number referenced by the XOpenDisplay function. This macro or function should be used to retrieve the screen number in applications that will use only a single screen. __ │

DefaultVisual(display, screen_number)

Visual *XDefaultVisual(display, screen_number)
Display *display;
int screen_number;

screen_number
Specifies the appropriate screen number on the
host server. │__

Both return the default visual type for the specified screen. For further information about visual types, see section 3.1. __ │

DisplayCells(display, screen_number)

int XDisplayCells(display, screen_number)
Display *display;
int screen_number;

screen_number
Specifies the appropriate screen number on the
host server. │__

Both return the number of entries in the default colormap. __ │

DisplayPlanes(display, screen_number)

int XDisplayPlanes(display, screen_number)
Display *display;
int screen_number;

screen_number
Specifies the appropriate screen number on the
host server. │__

Both return the depth of the root window of the specified screen. For an explanation of depth, see the glossary. __ │

DisplayString(display)

char *XDisplayString(display)
Display *display;

Both return the string that was passed to XOpenDisplay when the current display was opened. On POSIX-conformant systems, if the passed string was NULL, these return the value of the DISPLAY environment variable when the current display was opened. These are useful to applications that invoke the fork system call and want to open a new connection to the same display from the child process as well as for printing error messages. __ │

long XExtendedMaxRequestSize(display)

The XExtendedMaxRequestSize function returns zero if the specified display does not support an extended-length protocol encoding; otherwise, it returns the maximum request size (in 4-byte units) supported by the server using the extended-length encoding. The Xlib functions XDrawLines, XDrawArcs, XFillPolygon, XChangeProperty, XSetClipRectangles, and XSetRegion will use the extended-length encoding as necessary, if supported by the server. Use of the extended-length encoding in other Xlib functions (for example, XDrawPoints, XDrawRectangles, XDrawSegments, XFillArcs, XFillRectangles, XPutImage) is permitted but not required; an Xlib implementation may choose to split the data across multiple smaller requests instead. __ │

long XMaxRequestSize(display)

The XMaxRequestSize function returns the maximum request size (in 4-byte units) supported by the server without using an extended-length protocol encoding. 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. __ │

LastKnownRequestProcessed(display)

unsigned long XLastKnownRequestProcessed(display)
Display *display;

Both extract the full serial number of the last request known by Xlib to have been processed by the X server. Xlib automatically sets this number when replies, events, and errors are received. __ │

NextRequest(display)

unsigned long XNextRequest(display)
Display *display;

Both extract the full serial number that is to be used for the next request. Serial numbers are maintained separately for each display connection. __ │

ProtocolVersion(display)

int XProtocolVersion(display)
Display *display;

Both return the major version number (11) of the X protocol associated with the connected display. __ │

ProtocolRevision(display)

int XProtocolRevision(display)
Display *display;

Both return the minor protocol revision number of the X server. __ │

QLength(display)

int XQLength(display)
Display *display;

Both return the length of the event queue for the connected display. Note that there may be more events that have not been read into the queue yet (see XEventsQueued). __ │

RootWindow(display, screen_number)

Window XRootWindow(display, screen_number)
Display *display;
int screen_number;

screen_number
Specifies the appropriate screen number on the
host server. │__

Both return the root window. These are useful with functions that need a drawable of a particular screen and for creating top-level windows. __ │

ScreenCount(display)

int XScreenCount(display)
Display *display;

Both return the number of available screens. __ │

ServerVendor(display)

char *XServerVendor(display)
Display *display;

Both return a pointer to a null-terminated string that provides some identification of the owner of the X server implementation. If the data returned by the server is in the Latin Portable Character Encoding, then the string is in the Host Portable Character Encoding. Otherwise, the contents of the string are implementation-dependent. __ │

VendorRelease(display)

int XVendorRelease(display)
Display *display;

Both return a number related to a vendor’s release of the X server.

2.2.2. Image Format Functions and Macros

Applications are required to present data to the X server in a format that the server demands. To help simplify applications, most of the work required to convert the data is provided by Xlib (see sections 8.7 and 16.8).

The XPixmapFormatValues structure provides an interface to the pixmap format information that is returned at the time of a connection setup. It contains: __ │

typedef struct {

} XPixmapFormatValues; │__

To obtain the pixmap format information for a given display, use XListPixmapFormats. __ │

XPixmapFormatValues *XListPixmapFormats(display, count_return)
Display *display;
int *count_return;

count_return
Returns the number of pixmap formats that are sup-
ported by the display. │__

The XListPixmapFormats function returns an array of XPixmapFormatValues structures that describe the types of Z format images supported by the specified display. If insufficient memory is available, XListPixmapFormats returns NULL. To free the allocated storage for the XPixmapFormatValues structures, use XFree.

The following lists the C language macros, their corresponding function equivalents that are for other language bindings, and what data they both return for the specified server and screen. These are often used by toolkits as well as by simple applications. __ │

ImageByteOrder(display)

int XImageByteOrder(display)
Display *display;

Both specify the required byte order for images for each scanline unit in XY format (bitmap) or for each pixel value in Z format. The macro or function can return either LSBFirst or MSBFirst. __ │

BitmapUnit(display)

int XBitmapUnit(display)
Display *display;

Both return the size of a bitmap’s scanline unit in bits. The scanline is calculated in multiples of this value. __ │

BitmapBitOrder(display)

int XBitmapBitOrder(display)
Display *display;

Within each bitmap unit, the left-most bit in the bitmap as displayed on the screen is either the least significant or most significant bit in the unit. This macro or function can return LSBFirst or MSBFirst. __ │

BitmapPad(display)

int XBitmapPad(display)
Display *display;

Each scanline must be padded to a multiple of bits returned by this macro or function. __ │

DisplayHeight(display, screen_number)

int XDisplayHeight(display, screen_number)
Display *display;
int screen_number;

screen_number
Specifies the appropriate screen number on the
host server. │__

Both return an integer that describes the height of the screen in pixels. __ │

DisplayHeightMM(display, screen_number)

int XDisplayHeightMM(display, screen_number)
Display *display;
int screen_number;

screen_number
Specifies the appropriate screen number on the
host server. │__

Both return the height of the specified screen in millimeters. __ │

DisplayWidth(display, screen_number)

int XDisplayWidth(display, screen_number)
Display *display;
int screen_number;

screen_number
Specifies the appropriate screen number on the
host server. │__

Both return the width of the screen in pixels. __ │

DisplayWidthMM(display, screen_number)

int XDisplayWidthMM(display, screen_number)
Display *display;
int screen_number;

screen_number
Specifies the appropriate screen number on the
host server. │__

Both return the width of the specified screen in millimeters.

2.2.3. Screen Information Macros

The following lists the C language macros, their corresponding function equivalents that are for other language bindings, and what data they both can return. These macros or functions all take a pointer to the appropriate screen structure. __ │

BlackPixelOfScreen(screen)

unsigned long XBlackPixelOfScreen(screen)
Screen *screen;

Both return the black pixel value of the specified screen. __ │

WhitePixelOfScreen(screen)

unsigned long XWhitePixelOfScreen(screen)
Screen *screen;

Both return the white pixel value of the specified screen. __ │

CellsOfScreen(screen)

int XCellsOfScreen(screen)
Screen *screen;

Both return the number of colormap cells in the default colormap of the specified screen. __ │

DefaultColormapOfScreen(screen)

Colormap XDefaultColormapOfScreen(screen)
Screen *screen;

Both return the default colormap of the specified screen. __ │

DefaultDepthOfScreen(screen)

int XDefaultDepthOfScreen(screen)
Screen *screen;

Both return the depth of the root window. __ │

DefaultGCOfScreen(screen)

GC XDefaultGCOfScreen(screen)
Screen *screen;

Both return a default graphics context (GC) of the specified screen, which has the same depth as the root window of the screen. The GC must never be freed. __ │

DefaultVisualOfScreen(screen)

Visual *XDefaultVisualOfScreen(screen)
Screen *screen;

Both return the default visual of the specified screen. For information on visual types, see section 3.1. __ │

DoesBackingStore(screen)

int XDoesBackingStore(screen)
Screen *screen;

Both return a value indicating whether the screen supports backing stores. The value returned can be one of WhenMapped, NotUseful, or Always (see section 3.2.4). __ │

DoesSaveUnders(screen)

Bool XDoesSaveUnders(screen)
Screen *screen;

Both return a Boolean value indicating whether the screen supports save unders. If True, the screen supports save unders. If False, the screen does not support save unders (see section 3.2.5). __ │

DisplayOfScreen(screen)

Display *XDisplayOfScreen(screen)
Screen *screen;

Both return the display of the specified screen. __ │

int XScreenNumberOfScreen(screen)
Screen *screen;

The XScreenNumberOfScreen function returns the screen index number of the specified screen. __ │

EventMaskOfScreen(screen)

long XEventMaskOfScreen(screen)
Screen *screen;

Both return the event mask of the root window for the specified screen at connection setup time. __ │

WidthOfScreen(screen)

int XWidthOfScreen(screen)
Screen *screen;

Both return the width of the specified screen in pixels. __ │

HeightOfScreen(screen)

int XHeightOfScreen(screen)
Screen *screen;

Both return the height of the specified screen in pixels. __ │

WidthMMOfScreen(screen)

int XWidthMMOfScreen(screen)
Screen *screen;

Both return the width of the specified screen in millimeters. __ │

HeightMMOfScreen(screen)

int XHeightMMOfScreen(screen)
Screen *screen;

Both return the height of the specified screen in millimeters. __ │

MaxCmapsOfScreen(screen)

int XMaxCmapsOfScreen(screen)
Screen *screen;

Both return the maximum number of installed colormaps supported by the specified screen (see section 9.3). __ │

MinCmapsOfScreen(screen)

int XMinCmapsOfScreen(screen)
Screen *screen;

Both return the minimum number of installed colormaps supported by the specified screen (see section 9.3). __ │

PlanesOfScreen(screen)

int XPlanesOfScreen(screen)
Screen *screen;

Both return the depth of the root window. __ │

RootWindowOfScreen(screen)

Window XRootWindowOfScreen(screen)
Screen *screen;

Both return the root window of the specified screen.

2.3. Generating a NoOperation Protocol Request

To execute a NoOperation protocol request, use XNoOp. __ │

XNoOp(display)
Display *display;

The XNoOp function sends a NoOperation protocol request to the X server, thereby exercising the connection.

2.4. Freeing Client-Created Data

To free in-memory data that was created by an Xlib function, use XFree. __ │

XFree(data)
void *data;

The XFree function is a general-purpose Xlib routine that frees the specified data. You must use it to free any objects that were allocated by Xlib, unless an alternate function is explicitly specified for the object. A NULL pointer cannot be passed to this function.

2.5. Closing the Display

To close a display or disconnect from the X server, use XCloseDisplay. __ │

XCloseDisplay(display)
Display *display;

The XCloseDisplay function closes the connection to the X server for the display specified in the Display structure and destroys all windows, resource IDs (Window, Font, Pixmap, Colormap, Cursor, and GContext), or other resources that the client has created on this display, unless the close-down mode of the resource has been changed (see XSetCloseDownMode). Therefore, these windows, resource IDs, and other resources should never be referenced again or an error will be generated. Before exiting, you should call XCloseDisplay explicitly so that any pending errors are reported as XCloseDisplay performs a final XSync operation.

XCloseDisplay can generate a BadGC error.

Xlib provides a function to permit the resources owned by a client to survive after the client’s connection is closed. To change a client’s close-down mode, use XSetCloseDownMode. __ │

XSetCloseDownMode(display, close_mode)
Display *display;

int close_mode;

close_modeSpecifies the client close-down mode. You can
pass DestroyAll, RetainPermanent, or RetainTempo-
rary. │__

The XSetCloseDownMode defines what will happen to the client’s resources at connection close. A connection starts in DestroyAll mode. For information on what happens to the client’s resources when the close_mode argument is RetainPermanent or RetainTemporary, see section 2.6.

XSetCloseDownMode can generate a BadValue error.

2.6. Using X Server Connection Close Operations

When the X server’s connection to a client is closed either by an explicit call to XCloseDisplay or by a process that exits, the X server performs the following automatic operations:

When the close-down mode is DestroyAll, the X server destroys all of a client’s resources as follows:

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. When the last connection to the X server closes as a result of a connection closing with the close_mode of DestroyAll, the X server does the following:

However, the X server does not reset if you close a connection with a close-down mode set to RetainPermanent or RetainTemporary.

2.7. Using Xlib with Threads

On systems that have threads, support may be provided to permit multiple threads to use Xlib concurrently.

To initialize support for concurrent threads, use XInitThreads. __ │

Status XInitThreads(); │__

The XInitThreads function initializes Xlib support for concurrent threads. This function must be the first Xlib function a multi-threaded program calls, and it must complete before any other Xlib call is made. This function returns a nonzero status if initialization was successful; otherwise, it returns zero. On systems that do not support threads, this function always returns zero.

It is only necessary to call this function if multiple threads might use Xlib concurrently. If all calls to Xlib functions are protected by some other access mechanism (for example, a mutual exclusion lock in a toolkit or through explicit client programming), Xlib thread initialization is not required. It is recommended that single-threaded programs not call this function.

To lock a display across several Xlib calls, use XLockDisplay. __ │

void XLockDisplay(display)
Display *display;

The XLockDisplay function locks out all other threads from using the specified display. Other threads attempting to use the display will block until the display is unlocked by this thread. Nested calls to XLockDisplay work correctly; the display will not actually be unlocked until XUnlockDisplay has been called the same number of times as XLockDisplay. This function has no effect unless Xlib was successfully initialized for threads using XInitThreads.

To unlock a display, use XUnlockDisplay. __ │

void XUnlockDisplay(display)
Display *display;

The XUnlockDisplay function allows other threads to use the specified display again. Any threads that have blocked on the display are allowed to continue. Nested locking works correctly; if XLockDisplay has been called multiple times by a thread, then XUnlockDisplay must be called an equal number of times before the display is actually unlocked. This function has no effect unless Xlib was successfully initialized for threads using XInitThreads.

2.8. Using Internal Connections

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.

To track internal connections for a display, use XAddConnectionWatch. __ │

typedef void (*XConnectionWatchProc)(display, client_data, fd, opening, watch_data)
Display *display;
XPointer client_data;
int fd;
Bool opening;
XPointer *watch_data;

Status XAddConnectionWatch(display, procedure, client_data)
Display *display;
XWatchProc procedure;
XPointer client_data;

client_dataSpecifies the additional client data. │__

The XAddConnectionWatch function registers a procedure to be called each time Xlib opens or closes an internal connection for the specified display. The procedure is passed the display, the specified client_data, the file descriptor for the connection, a Boolean indicating whether the connection is being opened or closed, and a pointer to a location for private watch data. If opening is True, the procedure can store a pointer to private data in the location pointed to by watch_data; when the procedure is later called for this same connection and opening is False, the location pointed to by watch_data will hold this same private data pointer.

This function can be called at any time after a display is opened. If internal connections already exist, the registered procedure will immediately be called for each of them, before XAddConnectionWatch returns. XAddConnectionWatch returns a nonzero status if the procedure is successfully registered; otherwise, it returns zero.

The registered procedure should not call any Xlib functions. If the procedure directly or indirectly causes the state of internal connections or watch procedures to change, the result is not defined. 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.

To stop tracking internal connections for a display, use XRemoveConnectionWatch. __ │

Status XRemoveConnectionWatch(display, procedure, client_data)
Display *display;
XWatchProc procedure;
XPointer client_data;

client_dataSpecifies the additional client data. │__

The XRemoveConnectionWatch function removes a previously registered connection watch procedure. The client_data must match the client_data used when the procedure was initially registered.

To process input on an internal connection, use XProcessInternalConnection. __ │

void XProcessInternalConnection(display, fd)
Display *display;
int fd;

The XProcessInternalConnection function processes input available on an internal connection. This function should be called for an internal connection only after an operating system facility (for example, select or poll) has indicated that input is available; otherwise, the effect is not defined.

To obtain all of the current internal connections for a display, use XInternalConnectionNumbers. __ │

Status XInternalConnectionNumbers(display, fd_return, count_return)
Display *display;
int **fd_return;
int *count_return;

count_return
Returns the number of file descriptors. │__

The XInternalConnectionNumbers function returns a list of the file descriptors for all internal connections currently open for the specified display. When the allocated list is no longer needed, free it by using XFree. This functions returns a nonzero status if the list is successfully allocated; otherwise, it returns zero.

2

Xlib − C Library libX11 1.3.2

Chapter 3

Window Functions

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. This chapter begins with a discussion of visual types and window attributes. The chapter continues with a discussion of the Xlib functions you can use to:

This chapter also identifies the window actions that may generate events.

Note that it is vital that your application conform to the established conventions for communicating with window managers for it to work well with the various window managers in use (see section 14.1). Toolkits generally adhere to these conventions for you, relieving you of the burden. Toolkits also often supersede many functions in this chapter with versions of their own. For more information, refer to the documentation for the toolkit that you are using.

3.1. Visual Types

On some display hardware, it may be possible to deal with color resources in more than one way. For example, you may be able to deal with a screen of either 12-bit depth with arbitrary mapping of pixel to color (pseudo-color) or 24-bit depth with 8 bits of the pixel dedicated to each of red, green, and blue. These different ways of dealing with the visual aspects of the screen are called visuals. For each screen of the display, there may be a list of valid visual types supported at different depths of the screen. Because default windows and visual types are defined for each screen, most simple applications need not deal with this complexity. Xlib provides macros and functions that return the default root window, the default depth of the default root window, and the default visual type (see sections 2.2.1 and 16.7).

Xlib uses an opaque Visual structure that contains information about the possible color mapping. The visual utility functions (see section 16.7) use an XVisualInfo structure to return this information to an application. The members of this structure pertinent to this discussion are class, red_mask, green_mask, blue_mask, bits_per_rgb, and colormap_size. The class member specifies one of the possible visual classes of the screen and can be StaticGray, StaticColor, TrueColor, GrayScale, PseudoColor, or DirectColor.

The following concepts may serve to make the explanation of visual types clearer. The screen can be color or grayscale, can have a colormap that is writable or read-only, and can also have a colormap whose indices are decomposed into separate RGB pieces, provided one is not on a grayscale screen. This leads to the following diagram:

Color Gray-scale
R/O R/W R/O R/W
Undecomposed Static Pseudo Static Gray
Colormap Color Color Gray Scale
Decomposed True Direct
Colormap Color Color

Conceptually, as each pixel is read out of video memory for display on the screen, it goes through a look-up stage by indexing into a colormap. Colormaps can be manipulated arbitrarily on some hardware, in limited ways on other hardware, and not at all on other hardware. The visual types affect the colormap and the RGB values in the following ways:

The red_mask, green_mask, and blue_mask members are only defined for DirectColor and TrueColor. Each has one contiguous set of bits with no intersections. The bits_per_rgb member specifies the log base 2 of the number of distinct color values (individually) of red, green, and blue. Actual RGB values are unsigned 16-bit numbers. The colormap_size member defines the number of available colormap entries in a newly created colormap. For DirectColor and TrueColor, this is the size of an individual pixel subfield.

To obtain the visual ID from a Visual, use XVisualIDFromVisual. __ │

VisualID XVisualIDFromVisual(visual)
Visual *visual;

The XVisualIDFromVisual function returns the visual ID for the specified visual type.

3.2. Window Attributes

All InputOutput windows have a border width of zero or more pixels, an optional background, an event suppression mask (which suppresses propagation of events from children), and a property list (see section 4.3). The window border and background can be a solid color or a pattern, called a tile. All windows except the root have a parent and are clipped by their parent. If a window is stacked on top of another window, it obscures that other window for the purpose of input. 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:

If you specify any other attributes for an InputOnly window, a BadMatch error results.

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; and cannot be used in any graphics requests. Note that InputOnly windows cannot have InputOutput windows as inferiors.

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. 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. Instead, either your program should use the space given to it, or if the space is too small for any useful work, your program might ask the user to resize the window. The border of your top-level window is considered fair game for window managers.

To set an attribute of a window, set the appropriate member of the XSetWindowAttributes structure and OR in the corresponding value bitmask in your subsequent calls to XCreateWindow and XChangeWindowAttributes, or use one of the other convenience functions that set the appropriate attribute. The symbols for the value mask bits and the XSetWindowAttributes structure are: __ │

/* Window attribute value mask bits */

#de-
fine
CWBackPixmap
(1L<<0)

#de-
fine
CWBackPixel
(1L<<1)

#de-
fine
CWBorderPixmap
(1L<<2)

#de-
fine
CWBorderPixel
(1L<<3)

#de-
fine
CWBitGravity
(1L<<4)

#de-
fine
CWWinGravity
(1L<<5)

#de-
fine
CWBackingStore
(1L<<6)

#de-
fine
CWBackingPlanes
(1L<<7)

#de-
fine
CWBackingPixel
(1L<<8)

#de-
fine
CWOverrideRedirect
(1L<<9)

#de-
fine
CWSaveUnder
(1L<<10)

#de-
fine
CWEventMask
(1L<<11)

#de-
fine
CWDontPropagate
(1L<<12)

#de-
fine
CWColormap
(1L<<13)

#de-
fine
CWCursor
(1L<<14)

/* Values */

typedef struct {

} XSetWindowAttributes; │__

The following lists the defaults for each window attribute and indicates whether the attribute is applicable to InputOutput and InputOnly windows:
Attribute
Default
InputOutput
InputOnly
background-pixmap
None
Yes
No
background-pixel Undefined Yes No
border-pixmap
CopyFromParent
Yes
No
border-pixel Undefined Yes No
bit-gravity
ForgetGravity
Yes
No
win-gravity
NorthWestGravity
Yes
Yes
backing-store
NotUseful
Yes
No
backing-planes All ones Yes No
backing-pixel zero Yes No
save-under
False
Yes
No
event-mask empty set Yes Yes
do-not-propagate-mask empty set Yes Yes
override-redirect
False
Yes
Yes
colormap
CopyFromParent
Yes
No
cursor
None
Yes
Yes

3.2.1. Background Attribute

Only InputOutput windows can have a background. You can set the background of an InputOutput window by using a pixel or a pixmap.

The background-pixmap attribute of a window specifies the pixmap to be used for a window’s background. This pixmap can be of any size, although some sizes may be faster than others. The background-pixel attribute of a window specifies a pixel value used to paint a window’s background in a single color.

You can set the background-pixmap to a pixmap, None (default), or ParentRelative. You can set the background-pixel of a window to any pixel value (no default). If you specify a background-pixel, it overrides either the default background-pixmap or any value you may have set in the background-pixmap. A pixmap of an undefined size that is filled with the background-pixel is used for the background. Range checking is not performed on the background pixel; it simply is truncated to the appropriate number of bits.

If you set the background-pixmap, it overrides the default. The background-pixmap and the window must have the same depth, or a BadMatch error results. If you set background-pixmap to None, the window has no defined background. If you set the background-pixmap to ParentRelative:

Setting a new background, whether by setting background-pixmap or background-pixel, overrides any previous background. The background-pixmap can be freed immediately if no further explicit reference is made to it (the X server will keep a copy to use when needed). If you later draw into the pixmap used for the background, what happens is undefined because the X implementation is free to make a copy of the pixmap or to use the same pixmap.

When no valid contents are available for regions of a window and either the regions are visible or the server is maintaining backing store, the server automatically tiles the regions with the window’s background unless the window has a background of None. If the background is None, the previous screen contents from other windows of the same depth as the window are simply left in place as long as the contents come from the parent of the window or an inferior of the parent. Otherwise, the initial contents of the exposed regions are undefined. Expose events are then generated for the regions, even if the background-pixmap is None (see section 10.9).

3.2.2. Border Attribute

Only InputOutput windows can have a border. You can set the border of an InputOutput window by using a pixel or a pixmap.

The border-pixmap attribute of a window specifies the pixmap to be used for a window’s border. The border-pixel attribute of a window specifies a pixmap of undefined size filled with that pixel be used for a window’s border. Range checking is not performed on the background pixel; it simply is truncated to the appropriate number of bits. 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. However, the child window must have the same depth as the parent window, or a BadMatch error results.

The border-pixmap can be freed immediately if no further explicit reference is made to it. If you later draw into the pixmap used for the border, what happens is undefined because the X implementation is free either to make a copy of the pixmap or to use the same pixmap. If you specify a border-pixel, it overrides either the default border-pixmap or any value you may have set in the border-pixmap. All pixels in the window’s border will be set to the border-pixel. Setting a new border, whether by setting border-pixel or by setting border-pixmap, overrides any previous border.

Output to a window is always clipped to the inside of the window. Therefore, graphics operations never affect the window border.

3.2.3. Gravity Attributes

The bit gravity of a window defines which region of the window should be retained when an InputOutput window is resized. The default value for the bit-gravity attribute is ForgetGravity. The window gravity of a window allows you to define how the InputOutput or InputOnly window should be repositioned if its parent is resized. The default value for the win-gravity attribute is NorthWestGravity.

If the inside width or height of a window is not changed and if the window is moved or its border is changed, then the contents of the window are not lost but move with the window. Changing the inside width or height of the window causes its contents to be moved or lost (depending on the bit-gravity of the window) and causes children to be reconfigured (depending on their win-gravity). For a change of width and height, the (x, y) pairs are defined:
Gravity Direction Coordinates
NorthWestGravity
(0, 0)
NorthGravity
(Width/2, 0)
NorthEastGravity
(Width, 0)
WestGravity
(0, Height/2)
CenterGravity
(Width/2, Height/2)
EastGravity
(Width, Height/2)
SouthWestGravity
(0, Height)
SouthGravity
(Width/2, Height)
SouthEastGravity
(Width, Height)

When a window with one of these bit-gravity values is resized, the corresponding pair defines the change in position of each pixel in the window. When a window with one of these win-gravities has its parent window resized, the corresponding pair defines the change in position of the window within the parent. When a window is so repositioned, a GravityNotify event is generated (see section 10.10.5).

A bit-gravity of StaticGravity indicates that the contents or origin should not move relative to the origin of the root window. If the change in size of the window is coupled with a change in position (x, y), then for bit-gravity the change in position of each pixel is (−x, −y), and for win-gravity the change in position of a child when its parent is so resized is (−x, −y). Note that StaticGravity still only takes effect when the width or height of the window is changed, not when the window is moved.

A bit-gravity of ForgetGravity indicates that the window’s contents are always discarded after a size change, even if a backing store or save under has been requested. The window is tiled with its background and zero or more Expose events are generated. If no background is defined, the existing screen contents are not altered. Some X servers may also ignore the specified bit-gravity and always generate Expose events.

The contents and borders of inferiors are not affected by their parent’s bit-gravity. A server is permitted to ignore the specified bit-gravity and use Forget instead.

A win-gravity of UnmapGravity is like NorthWestGravity (the window is not moved), except the child is also unmapped when the parent is resized, and an UnmapNotify event is generated.

3.2.4. Backing Store Attribute

Some implementations of the X server may choose to maintain the contents of InputOutput windows. If the X server maintains the contents of a window, the off-screen saved pixels are known as backing store. The backing store advises the X server on what to do with the contents of a window. The backing-store attribute can be set to NotUseful (default), WhenMapped, or Always.

A backing-store attribute of NotUseful advises the X server that maintaining contents is unnecessary, although some X implementations may still choose to maintain contents and, therefore, not generate Expose events. A backing-store attribute of WhenMapped advises the X server that maintaining contents of obscured regions when the window is mapped would be beneficial. In this case, the server may generate an Expose event when the window is created. A backing-store attribute of Always advises the X server that maintaining contents even when the window is unmapped would be beneficial. Even if the window is larger than its parent, this is a request to the X server to maintain complete contents, not just the region within the parent window boundaries. While the X server maintains the window’s contents, Expose events normally are not generated, but the X server may stop maintaining contents at any time.

When the contents of obscured regions of a window are being maintained, regions obscured by noninferior windows are included in the destination of graphics requests (and source, when the window is the source). However, regions obscured by inferior windows are not included.

3.2.5. Save Under Flag

Some server implementations may preserve contents of InputOutput windows under other InputOutput windows. This is not the same as preserving the contents of a window for you. You may get better visual appeal if transient windows (for example, pop-up menus) request that the system preserve the screen contents under them, so the temporarily obscured applications do not have to repaint.

You can set the save-under flag to True or False (default). If save-under is True, the X server is advised that, when this window is mapped, saving the contents of windows it obscures would be beneficial.

3.2.6. Backing Planes and Backing Pixel Attributes

You can set backing planes to indicate (with bits set to 1) which bit planes of an InputOutput window hold dynamic data that must be preserved in backing store and during save unders. The default value for the backing-planes attribute is all bits set to 1. You can set backing pixel to specify what bits to use in planes not covered by backing planes. The default value for the backing-pixel attribute is all bits set to 0. The X server is free to save only the specified bit planes in the backing store or the save under and is free to regenerate the remaining planes with the specified pixel value. Any extraneous bits in these values (that is, those bits beyond the specified depth of the window) may be simply ignored. If you request backing store or save unders, you should use these members to minimize the amount of off-screen memory required to store your window.

3.2.7. Event Mask and Do Not Propagate Mask Attributes

The event mask defines which events the client is interested in for this InputOutput or InputOnly window (or, for some event types, inferiors of this window). The event mask is the bitwise inclusive OR of zero or more of the valid event mask bits. You can specify that no maskable events are reported by setting NoEventMask (default).

The do-not-propagate-mask attribute defines which events should not be propagated to ancestor windows when no client has the event type selected in this InputOutput or InputOnly window. The do-not-propagate-mask is the bitwise inclusive OR of zero or more of the following masks: KeyPress, KeyRelease, ButtonPress, ButtonRelease, PointerMotion, Button1Motion, Button2Motion, Button3Motion, Button4Motion, Button5Motion, and ButtonMotion. You can specify that all events are propagated by setting NoEventMask (default).

3.2.8. Override Redirect Flag

To control window placement or to add decoration, a window manager often needs to intercept (redirect) any map or configure request. Pop-up windows, however, often need to be mapped without a window manager getting in the way. To control whether an InputOutput or InputOnly window is to ignore these structure control facilities, use the override-redirect flag.

The override-redirect flag specifies whether map and configure requests on this window should override a SubstructureRedirectMask on the parent. You can set the override-redirect flag to True or False (default). Window managers use this information to avoid tampering with pop-up windows (see also chapter 14).

3.2.9. Colormap Attribute

The colormap attribute specifies which colormap best reflects the true colors of the InputOutput window. The colormap must have the same visual type as the window, or a BadMatch error results. X servers capable of supporting multiple hardware colormaps can use this information, and window managers can use it for calls to XInstallColormap. You can set the colormap attribute to a colormap or to CopyFromParent (default).

If you set the colormap to CopyFromParent, the parent window’s colormap is copied and used by its child. However, the child window must have the same visual type as the parent, or a BadMatch error results. The parent window must not have a colormap of None, or a BadMatch error results. The colormap is copied by sharing the colormap object between the child and parent, not by making a complete copy of the colormap contents. Subsequent changes to the parent window’s colormap attribute do not affect the child window.

3.2.10. Cursor Attribute

The cursor attribute specifies which cursor is to be used when the pointer is in the InputOutput or InputOnly window. You can set the cursor to a cursor or None (default).

If you set the cursor to None, the parent’s cursor is used when the pointer is in the InputOutput or InputOnly window, and any change in the parent’s cursor will cause an immediate change in the displayed cursor. By calling XFreeCursor, the cursor can be freed immediately as long as no further explicit reference to it is made.

3.3. Creating Windows

Xlib provides basic ways for creating windows, and toolkits often supply higher-level functions specifically for creating and placing top-level windows, which are discussed in the appropriate toolkit documentation. If you do not use a toolkit, however, you must provide some standard information or hints for the window manager by using the Xlib inter-client communication functions (see chapter 14).

If you use Xlib to create your own top-level windows (direct children of the root window), you must observe the following rules so that all applications interact reasonably across the different styles of window management:

For further information, see chapter 14 and the Inter-Client Communication Conventions Manual.

XCreateWindow is the more general function that allows you to set specific window attributes when you create a window. XCreateSimpleWindow creates a window that inherits its attributes from its parent window.

The X server acts as if InputOnly windows do not exist for the purposes of graphics requests, exposure processing, and VisibilityNotify events. An InputOnly window cannot be used as a drawable (that is, as a source or destination for graphics requests). InputOnly and InputOutput windows act identically in other respects (properties, grabs, input control, and so on). Extension packages can define other classes of windows.

To create an unmapped window and set its window attributes, use XCreateWindow. __ │

Window XCreateWindow(display, parent, x, y, width, height, border_width, depth,
class, visual, valuemask, attributes)
Display *display;
Window parent;
int x, y;
unsigned int width, height;
unsigned int border_width;
int depth;
unsigned int class;
Visual *visual;
unsigned long valuemask;
XSetWindowAttributes *attributes;

top-left outside corner of the created window’s
borders and are relative to the inside of the par-
ent window’s borders.

ed window’s inside dimensions and do not include
the created window’s borders. The dimensions must
be nonzero, or a BadValue error results.

border_width
Specifies the width of the created window’s border
in pixels.

FromParent means the depth is taken from the par-
ent.

pass InputOutput, InputOnly, or CopyFromParent. A
class of CopyFromParent means the class is taken
from the parent.

FromParent means the visual type is taken from the
parent.

the attributes argument. This mask is the bitwise
inclusive OR of the valid attribute mask bits. If
valuemask is zero, the attributes are ignored and
are not referenced.

attributesSpecifies the structure from which the values (as
specified by the value mask) are to be taken. The
value mask should have the appropriate bits set to
indicate which attributes have been set in the
structure. │__

The XCreateWindow function creates an unmapped subwindow for a specified parent window, returns the window ID of the created window, and causes the X server to generate a CreateNotify event. The created window is placed on top in the stacking order with respect to siblings.

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. Each window and pixmap has its own coordinate system. For a window, the origin is inside the border at the inside, upper-left corner.

The border_width for an InputOnly window must be zero, or a BadMatch error results. For class InputOutput, the visual type and depth must be a combination supported for the screen, or a BadMatch error results. The depth need not be the same as the parent, but the parent must not be a window of class InputOnly, or a BadMatch error results. For an InputOnly window, the depth must be zero, and the visual must be one supported by the screen. If either condition is not met, a BadMatch error results. The parent window, however, may have any depth and class. If you specify any invalid window attribute for a window, a BadMatch error results.

The created window is not yet displayed (mapped) on the user’s display. To display the window, call XMapWindow. The new window initially uses the same cursor as its parent. A new cursor can be defined for the new window by calling XDefineCursor. The window will not be visible on the screen unless it and all of its ancestors are mapped and it is not obscured by any of its ancestors.

XCreateWindow can generate BadAlloc, BadColor, BadCursor, BadMatch, BadPixmap, BadValue, and BadWindow errors.

To create an unmapped InputOutput subwindow of a given parent window, use XCreateSimpleWindow. __ │

Window XCreateSimpleWindow(display, parent, x, y, width, height, border_width,
border, background)
Display *display;
Window parent;
int x, y;
unsigned int width, height;
unsigned int border_width;
unsigned long border;
unsigned long background;

top-left outside corner of the new window’s bor-
ders and are relative to the inside of the parent
window’s borders.

ed window’s inside dimensions and do not include
the created window’s borders. The dimensions must
be nonzero, or a BadValue error results.

border_width
Specifies the width of the created window’s border
in pixels.

backgroundSpecifies the background pixel value of the win-
dow. │__

The XCreateSimpleWindow function creates an unmapped InputOutput subwindow for a specified parent window, returns the window ID of the created window, and causes the X server to generate a CreateNotify event. The created window is placed on top in the stacking order with respect to siblings. Any part of the window that extends outside its parent window is clipped. The border_width for an InputOnly window must be zero, or a BadMatch error results. XCreateSimpleWindow inherits its depth, class, and visual from its parent. All other window attributes, except background and border, have their default values.

XCreateSimpleWindow can generate BadAlloc, BadMatch, BadValue, and BadWindow errors.

3.4. Destroying Windows

Xlib provides functions that you can use to destroy a window or destroy all subwindows of a window.

To destroy a window and all of its subwindows, use XDestroyWindow. __ │

XDestroyWindow(display, w)
Display *display;
Window w;

The XDestroyWindow function destroys the specified window as well as all of its subwindows and causes the X server to generate a DestroyNotify event for each window. The window should never be referenced again. If the window specified by the w argument is mapped, it is unmapped automatically. The ordering of the DestroyNotify events is such that for any given window being destroyed, DestroyNotify is generated on any inferiors of the window before being generated on the window itself. The ordering among siblings and across subhierarchies is not otherwise constrained. If the window you specified is a root window, no windows are destroyed. Destroying a mapped window will generate Expose events on other windows that were obscured by the window being destroyed.

XDestroyWindow can generate a BadWindow error.

To destroy all subwindows of a specified window, use XDestroySubwindows. __ │

XDestroySubwindows(display, w)
Display *display;
Window w;

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. The subwindows should never be referenced again.

XDestroySubwindows can generate a BadWindow error.

3.5. Mapping Windows

A window is considered mapped if an XMapWindow call has been made on it. It may not be visible on the screen for one of the following reasons:

Expose events are generated for the window when part or all of it becomes visible on the screen. A client receives the Expose events only if it has asked for them. Windows retain their position in the stacking order when they are unmapped.

A window manager may want to control the placement of subwindows. If SubstructureRedirectMask has been selected by a window manager on a parent window (usually a root window), a map request initiated by other clients on a child window is not performed, and the window manager is sent a MapRequest event. However, if the override-redirect flag on the child had been set to True (usually only on pop-up menus), the map request is performed.

A tiling window manager might decide to reposition and resize other clients’ windows and then decide to map the window to its final location. A window manager that wants to provide decoration might reparent the child into a frame first. For further information, see sections 3.2.8 and 10.10. Only a single client at a time can select for SubstructureRedirectMask.

Similarly, a single client can select for ResizeRedirectMask on a parent window. Then, any attempt to resize the window by another client is suppressed, and the client receives a ResizeRequest event.

To map a given window, use XMapWindow. __ │

XMapWindow(display, w)
Display *display;
Window w;

The XMapWindow function maps the window and all of its subwindows that have had map requests. Mapping a window that has an unmapped ancestor does not display the window but marks it as eligible for display when the ancestor becomes mapped. Such a window is called unviewable. When all its ancestors are mapped, the window becomes viewable and will be visible on the screen if it is not obscured by another window. This function has no effect if the window is already mapped.

If the override-redirect of the window is False and if some other client has selected SubstructureRedirectMask on the parent window, then the X server generates a MapRequest event, and the XMapWindow function does not map the window. Otherwise, the window is mapped, and the X server generates a MapNotify event.

If the window becomes viewable and no earlier contents for it are remembered, the X server tiles the window with its background. If the window’s background is undefined, the existing screen contents are not altered, and the X server generates zero or more Expose events. If backing-store was maintained while the window was unmapped, no Expose events are generated. If backing-store will now be maintained, a full-window exposure is always generated. Otherwise, only visible regions may be reported. Similar tiling and exposure take place for any newly viewable inferiors.

If the window is an InputOutput window, XMapWindow generates Expose events on each InputOutput window that it causes to be displayed. If the client maps and paints the window and if the client begins processing events, the window is painted twice. To avoid this, first ask for Expose events and then map the window, so the client processes input events as usual. The event list will include Expose for each window that has appeared on the screen. The client’s normal response to an Expose event should be to repaint the window. This method usually leads to simpler programs and to proper interaction with window managers.

XMapWindow can generate a BadWindow error.

To map and raise a window, use XMapRaised. __ │

XMapRaised(display, w)
Display *display;
Window w;

The XMapRaised function essentially is similar to XMapWindow in that it maps the window and all of its subwindows that have had map requests. However, it also raises the specified window to the top of the stack. For additional information, see XMapWindow.

XMapRaised can generate multiple BadWindow errors.

To map all subwindows for a specified window, use XMapSubwindows. __ │

XMapSubwindows(display, w)
Display *display;
Window w;

The XMapSubwindows function maps all subwindows for a specified window in top-to-bottom stacking order. The X server generates Expose events on each newly displayed window. This may be much more efficient than mapping many windows one at a time because the server needs to perform much of the work only once, for all of the windows, rather than for each window.

XMapSubwindows can generate a BadWindow error.

3.6. Unmapping Windows

Xlib provides functions that you can use to unmap a window or all subwindows.

To unmap a window, use XUnmapWindow. __ │

XUnmapWindow(display, w)
Display *display;
Window w;

The XUnmapWindow function unmaps the specified window and causes the X server to generate an UnmapNotify event. If the specified window is already unmapped, XUnmapWindow has no effect. Normal exposure processing on formerly obscured windows is performed. Any child window will no longer be visible until another map call is made on the parent. In other words, the subwindows are still mapped but are not visible until the parent is mapped. Unmapping a window will generate Expose events on windows that were formerly obscured by it.

XUnmapWindow can generate a BadWindow error.

To unmap all subwindows for a specified window, use XUnmapSubwindows. __ │

XUnmapSubwindows(display, w)
Display *display;
Window w;

The XUnmapSubwindows function unmaps all subwindows for the specified window in bottom-to-top stacking order. It causes the X server to generate an UnmapNotify event on each subwindow and Expose events on formerly obscured windows. Using this function is much more efficient than unmapping multiple windows one at a time because the server needs to perform much of the work only once, for all of the windows, rather than for each window.

XUnmapSubwindows can generate a BadWindow error.

3.7. Configuring Windows

Xlib provides functions that you can use to move a window, resize a window, move and resize a window, or change a window’s border width. To change one of these parameters, set the appropriate member of the XWindowChanges structure and OR in the corresponding value mask in subsequent calls to XConfigureWindow. The symbols for the value mask bits and the XWindowChanges structure are: __ │

/* Configure window value mask bits */

#de-
fine
CWX
(1<<0)

#de-
fine
CWY
(1<<1)

#de-
fine
CWWidth
(1<<2)

#de-
fine
CWHeight
(1<<3)

#de-
fine
CWBorderWidth
(1<<4)

#de-
fine
CWSibling
(1<<5)

#de-
fine
CWStackMode
(1<<6)

/* Values */

typedef struct {

} XWindowChanges; │__

The x and y members are used to set the window’s x and y coordinates, which are relative to the parent’s origin and indicate the position of the upper-left outer corner of the window. The width and height members are used to set the inside size of the window, not including the border, and must be nonzero, or a BadValue error results. Attempts to configure a root window have no effect.

The border_width member is used to set the width of the border in pixels. Note that setting just the border width leaves the outer-left corner of the window in a fixed position but moves the absolute position of the window’s origin. If you attempt to set the border-width attribute of an InputOnly window nonzero, a BadMatch error results.

The sibling member is used to set the sibling window for stacking operations. The stack_mode member is used to set how the window is to be restacked and can be set to Above, Below, TopIf, BottomIf, or Opposite.

If the override-redirect flag of the window is False and if some other client has selected SubstructureRedirectMask on the parent, the X server generates a ConfigureRequest event, and no further processing is performed. Otherwise, if some other client has selected ResizeRedirectMask on the window and the inside width or height of the window is being changed, a ResizeRequest event is generated, and the current inside width and height are used instead. Note that the override-redirect flag of the window has no effect on ResizeRedirectMask and that SubstructureRedirectMask on the parent has precedence over ResizeRedirectMask on the window.

When the geometry of the window is changed as specified, the window is restacked among siblings, and a ConfigureNotify event is generated if the state of the window actually changes. GravityNotify events are generated after ConfigureNotify events. If the inside width or height of the window has actually changed, children of the window are affected as specified.

If a window’s size actually changes, the window’s subwindows move according to their window gravity. Depending on the window’s bit gravity, the contents of the window also may be moved (see section 3.2.3).

If regions of the window were obscured but now are not, exposure processing is performed on these formerly obscured windows, including the window itself and its inferiors. As a result of increasing the width or height, exposure processing is also performed on any new regions of the window and any regions where window contents are lost.

The restack check (specifically, the computation for BottomIf, TopIf, and Opposite) is performed with respect to the window’s final size and position (as controlled by the other arguments of the request), not its initial position. If a sibling is specified without a stack_mode, a BadMatch error results.

If a sibling and a stack_mode are specified, the window is restacked as follows:
Above
The window is placed just above the sibling.
Below
The window is placed just below the sibling.
TopIf
If the sibling occludes the window, the window is
placed at the top of the stack.
BottomIf
If the window occludes the sibling, the window is
placed at the bottom of the stack.
Opposite
If the sibling occludes the window, the window is
placed at the top of the stack. If the window
occludes the sibling, the window is placed at the
bottom of the stack.

If a stack_mode is specified but no sibling is specified, the window is restacked as follows:
Above
The window is placed at the top of the stack.
Below
The window is placed at the bottom of the stack.
TopIf
If any sibling occludes the window, the window is
placed at the top of the stack.
BottomIf
If the window occludes any sibling, the window is
placed at the bottom of the stack.
Opposite
If any sibling occludes the window, the window is
placed at the top of the stack. If the window
occludes any sibling, the window is placed at the
bottom of the stack.

Attempts to configure a root window have no effect.

To configure a window’s size, location, stacking, or border, use XConfigureWindow. __ │

XConfigureWindow(display, w, value_mask, values)
Display *display;
Window w;
unsigned int value_mask;
XWindowChanges *values;

value_maskSpecifies which values are to be set using infor-
mation in the values structure. This mask is the
bitwise inclusive OR of the valid configure window
values bits.

The XConfigureWindow function uses the values specified in the XWindowChanges structure to reconfigure a window’s size, position, border, and stacking order. Values not specified are taken from the existing geometry of the window.

If a sibling is specified without a stack_mode or if the window is not actually a sibling, a BadMatch error results. Note that the computations for BottomIf, TopIf, and Opposite are performed with respect to the window’s final geometry (as controlled by the other arguments passed to XConfigureWindow), not its initial geometry. Any backing store contents of the window, its inferiors, and other newly visible windows are either discarded or changed to reflect the current screen contents (depending on the implementation).

XConfigureWindow can generate BadMatch, BadValue, and BadWindow errors.

To move a window without changing its size, use XMoveWindow. __ │

XMoveWindow(display, w, x, y)
Display *display;
Window w;
int x, y;

new location of the top-left pixel of the window’s
border or the window itself if it has no border. │__

The XMoveWindow function moves the specified window to the specified x and y coordinates, but it does not change the window’s size, raise the window, or change the mapping state of the window. Moving a mapped window may or may not lose the window’s contents depending on if the window is obscured by nonchildren and if no backing store exists. If the contents of the window are lost, the X server generates Expose events. Moving a mapped window generates Expose events on any formerly obscured windows.

If the override-redirect flag of the window is False and some other client has selected SubstructureRedirectMask on the parent, the X server generates a ConfigureRequest event, and no further processing is performed. Otherwise, the window is moved.

XMoveWindow can generate a BadWindow error.

To change a window’s size without changing the upper-left coordinate, use XResizeWindow. __ │

XResizeWindow(display, w, width, height)
Display *display;
Window w;
unsigned int width, height;

rior dimensions of the window after the call com-
pletes. │__

The XResizeWindow function changes the inside dimensions of the specified window, not including its borders. This function does not change the window’s upper-left coordinate or the origin and does not restack the window. Changing the size of a mapped window may lose its contents and generate Expose events. If a mapped window is made smaller, changing its size generates Expose events on windows that the mapped window formerly obscured.

If the override-redirect flag of the window is False and some other client has selected SubstructureRedirectMask on the parent, the X server generates a ConfigureRequest event, and no further processing is performed. If either width or height is zero, a BadValue error results.

XResizeWindow can generate BadValue and BadWindow errors.

To change the size and location of a window, use XMoveResizeWindow. __ │

XMoveResizeWindow(display, w, x, y, width, height)
Display *display;
Window w;
int x, y;
unsigned int width, height;

new position of the window relative to its parent.

terior size of the window. │__

The XMoveResizeWindow function changes the size and location of the specified window without raising it. Moving and resizing a mapped window may generate an Expose event on the window. Depending on the new size and location parameters, moving and resizing a window may generate Expose events on windows that the window formerly obscured.

If the override-redirect flag of the window is False and some other client has selected SubstructureRedirectMask on the parent, the X server generates a ConfigureRequest event, and no further processing is performed. Otherwise, the window size and location are changed.

XMoveResizeWindow can generate BadValue and BadWindow errors.

To change the border width of a given window, use XSetWindowBorderWidth. __ │

XSetWindowBorderWidth(display, w, width)
Display *display;
Window w;
unsigned int width;

The XSetWindowBorderWidth function sets the specified window’s border width to the specified width.

XSetWindowBorderWidth can generate a BadWindow error.

3.8. Changing Window Stacking Order

Xlib provides functions that you can use to raise, lower, circulate, or restack windows.

To raise a window so that no sibling window obscures it, use XRaiseWindow. __ │

XRaiseWindow(display, w)
Display *display;
Window w;

The XRaiseWindow function raises the specified window to the top of the stack so that no sibling window obscures it. If the windows are regarded as overlapping sheets of paper stacked on a desk, then raising a window is analogous to moving the sheet to the top of the stack but leaving its x and y location on the desk constant. Raising a mapped window may generate Expose events for the window and any mapped subwindows that were formerly obscured.

If the override-redirect attribute of the window is False and some other client has selected SubstructureRedirectMask on the parent, the X server generates a ConfigureRequest event, and no processing is performed. Otherwise, the window is raised.

XRaiseWindow can generate a BadWindow error.

To lower a window so that it does not obscure any sibling windows, use XLowerWindow. __ │

XLowerWindow(display, w)
Display *display;
Window w;

The XLowerWindow function lowers the specified window to the bottom of the stack so that it does not obscure any sibling windows. If the windows are regarded as overlapping sheets of paper stacked on a desk, then lowering a window is analogous to moving the sheet to the bottom of the stack but leaving its x and y location on the desk constant. Lowering a mapped window will generate Expose events on any windows it formerly obscured.

If the override-redirect attribute of the window is False and some other client has selected SubstructureRedirectMask on the parent, the X server generates a ConfigureRequest event, and no processing is performed. Otherwise, the window is lowered to the bottom of the stack.

XLowerWindow can generate a BadWindow error.

To circulate a subwindow up or down, use XCirculateSubwindows. __ │

XCirculateSubwindows(display, w, direction)
Display *display;
Window w;
int direction;

to circulate the window. You can pass RaiseLowest
or LowerHighest. │__

The XCirculateSubwindows function circulates children of the specified window in the specified direction. If you specify RaiseLowest, XCirculateSubwindows raises the lowest mapped child (if any) that is occluded by another child to the top of the stack. If you specify LowerHighest, XCirculateSubwindows lowers the highest mapped child (if any) that occludes another child to the bottom of the stack. Exposure processing is then performed on formerly obscured windows. If some other client has selected SubstructureRedirectMask on the window, the X server generates a CirculateRequest event, and no further processing is performed. If a child is actually restacked, the X server generates a CirculateNotify event.

XCirculateSubwindows can generate BadValue and BadWindow errors.

To raise the lowest mapped child of a window that is partially or completely occluded by another child, use XCirculateSubwindowsUp. __ │

XCirculateSubwindowsUp(display, w)
Display *display;
Window w;

The XCirculateSubwindowsUp function raises the lowest mapped child of the specified window that is partially or completely occluded by another child. Completely unobscured children are not affected. This is a convenience function equivalent to XCirculateSubwindows with RaiseLowest specified.

XCirculateSubwindowsUp can generate a BadWindow error.

To lower the highest mapped child of a window that partially or completely occludes another child, use XCirculateSubwindowsDown. __ │

XCirculateSubwindowsDown(display, w)
Display *display;
Window w;

The XCirculateSubwindowsDown function lowers the highest mapped child of the specified window that partially or completely occludes another child. Completely unobscured children are not affected. This is a convenience function equivalent to XCirculateSubwindows with LowerHighest specified.

XCirculateSubwindowsDown can generate a BadWindow error.

To restack a set of windows from top to bottom, use XRestackWindows. __ │

XRestackWindows(display, windows, nwindows);
Display *display;
Window windows[];
int nwindows;

restacked.

The XRestackWindows function restacks the windows in the order specified, from top to bottom. The stacking order of the first window in the windows array is unaffected, but the other windows in the array are stacked underneath the first window, in the order of the array. The stacking order of the other windows is not affected. For each window in the window array that is not a child of the specified window, a BadMatch error results.

If the override-redirect attribute of a window is False and some other client has selected SubstructureRedirectMask on the parent, the X server generates ConfigureRequest events for each window whose override-redirect flag is not set, and no further processing is performed. Otherwise, the windows will be restacked in top-to-bottom order.

XRestackWindows can generate a BadWindow error.

3.9. Changing Window Attributes

Xlib provides functions that you can use to set window attributes. XChangeWindowAttributes is the more general function that allows you to set one or more window attributes provided by the XSetWindowAttributes structure. The other functions described in this section allow you to set one specific window attribute, such as a window’s background.

To change one or more attributes for a given window, use XChangeWindowAttributes. __ │

XChangeWindowAttributes(display, w, valuemask, attributes)
Display *display;
Window w;
unsigned long valuemask;
XSetWindowAttributes *attributes;

the attributes argument. This mask is the bitwise
inclusive OR of the valid attribute mask bits. If
valuemask is zero, the attributes are ignored and
are not referenced. The values and restrictions
are the same as for XCreateWindow.

attributesSpecifies the structure from which the values (as
specified by the value mask) are to be taken. The
value mask should have the appropriate bits set to
indicate which attributes have been set in the
structure (see section 3.2). │__

Depending on the valuemask, the XChangeWindowAttributes function uses the window attributes in the XSetWindowAttributes structure to change the specified window attributes. Changing the background does not cause the window contents to be changed. To repaint the window and its background, use XClearWindow. Setting the border or changing the background such that the border tile origin changes causes the border to be repainted. Changing the background of a root window to None or ParentRelative restores the default background pixmap. Changing the border of a root window to CopyFromParent restores the default border pixmap. Changing the win-gravity does not affect the current position of the window. Changing the backing-store of an obscured window to WhenMapped or Always, or changing the backing-planes, backing-pixel, or save-under of a mapped window may have no immediate effect. Changing the colormap of a window (that is, defining a new map, not changing the contents of the existing map) generates a ColormapNotify event. Changing the colormap of a visible window may have no immediate effect on the screen because the map may not be installed (see XInstallColormap). Changing the cursor of a root window to None restores the default cursor. Whenever possible, you are encouraged to share colormaps.

Multiple clients can select input on the same window. Their event masks are maintained separately. When an event is generated, it is reported to all interested clients. However, only one client at a time can select for SubstructureRedirectMask, ResizeRedirectMask, and ButtonPressMask. If a client attempts to select any of these event masks and some other client has already selected one, a BadAccess error results. There is only one do-not-propagate-mask for a window, not one per client.

XChangeWindowAttributes can generate BadAccess, BadColor, BadCursor, BadMatch, BadPixmap, BadValue, and BadWindow errors.

To set the background of a window to a given pixel, use XSetWindowBackground. __ │

XSetWindowBackground(display, w, background_pixel)
Display *display;
Window w;
unsigned long background_pixel;

background_pixel
Specifies the pixel that is to be used for the
background. │__

The XSetWindowBackground function sets the background of the window to the specified pixel value. Changing the background does not cause the window contents to be changed. XSetWindowBackground uses a pixmap of undefined size filled with the pixel value you passed. If you try to change the background of an InputOnly window, a BadMatch error results.

XSetWindowBackground can generate BadMatch and BadWindow errors.

To set the background of a window to a given pixmap, use XSetWindowBackgroundPixmap. __ │

XSetWindowBackgroundPixmap(display, w, background_pixmap)
Display *display;
Window w;
Pixmap background_pixmap;

background_pixmap
Specifies the background pixmap, ParentRelative,
or None. │__

The XSetWindowBackgroundPixmap function sets the background pixmap of the window to the specified pixmap. The background pixmap can immediately be freed if no further explicit references to it are to be made. If ParentRelative is specified, the background pixmap of the window’s parent is used, or on the root window, the default background is restored. If you try to change the background of an InputOnly window, a BadMatch error results. If the background is set to None, the window has no defined background.

XSetWindowBackgroundPixmap can generate BadMatch, BadPixmap, and BadWindow errors.

Note

XSetWindowBackground and XSetWindowBackgroundPixmap do not change the current contents of the window.

To change and repaint a window’s border to a given pixel, use XSetWindowBorder. __ │

XSetWindowBorder(display, w, border_pixel)
Display *display;
Window w;
unsigned long border_pixel;

border_pixel
Specifies the entry in the colormap. │__

The XSetWindowBorder function sets the border of the window to the pixel value you specify. If you attempt to perform this on an InputOnly window, a BadMatch error results.

XSetWindowBorder can generate BadMatch and BadWindow errors.

To change and repaint the border tile of a given window, use XSetWindowBorderPixmap. __ │

XSetWindowBorderPixmap(display, w, border_pixmap)
Display *display;
Window w;
Pixmap border_pixmap;

border_pixmap
Specifies the border pixmap or CopyFromParent. │__

The XSetWindowBorderPixmap function sets the border pixmap of the window to the pixmap you specify. The border pixmap can be freed immediately if no further explicit references to it are to be made. If you specify CopyFromParent, a copy of the parent window’s border pixmap is used. If you attempt to perform this on an InputOnly window, a BadMatch error results.

XSetWindowBorderPixmap can generate BadMatch, BadPixmap, and BadWindow errors.

To set the colormap of a given window, use XSetWindowColormap. __ │

XSetWindowColormap(display, w, colormap)
Display *display;
Window w;
Colormap colormap;

The XSetWindowColormap function sets the specified colormap of the specified window. The colormap must have the same visual type as the window, or a BadMatch error results.

XSetWindowColormap can generate BadColor, BadMatch, and BadWindow errors.

To define which cursor will be used in a window, use XDefineCursor. __ │

XDefineCursor(display, w, cursor)
Display *display;
Window w;
Cursor cursor;

None. │__

If a cursor is set, it will be used when the pointer is in the window. If the cursor is None, it is equivalent to XUndefineCursor.

XDefineCursor can generate BadCursor and BadWindow errors.

To undefine the cursor in a given window, use XUndefineCursor. __ │

XUndefineCursor(display, w)
Display *display;
Window w;

The XUndefineCursor function undoes the effect of a previous XDefineCursor for this window. When the pointer is in the window, the parent’s cursor will now be used. On the root window, the default cursor is restored.

XUndefineCursor can generate a BadWindow error.

3

Xlib − C Library libX11 1.3.2

Chapter 4

Window Information Functions

After you connect the display to the X server and create a window, you can use the Xlib window information functions to:

4.1. Obtaining Window Information

Xlib provides functions that you can use to obtain information about the window tree, the window’s current attributes, the window’s current geometry, or the current pointer coordinates. Because they are most frequently used by window managers, these functions all return a status to indicate whether the window still exists.

To obtain the parent, a list of children, and number of children for a given window, use XQueryTree. __ │

Status XQueryTree(display, w, root_return, parent_return, children_return, nchildren_return)
Display *display;
Window w;
Window *root_return;
Window *parent_return;
Window **children_return;
unsigned int *nchildren_return;

parent, and number of children you want to obtain.

root_returnReturns the root window.

parent_return
Returns the parent window.

children_return
Returns the list of children.

nchildren_return
Returns the number of children. │__

The XQueryTree function returns the root ID, the parent window ID, a pointer to the list of children windows (NULL when there are no children), and the number of children in the list for the specified window. The children are listed in current stacking order, from bottom-most (first) to top-most (last). XQueryTree returns zero if it fails and nonzero if it succeeds. To free a non-NULL children list when it is no longer needed, use XFree.

XQueryTree can generate a BadWindow error.

To obtain the current attributes of a given window, use XGetWindowAttributes. __ │

Status XGetWindowAttributes(display, w, window_attributes_return)
Display *display;
Window w;
XWindowAttributes *window_attributes_return;

want to obtain.

window_attributes_return
Returns the specified window’s attributes in the
XWindowAttributes structure. │__

The XGetWindowAttributes function returns the current attributes for the specified window to an XWindowAttributes structure. __ │

typedef struct {

} XWindowAttributes; │__

The x and y members are set to the upper-left outer corner relative to the parent window’s origin. The width and height members are set to the inside size of the window, not including the border. The border_width member is set to the window’s border width in pixels. The depth member is set to the depth of the window (that is, bits per pixel for the object). The visual member is a pointer to the screen’s associated Visual structure. The root member is set to the root window of the screen containing the window. The class member is set to the window’s class and can be either InputOutput or InputOnly.

The bit_gravity member is set to the window’s bit gravity and can be one of the following:
ForgetGravity
EastGravity
NorthWestGravity
SouthWestGravity
NorthGravity
SouthGravity
NorthEastGravity
SouthEastGravity
WestGravity
StaticGravity
CenterGravity

The win_gravity member is set to the window’s window gravity and can be one of the following:
UnmapGravity
EastGravity
NorthWestGravity
SouthWestGravity
NorthGravity
SouthGravity
NorthEastGravity
SouthEastGravity
WestGravity
StaticGravity
CenterGravity

For additional information on gravity, see section 3.2.3.

The backing_store member is set to indicate how the X server should maintain the contents of a window and can be WhenMapped, Always, or NotUseful. The backing_planes member is set to indicate (with bits set to 1) which bit planes of the window hold dynamic data that must be preserved in backing_stores and during save_unders. The backing_pixel member is set to indicate what values to use for planes not set in backing_planes.

The save_under member is set to True or False. The colormap member is set to the colormap for the specified window and can be a colormap ID or None. The map_installed member is set to indicate whether the colormap is currently installed and can be True or False. The map_state member is set to indicate the state of the window and can be IsUnmapped, IsUnviewable, or IsViewable. IsUnviewable is used if the window is mapped but some ancestor is unmapped.

The all_event_masks member is set to the bitwise inclusive OR of all event masks selected on the window by all clients. The your_event_mask member is set to the bitwise inclusive OR of all event masks selected by the querying client. The do_not_propagate_mask member is set to the bitwise inclusive OR of the set of events that should not propagate.

The override_redirect member is set to indicate whether this window overrides structure control facilities and can be True or False. Window manager clients should ignore the window if this member is True.

The screen member is set to a screen pointer that gives you a back pointer to the correct screen. This makes it easier to obtain the screen information without having to loop over the root window fields to see which field matches.

XGetWindowAttributes can generate BadDrawable and BadWindow errors.

To obtain the current geometry of a given drawable, use XGetGeometry. __ │

Status XGetGeometry(display, d, root_return, x_return, y_return, width_return,
height_return, border_width_return, depth_return)
Display *display;
Drawable d;
Window *root_return;
int *x_return, *y_return;
unsigned int *width_return, *height_return;
unsigned int *border_width_return;
unsigned int *depth_return;

pixmap.

root_returnReturns the root window.

cation of the drawable. For a window, these coor-
dinates specify the upper-left outer corner rela-
tive to its parent’s origin. For pixmaps, these
coordinates are always zero.

width_return
height_return
Return the drawable’s dimensions (width and
height). For a window, these dimensions specify
the inside size, not including the border.

border_width_return
Returns the border width in pixels. If the draw-
able is a pixmap, it returns zero.

depth_return
Returns the depth of the drawable (bits per pixel
for the object). │__

The XGetGeometry function returns the root window and the current geometry of the drawable. The geometry of the drawable includes the x and y coordinates, width and height, border width, and depth. These are described in the argument list. It is legal to pass to this function a window whose class is InputOnly.

XGetGeometry can generate a BadDrawable error.

4.2. Translating Screen Coordinates

Applications sometimes need to perform a coordinate transformation from the coordinate space of one window to another window or need to determine which window the pointing device is in. XTranslateCoordinates and XQueryPointer fulfill these needs (and avoid any race conditions) by asking the X server to perform these operations.

To translate a coordinate in one window to the coordinate space of another window, use XTranslateCoordinates. __ │

Bool XTranslateCoordinates(display, src_w, dest_w, src_x, src_y, dest_x_return,
dest_y_return, child_return)
Display *display;
Window src_w, dest_w;
int src_x, src_y;
int *dest_x_return, *dest_y_return;
Window *child_return;

window.

dest_x_return
dest_y_return
Return the x and y coordinates within the destina-
tion window.

child_return
Returns the child if the coordinates are contained
in a mapped child of the destination window. │__

If XTranslateCoordinates returns True, it takes the src_x and src_y coordinates relative to the source window’s origin and returns these coordinates to dest_x_return and dest_y_return relative to the destination window’s origin. If XTranslateCoordinates returns False, src_w and dest_w are on different screens, and dest_x_return and dest_y_return are zero. If the coordinates are contained in a mapped child of dest_w, that child is returned to child_return. Otherwise, child_return is set to None.

XTranslateCoordinates can generate a BadWindow error.

To obtain the screen coordinates of the pointer or to determine the pointer coordinates relative to a specified window, use XQueryPointer. __ │

Bool XQueryPointer(display, w, root_return, child_return, root_x_return, root_y_return,
win_x_return, win_y_return, mask_return)
Display *display;
Window w;
Window *root_return, *child_return;
int *root_x_return, *root_y_return;
int *win_x_return, *win_y_return;
unsigned int *mask_return;

root_returnReturns the root window that the pointer is in.

child_return
Returns the child window that the pointer is lo-
cated in, if any.

root_x_return
root_y_return
Return the pointer coordinates relative to the
root window’s origin.

win_x_return
win_y_return
Return the pointer coordinates relative to the
specified window.

mask_returnReturns the current state of the modifier keys
and pointer buttons. │__

The XQueryPointer function returns the root window the pointer is logically on and the pointer coordinates relative to the root window’s origin. If XQueryPointer returns False, the pointer is not on the same screen as the specified window, and XQueryPointer returns None to child_return and zero to win_x_return and win_y_return. If XQueryPointer returns True, the pointer coordinates returned to win_x_return and win_y_return are relative to the origin of the specified window. In this case, XQueryPointer returns the child that contains the pointer, if any, or else None to child_return.

XQueryPointer returns the current logical state of the keyboard buttons and the modifier keys in mask_return. It sets mask_return to the bitwise inclusive OR of one or more of the button or modifier key bitmasks to match the current state of the mouse buttons and the modifier keys.

Note that the logical state of a device (as seen through Xlib) may lag the physical state if device event processing is frozen (see section 12.1).

XQueryPointer can generate a BadWindow error.

4.3. Properties and Atoms

A property is a collection of named, typed data. The window system has a set of predefined properties (for example, the name of a window, size hints, and so on), and users can define any other arbitrary information and associate it with windows. Each property has a name, which is an ISO Latin-1 string. For each named property, a unique identifier (atom) is associated with it. A property also has a type, for example, string or integer. These types are also indicated using atoms, so arbitrary new types can be defined. Data of only one type may be associated with a single property name. Clients can store and retrieve properties associated with windows. For efficiency reasons, an atom is used rather than a character string. XInternAtom can be used to obtain the atom for property names.

A property is also stored in one of several possible formats. The X server can store the information as 8-bit quantities, 16-bit quantities, or 32-bit quantities. This permits the X server to present the data in the byte order that the client expects.

Note

If you define further properties of complex type, you must encode and decode them yourself. These functions must be carefully written if they are to be portable. For further information about how to write a library extension, see appendix C.

The type of a property is defined by an atom, which allows for arbitrary extension in this type scheme.

Certain property names are predefined in the server for commonly used functions. The atoms for these properties are defined in <X11/Xatom.h>. To avoid name clashes with user symbols, the #define name for each atom has the XA_ prefix. For an explanation of the functions that let you get and set much of the information stored in these predefined properties, see chapter 14.

The core protocol imposes no semantics on these property names, but semantics are specified in other X Consortium standards, such as the Inter-Client Communication Conventions Manual and the X Logical Font Description Conventions.

You can use properties to communicate other information between applications. The functions described in this section let you define new properties and get the unique atom IDs in your applications.

Although any particular atom can have some client interpretation within each of the name spaces, atoms occur in five distinct name spaces within the protocol:

The built-in selection property names are:

PRIMARY
SECONDARY

The built-in property names are:
CUT_BUFFER0 RESOURCE_MANAGER
CUT_BUFFER1 WM_CLASS
CUT_BUFFER2 WM_CLIENT_MACHINE
CUT_BUFFER3 WM_COLORMAP_WINDOWS
CUT_BUFFER4 WM_COMMAND
CUT_BUFFER5 WM_HINTS
CUT_BUFFER6 WM_ICON_NAME
CUT_BUFFER7 WM_ICON_SIZE
RGB_BEST_MAP WM_NAME
RGB_BLUE_MAP WM_NORMAL_HINTS
RGB_DEFAULT_MAP WM_PROTOCOLS
RGB_GRAY_MAP WM_STATE
RGB_GREEN_MAP WM_TRANSIENT_FOR
RGB_RED_MAP WM_ZOOM_HINTS

The built-in property types are:
ARC POINT
ATOM RGB_COLOR_MAP
BITMAP RECTANGLE
CARDINAL STRING
COLORMAP VISUALID
CURSOR WINDOW
DRAWABLE WM_HINTS
FONT WM_SIZE_HINTS
INTEGER
PIXMAP

The built-in font property names are:
MIN_SPACE STRIKEOUT_DESCENT
NORM_SPACE STRIKEOUT_ASCENT
MAX_SPACE ITALIC_ANGLE
END_SPACE X_HEIGHT
SUPERSCRIPT_X QUAD_WIDTH
SUPERSCRIPT_Y WEIGHT
SUBSCRIPT_X POINT_SIZE
SUBSCRIPT_Y RESOLUTION
UNDERLINE_POSITION COPYRIGHT
UNDERLINE_THICKNESS NOTICE
FONT_NAME FAMILY_NAME
FULL_NAME CAP_HEIGHT

For further information about font properties, see section 8.5.

To return an atom for a given name, use XInternAtom. __ │

Atom XInternAtom(display, atom_name, only_if_exists)
Display *display;
char *atom_name;
Bool only_if_exists;

want returned.

only_if_exists
Specifies a Boolean value that indicates whether
the atom must be created. │__

The XInternAtom function returns the atom identifier associated with the specified atom_name string. If only_if_exists is False, the atom is created if it does not exist. Therefore, XInternAtom can return None. If the atom name is not in the Host Portable Character Encoding, the result is implementation-dependent. Uppercase and lowercase matter; the strings ‘‘thing’’, ‘‘Thing’’, and ‘‘thinG’’ all designate different atoms. The atom will remain defined even after the client’s connection closes. It will become undefined only when the last connection to the X server closes.

XInternAtom can generate BadAlloc and BadValue errors.

To return atoms for an array of names, use XInternAtoms. __ │

Status XInternAtoms(display, names, count, only_if_exists, atoms_return)
Display *display;
char **names;
int count;
Bool only_if_exists;
Atom *atoms_return;

only_if_exists
Specifies a Boolean value that indicates whether
the atom must be created.

atoms_return
Returns the atoms. │__

The XInternAtoms function returns the atom identifiers associated with the specified names. The atoms are stored in the atoms_return array supplied by the caller. Calling this function is equivalent to calling XInternAtom for each of the names in turn with the specified value of only_if_exists, but this function minimizes the number of round-trip protocol exchanges between the client and the X server.

This function returns a nonzero status if atoms are returned for all of the names; otherwise, it returns zero.

XInternAtoms can generate BadAlloc and BadValue errors.

To return a name for a given atom identifier, use XGetAtomName. __ │

char *XGetAtomName(display, atom)
Display *display;
Atom atom;

returned. │__

The XGetAtomName function returns the name associated with the specified atom. If the data returned by the server is in the Latin Portable Character Encoding, then the returned string is in the Host Portable Character Encoding. Otherwise, the result is implementation-dependent. To free the resulting string, call XFree.

XGetAtomName can generate a BadAtom error.

To return the names for an array of atom identifiers, use XGetAtomNames. __ │

Status XGetAtomNames(display, atoms, count, names_return)
Display *display;
Atom *atoms;
int count;
char **names_return;

names_return
Returns the atom names. │__

The XGetAtomNames function returns the names associated with the specified atoms. The names are stored in the names_return array supplied by the caller. Calling this function is equivalent to calling XGetAtomName for each of the atoms in turn, but this function minimizes the number of round-trip protocol exchanges between the client and the X server.

This function returns a nonzero status if names are returned for all of the atoms; otherwise, it returns zero.

XGetAtomNames can generate a BadAtom error.

4.4. Obtaining and Changing Window Properties

You can attach a property list to every window. Each property has a name, a type, and a value (see section 4.3). The value is an array of 8-bit, 16-bit, or 32-bit quantities, whose interpretation is left to the clients. The type char is used to represent 8-bit quantities, the type short is used to represent 16-bit quantities, and the type long is used to represent 32-bit quantities.

Xlib provides functions that you can use to obtain, change, update, or interchange window properties. In addition, Xlib provides other utility functions for inter-client communication (see chapter 14).

To obtain the type, format, and value of a property of a given window, use XGetWindowProperty. __ │

int XGetWindowProperty(display, w, property, long_offset, long_length, delete, req_type,
actual_type_return, actual_format_return, nitems_return, bytes_after_return,
prop_return)
Display *display;
Window w;
Atom property;
long long_offset, long_length;
Bool delete;
Atom req_type;
Atom *actual_type_return;
int *actual_format_return;
unsigned long *nitems_return;
unsigned long *bytes_after_return;
unsigned char **prop_return;

obtain.

long_offsetSpecifies the offset in the specified property
(in 32-bit quantities) where the data is to be re-
trieved.

long_lengthSpecifies the length in 32-bit multiples of the
data to be retrieved.

the property is deleted.

property type or AnyPropertyType.

actual_type_return
Returns the atom identifier that defines the ac-
tual type of the property.

actual_format_return
Returns the actual format of the property.

nitems_return
Returns the actual number of 8-bit, 16-bit, or
32-bit items stored in the prop_return data.

bytes_after_return
Returns the number of bytes remaining to be read
in the property if a partial read was performed.

prop_returnReturns the data in the specified format. │__

The XGetWindowProperty function returns the actual type of the property; the actual format of the property; the number of 8-bit, 16-bit, or 32-bit items transferred; the number of bytes remaining to be read in the property; and a pointer to the data actually returned. XGetWindowProperty sets the return arguments as follows:

The returned value starts at byte index I in the property (indexing from zero), and its length in bytes is L. If the value for long_offset causes L to be negative, a BadValue error results. The value of bytes_after_return is A, giving the number of trailing unread bytes in the stored property.

If the returned format is 8, the returned data is represented as a char array. If the returned format is 16, the returned data is represented as a short array and should be cast to that type to obtain the elements. If the returned format is 32, the returned data is represented as a long array and should be cast to that type to obtain the elements.

XGetWindowProperty always allocates one extra byte in prop_return (even if the property is zero length) and sets it to zero so that simple properties consisting of characters do not have to be copied into yet another string before use.

If delete is True and bytes_after_return is zero, XGetWindowProperty deletes the property from the window and generates a PropertyNotify event on the window.

The function returns Success if it executes successfully. To free the resulting data, use XFree.

XGetWindowProperty can generate BadAtom, BadValue, and BadWindow errors.

To obtain a given window’s property list, use XListProperties. __ │

Atom *XListProperties(display, w, num_prop_return)
Display *display;
Window w;
int *num_prop_return;

to obtain.

num_prop_return
Returns the length of the properties array. │__

The XListProperties function returns a pointer to an array of atom properties that are defined for the specified window or returns NULL if no properties were found. To free the memory allocated by this function, use XFree.

XListProperties can generate a BadWindow error.

To change a property of a given window, use XChangeProperty. __ │

XChangeProperty(display, w, property, type, format, mode, data, nelements)
Display *display;
Window w;
Atom property, type;
int format;
int mode;
unsigned char *data;
int nelements;

change.

does not interpret the type but simply passes it
back to an application that later calls XGetWin-
dowProperty.

list of 8-bit, 16-bit, or 32-bit quantities. Pos-
sible values are 8, 16, and 32. This information
allows the X server to correctly perform byte-swap
operations as necessary. If the format is 16-bit
or 32-bit, you must explicitly cast your data
pointer to an (unsigned char *) in the call to
XChangeProperty.

PropModeReplace, PropModePrepend, or PropModeAp-
pend.

data format. │__

The XChangeProperty function alters the property for the specified window and causes the X server to generate a PropertyNotify event on that window. XChangeProperty performs the following:

If the specified format is 8, the property data must be a char array. If the specified format is 16, the property data must be a short array. If the specified format is 32, the property data must be a long array.

The lifetime of a property is not tied to the storing client. Properties remain until explicitly deleted, until the window is destroyed, or until the server resets. For a discussion of what happens when the connection to the X server is closed, see section 2.6. The maximum size of a property is server dependent and can vary dynamically depending on the amount of memory the server has available. (If there is insufficient space, a BadAlloc error results.)

XChangeProperty can generate BadAlloc, BadAtom, BadMatch, BadValue, and BadWindow errors.

To rotate a window’s property list, use XRotateWindowProperties. __ │

XRotateWindowProperties(display, w, properties, num_prop, npositions)
Display *display;
Window w;
Atom properties[];
int num_prop;
int npositions;

propertiesSpecifies the array of properties that are to be
rotated.

npositionsSpecifies the rotation amount. │__

The XRotateWindowProperties function allows you to rotate properties on a window and causes the X server to generate PropertyNotify events. If the property names in the properties array are viewed as being numbered starting from zero and if there are num_prop property names in the list, then the value associated with property name I becomes the value associated with property name (I + npositions) mod N for all I from zero to N − 1. The effect is to rotate the states by npositions places around the virtual ring of property names (right for positive npositions, left for negative npositions). If npositions mod N is nonzero, the X server generates a PropertyNotify event for each property in the order that they are listed in the array. If an atom occurs more than once in the list or no property with that name is defined for the window, a BadMatch error results. If a BadAtom or BadMatch error results, no properties are changed.

XRotateWindowProperties can generate BadAtom, BadMatch, and BadWindow errors.

To delete a property on a given window, use XDeleteProperty. __ │

XDeleteProperty(display, w, property)
Display *display;
Window w;
Atom property;

delete.

The XDeleteProperty function deletes the specified property only if the property was defined on the specified window and causes the X server to generate a PropertyNotify event on the window unless the property does not exist.

XDeleteProperty can generate BadAtom and BadWindow errors.

4.5. Selections

Selections are one method used by applications to exchange data. By using the property mechanism, applications can exchange data of arbitrary types and can negotiate the type of the data. A selection can be thought of as an indirect property with a dynamic type. That is, rather than having the property stored in the X server, the property is maintained by some client (the owner). A selection is global in nature (considered to belong to the user but be maintained by clients) rather than being private to a particular window subhierarchy or a particular set of clients.

Xlib provides functions that you can use to set, get, or request conversion of selections. This allows applications to implement the notion of current selection, which requires that notification be sent to applications when they no longer own the selection. Applications that support selection often highlight the current selection and so must be informed when another application has acquired the selection so that they can unhighlight the selection.

When a client asks for the contents of a selection, it specifies a selection target type. This target type can be used to control the transmitted representation of the contents. For example, if the selection is ‘‘the last thing the user clicked on’’ and that is currently an image, then the target type might specify whether the contents of the image should be sent in XY format or Z format.

The target type can also be used to control the class of contents transmitted, for example, asking for the ‘‘looks’’ (fonts, line spacing, indentation, and so forth) of a paragraph selection, not the text of the paragraph. The target type can also be used for other purposes. The protocol does not constrain the semantics.

To set the selection owner, use XSetSelectionOwner. __ │

XSetSelectionOwner(display, selection, owner, time)
Display *display;
Atom selection;
Window owner;
Time time;

atom. You can pass a window or None.

stamp or CurrentTime. │__

The XSetSelectionOwner function changes the owner and last-change time for the specified selection and has no effect if the specified time is earlier than the current last-change time of the specified selection or is later than the current X server time. Otherwise, the last-change time is set to the specified time, with CurrentTime replaced by the current server time. If the owner window is specified as None, then the owner of the selection becomes None (that is, no owner). Otherwise, the owner of the selection becomes the client executing the request.

If the new owner (whether a client or None) is not the same as the current owner of the selection and the current owner is not None, the current owner is sent a SelectionClear event. If the client that is the owner of a selection is later terminated (that is, its connection is closed) or if the owner window it has specified in the request is later destroyed, the owner of the selection automatically reverts to None, but the last-change time is not affected. The selection atom is uninterpreted by the X server. XGetSelectionOwner returns the owner window, which is reported in SelectionRequest and SelectionClear events. Selections are global to the X server.

XSetSelectionOwner can generate BadAtom and BadWindow errors.

To return the selection owner, use XGetSelectionOwner. __ │

Window XGetSelectionOwner(display, selection)
Display *display;
Atom selection;

returned. │__

The XGetSelectionOwner function returns the window ID associated with the window that currently owns the specified selection. If no selection was specified, the function returns the constant None. If None is returned, there is no owner for the selection.

XGetSelectionOwner can generate a BadAtom error.

To request conversion of a selection, use XConvertSelection. __ │

XConvertSelection(display, selection, target, property, requestor, time)
Display *display;
Atom selection, target;
Atom property;
Window requestor;
Time time;

None.

stamp or CurrentTime. │__

XConvertSelection requests that the specified selection be converted to the specified target type:

The arguments are passed on unchanged in either of the events. There are two predefined selection atoms: PRIMARY and SECONDARY.

XConvertSelection can generate BadAtom and BadWindow errors.

4

Xlib − C Library libX11 1.3.2

Chapter 5

Pixmap and Cursor Functions

Once you have connected to an X server, you can use the Xlib functions to:

5.1. Creating and Freeing Pixmaps

Pixmaps can only be used on the screen on which they were created. Pixmaps are off-screen resources that are used for various operations, such as defining cursors as tiling patterns or as the source for certain raster operations. Most graphics requests can operate either on a window or on a pixmap. A bitmap is a single bit-plane pixmap.

To create a pixmap of a given size, use XCreatePixmap. __ │

Pixmap XCreatePixmap(display, d, width, height, depth)
Display *display;
Drawable d;
unsigned int width, height;
unsigned int depth;

mensions of the pixmap.

The XCreatePixmap function creates a pixmap of the width, height, and depth you specified and returns a pixmap ID that identifies it. It is valid to pass an InputOnly window to the drawable argument. The width and height arguments must be nonzero, or a BadValue error results. The depth argument must be one of the depths supported by the screen of the specified drawable, or a BadValue error results.

The server uses the specified drawable to determine on which screen to create the pixmap. The pixmap can be used only on this screen and only with other drawables of the same depth (see XCopyPlane for an exception to this rule). The initial contents of the pixmap are undefined.

XCreatePixmap can generate BadAlloc, BadDrawable, and BadValue errors.

To free all storage associated with a specified pixmap, use XFreePixmap. __ │

XFreePixmap(display, pixmap)
Display *display;
Pixmap pixmap;

The XFreePixmap function first deletes the association between the pixmap ID and the pixmap. Then, the X server frees the pixmap storage when there are no references to it. The pixmap should never be referenced again.

XFreePixmap can generate a BadPixmap error.

5.2. Creating, Recoloring, and Freeing Cursors

Each window can have a different cursor defined for it. Whenever the pointer is in a visible window, it is set to the cursor defined for that window. If no cursor was defined for that window, the cursor is the one defined for the parent window.

From X’s perspective, a cursor consists of a cursor source, mask, colors, and a hotspot. The mask pixmap determines the shape of the cursor and must be a depth of one. The source pixmap must have a depth of one, and the colors determine the colors of the source. The hotspot defines the point on the cursor that is reported when a pointer event occurs. There may be limitations imposed by the hardware on cursors as to size and whether a mask is implemented. XQueryBestCursor can be used to find out what sizes are possible. There is a standard font for creating cursors, but Xlib provides functions that you can use to create cursors from an arbitrary font or from bitmaps.

To create a cursor from the standard cursor font, use XCreateFontCursor. __ │

#include <X11/cursorfont.h>
Cursor XCreateFontCursor(display, shape)
Display *display;
unsigned int shape;

X provides a set of standard cursor shapes in a special font named cursor. Applications are encouraged to use this interface for their cursors because the font can be customized for the individual display type. The shape argument specifies which glyph of the standard fonts to use.

The hotspot comes from the information stored in the cursor font. The initial colors of a cursor are a black foreground and a white background (see XRecolorCursor). For further information about cursor shapes, see appendix B.

XCreateFontCursor can generate BadAlloc and BadValue errors.

To create a cursor from font glyphs, use XCreateGlyphCursor. __ │

Cursor XCreateGlyphCursor(display, source_font, mask_font, source_char, mask_char,
foreground_color, background_color)
Display *display;
Font source_font, mask_font;
unsigned int source_char, mask_char;
XColor *foreground_color;
XColor *background_color;

source_fontSpecifies the font for the source glyph.

source_charSpecifies the character glyph for the source.

foreground_color
Specifies the RGB values for the foreground of the
source.

background_color
Specifies the RGB values for the background of the
source. │__

The XCreateGlyphCursor function is similar to XCreatePixmapCursor except that the source and mask bitmaps are obtained from the specified font glyphs. The source_char must be a defined glyph in source_font, or a BadValue error results. If mask_font is given, mask_char must be a defined glyph in mask_font, or a BadValue error results. The mask_font and character are optional. The origins of the source_char and mask_char (if defined) glyphs are positioned coincidently and define the hotspot. The source_char and mask_char need not have the same bounding box metrics, and there is no restriction on the placement of the hotspot relative to the bounding boxes. If no mask_char is given, all pixels of the source are displayed. You can free the fonts immediately by calling XFreeFont if no further explicit references to them are to be made.

For 2-byte matrix fonts, the 16-bit value should be formed with the byte1 member in the most significant byte and the byte2 member in the least significant byte.

XCreateGlyphCursor can generate BadAlloc, BadFont, and BadValue errors.

To create a cursor from two bitmaps, use XCreatePixmapCursor. __ │

Cursor XCreatePixmapCursor(display, source, mask, foreground_color, background_color, x, y)
Display *display;
Pixmap source;
Pixmap mask;
XColor *foreground_color;
XColor *background_color;
unsigned int x, y;

or None.

foreground_color
Specifies the RGB values for the foreground of the
source.

background_color
Specifies the RGB values for the background of the
source.

the hotspot relative to the source’s origin. │__

The XCreatePixmapCursor function creates a cursor and returns the cursor ID associated with it. The foreground and background RGB values must be specified using foreground_color and background_color, even if the X server only has a StaticGray or GrayScale screen. The foreground color is used for the pixels set to 1 in the source, and the background color is used for the pixels set to 0. Both source and mask, if specified, must have depth one (or a BadMatch error results) but can have any root. The mask argument defines the shape of the cursor. The pixels set to 1 in the mask define which source pixels are displayed, and the pixels set to 0 define which pixels are ignored. If no mask is given, all pixels of the source are displayed. The mask, if present, must be the same size as the pixmap defined by the source argument, or a BadMatch error results. The hotspot must be a point within the source, or a BadMatch error results.

The components of the cursor can be transformed arbitrarily to meet display limitations. The pixmaps can be freed immediately if no further explicit references to them are to be made. Subsequent drawing in the source or mask pixmap has an undefined effect on the cursor. The X server might or might not make a copy of the pixmap.

XCreatePixmapCursor can generate BadAlloc and BadPixmap errors.

To determine useful cursor sizes, use XQueryBestCursor. __ │

Status XQueryBestCursor(display, d, width, height, width_return, height_return)
Display *display;
Drawable d;
unsigned int width, height;
unsigned int *width_return, *height_return;

screen.

you want the size information for.

width_return
height_return
Return the best width and height that is closest
to the specified width and height. │__

Some displays allow larger cursors than other displays. The XQueryBestCursor function provides a way to find out what size cursors are actually possible on the display. It returns the largest size that can be displayed. Applications should be prepared to use smaller cursors on displays that cannot support large ones.

XQueryBestCursor can generate a BadDrawable error.

To change the color of a given cursor, use XRecolorCursor. __ │

XRecolorCursor(display, cursor, foreground_color, background_color)
Display *display;
Cursor cursor;
XColor *foreground_color, *background_color;

foreground_color
Specifies the RGB values for the foreground of the
source.

background_color
Specifies the RGB values for the background of the
source. │__

The XRecolorCursor function changes the color of the specified cursor, and if the cursor is being displayed on a screen, the change is visible immediately. The pixel members of the XColor structures are ignored; only the RGB values are used.

XRecolorCursor can generate a BadCursor error.

To free (destroy) a given cursor, use XFreeCursor. __ │

XFreeCursor(display, cursor)
Display *display;
Cursor cursor;

The XFreeCursor function deletes the association between the cursor resource ID and the specified cursor. The cursor storage is freed when no other resource references it. The specified cursor ID should not be referred to again.

XFreeCursor can generate a BadCursor error.

5

Xlib − C Library libX11 1.3.2

Chapter 6

Color Management Functions

Each X window always has an associated colormap that provides a level of indirection between pixel values and colors displayed on the screen. Xlib provides functions that you can use to manipulate a colormap. The X protocol defines colors using values in the RGB color space. The RGB color space is device dependent; rendering an RGB value on differing output devices typically results in different colors. Xlib also provides a means for clients to specify color using device-independent color spaces for consistent results across devices. Xlib supports device-independent color spaces derivable from the CIE XYZ color space. This includes the CIE XYZ, xyY, L*u*v*, and L*a*b* color spaces as well as the TekHVC color space.

This chapter discusses how to:

All functions, types, and symbols in this chapter with the prefix ‘‘Xcms’’ are defined in <X11/Xcms.h>. The remaining functions and types are defined in <X11/Xlib.h>.

Functions in this chapter manipulate the representation of color on the screen. For each possible value that a pixel can take in a window, there is a color cell in the colormap. For example, if a window is 4 bits deep, pixel values 0 through 15 are defined. A colormap is a collection of color cells. A color cell consists of a triple of red, green, and blue (RGB) values. The hardware imposes limits on the number of significant bits in these values. As each pixel is read out of display memory, the pixel is looked up in a colormap. The RGB value of the cell determines what color is displayed on the screen. On a grayscale display with a black-and-white monitor, the values are combined to determine the brightness on the screen.

Typically, an application allocates color cells or sets of color cells to obtain the desired colors. The client can allocate read-only cells. In which case, the pixel values for these colors can be shared among multiple applications, and the RGB value of the cell cannot be changed. If the client allocates read/write cells, they are exclusively owned by the client, and the color associated with the pixel value can be changed at will. Cells must be allocated (and, if read/write, initialized with an RGB value) by a client to obtain desired colors. The use of pixel value for an unallocated cell results in an undefined color.

Because colormaps are associated with windows, X supports displays with multiple colormaps and, indeed, different types of colormaps. If there are insufficient colormap resources in the display, some windows will display in their true colors, and others will display with incorrect colors. A window manager usually controls which windows are displayed in their true colors if more than one colormap is required for the color resources the applications are using. At any time, there is a set of installed colormaps for a screen. Windows using one of the installed colormaps display with true colors, and windows using other colormaps generally display with incorrect colors. You can control the set of installed colormaps by using XInstallColormap and XUninstallColormap.

Colormaps are local to a particular screen. Screens always have a default colormap, and programs typically allocate cells out of this colormap. Generally, you should not write applications that monopolize color resources. Although some hardware supports multiple colormaps installed at one time, many of the hardware displays built today support only a single installed colormap, so the primitives are written to encourage sharing of colormap entries between applications.

The DefaultColormap macro returns the default colormap. The DefaultVisual macro returns the default visual type for the specified screen. Possible visual types are StaticGray, GrayScale, StaticColor, PseudoColor, TrueColor, or DirectColor (see section 3.1).

6.1. Color Structures

Functions that operate only on RGB color space values use an XColor structure, which contains: __ │

typedef struct {

} XColor; │__

The red, green, and blue values are always in the range 0 to 65535 inclusive, independent of the number of bits actually used in the display hardware. The server scales these values down to the range used by the hardware. Black is represented by (0,0,0), and white is represented by (65535,65535,65535). In some functions, the flags member controls which of the red, green, and blue members is used and can be the inclusive OR of zero or more of DoRed, DoGreen, and DoBlue.

Functions that operate on all color space values use an XcmsColor structure. This structure contains a union of substructures, each supporting color specification encoding for a particular color space. Like the XColor structure, the XcmsColor structure contains pixel and color specification information (the spec member in the XcmsColor structure). __ │

typedef unsigned long XcmsColorFormat;/* Color Specification Format */

typedef struct {

Because the color specification can be encoded for the various color spaces, encoding for the spec member is identified by the format member, which is of type XcmsColorFormat. The following macros define standard formats. __ │
#de-
fine
XcmsUndefined-
Format
0x00000000

#de-
fine
XcmsCIEXYZFormat
0x00000001
/* CIE XYZ */

#de-
fine
XcmsCIEuvYFormat
0x00000002
/* CIE u’v’Y */

#de-
fine
XcmsCIExyYFormat
0x00000003
/* CIE xyY */

#de-
fine
XcmsCIELabFormat
0x00000004
/* CIE L*a*b*
*/
#de-
fine
XcmsCIELuvFormat
0x00000005
/* CIE L*u*v*
*/
#de-
fine
XcmsTekHVCFormat
0x00000006
/* TekHVC */

#de-
fine
XcmsRGBFormat
0x80000000
/* RGB Device
*/
#de-
fine
XcmsRGBiFormat
0x80000001
/* RGB Intensi-
ty */ │__

Formats for device-independent color spaces are distinguishable from those for device-dependent spaces by the 32nd bit. If this bit is set, it indicates that the color specification is in a device-dependent form; otherwise, it is in a device-independent form. If the 31st bit is set, this indicates that the color space has been added to Xlib at run time (see section 6.12.4). The format value for a color space added at run time may be different each time the program is executed. If references to such a color space must be made outside the client (for example, storing a color specification in a file), then reference should be made by color space string prefix (see XcmsFormatOfPrefix and XcmsPrefixOfFormat).

Data types that describe the color specification encoding for the various color spaces are defined as follows: __ │

typedef double XcmsFloat;

typedef struct {

typedef struct {

typedef struct {

typedef struct {

typedef struct {

typedef struct {

typedef struct {

typedef struct {

typedef struct {

The device-dependent formats provided allow color specification in:

Red, green, and blue linear intensity values, floating-point values from 0.0 to 1.0, where 1.0 indicates full intensity, 0.5 half intensity, and so on.

Red, green, and blue values appropriate for the specified output device. XcmsRGB values are of type unsigned short, scaled from 0 to 65535 inclusive, and are interchangeable with the red, green, and blue values in an XColor structure.

It is important to note that RGB Intensity values are not gamma corrected values. In contrast, RGB Device values generated as a result of converting color specifications are always gamma corrected, and RGB Device values acquired as a result of querying a colormap or passed in by the client are assumed by Xlib to be gamma corrected. The term RGB value in this manual always refers to an RGB Device value.

6.2. Color Strings

Xlib provides a mechanism for using string names for colors. A color string may either contain an abstract color name or a numerical color specification. Color strings are case-insensitive.

Color strings are used in the following functions:

Xlib supports the use of abstract color names, for example, red or blue. A value for this abstract name is obtained by searching one or more color name databases. Xlib first searches zero or more client-side databases; the number, location, and content of these databases is implementation-dependent and might depend on the current locale. If the name is not found, Xlib then looks for the color in the X server’s database. If the color name is not in the Host Portable Character Encoding, the result is implementation-dependent.

A numerical color specification consists of a color space name and a set of values in the following syntax: __ │

<color_space_name>:<value>/.../<value> │__

The following are examples of valid color strings.

"CIEXYZ:0.3227/0.28133/0.2493"
"RGBi:1.0/0.0/0.0"
"rgb:00/ff/00"
"CIELuv:50.0/0.0/0.0"

The syntax and semantics of numerical specifications are given for each standard color space in the following sections.

6.2.1. RGB Device String Specification

An RGB Device specification is identified by the prefix ‘‘rgb:’’ and conforms to the following syntax:

rgb:<red>/<green>/<blue>

<red>, <green>, <blue> := h | hh | hhh | hhhh
h := single hexadecimal digits (case insignificant)

Note that h indicates the value scaled in 4 bits, hh the value scaled in 8 bits, hhh the value scaled in 12 bits, and hhhh the value scaled in 16 bits, respectively.

Typical examples are the strings ‘‘rgb:ea/75/52’’ and ‘‘rgb:ccc/320/320’’, but mixed numbers of hexadecimal digit strings (‘‘rgb:ff/a5/0’’ and ‘‘rgb:ccc/32/0’’) are also allowed.

For backward compatibility, an older syntax for RGB Device is supported, but its continued use is not encouraged. The syntax is an initial sharp sign character followed by a numeric specification, in one of the following formats:

The R, G, and B represent single hexadecimal digits. When fewer than 16 bits each are specified, they represent the most significant bits of the value (unlike the ‘‘rgb:’’ syntax, in which values are scaled). For example, the string ‘‘#3a7’’ is the same as ‘‘#3000a0007000’’.

6.2.2. RGB Intensity String Specification

An RGB intensity specification is identified by the prefix ‘‘rgbi:’’ and conforms to the following syntax:

rgbi:<red>/<green>/<blue>

Note that red, green, and blue are floating-point values between 0.0 and 1.0, inclusive. The input format for these values is an optional sign, a string of numbers possibly containing a decimal point, and an optional exponent field containing an E or e followed by a possibly signed integer string.

6.2.3. Device-Independent String Specifications

The standard device-independent string specifications have the following syntax:

CIEXYZ:<X>/<Y>/<Z>
CIEuvY:<u>/<v>/<Y>
CIExyY:<x>/<y>/<Y>
CIELab:<L>/<a>/<b>
CIELuv:<L>/<u>/<v>
TekHVC:<H>/<V>/<C>

All of the values (C, H, V, X, Y, Z, a, b, u, v, y, x) are floating-point values. The syntax for these values is an optional plus or minus sign, a string of digits possibly containing a decimal point, and an optional exponent field consisting of an ‘‘E’’ or ‘‘e’’ followed by an optional plus or minus followed by a string of digits.

6.3. Color Conversion Contexts and Gamut Mapping

When Xlib converts device-independent color specifications into device-dependent specifications and vice versa, it uses knowledge about the color limitations of the screen hardware. This information, typically called the device profile, is available in a Color Conversion Context (CCC).

Because a specified color may be outside the color gamut of the target screen and the white point associated with the color specification may differ from the white point inherent to the screen, Xlib applies gamut mapping when it encounters certain conditions:

Gamut handling methods are stored as callbacks in the CCC, which in turn are used by the color space conversion routines. Client data is also stored in the CCC for each callback. The CCC also contains the white point the client assumes to be associated with color specifications (that is, the Client White Point). The client can specify the gamut handling callbacks and client data as well as the Client White Point. Xlib does not preclude the X client from performing other forms of gamut handling (for example, gamut expansion); however, Xlib does not provide direct support for gamut handling other than white adjustment and gamut compression.

Associated with each colormap is an initial CCC transparently generated by Xlib. Therefore, when you specify a colormap as an argument to an Xlib function, you are indirectly specifying a CCC. There is a default CCC associated with each screen. Newly created CCCs inherit attributes from the default CCC, so the default CCC attributes can be modified to affect new CCCs.

Xcms functions in which gamut mapping can occur return Status and have specific status values defined for them, as follows:

6.4. Creating, Copying, and Destroying Colormaps

To create a colormap for a screen, use XCreateColormap. __ │

Colormap XCreateColormap(display, w, visual, alloc)
Display *display;
Window w;
Visual *visual;
int alloc;

create a colormap.

If the visual type is not one supported by the
screen, a BadMatch error results.

You can pass AllocNone or AllocAll. │__

The XCreateColormap function creates a colormap of the specified visual type for the screen on which the specified window resides and returns the colormap ID associated with it. Note that the specified window is only used to determine the screen.

The initial values of the colormap entries are undefined for the visual classes GrayScale, PseudoColor, and DirectColor. For StaticGray, StaticColor, and TrueColor, the entries have defined values, but those values are specific to the visual and are not defined by X. For StaticGray, StaticColor, and TrueColor, alloc must be AllocNone, or a BadMatch error results. For the other visual classes, if alloc is AllocNone, the colormap initially has no allocated entries, and clients can allocate them. For information about the visual types, see section 3.1.

If alloc is AllocAll, the entire colormap is allocated writable. The initial values of all allocated entries are undefined. For GrayScale and PseudoColor, the effect is as if an XAllocColorCells call returned all pixel values from zero to N − 1, where N is the colormap entries value in the specified visual. For DirectColor, the effect is as if an XAllocColorPlanes call returned a pixel value of zero and red_mask, green_mask, and blue_mask values containing the same bits as the corresponding masks in the specified visual. However, in all cases, none of these entries can be freed by using XFreeColors.

XCreateColormap can generate BadAlloc, BadMatch, BadValue, and BadWindow errors.

To create a new colormap when the allocation out of a previously shared colormap has failed because of resource exhaustion, use XCopyColormapAndFree. __ │

Colormap XCopyColormapAndFree(display, colormap)
Display *display;
Colormap colormap;

The XCopyColormapAndFree function creates a colormap of the same visual type and for the same screen as the specified colormap and returns the new colormap ID. It also moves all of the client’s existing allocation from the specified colormap to the new colormap with their color values intact and their read-only or writable characteristics intact and frees those entries in the specified colormap. Color values in other entries in the new colormap are undefined. If the specified colormap was created by the client with alloc set to AllocAll, the new colormap is also created with AllocAll, all color values for all entries are copied from the specified colormap, and then all entries in the specified colormap are freed. If the specified colormap was not created by the client with AllocAll, the allocations to be moved are all those pixels and planes that have been allocated by the client using XAllocColor, XAllocNamedColor, XAllocColorCells, or XAllocColorPlanes and that have not been freed since they were allocated.

XCopyColormapAndFree can generate BadAlloc and BadColor errors.

To destroy a colormap, use XFreeColormap. __ │

XFreeColormap(display, colormap)
Display *display;
Colormap colormap;

The XFreeColormap function deletes the association between the colormap resource ID and the colormap and frees the colormap storage. However, this function has no effect on the default colormap for a screen. If the specified colormap is an installed map for a screen, it is uninstalled (see XUninstallColormap). If the specified colormap is defined as the colormap for a window (by XCreateWindow, XSetWindowColormap, or XChangeWindowAttributes), XFreeColormap changes the colormap associated with the window to None and generates a ColormapNotify event. X does not define the colors displayed for a window with a colormap of None.

XFreeColormap can generate a BadColor error.

6.5. Mapping Color Names to Values

To map a color name to an RGB value, use XLookupColor. __ │

Status XLookupColor(display, colormap, color_name, exact_def_return, screen_def_return)
Display *display;
Colormap colormap;
char *color_name;
XColor *exact_def_return, *screen_def_return;

color_nameSpecifies the color name string (for example, red)
whose color definition structure you want re-
turned.

exact_def_return
Returns the exact RGB values.

screen_def_return
Returns the closest RGB values provided by the
hardware. │__

The XLookupColor function looks up the string name of a color with respect to the screen associated with the specified colormap. It returns both the exact color values and the closest values provided by the screen with respect to the visual type of the specified colormap. If the color name is not in the Host Portable Character Encoding, the result is implementation-dependent. Use of uppercase or lowercase does not matter. XLookupColor returns nonzero if the name is resolved; otherwise, it returns zero.

XLookupColor can generate a BadColor error.

To map a color name to the exact RGB value, use XParseColor. __ │

Status XParseColor(display, colormap, spec, exact_def_return)
Display *display;
Colormap colormap;
char *spec;
XColor *exact_def_return;

exact_def_return
Returns the exact color value for later use and
sets the DoRed, DoGreen, and DoBlue flags. │__

The XParseColor function looks up the string name of a color with respect to the screen associated with the specified colormap. It returns the exact color value. If the color name is not in the Host Portable Character Encoding, the result is implementation-dependent. Use of uppercase or lowercase does not matter. XParseColor returns nonzero if the name is resolved; otherwise, it returns zero.

XParseColor can generate a BadColor error.

To map a color name to a value in an arbitrary color space, use XcmsLookupColor. __ │

Status XcmsLookupColor(display, colormap, color_string, color_exact_return, color_screen_return,

Display *display;
Colormap colormap;
char *color_string;
XcmsColor *color_exact_return, *color_screen_return;
XcmsColorFormat result_format;

color_string
Specifies the color string.

color_exact_return
Returns the color specification parsed from the
color string or parsed from the corresponding
string found in a color-name database.

color_screen_return
Returns the color that can be reproduced on the
screen.

result_format
Specifies the color format for the returned color
specifications (color_screen_return and color_ex-
act_return arguments). If the format is XcmsUnde-
finedFormat and the color string contains a numer-
ical color specification, the specification is re-
turned in the format used in that numerical color
specification. If the format is XcmsUndefinedFor-
mat and the color string contains a color name,
the specification is returned in the format used
to store the color in the database. │__

The XcmsLookupColor function looks up the string name of a color with respect to the screen associated with the specified colormap. It returns both the exact color values and the closest values provided by the screen with respect to the visual type of the specified colormap. The values are returned in the format specified by result_format. If the color name is not in the Host Portable Character Encoding, the result is implementation-dependent. Use of uppercase or lowercase does not matter. XcmsLookupColor returns XcmsSuccess or XcmsSuccessWithCompression if the name is resolved; otherwise, it returns XcmsFailure. If XcmsSuccessWithCompression is returned, the color specification returned in color_screen_return is the result of gamut compression.

6.6. Allocating and Freeing Color Cells

There are two ways of allocating color cells: explicitly as read-only entries, one pixel value at a time, or read/write, where you can allocate a number of color cells and planes simultaneously. A read-only cell has its RGB value set by the server. Read/write cells do not have defined colors initially; functions described in the next section must be used to store values into them. Although it is possible for any client to store values into a read/write cell allocated by another client, read/write cells normally should be considered private to the client that allocated them.

Read-only colormap cells are shared among clients. The server counts each allocation and freeing of the cell by clients. When the last client frees a shared cell, the cell is finally deallocated. If a single client allocates the same read-only cell multiple times, the server counts each such allocation, not just the first one.

To allocate a read-only color cell with an RGB value, use XAllocColor. __ │

Status XAllocColor(display, colormap, screen_in_out)
Display *display;
Colormap colormap;
XColor *screen_in_out;

screen_in_out
Specifies and returns the values actually used in
the colormap. │__

The XAllocColor function allocates a read-only colormap entry corresponding to the closest RGB value supported by the hardware. XAllocColor returns the pixel value of the color closest to the specified RGB elements supported by the hardware and returns the RGB value actually used. The corresponding colormap cell is read-only. In addition, XAllocColor returns nonzero if it succeeded or zero if it failed. Multiple clients that request the same effective RGB value can be assigned the same read-only entry, thus allowing entries to be shared. When the last client deallocates a shared cell, it is deallocated. XAllocColor does not use or affect the flags in the XColor structure.

XAllocColor can generate a BadColor error.

To allocate a read-only color cell with a color in arbitrary format, use XcmsAllocColor. __ │

Status XcmsAllocColor(display, colormap, color_in_out, result_format)
Display *display;
Colormap colormap;
XcmsColor *color_in_out;
XcmsColorFormat result_format;

color_in_out
Specifies the color to allocate and returns the
pixel and color that is actually used in the col-
ormap.

result_format
Specifies the color format for the returned color
specification. │__

The XcmsAllocColor function is similar to XAllocColor except the color can be specified in any format. The XcmsAllocColor function ultimately calls XAllocColor to allocate a read-only color cell (colormap entry) with the specified color. XcmsAllocColor first converts the color specified to an RGB value and then passes this to XAllocColor. XcmsAllocColor returns the pixel value of the color cell and the color specification actually allocated. This returned color specification is the result of converting the RGB value returned by XAllocColor into the format specified with the result_format argument. If there is no interest in a returned color specification, unnecessary computation can be bypassed if result_format is set to XcmsRGBFormat. The corresponding colormap cell is read-only. If this routine returns XcmsFailure, the color_in_out color specification is left unchanged.

XcmsAllocColor can generate a BadColor error.

To allocate a read-only color cell using a color name and return the closest color supported by the hardware in RGB format, use XAllocNamedColor. __ │

Status XAllocNamedColor(display, colormap, color_name, screen_def_return, exact_def_return)
Display *display;
Colormap colormap;
char *color_name;
XColor *screen_def_return, *exact_def_return;

color_nameSpecifies the color name string (for example, red)
whose color definition structure you want re-
turned.

screen_def_return
Returns the closest RGB values provided by the
hardware.

exact_def_return
Returns the exact RGB values. │__

The XAllocNamedColor function looks up the named color with respect to the screen that is associated with the specified colormap. It returns both the exact database definition and the closest color supported by the screen. The allocated color cell is read-only. The pixel value is returned in screen_def_return. If the color name is not in the Host Portable Character Encoding, the result is implementation-dependent. Use of uppercase or lowercase does not matter. If screen_def_return and exact_def_return point to the same structure, the pixel field will be set correctly, but the color values are undefined. XAllocNamedColor returns nonzero if a cell is allocated; otherwise, it returns zero.

XAllocNamedColor can generate a BadColor error.

To allocate a read-only color cell using a color name and return the closest color supported by the hardware in an arbitrary format, use XcmsAllocNamedColor. __ │

Status XcmsAllocNamedColor(display, colormap, color_string, color_screen_return, color_exact_return,
result_format)
Display *display;
Colormap colormap;
char *color_string;
XcmsColor *color_screen_return;
XcmsColor *color_exact_return;
XcmsColorFormat result_format;

color_string
Specifies the color string whose color definition
structure is to be returned.

color_screen_return
Returns the pixel value of the color cell and col-
or specification that actually is stored for that
cell.

color_exact_return
Returns the color specification parsed from the
color string or parsed from the corresponding
string found in a color-name database.

result_format
Specifies the color format for the returned color
specifications (color_screen_return and color_ex-
act_return arguments). If the format is XcmsUnde-
finedFormat and the color string contains a numer-
ical color specification, the specification is re-
turned in the format used in that numerical color
specification. If the format is XcmsUndefinedFor-
mat and the color string contains a color name,
the specification is returned in the format used
to store the color in the database. │__

The XcmsAllocNamedColor function is similar to XAllocNamedColor except that the color returned can be in any format specified. This function ultimately calls XAllocColor to allocate a read-only color cell with the color specified by a color string. The color string is parsed into an XcmsColor structure (see XcmsLookupColor), converted to an RGB value, and finally passed to XAllocColor. If the color name is not in the Host Portable Character Encoding, the result is implementation-dependent. Use of uppercase or lowercase does not matter.

This function returns both the color specification as a result of parsing (exact specification) and the actual color specification stored (screen specification). This screen specification is the result of converting the RGB value returned by XAllocColor into the format specified in result_format. If there is no interest in a returned color specification, unnecessary computation can be bypassed if result_format is set to XcmsRGBFormat. If color_screen_return and color_exact_return point to the same structure, the pixel field will be set correctly, but the color values are undefined.

XcmsAllocNamedColor can generate a BadColor error.

To allocate read/write color cell and color plane combinations for a PseudoColor model, use XAllocColorCells. __ │

Status XAllocColorCells(display, colormap, contig, plane_masks_return, nplanes,
pixels_return, npixels)
Display *display;
Colormap colormap;
Bool contig;
unsigned long plane_masks_return[];
unsigned int nplanes;
unsigned long pixels_return[];
unsigned int npixels;

the planes must be contiguous.

plane_mask_return
Returns an array of plane masks.

returned in the plane masks array.

pixels_return
Returns an array of pixel values.

be returned in the pixels_return array. │__

The XAllocColorCells function allocates read/write color cells. The number of colors must be positive and the number of planes nonnegative, or a BadValue error results. If ncolors and nplanes are requested, then ncolors pixels and nplane plane masks are returned. No mask will have any bits set to 1 in common with any other mask or with any of the pixels. By ORing together each pixel with zero or more masks, ncolors * distinct pixels can be produced. All of these are allocated writable by the request. For GrayScale or PseudoColor, each mask has exactly one bit set to 1. For DirectColor, each has exactly three bits set to 1. If contig is True and if all masks are ORed together, a single contiguous set of bits set to 1 will be formed for GrayScale or PseudoColor and three contiguous sets of bits set to 1 (one within each pixel subfield) for DirectColor. The RGB values of the allocated entries are undefined. XAllocColorCells returns nonzero if it succeeded or zero if it failed.

XAllocColorCells can generate BadColor and BadValue errors.

To allocate read/write color resources for a DirectColor model, use XAllocColorPlanes. __ │

Status XAllocColorPlanes(display, colormap, contig, pixels_return, ncolors, nreds, ngreens,
nblues, rmask_return, gmask_return, bmask_return)
Display *display;
Colormap colormap;
Bool contig;
unsigned long pixels_return[];
int ncolors;
int nreds, ngreens, nblues;
unsigned long *rmask_return, *gmask_return, *bmask_return;

the planes must be contiguous.

pixels_return
Returns an array of pixel values. XAllocColor-
Planes returns the pixel values in this array.

be returned in the pixels_return array.

Specify the number of red, green, and blue planes.
The value you pass must be nonnegative.

rmask_return
gmask_return
bmask_return
Return bit masks for the red, green, and blue
planes. │__

The specified ncolors must be positive; and nreds, ngreens, and nblues must be nonnegative, or a BadValue error results. If ncolors colors, nreds reds, ngreens greens, and nblues blues are requested, ncolors pixels are returned; and the masks have nreds, ngreens, and nblues bits set to 1, respectively. If contig is True, each mask will have a contiguous set of bits set to 1. No mask will have any bits set to 1 in common with any other mask or with any of the pixels. For DirectColor, each mask will lie within the corresponding pixel subfield. By ORing together subsets of masks with each pixel value, ncolors * distinct pixel values can be produced. All of these are allocated by the request. However, in the colormap, there are only ncolors * independent red entries, ncolors * independent green entries, and ncolors * independent blue entries. This is true even for PseudoColor. When the colormap entry of a pixel value is changed (using XStoreColors, XStoreColor, or XStoreNamedColor), the pixel is decomposed according to the masks, and the corresponding independent entries are updated. XAllocColorPlanes returns nonzero if it succeeded or zero if it failed.

XAllocColorPlanes can generate BadColor and BadValue errors.

To free colormap cells, use XFreeColors. __ │

XFreeColors(display, colormap, pixels, npixels, planes)
Display *display;
Colormap colormap;
unsigned long pixels[];
int npixels;
unsigned long planes;

cells in the specified colormap.

The XFreeColors function frees the cells represented by pixels whose values are in the pixels array. The planes argument should not have any bits set to 1 in common with any of the pixels. The set of all pixels is produced by ORing together subsets of the planes argument with the pixels. The request frees all of these pixels that were allocated by the client (using XAllocColor, XAllocNamedColor, XAllocColorCells, and XAllocColorPlanes). Note that freeing an individual pixel obtained from XAllocColorPlanes may not actually allow it to be reused until all of its related pixels are also freed. Similarly, a read-only entry is not actually freed until it has been freed by all clients, and if a client allocates the same read-only entry multiple times, it must free the entry that many times before the entry is actually freed.

All specified pixels that are allocated by the client in the colormap are freed, even if one or more pixels produce an error. If a specified pixel is not a valid index into the colormap, a BadValue error results. If a specified pixel is not allocated by the client (that is, is unallocated or is only allocated by another client) or if the colormap was created with all entries writable (by passing AllocAll to XCreateColormap), a BadAccess error results. If more than one pixel is in error, the one that gets reported is arbitrary.

XFreeColors can generate BadAccess, BadColor, and BadValue errors.

6.7. Modifying and Querying Colormap Cells

To store an RGB value in a single colormap cell, use XStoreColor. __ │

XStoreColor(display, colormap, color)
Display *display;
Colormap colormap;
XColor *color;

The XStoreColor function changes the colormap entry of the pixel value specified in the pixel member of the XColor structure. You specified this value in the pixel member of the XColor structure. This pixel value must be a read/write cell and a valid index into the colormap. If a specified pixel is not a valid index into the colormap, a BadValue error results. XStoreColor also changes the red, green, and/or blue color components. You specify which color components are to be changed by setting DoRed, DoGreen, and/or DoBlue in the flags member of the XColor structure. If the colormap is an installed map for its screen, the changes are visible immediately.

XStoreColor can generate BadAccess, BadColor, and BadValue errors.

To store multiple RGB values in multiple colormap cells, use XStoreColors. __ │

XStoreColors(display, colormap, color, ncolors)
Display *display;
Colormap colormap;
XColor color[];
int ncolors;

to be stored.