1mXlib C Language X Interface0m 1mX Window System Standard0m 1mX Version 11, Release 6.9/7.00m James Gettys Cambridge Research Laboratory Digital Equipment Corporation Robert W. Scheifler Laboratory for Computer Science Massachusetts Institute of Technology 4mwith24m 4mcontributions24m 4mfrom0m 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 documenta- tion 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 PUR- POSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE X CONSOR- TIUM 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 pro- mote the sale, use or other dealings in this Software with- out prior written authorization from The Open Group. Copyright 1985, 1986, 1987, 1988, 1989, 1990, 1991 by Dig- ital Equipment Corporation Portions Copyright 1990, 1991 by Tektronix, Inc. Permission to use, copy, modify and distribute this documen- tation 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 permis- sion notice appear in all copies, and that the names of Dig- ital and Tektronix not be used in in advertising or public- ity pertaining to this documentation without specific, writ- ten prior permission. Digital and Tektronix makes no repre- sentations about the suitability of this documentation for any purpose. It is provided as is without express or implied warranty. 1mAcknowledgments0m The design and implementation of the first 10 versions of X were primarily the work of three individuals: Robert Schei- fler of the MIT Laboratory for Computer Science and Jim Get- tys 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 acknowl- edge some of the people who deserve special credit and recognition for their work on Xlib. Our apologies to anyone inadvertently overlooked. 1mRelease 10m Our thanks does to Ron Newman (MIT Project Athena), who con- tributed substantially to the design and implementation of the Version 11 Xlib interface. Our thanks also goes to Ralph Swick (Project Athena and Dig- ital) 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 suc- cessful 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 Digitals 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 pro- vided the sample generic color frame buffer device-dependent code. The alpha and beta test participants deserve special recog- nition 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 uni- versities is certainly to the benefit of the entire X commu- nity. 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 MITs 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 projects suc- cess. 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 Stan- ford University and now of Digital WRL, who had much to do with Ws design. Finally, our thanks goes to MIT, Digital Equipment Corpora- tion, and IBM for providing the environment where it could happen. 1mRelease 40m Our thanks go to Jim Fulton (MIT X Consortium) for designing and specifying the new Xlib functions for Inter-Client Com- munication Conventions (ICCCM) support. We also thank Al Mento of Digital for his continued effort in maintaining this document and Jim Fulton and Donna Con- verse (MIT X Consortium) for their much-appreciated efforts in reviewing the changes. 1mRelease 50m 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 (Tek- tronix). 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 Bad- shah (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 Kurib- ayashi (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 Tech- nosystems Laboratory), Kazunori Nishihara (Fuji Xerox), Masaki Takeuchi (Sony), Katsuhisa Yano (Toshiba), Makoto Wakamatsu (Sony Corporation) for producing the another com- plete sample implementation of the internationalization facilities. The principal authors (design and implementation) of the Xcms color management facilities are Al Tabayoyon (Tek- tronix) and Chuck Adams (Tektronix). Joann Taylor (Tek- tronix), Bob Toole (Tektronix), and Keith Packard (MIT X Consortium) also contributed significantly to the design. Others who contributed are: Harold Boll (Kodak), Ken Bron- stein (HP), Nancy Cam (SGI), Donna Converse (MIT X Consor- tium), 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. 1mRelease 60m Stephen Gildea (X Consortium) authored the threads support. Ovais Ashraf (Sun) and Greg Olsen (Sun) contributed substan- tially by testing the facilities and reporting bugs in a timely fashion. The principal authors of the internationalization facili- ties, 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 implementa- tion. They are: Takashi Fujiwara (Fujitsu), Yoshio Horiuchi (IBM), Makoto Inada (Digital), Hiromu Inukai (Nihon Sun- Soft), 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 Tera- zono (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 international- ization facilities are: Hector Chan (Digital), Michael Kung (IBM), Joseph Kwok (Digital), Hiroyuki Machida (Sony), Nel- son 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 1mChapter 10m 1mIntroduction to Xlib0m The X Window System is a network-transparent window system that was designed at MIT. X display servers run on comput- ers 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 sub- routine library that application programs (clients) use to interface with the window system by means of a stream con- nection. Although a client usually runs on the same machine as the X server it is talking to, this need not be the case. 4mXlib24m 4m24m 4mC24m 4mLanguage24m 4mX24m 4mInterface24m is a reference guide to the low-level C language interface to the X Window System proto- col. It is neither a tutorial nor a users guide to pro- gramming 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. 4mXlib0m 4m24m 4mC24m 4mLanguage24m 4mX24m 4mInterface24m 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 4mX24m 4mWindow0m 4mSystem24m 4mProtocol24m 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: Overview of the X Window System Errors Standard header files Generic values and types Naming and argument conventions within Xlib Programming considerations Character sets and encodings Formatting conventions 1m10m 1mXlib C Library X11, Release 6.9/7.00m 1m1.1. Overview of the X Window System0m 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 ser- vices 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 hier- archies. 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 win- dow 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. 1m20m 1mXlib C Library X11, Release 6.9/7.00m 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 4mExpose24m 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 some- times 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 asyn- chronously, it can follow the request with a call to 4mXSync24m, 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 4mWindow24m, 4mFont24m, 4mPixmap24m, 4mColormap24m, 4mCursor24m, and 4mGContext24m, as defined in the file <4mX11/X.h24m>. 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 applica- tions, and in fact, windows are manipulated explicitly by window manager programs. Fonts and cursors are shared auto- matically 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 sup- port for sharing graphics contexts between applications. Client programs are informed of events. Events may either be side effects of a request (for example, restacking win- dows generates 4mExpose24m 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. 1m30m 1mXlib C Library X11, Release 6.9/7.00m 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, 4mXNextEvent24m or 4mXWindowEvent24m). In addition, some library functions (for example, 4mXRaiseWindow24m) generate 4mExpose24m and 4mConfigureRequest24m events. These events also arrive asyn- chronously, but the client may wish to explicitly wait for them by calling 4mXSync24m after calling a function that can cause the server to generate events. 1m1.2. Errors0m Some functions return 4mStatus24m, 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 val- ues, 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 synchro- nization is enabled, errors are reported as they are gener- ated. 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. 1m1.3. Standard Header Files0m The following include files are part of the Xlib standard: <4mX11/Xlib.h24m> 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 4mXlib-0m 4mSpecificationRelease24m. 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.) <4mX11/X.h24m> 1m40m 1mXlib C Library X11, Release 6.9/7.00m This file declares types and constants for the X proto- col that are to be used by applications. It is included automatically from <4mX11/Xlib.h24m>, so applica- tion code should never need to reference this file directly. <4mX11/Xcms.h24m> This file contains symbols for much of the color man- agement facilities described in chapter 6. All func- tions, types, and symbols with the prefix Xcms, plus the Color Conversion Contexts macros, are declared in this file. <4mX11/Xlib.h24m> must be included before including this file. <4mX11/Xutil.h24m> This file declares various functions, types, and sym- bols used for inter-client communication and applica- tion utility functions, which are described in chapters 14 and 16. <4mX11/Xlib.h24m> must be included before including this file. <4mX11/Xresource.h24m> This file declares all functions, types, and symbols for the resource manager facilities, which are described in chapter 15. <4mX11/Xlib.h24m> must be included before including this file. <4mX11/Xatom.h24m> This file declares all predefined atoms, which are sym- bols with the prefix XA_. <4mX11/cursorfont.h24m> This file declares the cursor symbols for the standard cursor font, which are listed in appendix B. All cur- sor symbols have the prefix XC_. <4mX11/keysymdef.h24m> 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_ARA- BIC, XK_CYRILLIC, XK_GREEK, XK_TECHNICAL, XK_SPECIAL, XK_PUBLISHING, XK_APL, XK_HEBREW, XK_THAI, and XK_KOREAN. 1m50m 1mXlib C Library X11, Release 6.9/7.00m <4mX11/keysym.h24m> This file defines the preprocessor symbols XK_MISCEL- LANY, XK_XKB_KEYS, XK_LATIN1, XK_LATIN2, XK_LATIN3, XK_LATIN4, and XK_GREEK and then includes <4mX11/keysymdef.h24m>. <4mX11/Xlibint.h24m> This file declares all the functions, types, and sym- bols used for extensions, which are described in appendix C. This file automatically includes <4mX11/Xlib.h24m>. <4mX11/Xproto.h24m> This file declares types and symbols for the basic X protocol, for use in implementing extensions. It is included automatically from <4mX11/Xlibint.h24m>, so appli- cation and extension code should never need to refer- ence this file directly. <4mX11/Xprotostr.h24m> This file declares types and symbols for the basic X protocol, for use in implementing extensions. It is included automatically from <4mX11/Xproto.h24m>, so applica- tion and extension code should never need to reference this file directly. <4mX11/X10.h24m> This file declares all the functions, types, and sym- bols used for the X10 compatibility functions, which are described in appendix D. 1m1.4. Generic Values and Types0m The following symbols are defined by Xlib and used through- out the manual: Xlib defines the type 4mBool24m and the Boolean values 4mTrue0m and 4mFalse24m. 4mNone24m is the universal null resource ID or atom. The type 4mXID24m is used for generic resource IDs. The type 4mXPointer24m is defined to be char* and is used as a generic opaque pointer to data. 1m60m 1mXlib C Library X11, Release 6.9/7.00m 1m1.5. Naming and Argument Conventions within Xlib0m Xlib follows a number of conventions for the naming and syn- tax of the functions. Given that you remember what informa- tion the function requires, these conventions are intended to make the syntax of the functions more predictable. The major naming conventions are: To differentiate the X symbols from the other symbols, the library uses mixed case for external symbols. It leaves lowercase for variables and all uppercase for user macros, as per existing convention. All Xlib functions begin with a capital X. The beginnings of all function names and symbols are capitalized. All user-visible data structures begin with a capital X. More generally, anything that a user might derefer- ence begins with a capital X. Macros and other symbols do not begin with a capital X. To distinguish them from all user symbols, each word in the macro is capitalized. All elements of or variables in a data structure are in lowercase. Compound words, where needed, are con- structed with underscores (_). The display argument, where used, is always first in the argument list. All resource objects, where used, occur at the begin- ning of the argument list immediately after the display argument. When a graphics context is present together with another type of resource (most commonly, a drawable), the graphics context occurs in the argument list after the other resource. Drawables outrank all other resources. Source arguments always precede the destination argu- ments in the argument list. The x argument always precedes the y argument in the argument list. The width argument always precedes the height argument in the argument list. 1m70m 1mXlib C Library X11, Release 6.9/7.00m Where the x, y, width, and height arguments are used together, the x and y arguments always precede the width and height arguments. Where a mask is accompanied with a structure, the mask always precedes the pointer to the structure in the argument list. 1m1.6. Programming Considerations0m The major programming considerations are: Coordinates and sizes in X are actually 16-bit quanti- ties. This decision was made to minimize the bandwidth required for a given level of performance. Coordinates usually are declared as an 4mint24m in the interface. Val- ues larger than 16 bits are truncated silently. Sizes (width and height) are declared as unsigned quantities. Keyboards are the greatest variable between different manufacturers workstations. If you want your program to be portable, you should be particularly conservative here. Many display systems have limited amounts of off-screen memory. If you can, you should minimize use of pixmaps and backing store. The user should have control of his screen real estate. Therefore, you should write your applications to react to window management rather than presume control of the entire screen. What you do inside of your top-level window, however, is up to your application. For fur- ther information, see chapter 14 and the 4mInter-Client0m 4mCommunication24m 4mConventions24m 4mManual24m. 1m1.7. Character Sets and Encodings0m Some of the Xlib functions make reference to specific char- acter sets and character encodings. The following are the most common: X Portable Character Set A basic set of 97 characters, which are assumed to exist in all locales supported by Xlib. This set con- tains the following characters: a..z A..Z 0..9 !"#$%&()*+,-./:;<=>?@[\]^_{|}~ , , and 1m80m 1mXlib C Library X11, Release 6.9/7.00m This set is the left/lower half of the graphic charac- ter 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. Host Portable Character Encoding The encoding of the X Portable Character Set on the host. The encoding itself is not defined by this stan- dard, 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. Latin-1 The coded character set defined by the ISO8859-1 stan- dard. Latin Portable Character Encoding 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. STRING Encoding Latin-1, plus tab and newline. POSIX Portable Filename Character Set 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 ._- 1m1.8. Formatting Conventions0m 4mXlib24m 4m24m 4mC24m 4mLanguage24m 4mX24m 4mInterface24m uses the following conven- tions: Global symbols are printed in 4mthis24m 4mspecial24m 4mfont24m. These can be either function names, symbols defined in include files, or structure names. When declared and defined, function arguments are printed in 4mitalics24m. In the explanatory text that follows, they usually are 1m90m 1mXlib C Library X11, Release 6.9/7.00m printed in regular type. Each function is introduced by a general discussion that distinguishes it from other functions. The func- tion declaration itself follows, and each argument is specifically explained. Although ANSI C function pro- totype syntax is not used, Xlib header files normally declare functions using function prototypes in ANSI C environments. General discussion of the function, if any is required, follows the arguments. Where applica- ble, the last paragraph of the explanation lists the possible Xlib error codes that the function can gener- ate. For a complete discussion of the Xlib error codes, see section 11.8.2. To eliminate any ambiguity between those arguments that you pass and those that a function returns to you, the explanations for all arguments that you pass start with the word 4mspecifies24m or, in the case of multiple argu- ments, the word 4mspecify24m. The explanations for all arguments that are returned to you start with the word 4mreturns24m or, in the case of multiple arguments, the word 4mreturn24m. The explanations for all arguments that you can pass and are returned start with the words 4mspeci-0m 4mfies24m 4mand24m 4mreturns24m. Any pointer to a structure that is used to return a value is designated as such by the 4m_return24m suffix as part of its name. All other pointers passed to these functions are used for reading only. A few arguments use pointers to structures that are used for both input and output and are indicated by using the 4m_in_out24m suf- fix. 1m100m 1mXlib C Library X11, Release 6.9/7.00m 1mChapter 20m 1mDisplay Functions0m 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: Open (connect to) the display Obtain information about the display, image formats, or screens Generate a 4mNoOperation24m protocol request Free client-created data Close (disconnect from) a display Use X Server connection close operations Use Xlib with threads Use internal connections 1m2.1. Opening the Display0m To open a connection to the X server that controls a dis- play, use 4mXOpenDisplay24m. __ Display *XOpenDisplay(4mdisplay_name24m) char *4mdisplay_name24m; 4mdisplay_name0m 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 charac- ters is implementation-dependent. On POSIX-conformant 1m110m 1mXlib C Library X11, Release 6.9/7.00m systems, the display name or DISPLAY environment variable can be a string in the format: __ 4mprotocol24m/4mhostname24m:4mnumber24m.4mscreen_number0m 4mprotocol24m Specifies a protocol family or an alias for a pro- tocol family. Supported protocol families are implementation dependent. The protocol entry is optional. If protocol is not specified, the / separating protocol and hostname must also not be specified. 4mhostname24m Specifies the name of the host machine on which the display is physically attached. You follow the hostname with either a single colon (:) or a double colon (::). 4mnumber24m Specifies the number of the display server on that host machine. You may optionally follow this dis- play number with a period (.). A single CPU can have more than one display. Multiple displays are usually numbered starting with zero. 4mscreen_number0m 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 vari- able that can be accessed by using the 4mDefault-0m 4mScreen24m macro or the 4mXDefaultScreen24m 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 4mXOpenDisplay24m function returns a 4mDisplay24m structure that serves as the connection to the X server and that contains all the information about that X server. 4mXOpenDisplay24m con- nects your application to the X server through TCP or DECnet communications protocols, or through some local inter-pro- cess 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, 4mXOpenDisplay0m connects using TCP streams. (If the protocol is specified as "inet", TCP over IPv4 is used. If the protocol is 1m120m 1mXlib C Library X11, Release 6.9/7.00m 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 host- name is a host machine name and a double colon (::) sepa- rates the hostname and display number, 4mXOpenDisplay24m 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, 4mXOpenDisplay24m returns a pointer to a 4mDisplay0m structure, which is defined in <4mX11/Xlib.h24m>. If 4mXOpenDis-0m 4mplay24m does not succeed, it returns NULL. After a successful call to 4mXOpenDisplay24m, 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 4mDefaultScreen24m macro (or the 4mXDefaultScreen24m function). You can access elements of the 4mDisplay24m and 4mScreen24m structures only by using the information macros or functions. For information about using macros and functions to obtain information from the 4mDisplay24m structure, see section 2.2.1. X servers may implement various types of access control mechanisms (see section 9.8). 1m2.2. Obtaining Information about the Display, Image For-0m 1mmats, or Screens0m The Xlib library provides a number of useful macros and cor- responding functions that return data from the 4mDisplay0m 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 4mDisplay24m 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 4mDisplay24m structure. Note The 4mXDisplayWidth24m, 4mXDisplayHeight24m, 4mXDisplayCells24m, 4mXDisplayPlanes24m, 4mXDisplayWidthMM24m, and 4mXDisplay-0m 4mHeightMM24m functions in the next sections are mis- named. These functions really should be named Screen4mwhatever24m and XScreen4mwhatever24m, not Display- 4mwhatever24m or XDisplay4mwhatever24m. Our apologies for 1m130m 1mXlib C Library X11, Release 6.9/7.00m the resulting confusion. 1m2.2.1. Display Macros0m Applications should not directly modify any part of the 4mDis-0m 4mplay24m and 4mScreen24m structures. The members should be consid- ered read-only, although they may change as the result of other operations on the display. The following lists the C language macros, their correspond- ing function equivalents that are for other language bind- ings, 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 4mBlackPixel24m and 4mWhitePixel24m can be used in implementing a monochrome application. These pixel values are for perma- nently 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 rela- tive intensity of the colors. __ BlackPixel(4mdisplay24m, 4mscreen_number24m) unsigned long XBlackPixel(4mdisplay24m, 4mscreen_number24m) Display *4mdisplay24m; int 4mscreen_number24m; 4mdisplay24m Specifies the connection to the X server. 4mscreen_number0m Specifies the appropriate screen number on the host server. __ Both return the black pixel value for the specified screen. 1m140m 1mXlib C Library X11, Release 6.9/7.00m __ WhitePixel(4mdisplay24m, 4mscreen_number24m) unsigned long XWhitePixel(4mdisplay24m, 4mscreen_number24m) Display *4mdisplay24m; int 4mscreen_number24m; 4mdisplay24m Specifies the connection to the X server. 4mscreen_number0m Specifies the appropriate screen number on the host server. __ Both return the white pixel value for the specified screen. __ ConnectionNumber(4mdisplay24m) int XConnectionNumber(4mdisplay24m) Display *4mdisplay24m; 4mdisplay24m Specifies the connection to the X server. __ Both return a connection number for the specified display. On a POSIX-conformant system, this is the file descriptor of the connection. __ DefaultColormap(4mdisplay24m, 4mscreen_number24m) Colormap XDefaultColormap(4mdisplay24m, 4mscreen_number24m) Display *4mdisplay24m; int 4mscreen_number24m; 4mdisplay24m Specifies the connection to the X server. 4mscreen_number0m 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. 1m150m 1mXlib C Library X11, Release 6.9/7.00m __ DefaultDepth(4mdisplay24m, 4mscreen_number24m) int XDefaultDepth(4mdisplay24m, 4mscreen_number24m) Display *4mdisplay24m; int 4mscreen_number24m; 4mdisplay24m Specifies the connection to the X server. 4mscreen_number0m 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 4mXMatchVisualInfo24m). To determine the number of depths that are available on a given screen, use 4mXListDepths24m. __ int *XListDepths(4mdisplay24m, 4mscreen_number24m, 4mcount_return24m) Display *4mdisplay24m; int 4mscreen_number24m; int *4mcount_return24m; 4mdisplay24m Specifies the connection to the X server. 4mscreen_number0m Specifies the appropriate screen number on the host server. 4mcount_return0m Returns the number of depths. __ The 4mXListDepths24m 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, 4mXListDepths24m sets count_return to the num- ber of available depths. Otherwise, it does not set count_return and returns NULL. To release the memory allo- cated for the array of depths, use 4mXFree24m. 1m160m 1mXlib C Library X11, Release 6.9/7.00m __ DefaultGC(4mdisplay24m, 4mscreen_number24m) GC XDefaultGC(4mdisplay24m, 4mscreen_number24m) Display *4mdisplay24m; int 4mscreen_number24m; 4mdisplay24m Specifies the connection to the X server. 4mscreen_number0m 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 conve- nience 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(4mdisplay24m) Window XDefaultRootWindow(4mdisplay24m) Display *4mdisplay24m; 4mdisplay24m Specifies the connection to the X server. __ Both return the root window for the default screen. __ DefaultScreenOfDisplay(4mdisplay24m) Screen *XDefaultScreenOfDisplay(4mdisplay24m) Display *4mdisplay24m; 4mdisplay24m Specifies the connection to the X server. __ Both return a pointer to the default screen. 1m170m 1mXlib C Library X11, Release 6.9/7.00m __ ScreenOfDisplay(4mdisplay24m, 4mscreen_number24m) Screen *XScreenOfDisplay(4mdisplay24m, 4mscreen_number24m) Display *4mdisplay24m; int 4mscreen_number24m; 4mdisplay24m Specifies the connection to the X server. 4mscreen_number0m Specifies the appropriate screen number on the host server. __ Both return a pointer to the indicated screen. __ DefaultScreen(4mdisplay24m) int XDefaultScreen(4mdisplay24m) Display *4mdisplay24m; 4mdisplay24m Specifies the connection to the X server. __ Both return the default screen number referenced by the 4mXOpenDisplay24m function. This macro or function should be used to retrieve the screen number in applications that will use only a single screen. __ DefaultVisual(4mdisplay24m, 4mscreen_number24m) Visual *XDefaultVisual(4mdisplay24m, 4mscreen_number24m) Display *4mdisplay24m; int 4mscreen_number24m; 4mdisplay24m Specifies the connection to the X server. 4mscreen_number0m 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. 1m180m 1mXlib C Library X11, Release 6.9/7.00m __ DisplayCells(4mdisplay24m, 4mscreen_number24m) int XDisplayCells(4mdisplay24m, 4mscreen_number24m) Display *4mdisplay24m; int 4mscreen_number24m; 4mdisplay24m Specifies the connection to the X server. 4mscreen_number0m Specifies the appropriate screen number on the host server. __ Both return the number of entries in the default colormap. __ DisplayPlanes(4mdisplay24m, 4mscreen_number24m) int XDisplayPlanes(4mdisplay24m, 4mscreen_number24m) Display *4mdisplay24m; int 4mscreen_number24m; 4mdisplay24m Specifies the connection to the X server. 4mscreen_number0m 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(4mdisplay24m) char *XDisplayString(4mdisplay24m) Display *4mdisplay24m; 4mdisplay24m Specifies the connection to the X server. __ Both return the string that was passed to 4mXOpenDisplay24m when the current display was opened. On POSIX-conformant sys- tems, 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 1m190m 1mXlib C Library X11, Release 6.9/7.00m the 4mfork24m 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(4mdisplay24m) Display *4mdisplay24m; 4mdisplay24m Specifies the connection to the X server. __ The 4mXExtendedMaxRequestSize24m function returns zero if the specified display does not support an extended-length proto- col encoding; otherwise, it returns the maximum request size (in 4-byte units) supported by the server using the extended-length encoding. The Xlib functions 4mXDrawLines24m, 4mXDrawArcs24m, 4mXFillPolygon24m, 4mXChangeProperty24m, 4mXSetClipRectan-0m 4mgles24m, and 4mXSetRegion24m will use the extended-length encoding as necessary, if supported by the server. Use of the extended-length encoding in other Xlib functions (for exam- ple, 4mXDrawPoints24m, 4mXDrawRectangles24m, 4mXDrawSegments24m, 4mXFillArcs24m, 4mXFillRectangles24m, 4mXPutImage24m) is permitted but not required; an Xlib implementation may choose to split the data across multiple smaller requests instead. __ long XMaxRequestSize(4mdisplay24m) Display *4mdisplay24m; 4mdisplay24m Specifies the connection to the X server. __ The 4mXMaxRequestSize24m 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: 4mXDrawPoints24m, 4mXDrawRectangles24m, 4mXDrawSegments24m, 4mXFillArcs24m, 4mXFillRectangles24m, and 4mXPutImage24m. 1m200m 1mXlib C Library X11, Release 6.9/7.00m __ LastKnownRequestProcessed(4mdisplay24m) unsigned long XLastKnownRequestProcessed(4mdisplay24m) Display *4mdisplay24m; 4mdisplay24m Specifies the connection to the X server. __ 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(4mdisplay24m) unsigned long XNextRequest(4mdisplay24m) Display *4mdisplay24m; 4mdisplay24m Specifies the connection to the X server. __ 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(4mdisplay24m) int XProtocolVersion(4mdisplay24m) Display *4mdisplay24m; 4mdisplay24m Specifies the connection to the X server. __ Both return the major version number (11) of the X protocol associated with the connected display. 1m210m 1mXlib C Library X11, Release 6.9/7.00m __ ProtocolRevision(4mdisplay24m) int XProtocolRevision(4mdisplay24m) Display *4mdisplay24m; 4mdisplay24m Specifies the connection to the X server. __ Both return the minor protocol revision number of the X server. __ QLength(4mdisplay24m) int XQLength(4mdisplay24m) Display *4mdisplay24m; 4mdisplay24m Specifies the connection to the X server. __ 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 4mXEventsQueued24m). __ RootWindow(4mdisplay24m, 4mscreen_number24m) Window XRootWindow(4mdisplay24m, 4mscreen_number24m) Display *4mdisplay24m; int 4mscreen_number24m; 4mdisplay24m Specifies the connection to the X server. 4mscreen_number0m Specifies the appropriate screen number on the host server. __ Both return the root window. These are useful with func- tions that need a drawable of a particular screen and for creating top-level windows. 1m220m 1mXlib C Library X11, Release 6.9/7.00m __ ScreenCount(4mdisplay24m) int XScreenCount(4mdisplay24m) Display *4mdisplay24m; 4mdisplay24m Specifies the connection to the X server. __ Both return the number of available screens. __ ServerVendor(4mdisplay24m) char *XServerVendor(4mdisplay24m) Display *4mdisplay24m; 4mdisplay24m Specifies the connection to the X server. __ Both return a pointer to a null-terminated string that pro- vides 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 con- tents of the string are implementation-dependent. __ VendorRelease(4mdisplay24m) int XVendorRelease(4mdisplay24m) Display *4mdisplay24m; 4mdisplay24m Specifies the connection to the X server. __ Both return a number related to a vendors release of the X server. 1m2.2.2. Image Format Functions and Macros0m Applications are required to present data to the X server in a format that the server demands. To help simplify applica- tions, most of the work required to convert the data is pro- vided by Xlib (see sections 8.7 and 16.8). 1m230m 1mXlib C Library X11, Release 6.9/7.00m The 4mXPixmapFormatValues24m structure provides an interface to the pixmap format information that is returned at the time of a connection setup. It contains: __ typedef struct { int depth; int bits_per_pixel; int scanline_pad; } XPixmapFormatValues; __ To obtain the pixmap format information for a given display, use 4mXListPixmapFormats24m. __ XPixmapFormatValues *XListPixmapFormats(4mdisplay24m, 4mcount_return24m) Display *4mdisplay24m; int *4mcount_return24m; 4mdisplay24m Specifies the connection to the X server. 4mcount_return0m Returns the number of pixmap formats that are sup- ported by the display. __ The 4mXListPixmapFormats24m function returns an array of 4mXPixmap-0m 4mFormatValues24m structures that describe the types of Z format images supported by the specified display. If insufficient memory is available, 4mXListPixmapFormats24m returns NULL. To free the allocated storage for the 4mXPixmapFormatValues0m structures, use 4mXFree24m. The following lists the C language macros, their correspond- ing function equivalents that are for other language bind- ings, and what data they both return for the specified server and screen. These are often used by toolkits as well as by simple applications. 1m240m 1mXlib C Library X11, Release 6.9/7.00m __ ImageByteOrder(4mdisplay24m) int XImageByteOrder(4mdisplay24m) Display *4mdisplay24m; 4mdisplay24m Specifies the connection to the X server. __ 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 4mLSB-0m 4mFirst24m or 4mMSBFirst24m. __ BitmapUnit(4mdisplay24m) int XBitmapUnit(4mdisplay24m) Display *4mdisplay24m; 4mdisplay24m Specifies the connection to the X server. __ Both return the size of a bitmaps scanline unit in bits. The scanline is calculated in multiples of this value. __ BitmapBitOrder(4mdisplay24m) int XBitmapBitOrder(4mdisplay24m) Display *4mdisplay24m; 4mdisplay24m Specifies the connection to the X server. __ 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 4mLSBFirst24m or 4mMSBFirst24m. 1m250m 1mXlib C Library X11, Release 6.9/7.00m __ BitmapPad(4mdisplay24m) int XBitmapPad(4mdisplay24m) Display *4mdisplay24m; 4mdisplay24m Specifies the connection to the X server. __ Each scanline must be padded to a multiple of bits returned by this macro or function. __ DisplayHeight(4mdisplay24m, 4mscreen_number24m) int XDisplayHeight(4mdisplay24m, 4mscreen_number24m) Display *4mdisplay24m; int 4mscreen_number24m; 4mdisplay24m Specifies the connection to the X server. 4mscreen_number0m Specifies the appropriate screen number on the host server. __ Both return an integer that describes the height of the screen in pixels. __ DisplayHeightMM(4mdisplay24m, 4mscreen_number24m) int XDisplayHeightMM(4mdisplay24m, 4mscreen_number24m) Display *4mdisplay24m; int 4mscreen_number24m; 4mdisplay24m Specifies the connection to the X server. 4mscreen_number0m Specifies the appropriate screen number on the host server. __ Both return the height of the specified screen in millime- ters. 1m260m 1mXlib C Library X11, Release 6.9/7.00m __ DisplayWidth(4mdisplay24m, 4mscreen_number24m) int XDisplayWidth(4mdisplay24m, 4mscreen_number24m) Display *4mdisplay24m; int 4mscreen_number24m; 4mdisplay24m Specifies the connection to the X server. 4mscreen_number0m Specifies the appropriate screen number on the host server. __ Both return the width of the screen in pixels. __ DisplayWidthMM(4mdisplay24m, 4mscreen_number24m) int XDisplayWidthMM(4mdisplay24m, 4mscreen_number24m) Display *4mdisplay24m; int 4mscreen_number24m; 4mdisplay24m Specifies the connection to the X server. 4mscreen_number0m Specifies the appropriate screen number on the host server. __ Both return the width of the specified screen in millime- ters. 1m2.2.3. Screen Information Macros0m The following lists the C language macros, their correspond- ing function equivalents that are for other language bind- ings, and what data they both can return. These macros or functions all take a pointer to the appropriate screen structure. 1m270m 1mXlib C Library X11, Release 6.9/7.00m __ BlackPixelOfScreen(4mscreen24m) unsigned long XBlackPixelOfScreen(4mscreen24m) Screen *4mscreen24m; 4mscreen24m Specifies the appropriate 4mScreen24m structure. __ Both return the black pixel value of the specified screen. __ WhitePixelOfScreen(4mscreen24m) unsigned long XWhitePixelOfScreen(4mscreen24m) Screen *4mscreen24m; 4mscreen24m Specifies the appropriate 4mScreen24m structure. __ Both return the white pixel value of the specified screen. __ CellsOfScreen(4mscreen24m) int XCellsOfScreen(4mscreen24m) Screen *4mscreen24m; 4mscreen24m Specifies the appropriate 4mScreen24m structure. __ Both return the number of colormap cells in the default col- ormap of the specified screen. __ DefaultColormapOfScreen(4mscreen24m) Colormap XDefaultColormapOfScreen(4mscreen24m) Screen *4mscreen24m; 4mscreen24m Specifies the appropriate 4mScreen24m structure. __ Both return the default colormap of the specified screen. 1m280m 1mXlib C Library X11, Release 6.9/7.00m __ DefaultDepthOfScreen(4mscreen24m) int XDefaultDepthOfScreen(4mscreen24m) Screen *4mscreen24m; 4mscreen24m Specifies the appropriate 4mScreen24m structure. __ Both return the depth of the root window. __ DefaultGCOfScreen(4mscreen24m) GC XDefaultGCOfScreen(4mscreen24m) Screen *4mscreen24m; 4mscreen24m Specifies the appropriate 4mScreen24m structure. __ 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(4mscreen24m) Visual *XDefaultVisualOfScreen(4mscreen24m) Screen *4mscreen24m; 4mscreen24m Specifies the appropriate 4mScreen24m structure. __ Both return the default visual of the specified screen. For information on visual types, see section 3.1. 1m290m 1mXlib C Library X11, Release 6.9/7.00m __ DoesBackingStore(4mscreen24m) int XDoesBackingStore(4mscreen24m) Screen *4mscreen24m; 4mscreen24m Specifies the appropriate 4mScreen24m structure. __ Both return a value indicating whether the screen supports backing stores. The value returned can be one of 4mWhen-0m 4mMapped24m, 4mNotUseful24m, or 4mAlways24m (see section 3.2.4). __ DoesSaveUnders(4mscreen24m) Bool XDoesSaveUnders(4mscreen24m) Screen *4mscreen24m; 4mscreen24m Specifies the appropriate 4mScreen24m structure. __ Both return a Boolean value indicating whether the screen supports save unders. If 4mTrue24m, the screen supports save unders. If 4mFalse24m, the screen does not support save unders (see section 3.2.5). __ DisplayOfScreen(4mscreen24m) Display *XDisplayOfScreen(4mscreen24m) Screen *4mscreen24m; 4mscreen24m Specifies the appropriate 4mScreen24m structure. __ Both return the display of the specified screen. 1m300m 1mXlib C Library X11, Release 6.9/7.00m __ int XScreenNumberOfScreen(4mscreen24m) Screen *4mscreen24m; 4mscreen24m Specifies the appropriate 4mScreen24m structure. __ The 4mXScreenNumberOfScreen24m function returns the screen index number of the specified screen. __ EventMaskOfScreen(4mscreen24m) long XEventMaskOfScreen(4mscreen24m) Screen *4mscreen24m; 4mscreen24m Specifies the appropriate 4mScreen24m structure. __ Both return the event mask of the root window for the speci- fied screen at connection setup time. __ WidthOfScreen(4mscreen24m) int XWidthOfScreen(4mscreen24m) Screen *4mscreen24m; 4mscreen24m Specifies the appropriate 4mScreen24m structure. __ Both return the width of the specified screen in pixels. __ HeightOfScreen(4mscreen24m) int XHeightOfScreen(4mscreen24m) Screen *4mscreen24m; 4mscreen24m Specifies the appropriate 4mScreen24m structure. __ Both return the height of the specified screen in pixels. 1m310m 1mXlib C Library X11, Release 6.9/7.00m __ WidthMMOfScreen(4mscreen24m) int XWidthMMOfScreen(4mscreen24m) Screen *4mscreen24m; 4mscreen24m Specifies the appropriate 4mScreen24m structure. __ Both return the width of the specified screen in millime- ters. __ HeightMMOfScreen(4mscreen24m) int XHeightMMOfScreen(4mscreen24m) Screen *4mscreen24m; 4mscreen24m Specifies the appropriate 4mScreen24m structure. __ Both return the height of the specified screen in millime- ters. __ MaxCmapsOfScreen(4mscreen24m) int XMaxCmapsOfScreen(4mscreen24m) Screen *4mscreen24m; 4mscreen24m Specifies the appropriate 4mScreen24m structure. __ Both return the maximum number of installed colormaps sup- ported by the specified screen (see section 9.3). 1m320m 1mXlib C Library X11, Release 6.9/7.00m __ MinCmapsOfScreen(4mscreen24m) int XMinCmapsOfScreen(4mscreen24m) Screen *4mscreen24m; 4mscreen24m Specifies the appropriate 4mScreen24m structure. __ Both return the minimum number of installed colormaps sup- ported by the specified screen (see section 9.3). __ PlanesOfScreen(4mscreen24m) int XPlanesOfScreen(4mscreen24m) Screen *4mscreen24m; 4mscreen24m Specifies the appropriate 4mScreen24m structure. __ Both return the depth of the root window. __ RootWindowOfScreen(4mscreen24m) Window XRootWindowOfScreen(4mscreen24m) Screen *4mscreen24m; 4mscreen24m Specifies the appropriate 4mScreen24m structure. __ Both return the root window of the specified screen. 1m2.3. Generating a NoOperation Protocol Request0m To execute a 4mNoOperation24m protocol request, use 4mXNoOp24m. __ XNoOp(4mdisplay24m) Display *4mdisplay24m; 4mdisplay24m Specifies the connection to the X server. __ The 4mXNoOp24m function sends a 4mNoOperation24m protocol request to 1m330m 1mXlib C Library X11, Release 6.9/7.00m the X server, thereby exercising the connection. 1m2.4. Freeing Client-Created Data0m To free in-memory data that was created by an Xlib function, use 4mXFree24m. __ XFree(4mdata24m) void *4mdata24m; 4mdata24m Specifies the data that is to be freed. __ The 4mXFree24m 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. 1m2.5. Closing the Display0m To close a display or disconnect from the X server, use 4mXCloseDisplay24m. __ XCloseDisplay(4mdisplay24m) Display *4mdisplay24m; 4mdisplay24m Specifies the connection to the X server. __ The 4mXCloseDisplay24m function closes the connection to the X server for the display specified in the 4mDisplay24m structure and destroys all windows, resource IDs (4mWindow24m, 4mFont24m, 4mPixmap24m, 4mColormap24m, 4mCursor24m, and 4mGContext24m), or other resources that the client has created on this display, unless the close-down mode of the resource has been changed (see 4mXSet-0m 4mCloseDownMode24m). Therefore, these windows, resource IDs, and other resources should never be referenced again or an error will be generated. Before exiting, you should call 4mXCloseDisplay24m explicitly so that any pending errors are reported as 4mXCloseDisplay24m performs a final 4mXSync24m operation. 4mXCloseDisplay24m can generate a 4mBadGC24m error. Xlib provides a function to permit the resources owned by a client to survive after the clients connection is closed. To change a clients close-down mode, use 4mXSetCloseDownMode24m. 1m340m 1mXlib C Library X11, Release 6.9/7.00m __ XSetCloseDownMode(4mdisplay24m, 4mclose_mode24m) Display *4mdisplay24m; int 4mclose_mode24m; 4mdisplay24m Specifies the connection to the X server. 4mclose_mode0m Specifies the client close-down mode. You can pass 4mDestroyAll24m, 4mRetainPermanent24m, or 4mRetainTempo-0m 4mrary24m. __ The 4mXSetCloseDownMode24m defines what will happen to the clients resources at connection close. A connection starts in 4mDestroyAll24m mode. For information on what happens to the clients resources when the close_mode argument is 4mRetain-0m 4mPermanent24m or 4mRetainTemporary24m, see section 2.6. 4mXSetCloseDownMode24m can generate a 4mBadValue24m error. 1m2.6. Using X Server Connection Close Operations0m When the X servers connection to a client is closed either by an explicit call to 4mXCloseDisplay24m or by a process that exits, the X server performs the following automatic opera- tions: It disowns all selections owned by the client (see 4mXSetSelectionOwner24m). It performs an 4mXUngrabPointer24m and 4mXUngrabKeyboard24m if the client has actively grabbed the pointer or the key- board. It performs an 4mXUngrabServer24m if the client has grabbed the server. It releases all passive grabs made by the client. It marks all resources (including colormap entries) allocated by the client either as permanent or tempo- rary, depending on whether the close-down mode is 4mRetainPermanent24m or 4mRetainTemporary24m. However, this does not prevent other client applications from explicitly destroying the resources (see 4mXSetCloseDownMode24m). When the close-down mode is 4mDestroyAll24m, the X server destroys all of a clients resources as follows: It examines each window in the clients save-set to determine if it is an inferior (subwindow) of a window created by the client. (The save-set is a list of 1m350m 1mXlib C Library X11, Release 6.9/7.00m other clients windows that are referred to as save-set windows.) If so, the X server reparents the save-set window to the closest ancestor so that the save-set window is not an inferior of a window created by the client. The reparenting leaves unchanged the absolute coordinates (with respect to the root window) of the upper-left outer corner of the save-set window. It performs a 4mMapWindow24m request on the save-set window if the save-set window is unmapped. The X server does this even if the save-set window was not an inferior of a window created by the client. It destroys all windows created by the client. It performs the appropriate free request on each non- window resource created by the client in the server (for example, 4mFont24m, 4mPixmap24m, 4mCursor24m, 4mColormap24m, and 4mGCon-0m 4mtext24m). It frees all colors and colormap entries allocated by a client application. Additional processing occurs when the last connection to the X server closes. An X server goes through a cycle of having no connections and having some connections. When the last connection to the X server closes as a result of a connec- tion closing with the close_mode of 4mDestroyAll24m, the X server does the following: It resets its state as if it had just been started. The X server begins by destroying all lingering resources from clients that have terminated in 4mRetain-0m 4mPermanent24m or 4mRetainTemporary24m mode. It deletes all but the predefined atom identifiers. It deletes all properties on all root windows (see sec- tion 4.3). It resets all device maps and attributes (for example, key click, bell volume, and acceleration) as well as the access control list. It restores the standard root tiles and cursors. It restores the default font path. It restores the input focus to state 4mPointerRoot24m. However, the X server does not reset if you close a connec- tion with a close-down mode set to 4mRetainPermanent24m or 4mRetainTemporary24m. 1m360m 1mXlib C Library X11, Release 6.9/7.00m 1m2.7. Using Xlib with Threads0m On systems that have threads, support may be provided to permit multiple threads to use Xlib concurrently. To initialize support for concurrent threads, use 4mXInit-0m 4mThreads24m. __ Status XInitThreads(); __ The 4mXInitThreads24m function initializes Xlib support for con- current threads. This function must be the first Xlib func- tion 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 pro- grams not call this function. To lock a display across several Xlib calls, use 4mXLockDis-0m 4mplay24m. __ void XLockDisplay(4mdisplay24m) Display *4mdisplay24m; 4mdisplay24m Specifies the connection to the X server. __ The 4mXLockDisplay24m 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 4mXLockDisplay24m work correctly; the display will not actually be unlocked until 4mXUnlockDis-0m 4mplay24m has been called the same number of times as 4mXLockDis-0m 4mplay24m. This function has no effect unless Xlib was success- fully initialized for threads using 4mXInitThreads24m. To unlock a display, use 4mXUnlockDisplay24m. 1m370m 1mXlib C Library X11, Release 6.9/7.00m __ void XUnlockDisplay(4mdisplay24m) Display *4mdisplay24m; 4mdisplay24m Specifies the connection to the X server. __ The 4mXUnlockDisplay24m 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 4mXLockDisplay24m has been called multiple times by a thread, then 4mXUnlockDisplay24m must be called an equal number of times before the display is actually unlocked. This function has no effect unless Xlib was successfully initial- ized for threads using 4mXInitThreads24m. 1m2.8. Using Internal Connections0m 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 dis- plays, or that use displays in combination with other inputs, need to obtain these additional connections to cor- rectly 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 4mXAddConnec-0m 4mtionWatch24m. 1m380m 1mXlib C Library X11, Release 6.9/7.00m __ typedef void (*XConnectionWatchProc)(4mdisplay24m, 4mclient_data24m, 4mfd24m, 4mopening24m, 4mwatch_data24m) Display *4mdisplay24m; XPointer 4mclient_data24m; int 4mfd24m; Bool 4mopening24m; XPointer *4mwatch_data24m; Status XAddConnectionWatch(4mdisplay24m, 4mprocedure24m, 4mclient_data24m) Display *4mdisplay24m; XWatchProc 4mprocedure24m; XPointer 4mclient_data24m; 4mdisplay24m Specifies the connection to the X server. 4mprocedure24m Specifies the procedure to be called. 4mclient_data0m Specifies the additional client data. __ The 4mXAddConnectionWatch24m 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 dis- play, 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 pri- vate watch data. If opening is 4mTrue24m, 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 4mFalse24m, 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 regis- tered procedure will immediately be called for each of them, before 4mXAddConnectionWatch24m returns. 4mXAddConnectionWatch0m 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 4mXLockDisplay24m. To stop tracking internal connections for a display, use 4mXRemoveConnectionWatch24m. 1m390m 1mXlib C Library X11, Release 6.9/7.00m __ Status XRemoveConnectionWatch(4mdisplay24m, 4mprocedure24m, 4mclient_data24m) Display *4mdisplay24m; XWatchProc 4mprocedure24m; XPointer 4mclient_data24m; 4mdisplay24m Specifies the connection to the X server. 4mprocedure24m Specifies the procedure to be called. 4mclient_data0m Specifies the additional client data. __ The 4mXRemoveConnectionWatch24m 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 4mXProcessIn-0m 4mternalConnection24m. __ void XProcessInternalConnection(4mdisplay24m, 4mfd24m) Display *4mdisplay24m; int 4mfd24m; 4mdisplay24m Specifies the connection to the X server. 4mfd24m Specifies the file descriptor. __ The 4mXProcessInternalConnection24m 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, 4mselect24m or 4mpoll24m) has indicated that input is available; otherwise, the effect is not defined. To obtain all of the current internal connections for a dis- play, use 4mXInternalConnectionNumbers24m. 1m400m 1mXlib C Library X11, Release 6.9/7.00m __ Status XInternalConnectionNumbers(4mdisplay24m, 4mfd_return24m, 4mcount_return24m) Display *4mdisplay24m; int **4mfd_return24m; int *4mcount_return24m; 4mdisplay24m Specifies the connection to the X server. 4mfd_return24m Returns the file descriptors. 4mcount_return0m Returns the number of file descriptors. __ The 4mXInternalConnectionNumbers24m 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 4mXFree24m. This functions returns a nonzero status if the list is successfully allo- cated; otherwise, it returns zero. 1m410m 1mXlib C Library X11, Release 6.9/7.00m 1mChapter 30m 1mWindow Functions0m In the X Window System, a window is a rectangular area on the screen that lets you view graphic output. Client appli- cations 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 4mXOpenDis-0m 4mplay24m. This chapter begins with a discussion of visual types and window attributes. The chapter continues with a discus- sion of the Xlib functions you can use to: Create windows Destroy windows Map windows Unmap windows Configure windows Change window stacking order Change window attributes 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 man- agers 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. 1m3.1. Visual Types0m 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 1m420m 1mXlib C Library X11, Release 6.9/7.00m 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 4mVisual24m structure that contains informa- tion about the possible color mapping. The visual utility functions (see section 16.7) use an 4mXVisualInfo24m 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 col- ormap_size. The class member specifies one of the possible visual classes of the screen and can be 4mStaticGray24m, 4mStatic-0m 4mColor24m, 4mTrueColor24m, 4mGrayScale24m, 4mPseudoColor24m, or 4mDirectColor24m. 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 sepa- rate 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 hard- ware, and not at all on other hardware. The visual types affect the colormap and the RGB values in the following ways: For 4mPseudoColor24m, a pixel value indexes a colormap to produce independent RGB values, and the RGB values can be changed dynamically. 4mGrayScale24m is treated the same way as 4mPseudoColor24m except that the primary that drives the screen is undefined. 1m430m 1mXlib C Library X11, Release 6.9/7.00m Thus, the client should always store the same value for red, green, and blue in the colormaps. For 4mDirectColor24m, a pixel value is decomposed into sepa- rate RGB subfields, and each subfield separately indexes the colormap for the corresponding value. The RGB values can be changed dynamically. 4mTrueColor24m is treated the same way as 4mDirectColor24m except that the colormap has predefined, read-only RGB values. These RGB values are server dependent but provide lin- ear or near-linear ramps in each primary. 4mStaticColor24m is treated the same way as 4mPseudoColor0m except that the colormap has predefined, read-only, server-dependent RGB values. 4mStaticGray24m is treated the same way as 4mStaticColor0m except that the RGB values are equal for any single pixel value, thus resulting in shades of gray. 4mStat-0m 4micGray24m with a two-entry colormap can be thought of as monochrome. The red_mask, green_mask, and blue_mask members are only defined for 4mDirectColor24m and 4mTrueColor24m. Each has one con- tiguous 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 4mDirectColor24m and 4mTrueColor24m, this is the size of an individual pixel subfield. To obtain the visual ID from a 4mVisual24m, use 4mXVisualIDFromVi-0m 4msual24m. __ VisualID XVisualIDFromVisual(4mvisual24m) Visual *4mvisual24m; 4mvisual24m Specifies the visual type. __ The 4mXVisualIDFromVisual24m function returns the visual ID for the specified visual type. 1m3.2. Window Attributes0m All 4mInputOutput24m 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 1m440m 1mXlib C Library X11, Release 6.9/7.00m 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 win- dow, 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 4mInputOutput24m and 4mInputOnly24m windows have the following common attributes, which are the only attributes of an 4mInpu-0m 4mtOnly24m window: win-gravity event-mask do-not-propagate-mask override-redirect cursor If you specify any other attributes for an 4mInputOnly24m window, a 4mBadMatch24m error results. 4mInputOnly24m windows are used for controlling input events in situations where 4mInputOutput24m windows are unnecessary. 4mInpu-0m 4mtOnly24m windows are invisible; can only be used to control such things as cursors, input event generation, and grab- bing; and cannot be used in any graphics requests. Note that 4mInputOnly24m windows cannot have 4mInputOutput24m 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 4mParentRelative24m, the parents 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 win- dow long before it is mapped to the screen. When a window is eventually mapped to the screen (using 4mXMapWindow24m), the X server generates an 4mExpose24m event for the window if backing store has not been maintained. 1m450m 1mXlib C Library X11, Release 6.9/7.00m 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 com- mand to do so. Instead, either your program should use the space given to it, or if the space is too small for any use- ful work, your program might ask the user to resize the win- dow. 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 4mXSetWindowAttributes24m structure and OR in the corre- sponding value bitmask in your subsequent calls to 4mXCre-0m 4mateWindow24m and 4mXChangeWindowAttributes24m, or use one of the other convenience functions that set the appropriate attribute. The symbols for the value mask bits and the 4mXSetWindowAttributes24m structure are: 1m460m 1mXlib C Library X11, Release 6.9/7.00m __ /* Window attribute value mask bits */ #define 4mCWBackPixmap24m (1L<<0) #define 4mCWBackPixel24m (1L<<1) #define 4mCWBorderPixmap24m (1L<<2) #define 4mCWBorderPixel24m (1L<<3) #define 4mCWBitGravity24m (1L<<4) #define 4mCWWinGravity24m (1L<<5) #define 4mCWBackingStore24m (1L<<6) #define 4mCWBackingPlanes24m (1L<<7) #define 4mCWBackingPixel24m (1L<<8) #define 4mCWOverrideRedirect24m (1L<<9) #define 4mCWSaveUnder24m (1L<<10) #define 4mCWEventMask24m (1L<<11) #define 4mCWDontPropagate24m (1L<<12) #define 4mCWColormap24m (1L<<13) #define 4mCWCursor24m (1L<<14) /* Values */ typedef struct { Pixmap background_pixmap;/* background, None, or ParentRelative */ unsigned long background_pixel;/* background pixel */ Pixmap border_pixmap; /* border of the window or CopyFromParent */ unsigned long border_pixel;/* border pixel value */ int bit_gravity; /* one of bit gravity values */ int win_gravity; /* one of the window gravity values */ int backing_store; /* NotUseful, WhenMapped, Always */ unsigned long backing_planes;/* planes to be preserved if possible */ unsigned long backing_pixel;/* value to use in restoring planes */ Bool save_under; /* should bits under be saved? (popups) */ long event_mask; /* set of events that should be saved */ long do_not_propagate_mask;/* set of events that should not propagate */ Bool override_redirect; /* boolean value for override_redirect */ Colormap colormap; /* color map to be associated with window */ Cursor cursor; /* cursor to be displayed (or None) */ } XSetWindowAttributes; __ The following lists the defaults for each window attribute and indicates whether the attribute is applicable to 4mInputOutput24m and 4mInputOnly24m windows: ------------------------------------------------------------- 1mAttribute Default 4m22mInputOut-24m 4mInpu-0m 4mput24m 4mtOnly0m ------------------------------------------------------------- background-pixmap 4mNone24m Yes No background-pixel Undefined Yes No 1m470m 1mXlib C Library X11, Release 6.9/7.00m ------------------------------------------------------------- 1mAttribute Default 4m22mInputOut-24m 4mInpu-0m 4mput24m 4mtOnly0m ------------------------------------------------------------- border-pixmap 4mCopyFromPar-24m Yes No 4ment0m border-pixel Undefined Yes No bit-gravity 4mForgetGravity24m Yes No win-gravity 4mNorthWest-24m Yes Yes 4mGravity0m backing-store 4mNotUseful24m Yes No backing-planes All ones Yes No backing-pixel zero Yes No save-under 4mFalse24m Yes No event-mask empty set Yes Yes do-not-propagate-mask empty set Yes Yes override-redirect 4mFalse24m Yes Yes colormap 4mCopyFromPar-24m Yes No 4ment0m cursor 4mNone24m Yes Yes ------------------------------------------------------------- 1m3.2.1. Background Attribute0m Only 4mInputOutput24m windows can have a background. You can set the background of an 4mInputOutput24m window by using a pixel or a pixmap. The background-pixmap attribute of a window specifies the pixmap to be used for a windows background. This pixmap can be of any size, although some sizes may be faster than others. The background-pixel attribute of a window speci- fies a pixel value used to paint a windows background in a single color. You can set the background-pixmap to a pixmap, 4mNone0m (default), or 4mParentRelative24m. 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 back- ground-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 4mBadMatch24m error results. If you set background- pixmap to 4mNone24m, the window has no defined background. If you set the background-pixmap to 4mParentRelative24m: The parent windows background-pixmap is used. The child window, however, must have the same depth as its 1m480m 1mXlib C Library X11, Release 6.9/7.00m parent, or a 4mBadMatch24m error results. If the parent window has a background-pixmap of 4mNone24m, the window also has a background-pixmap of 4mNone24m. A copy of the parent windows background-pixmap is not made. The parents background-pixmap is examined each time the child windows background-pixmap is required. The background tile origin always aligns with the par- ent windows background tile origin. If the back- ground-pixmap is not 4mParentRelative24m, the background tile origin is the child windows origin. Setting a new background, whether by setting background- pixmap or background-pixel, overrides any previous back- ground. 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 main- taining backing store, the server automatically tiles the regions with the windows background unless the window has a background of 4mNone24m. If the background is 4mNone24m, 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. 4mExpose24m events are then generated for the regions, even if the background-pixmap is 4mNone24m (see section 10.9). 1m3.2.2. Border Attribute0m Only 4mInputOutput24m windows can have a border. You can set the border of an 4mInputOutput24m window by using a pixel or a pixmap. The border-pixmap attribute of a window specifies the pixmap to be used for a windows border. The border-pixel attribute of a window specifies a pixmap of undefined size filled with that pixel be used for a windows 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 ori- gin. You can also set the border-pixmap to a pixmap of any size (some may be faster than others) or to 4mCopyFromParent0m (default). You can set the border-pixel to any pixel value 1m490m 1mXlib C Library X11, Release 6.9/7.00m (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 4mBadMatch24m error results. If you set the border-pixmap to 4mCopyFromParent24m, the parent windows border-pixmap is copied. Subsequent changes to the parent windows border attribute do not affect the child window. However, the child window must have the same depth as the parent window, or a 4mBadMatch0m 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 windows 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. 1m3.2.3. Gravity Attributes0m The bit gravity of a window defines which region of the win- dow should be retained when an 4mInputOutput24m window is resized. The default value for the bit-gravity attribute is 4mForgetGravity24m. The window gravity of a window allows you to define how the 4mInputOutput24m or 4mInputOnly24m window should be repositioned if its parent is resized. The default value for the win-gravity attribute is 4mNorthWestGravity24m. 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 win- dow. 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 recon- figured (depending on their win-gravity). For a change of width and height, the (x, y) pairs are defined: ---------------------------------------- 1mGravity Direction Coordinates0m ---------------------------------------- 4mNorthWestGravity24m (0, 0) 4mNorthGravity24m (Width/2, 0) 4mNorthEastGravity24m (Width, 0) 1m500m 1mXlib C Library X11, Release 6.9/7.00m 4mWestGravity24m (0, Height/2) 4mCenterGravity24m (Width/2, Height/2) 4mEastGravity24m (Width, Height/2) 4mSouthWestGravity24m (0, Height) 4mSouthGravity24m (Width/2, Height) 4mSouthEastGravity24m (Width, Height) ---------------------------------------- When a window with one of these bit-gravity values is resized, the corresponding pair defines the change in posi- tion of each pixel in the window. When a window with one of these win-gravities has its parent window resized, the cor- responding pair defines the change in position of the window within the parent. When a window is so repositioned, a 4mGravityNotify24m event is generated (see section 10.10.5). A bit-gravity of 4mStaticGravity24m 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 4mStaticGravity24m still only takes effect when the width or height of the window is changed, not when the window is moved. A bit-gravity of 4mForgetGravity24m indicates that the windows 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 4mExpose24m 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 4mExpose0m events. The contents and borders of inferiors are not affected by their parents bit-gravity. A server is permitted to ignore the specified bit-gravity and use 4mForget24m instead. A win-gravity of 4mUnmapGravity24m is like 4mNorthWestGravity24m (the window is not moved), except the child is also unmapped when the parent is resized, and an 4mUnmapNotify24m event is gener- ated. 1m3.2.4. Backing Store Attribute0m Some implementations of the X server may choose to maintain the contents of 4mInputOutput24m windows. If the X server main- tains 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 4mNotUseful24m (default), 4mWhenMapped24m, or 4mAlways24m. 1m510m 1mXlib C Library X11, Release 6.9/7.00m A backing-store attribute of 4mNotUseful24m advises the X server that maintaining contents is unnecessary, although some X implementations may still choose to maintain contents and, therefore, not generate 4mExpose24m events. A backing-store attribute of 4mWhenMapped24m advises the X server that maintain- ing contents of obscured regions when the window is mapped would be beneficial. In this case, the server may generate an 4mExpose24m event when the window is created. A backing-store attribute of 4mAlways24m advises the X server that maintaining contents even when the window is unmapped would be benefi- cial. 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 windows contents, 4mExpose24m events normally are not generated, but the X server may stop main- taining 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. 1m3.2.5. Save Under Flag0m Some server implementations may preserve contents of 4mInputOutput24m windows under other 4mInputOutput24m 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 4mTrue24m or 4mFalse24m (default). If save-under is 4mTrue24m, the X server is advised that, when this window is mapped, saving the contents of windows it obscures would be beneficial. 1m3.2.6. Backing Planes and Backing Pixel Attributes0m You can set backing planes to indicate (with bits set to 1) which bit planes of an 4mInputOutput24m 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 speci- fied bit planes in the backing store or the save under and is free to regenerate the remaining planes with the speci- fied 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 1m520m 1mXlib C Library X11, Release 6.9/7.00m of off-screen memory required to store your window. 1m3.2.7. Event Mask and Do Not Propagate Mask Attributes0m The event mask defines which events the client is interested in for this 4mInputOutput24m or 4mInputOnly24m 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 4mNoEventMask24m (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 4mInputOutput24m or 4mInputOnly0m window. The do-not-propagate-mask is the bitwise inclusive OR of zero or more of the following masks: 4mKeyPress24m, 4mKeyRe-0m 4mlease24m, 4mButtonPress24m, 4mButtonRelease24m, 4mPointerMotion24m, 4mBut-0m 4mton1Motion24m, 4mButton2Motion24m, 4mButton3Motion24m, 4mButton4Motion24m, 4mButton5Motion24m, and 4mButtonMotion24m. You can specify that all events are propagated by setting 4mNoEventMask24m (default). 1m3.2.8. Override Redirect Flag0m To control window placement or to add decoration, a window manager often needs to intercept (redirect) any map or con- figure request. Pop-up windows, however, often need to be mapped without a window manager getting in the way. To con- trol whether an 4mInputOutput24m or 4mInputOnly24m window is to ignore these structure control facilities, use the override-redi- rect flag. The override-redirect flag specifies whether map and config- ure requests on this window should override a 4mSubstructur-0m 4meRedirectMask24m on the parent. You can set the override-redi- rect flag to 4mTrue24m or 4mFalse24m (default). Window managers use this information to avoid tampering with pop-up windows (see also chapter 14). 1m3.2.9. Colormap Attribute0m The colormap attribute specifies which colormap best reflects the true colors of the 4mInputOutput24m window. The colormap must have the same visual type as the window, or a 4mBadMatch24m error results. X servers capable of supporting multiple hardware colormaps can use this information, and window managers can use it for calls to 4mXInstallColormap24m. You can set the colormap attribute to a colormap or to 4mCopy-0m 4mFromParent24m (default). If you set the colormap to 4mCopyFromParent24m, the parent win- dows colormap is copied and used by its child. However, the child window must have the same visual type as the par- ent, or a 4mBadMatch24m error results. The parent window must not have a colormap of 4mNone24m, or a 4mBadMatch24m error results. 1m530m 1mXlib C Library X11, Release 6.9/7.00m 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 windows colormap attribute do not affect the child window. 1m3.2.10. Cursor Attribute0m The cursor attribute specifies which cursor is to be used when the pointer is in the 4mInputOutput24m or 4mInputOnly24m window. You can set the cursor to a cursor or 4mNone24m (default). If you set the cursor to 4mNone24m, the parents cursor is used when the pointer is in the 4mInputOutput24m or 4mInputOnly24m window, and any change in the parents cursor will cause an immedi- ate change in the displayed cursor. By calling 4mXFreeCursor24m, the cursor can be freed immediately as long as no further explicit reference to it is made. 1m3.3. Creating Windows0m Xlib provides basic ways for creating windows, and toolkits often supply higher-level functions specifically for creat- ing 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: You must never fight with the window manager for the size or placement of your top-level window. You must be able to deal with whatever size window you get, even if this means that your application just prints a message like Please make me bigger in its window. You should only attempt to resize or move top-level windows in direct response to a user request. If a request to change the size of a top-level window fails, you must be prepared to live with what you get. You are free to resize or move the children of top-level windows as necessary. (Toolkits often have facilities for automatic relayout.) If you do not use a toolkit that automatically sets standard window properties, you should set these prop- erties for top-level windows before mapping them. 1m540m 1mXlib C Library X11, Release 6.9/7.00m For further information, see chapter 14 and the 4mInter-Client0m 4mCommunication24m 4mConventions24m 4mManual24m. 4mXCreateWindow24m is the more general function that allows you to set specific window attributes when you create a window. 4mXCreateSimpleWindow24m creates a window that inherits its attributes from its parent window. The X server acts as if 4mInputOnly24m windows do not exist for the purposes of graphics requests, exposure processing, and 4mVisibilityNotify24m events. An 4mInputOnly24m window cannot be used as a drawable (that is, as a source or destination for graphics requests). 4mInputOnly24m and 4mInputOutput24m windows act identically in other respects (properties, grabs, input con- trol, and so on). Extension packages can define other classes of windows. To create an unmapped window and set its window attributes, use 4mXCreateWindow24m. 1m550m 1mXlib C Library X11, Release 6.9/7.00m __ Window XCreateWindow(4mdisplay24m, 4mparent24m, 4mx24m, 4my24m, 4mwidth24m, 4mheight24m, 4mborder_width24m, 4mdepth24m, 4mclass24m, 4mvisual24m, 4mvaluemask24m, 4mattributes24m) Display *4mdisplay24m; Window 4mparent24m; int 4mx24m, 4my24m; unsigned int 4mwidth24m, 4mheight24m; unsigned int 4mborder_width24m; int 4mdepth24m; unsigned int 4mclass24m; Visual *4mvisual24m; unsigned long 4mvaluemask24m; XSetWindowAttributes *4mattributes24m; 4mdisplay24m Specifies the connection to the X server. 4mparent24m Specifies the parent window. 4mx0m 4my24m Specify the x and y coordinates, which are the top-left outside corner of the created windows borders and are relative to the inside of the par- ent windows borders. 4mwidth0m 4mheight24m Specify the width and height, which are the cre- ated windows inside dimensions and do not include the created windows borders. The dimensions must be nonzero, or a 4mBadValue24m error results. 4mborder_width0m Specifies the width of the created windows border in pixels. 4mdepth24m Specifies the windows depth. A depth of 4mCopy-0m 4mFromParent24m means the depth is taken from the par- ent. 4mclass24m Specifies the created windows class. You can pass 4mInputOutput24m, 4mInputOnly24m, or 4mCopyFromParent24m. A class of 4mCopyFromParent24m means the class is taken from the parent. 4mvisual24m Specifies the visual type. A visual of 4mCopy-0m 4mFromParent24m means the visual type is taken from the parent. 4mvaluemask24m Specifies which window attributes are defined in 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. 1m560m 1mXlib C Library X11, Release 6.9/7.00m 4mattributes0m Specifies 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 4mXCreateWindow24m function creates an unmapped subwindow for a specified parent window, returns the window ID of the cre- ated window, and causes the X server to generate a 4mCreateNo-0m 4mtify24m 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 cor- ner. 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 4mInputOnly24m window must be zero, or a 4mBadMatch24m error results. For class 4mInputOutput24m, the visual type and depth must be a combination supported for the screen, or a 4mBadMatch24m error results. The depth need not be the same as the parent, but the parent must not be a window of class 4mInputOnly24m, or a 4mBadMatch24m error results. For an 4mInputOnly24m window, the depth must be zero, and the visual must be one supported by the screen. If either condition is not met, a 4mBadMatch24m error results. The parent window, how- ever, may have any depth and class. If you specify any invalid window attribute for a window, a 4mBadMatch24m error results. The created window is not yet displayed (mapped) on the users display. To display the window, call 4mXMapWindow24m. The new window initially uses the same cursor as its parent. A new cursor can be defined for the new window by calling 4mXDefineCursor24m. 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. 4mXCreateWindow24m can generate 4mBadAlloc24m, 4mBadColor24m, 4mBadCursor24m, 4mBadMatch24m, 4mBadPixmap24m, 4mBadValue24m, and 4mBadWindow24m errors. To create an unmapped 4mInputOutput24m subwindow of a given par- ent window, use 4mXCreateSimpleWindow24m. 1m570m 1mXlib C Library X11, Release 6.9/7.00m __ Window XCreateSimpleWindow(4mdisplay24m, 4mparent24m, 4mx24m, 4my24m, 4mwidth24m, 4mheight24m, 4mborder_width24m, 4mborder24m, 4mbackground24m) Display *4mdisplay24m; Window 4mparent24m; int 4mx24m, 4my24m; unsigned int 4mwidth24m, 4mheight24m; unsigned int 4mborder_width24m; unsigned long 4mborder24m; unsigned long 4mbackground24m; 4mdisplay24m Specifies the connection to the X server. 4mparent24m Specifies the parent window. 4mx0m 4my24m Specify the x and y coordinates, which are the top-left outside corner of the new windows bor- ders and are relative to the inside of the parent windows borders. 4mwidth0m 4mheight24m Specify the width and height, which are the cre- ated windows inside dimensions and do not include the created windows borders. The dimensions must be nonzero, or a 4mBadValue24m error results. 4mborder_width0m Specifies the width of the created windows border in pixels. 4mborder24m Specifies the border pixel value of the window. 4mbackground0m Specifies the background pixel value of the win- dow. __ The 4mXCreateSimpleWindow24m function creates an unmapped 4mInputOutput24m subwindow for a specified parent window, returns the window ID of the created window, and causes the X server to generate a 4mCreateNotify24m event. The created window is placed on top in the stacking order with respect to sib- lings. Any part of the window that extends outside its par- ent window is clipped. The border_width for an 4mInputOnly0m window must be zero, or a 4mBadMatch24m error results. 4mXCreateS-0m 4mimpleWindow24m inherits its depth, class, and visual from its parent. All other window attributes, except background and border, have their default values. 4mXCreateSimpleWindow24m can generate 4mBadAlloc24m, 4mBadMatch24m, 4mBad-0m 4mValue24m, and 4mBadWindow24m errors. 1m580m 1mXlib C Library X11, Release 6.9/7.00m 1m3.4. Destroying Windows0m 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 4mXDestroy-0m 4mWindow24m. __ XDestroyWindow(4mdisplay24m, 4mw24m) Display *4mdisplay24m; Window 4mw24m; 4mdisplay24m Specifies the connection to the X server. 4mw24m Specifies the window. __ The 4mXDestroyWindow24m function destroys the specified window as well as all of its subwindows and causes the X server to generate a 4mDestroyNotify24m 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 4mDestroyNotify24m events is such that for any given window being destroyed, 4mDestroyNotify24m is generated on any inferiors of the window before being generated on the window itself. The ordering among siblings and across sub- hierarchies is not otherwise constrained. If the window you specified is a root window, no windows are destroyed. Destroying a mapped window will generate 4mExpose24m events on other windows that were obscured by the window being destroyed. 4mXDestroyWindow24m can generate a 4mBadWindow24m error. To destroy all subwindows of a specified window, use 4mXDe-0m 4mstroySubwindows24m. __ XDestroySubwindows(4mdisplay24m, 4mw24m) Display *4mdisplay24m; Window 4mw24m; 4mdisplay24m Specifies the connection to the X server. 4mw24m Specifies the window. __ The 4mXDestroySubwindows24m function destroys all inferior win- dows of the specified window, in bottom-to-top stacking 1m590m 1mXlib C Library X11, Release 6.9/7.00m order. It causes the X server to generate a 4mDestroyNotify0m event for each window. If any mapped subwindows were actu- ally destroyed, 4mXDestroySubwindows24m causes the X server to generate 4mExpose24m 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. 4mXDestroySubwindows24m can generate a 4mBadWindow24m error. 1m3.5. Mapping Windows0m A window is considered mapped if an 4mXMapWindow24m call has been made on it. It may not be visible on the screen for one of the following reasons: It is obscured by another opaque window. One of its ancestors is not mapped. It is entirely clipped by an ancestor. 4mExpose24m events are generated for the window when part or all of it becomes visible on the screen. A client receives the 4mExpose24m 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 sub- windows. If 4mSubstructureRedirectMask24m 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 4mMapRequest0m event. However, if the override-redirect flag on the child had been set to 4mTrue24m (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 4mSub-0m 4mstructureRedirectMask24m. Similarly, a single client can select for 4mResizeRedirectMask0m on a parent window. Then, any attempt to resize the window by another client is suppressed, and the client receives a 4mResizeRequest24m event. To map a given window, use 4mXMapWindow24m. 1m600m 1mXlib C Library X11, Release 6.9/7.00m __ XMapWindow(4mdisplay24m, 4mw24m) Display *4mdisplay24m; Window 4mw24m; 4mdisplay24m Specifies the connection to the X server. 4mw24m Specifies the window. __ The 4mXMapWindow24m function maps the window and all of its sub- windows 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 4mFalse24m and if some other client has selected 4mSubstructureRedirectMask24m on the parent window, then the X server generates a 4mMapRequest0m event, and the 4mXMapWindow24m function does not map the window. Otherwise, the window is mapped, and the X server generates a 4mMapNotify24m 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 windows background is undefined, the existing screen contents are not altered, and the X server generates zero or more 4mExpose24m events. If backing-store was maintained while the window was unmapped, no 4mExpose24m 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 expo- sure take place for any newly viewable inferiors. If the window is an 4mInputOutput24m window, 4mXMapWindow24m generates 4mExpose24m events on each 4mInputOutput24m 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 4mExpose24m events and then map the window, so the client processes input events as usual. The event list will include 4mExpose24m for each window that has appeared on the screen. The clients normal response to an 4mExpose24m event should be to repaint the window. This method usually leads to simpler programs and to proper interaction with window managers. 4mXMapWindow24m can generate a 4mBadWindow24m error. 1m610m 1mXlib C Library X11, Release 6.9/7.00m To map and raise a window, use 4mXMapRaised24m. __ XMapRaised(4mdisplay24m, 4mw24m) Display *4mdisplay24m; Window 4mw24m; 4mdisplay24m Specifies the connection to the X server. 4mw24m Specifies the window. __ The 4mXMapRaised24m function essentially is similar to 4mXMapWindow0m in that it maps the window and all of its subwindows that have had map requests. However, it also raises the speci- fied window to the top of the stack. For additional infor- mation, see 4mXMapWindow24m. 4mXMapRaised24m can generate multiple 4mBadWindow24m errors. To map all subwindows for a specified window, use 4mXMapSub-0m 4mwindows24m. __ XMapSubwindows(4mdisplay24m, 4mw24m) Display *4mdisplay24m; Window 4mw24m; 4mdisplay24m Specifies the connection to the X server. 4mw24m Specifies the window. __ The 4mXMapSubwindows24m function maps all subwindows for a speci- fied window in top-to-bottom stacking order. The X server generates 4mExpose24m 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. 4mXMapSubwindows24m can generate a 4mBadWindow24m error. 1m3.6. Unmapping Windows0m Xlib provides functions that you can use to unmap a window or all subwindows. To unmap a window, use 4mXUnmapWindow24m. 1m620m 1mXlib C Library X11, Release 6.9/7.00m __ XUnmapWindow(4mdisplay24m, 4mw24m) Display *4mdisplay24m; Window 4mw24m; 4mdisplay24m Specifies the connection to the X server. 4mw24m Specifies the window. __ The 4mXUnmapWindow24m function unmaps the specified window and causes the X server to generate an 4mUnmapNotify24m event. If the specified window is already unmapped, 4mXUnmapWindow24m 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 4mExpose24m events on windows that were formerly obscured by it. 4mXUnmapWindow24m can generate a 4mBadWindow24m error. To unmap all subwindows for a specified window, use 4mXUnmap-0m 4mSubwindows24m. __ XUnmapSubwindows(4mdisplay24m, 4mw24m) Display *4mdisplay24m; Window 4mw24m; 4mdisplay24m Specifies the connection to the X server. 4mw24m Specifies the window. __ The 4mXUnmapSubwindows24m function unmaps all subwindows for the specified window in bottom-to-top stacking order. It causes the X server to generate an 4mUnmapNotify24m event on each sub- window and 4mExpose24m 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. 4mXUnmapSubwindows24m can generate a 4mBadWindow24m error. 1m3.7. Configuring Windows0m 1m630m 1mXlib C Library X11, Release 6.9/7.00m Xlib provides functions that you can use to move a window, resize a window, move and resize a window, or change a win- dows border width. To change one of these parameters, set the appropriate member of the 4mXWindowChanges24m structure and OR in the corresponding value mask in subsequent calls to 4mXConfigureWindow24m. The symbols for the value mask bits and the 4mXWindowChanges24m structure are: __ /* Configure window value mask bits */ #define 4mCWX24m (1<<0) #define 4mCWY24m (1<<1) #define 4mCWWidth24m (1<<2) #define 4mCWHeight24m (1<<3) #define 4mCWBorderWidth24m (1<<4) #define 4mCWSibling24m (1<<5) #define 4mCWStackMode24m (1<<6) /* Values */ typedef struct { int x, y; int width, height; int border_width; Window sibling; int stack_mode; } XWindowChanges; __ The x and y members are used to set the windows x and y coordinates, which are relative to the parents 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 4mBadValue24m error results. Attempts to configure a root window have no effect. The border_width member is used to set the width of the bor- der in pixels. Note that setting just the border width leaves the outer-left corner of the window in a fixed posi- tion but moves the absolute position of the windows origin. If you attempt to set the border-width attribute of an 4mInpu-0m 4mtOnly24m window nonzero, a 4mBadMatch24m 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 4mAbove24m, 4mBelow24m, 4mTopIf24m, 4mBottomIf24m, or 4mOpposite24m. If the override-redirect flag of the window is 4mFalse24m and if some other client has selected 4mSubstructureRedirectMask24m on 1m640m 1mXlib C Library X11, Release 6.9/7.00m the parent, the X server generates a 4mConfigureRequest24m event, and no further processing is performed. Otherwise, if some other client has selected 4mResizeRedirectMask24m on the window and the inside width or height of the window is being changed, a 4mResizeRequest24m 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 4mResiz-0m 4meRedirectMask24m and that 4mSubstructureRedirectMask24m on the par- ent has precedence over 4mResizeRedirectMask24m on the window. When the geometry of the window is changed as specified, the window is restacked among siblings, and a 4mConfigureNotify0m event is generated if the state of the window actually changes. 4mGravityNotify24m events are generated after 4mConfig-0m 4mureNotify24m events. If the inside width or height of the win- dow has actually changed, children of the window are affected as specified. If a windows size actually changes, the windows subwindows move according to their window gravity. Depending on the windows 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 pro- cessing 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 4mBot-0m 4mtomIf24m, 4mTopIf24m, and 4mOpposite24m) is performed with respect to the windows 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 4mBadMatch24m error results. If a sibling and a stack_mode are specified, the window is restacked as follows: 4mAbove24m The window is placed just above the sibling. 4mBelow24m The window is placed just below the sibling. 4mTopIf24m If the sibling occludes the window, the window is placed at the top of the stack. 4mBottomIf24m If the window occludes the sibling, the window is placed at the bottom of the stack. 4mOpposite24m 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: 1m650m 1mXlib C Library X11, Release 6.9/7.00m 4mAbove24m The window is placed at the top of the stack. 4mBelow24m The window is placed at the bottom of the stack. 4mTopIf24m If any sibling occludes the window, the window is placed at the top of the stack. 4mBottomIf24m If the window occludes any sibling, the window is placed at the bottom of the stack. 4mOpposite24m 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 windows size, location, stacking, or border, use 4mXConfigureWindow24m. __ XConfigureWindow(4mdisplay24m, 4mw24m, 4mvalue_mask24m, 4mvalues24m) Display *4mdisplay24m; Window 4mw24m; unsigned int 4mvalue_mask24m; XWindowChanges *4mvalues24m; 4mdisplay24m Specifies the connection to the X server. 4mw24m Specifies the window to be reconfigured. 4mvalue_mask0m Specifies 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. 4mvalues24m Specifies the 4mXWindowChanges24m structure. __ The 4mXConfigureWindow24m function uses the values specified in the 4mXWindowChanges24m structure to reconfigure a windows 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 4mBadMatch24m error results. Note that the computations for 4mBottomIf24m, 4mTopIf24m, and 4mOpposite0m are performed with respect to the windows final geometry (as controlled by the other arguments passed to 4mXConfig-0m 4mureWindow24m), not its initial geometry. Any backing store contents of the window, its inferiors, and other newly visi- ble windows are either discarded or changed to reflect the current screen contents (depending on the implementation). 1m660m 1mXlib C Library X11, Release 6.9/7.00m 4mXConfigureWindow24m can generate 4mBadMatch24m, 4mBadValue24m, and 4mBad-0m 4mWindow24m errors. To move a window without changing its size, use 4mXMoveWindow24m. __ XMoveWindow(4mdisplay24m, 4mw24m, 4mx24m, 4my24m) Display *4mdisplay24m; Window 4mw24m; int 4mx24m, 4my24m; 4mdisplay24m Specifies the connection to the X server. 4mw24m Specifies the window to be moved. 4mx0m 4my24m Specify the x and y coordinates, which define the new location of the top-left pixel of the windows border or the window itself if it has no border. __ The 4mXMoveWindow24m function moves the specified window to the specified x and y coordinates, but it does not change the windows size, raise the window, or change the mapping state of the window. Moving a mapped window may or may not lose the windows contents depending on if the window is obscured by nonchildren and if no backing store exists. If the con- tents of the window are lost, the X server generates 4mExpose0m events. Moving a mapped window generates 4mExpose24m events on any formerly obscured windows. If the override-redirect flag of the window is 4mFalse24m and some other client has selected 4mSubstructureRedirectMask24m on the parent, the X server generates a 4mConfigureRequest24m event, and no further processing is performed. Otherwise, the win- dow is moved. 4mXMoveWindow24m can generate a 4mBadWindow24m error. To change a windows size without changing the upper-left coordinate, use 4mXResizeWindow24m. 1m670m 1mXlib C Library X11, Release 6.9/7.00m __ XResizeWindow(4mdisplay24m, 4mw24m, 4mwidth24m, 4mheight24m) Display *4mdisplay24m; Window 4mw24m; unsigned int 4mwidth24m, 4mheight24m; 4mdisplay24m Specifies the connection to the X server. 4mw24m Specifies the window. 4mwidth0m 4mheight24m Specify the width and height, which are the inte- rior dimensions of the window after the call com- pletes. __ The 4mXResizeWindow24m function changes the inside dimensions of the specified window, not including its borders. This func- tion does not change the windows 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 4mExpose24m events. If a mapped window is made smaller, changing its size generates 4mExpose24m events on windows that the mapped window formerly obscured. If the override-redirect flag of the window is 4mFalse24m and some other client has selected 4mSubstructureRedirectMask24m on the parent, the X server generates a 4mConfigureRequest24m event, and no further processing is performed. If either width or height is zero, a 4mBadValue24m error results. 4mXResizeWindow24m can generate 4mBadValue24m and 4mBadWindow24m errors. To change the size and location of a window, use 4mXMoveRe-0m 4msizeWindow24m. 1m680m 1mXlib C Library X11, Release 6.9/7.00m __ XMoveResizeWindow(4mdisplay24m, 4mw24m, 4mx24m, 4my24m, 4mwidth24m, 4mheight24m) Display *4mdisplay24m; Window 4mw24m; int 4mx24m, 4my24m; unsigned int 4mwidth24m, 4mheight24m; 4mdisplay24m Specifies the connection to the X server. 4mw24m Specifies the window to be reconfigured. 4mx0m 4my24m Specify the x and y coordinates, which define the new position of the window relative to its parent. 4mwidth0m 4mheight24m Specify the width and height, which define the interior size of the window. __ The 4mXMoveResizeWindow24m function changes the size and location of the specified window without raising it. Moving and resizing a mapped window may generate an 4mExpose24m event on the window. Depending on the new size and location parameters, moving and resizing a window may generate 4mExpose24m events on windows that the window formerly obscured. If the override-redirect flag of the window is 4mFalse24m and some other client has selected 4mSubstructureRedirectMask24m on the parent, the X server generates a 4mConfigureRequest24m event, and no further processing is performed. Otherwise, the win- dow size and location are changed. 4mXMoveResizeWindow24m can generate 4mBadValue24m and 4mBadWindow0m errors. To change the border width of a given window, use 4mXSetWin-0m 4mdowBorderWidth24m. 1m690m 1mXlib C Library X11, Release 6.9/7.00m __ XSetWindowBorderWidth(4mdisplay24m, 4mw24m, 4mwidth24m) Display *4mdisplay24m; Window 4mw24m; unsigned int 4mwidth24m; 4mdisplay24m Specifies the connection to the X server. 4mw24m Specifies the window. 4mwidth24m Specifies the width of the window border. __ The 4mXSetWindowBorderWidth24m function sets the specified win- dows border width to the specified width. 4mXSetWindowBorderWidth24m can generate a 4mBadWindow24m error. 1m3.8. Changing Window Stacking Order0m 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 4mXRaiseWindow24m. __ XRaiseWindow(4mdisplay24m, 4mw24m) Display *4mdisplay24m; Window 4mw24m; 4mdisplay24m Specifies the connection to the X server. 4mw24m Specifies the window. __ The 4mXRaiseWindow24m 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 win- dow may generate 4mExpose24m events for the window and any mapped subwindows that were formerly obscured. If the override-redirect attribute of the window is 4mFalse0m and some other client has selected 4mSubstructureRedirectMask0m on the parent, the X server generates a 4mConfigureRequest0m event, and no processing is performed. Otherwise, the win- dow is raised. 1m700m 1mXlib C Library X11, Release 6.9/7.00m 4mXRaiseWindow24m can generate a 4mBadWindow24m error. To lower a window so that it does not obscure any sibling windows, use 4mXLowerWindow24m. __ XLowerWindow(4mdisplay24m, 4mw24m) Display *4mdisplay24m; Window 4mw24m; 4mdisplay24m Specifies the connection to the X server. 4mw24m Specifies the window. __ The 4mXLowerWindow24m 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 analo- gous 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 4mExpose24m events on any windows it formerly obscured. If the override-redirect attribute of the window is 4mFalse0m and some other client has selected 4mSubstructureRedirectMask0m on the parent, the X server generates a 4mConfigureRequest0m event, and no processing is performed. Otherwise, the win- dow is lowered to the bottom of the stack. 4mXLowerWindow24m can generate a 4mBadWindow24m error. To circulate a subwindow up or down, use 4mXCirculateSubwin-0m 4mdows24m. 1m710m 1mXlib C Library X11, Release 6.9/7.00m __ XCirculateSubwindows(4mdisplay24m, 4mw24m, 4mdirection24m) Display *4mdisplay24m; Window 4mw24m; int 4mdirection24m; 4mdisplay24m Specifies the connection to the X server. 4mw24m Specifies the window. 4mdirection24m Specifies the direction (up or down) that you want to circulate the window. You can pass 4mRaiseLowest0m or 4mLowerHighest24m. __ The 4mXCirculateSubwindows24m function circulates children of the specified window in the specified direction. If you specify 4mRaiseLowest24m, 4mXCirculateSubwindows24m raises the lowest mapped child (if any) that is occluded by another child to the top of the stack. If you specify 4mLowerHighest24m, 4mXCirculateSub-0m 4mwindows24m 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 4mSubstructureRedirectMask0m on the window, the X server generates a 4mCirculateRequest0m event, and no further processing is performed. If a child is actually restacked, the X server generates a 4mCirculateNo-0m 4mtify24m event. 4mXCirculateSubwindows24m can generate 4mBadValue24m and 4mBadWindow0m errors. To raise the lowest mapped child of a window that is par- tially or completely occluded by another child, use 4mXCircu-0m 4mlateSubwindowsUp24m. __ XCirculateSubwindowsUp(4mdisplay24m, 4mw24m) Display *4mdisplay24m; Window 4mw24m; 4mdisplay24m Specifies the connection to the X server. 4mw24m Specifies the window. __ The 4mXCirculateSubwindowsUp24m function raises the lowest mapped child of the specified window that is partially or com- pletely occluded by another child. Completely unobscured children are not affected. This is a convenience function equivalent to 4mXCirculateSubwindows24m with 4mRaiseLowest0m 1m720m 1mXlib C Library X11, Release 6.9/7.00m specified. 4mXCirculateSubwindowsUp24m can generate a 4mBadWindow24m error. To lower the highest mapped child of a window that partially or completely occludes another child, use 4mXCirculateSubwin-0m 4mdowsDown24m. __ XCirculateSubwindowsDown(4mdisplay24m, 4mw24m) Display *4mdisplay24m; Window 4mw24m; 4mdisplay24m Specifies the connection to the X server. 4mw24m Specifies the window. __ The 4mXCirculateSubwindowsDown24m function lowers the highest mapped child of the specified window that partially or com- pletely occludes another child. Completely unobscured chil- dren are not affected. This is a convenience function equivalent to 4mXCirculateSubwindows24m with 4mLowerHighest24m speci- fied. 4mXCirculateSubwindowsDown24m can generate a 4mBadWindow24m error. To restack a set of windows from top to bottom, use 4mXRestackWindows24m. __ XRestackWindows(4mdisplay24m, 4mwindows24m, 4mnwindows24m); Display *4mdisplay24m; Window 4mwindows24m[]; int 4mnwindows24m; 4mdisplay24m Specifies the connection to the X server. 4mwindows24m Specifies an array containing the windows to be restacked. 4mnwindows24m Specifies the number of windows to be restacked. __ The 4mXRestackWindows24m 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 1m730m 1mXlib C Library X11, Release 6.9/7.00m window array that is not a child of the specified window, a 4mBadMatch24m error results. If the override-redirect attribute of a window is 4mFalse24m and some other client has selected 4mSubstructureRedirectMask24m on the parent, the X server generates 4mConfigureRequest24m 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. 4mXRestackWindows24m can generate a 4mBadWindow24m error. 1m3.9. Changing Window Attributes0m Xlib provides functions that you can use to set window attributes. 4mXChangeWindowAttributes24m is the more general function that allows you to set one or more window attributes provided by the 4mXSetWindowAttributes24m structure. The other functions described in this section allow you to set one specific window attribute, such as a windows back- ground. To change one or more attributes for a given window, use 4mXChangeWindowAttributes24m. 1m740m 1mXlib C Library X11, Release 6.9/7.00m __ XChangeWindowAttributes(4mdisplay24m, 4mw24m, 4mvaluemask24m, 4mattributes24m) Display *4mdisplay24m; Window 4mw24m; unsigned long 4mvaluemask24m; XSetWindowAttributes *4mattributes24m; 4mdisplay24m Specifies the connection to the X server. 4mw24m Specifies the window. 4mvaluemask24m Specifies which window attributes are defined in 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 4mXCreateWindow24m. 4mattributes0m Specifies 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 4mXChangeWindowAttributes0m function uses the window attributes in the 4mXSetWindowAt-0m 4mtributes24m structure to change the specified window attributes. Changing the background does not cause the win- dow contents to be changed. To repaint the window and its background, use 4mXClearWindow24m. Setting the border or chang- ing the background such that the border tile origin changes causes the border to be repainted. Changing the background of a root window to 4mNone24m or 4mParentRelative24m restores the default background pixmap. Changing the border of a root window to 4mCopyFromParent24m restores the default border pixmap. Changing the win-gravity does not affect the current posi- tion of the window. Changing the backing-store of an obscured window to 4mWhenMapped24m or 4mAlways24m, 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 4mColormapNotify0m event. Changing the colormap of a visible window may have no immediate effect on the screen because the map may not be installed (see 4mXInstallColormap24m). Changing the cursor of a root window to 4mNone24m 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 1m750m 1mXlib C Library X11, Release 6.9/7.00m generated, it is reported to all interested clients. How- ever, only one client at a time can select for 4mSubstructur-0m 4meRedirectMask24m, 4mResizeRedirectMask24m, and 4mButtonPressMask24m. If a client attempts to select any of these event masks and some other client has already selected one, a 4mBadAccess0m error results. There is only one do-not-propagate-mask for a window, not one per client. 4mXChangeWindowAttributes24m can generate 4mBadAccess24m, 4mBadColor24m, 4mBadCursor24m, 4mBadMatch24m, 4mBadPixmap24m, 4mBadValue24m, and 4mBadWindow0m errors. To set the background of a window to a given pixel, use 4mXSetWindowBackground24m. __ XSetWindowBackground(4mdisplay24m, 4mw24m, 4mbackground_pixel24m) Display *4mdisplay24m; Window 4mw24m; unsigned long 4mbackground_pixel24m; 4mdisplay24m Specifies the connection to the X server. 4mw24m Specifies the window. 4mbackground_pixel0m Specifies the pixel that is to be used for the background. __ The 4mXSetWindowBackground24m function sets the background of the window to the specified pixel value. Changing the back- ground does not cause the window contents to be changed. 4mXSetWindowBackground24m uses a pixmap of undefined size filled with the pixel value you passed. If you try to change the background of an 4mInputOnly24m window, a 4mBadMatch24m error results. 4mXSetWindowBackground24m can generate 4mBadMatch24m and 4mBadWindow0m errors. To set the background of a window to a given pixmap, use 4mXSetWindowBackgroundPixmap24m. 1m760m 1mXlib C Library X11, Release 6.9/7.00m __ XSetWindowBackgroundPixmap(4mdisplay24m, 4mw24m, 4mbackground_pixmap24m) Display *4mdisplay24m; Window 4mw24m; Pixmap 4mbackground_pixmap24m; 4mdisplay24m Specifies the connection to the X server. 4mw24m Specifies the window. 4mbackground_pixmap0m Specifies the background pixmap, 4mParentRelative24m, or 4mNone24m. __ The 4mXSetWindowBackgroundPixmap24m function sets the background pixmap of the window to the specified pixmap. The back- ground pixmap can immediately be freed if no further explicit references to it are to be made. If 4mParentRelative0m is specified, the background pixmap of the windows parent is used, or on the root window, the default background is restored. If you try to change the background of an 4mInpu-0m 4mtOnly24m window, a 4mBadMatch24m error results. If the background is set to 4mNone24m, the window has no defined background. 4mXSetWindowBackgroundPixmap24m can generate 4mBadMatch24m, 4mBadPixmap24m, and 4mBadWindow24m errors. Note 4mXSetWindowBackground24m and 4mXSetWindowBackground-0m 4mPixmap24m do not change the current contents of the window. To change and repaint a windows border to a given pixel, use 4mXSetWindowBorder24m. 1m770m 1mXlib C Library X11, Release 6.9/7.00m __ XSetWindowBorder(4mdisplay24m, 4mw24m, 4mborder_pixel24m) Display *4mdisplay24m; Window 4mw24m; unsigned long 4mborder_pixel24m; 4mdisplay24m Specifies the connection to the X server. 4mw24m Specifies the window. 4mborder_pixel0m Specifies the entry in the colormap. __ The 4mXSetWindowBorder24m function sets the border of the window to the pixel value you specify. If you attempt to perform this on an 4mInputOnly24m window, a 4mBadMatch24m error results. 4mXSetWindowBorder24m can generate 4mBadMatch24m and 4mBadWindow24m errors. To change and repaint the border tile of a given window, use 4mXSetWindowBorderPixmap24m. __ XSetWindowBorderPixmap(4mdisplay24m, 4mw24m, 4mborder_pixmap24m) Display *4mdisplay24m; Window 4mw24m; Pixmap 4mborder_pixmap24m; 4mdisplay24m Specifies the connection to the X server. 4mw24m Specifies the window. 4mborder_pixmap0m Specifies the border pixmap or 4mCopyFromParent24m. __ The 4mXSetWindowBorderPixmap24m 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 4mCopyFromParent24m, a copy of the parent windows border pixmap is used. If you attempt to perform this on an 4mInputOnly24m window, a 4mBadMatch0m error results. 4mXSetWindowBorderPixmap24m can generate 4mBadMatch24m, 4mBadPixmap24m, and 4mBadWindow24m errors. To set the colormap of a given window, use 4mXSetWindowCol-0m 4mormap24m. 1m780m 1mXlib C Library X11, Release 6.9/7.00m __ XSetWindowColormap(4mdisplay24m, 4mw24m, 4mcolormap24m) Display *4mdisplay24m; Window 4mw24m; Colormap 4mcolormap24m; 4mdisplay24m Specifies the connection to the X server. 4mw24m Specifies the window. 4mcolormap24m Specifies the colormap. __ The 4mXSetWindowColormap24m function sets the specified colormap of the specified window. The colormap must have the same visual type as the window, or a 4mBadMatch24m error results. 4mXSetWindowColormap24m can generate 4mBadColor24m, 4mBadMatch24m, and 4mBad-0m 4mWindow24m errors. To define which cursor will be used in a window, use 4mXDe-0m 4mfineCursor24m. __ XDefineCursor(4mdisplay24m, 4mw24m, 4mcursor24m) Display *4mdisplay24m; Window 4mw24m; Cursor 4mcursor24m; 4mdisplay24m Specifies the connection to the X server. 4mw24m Specifies the window. 4mcursor24m Specifies the cursor that is to be displayed or 4mNone24m. __ If a cursor is set, it will be used when the pointer is in the window. If the cursor is 4mNone24m, it is equivalent to 4mXUn-0m 4mdefineCursor24m. 4mXDefineCursor24m can generate 4mBadCursor24m and 4mBadWindow24m errors. To undefine the cursor in a given window, use 4mXUndefineCur-0m 4msor24m. 1m790m 1mXlib C Library X11, Release 6.9/7.00m __ XUndefineCursor(4mdisplay24m, 4mw24m) Display *4mdisplay24m; Window 4mw24m; 4mdisplay24m Specifies the connection to the X server. 4mw24m Specifies the window. __ The 4mXUndefineCursor24m function undoes the effect of a previous 4mXDefineCursor24m for this window. When the pointer is in the window, the parents cursor will now be used. On the root window, the default cursor is restored. 4mXUndefineCursor24m can generate a 4mBadWindow24m error. 1m800m 1mXlib C Library X11, Release 6.9/7.00m 1mChapter 40m 1mWindow Information Functions0m After you connect the display to the X server and create a window, you can use the Xlib window information functions to: Obtain information about a window Translate screen coordinates Manipulate property lists Obtain and change window properties Manipulate selections 1m4.1. Obtaining Window Information0m Xlib provides functions that you can use to obtain informa- tion about the window tree, the windows current attributes, the windows current geometry, or the current pointer coor- dinates. 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 4mXQueryTree24m. 1m810m 1mXlib C Library X11, Release 6.9/7.00m __ Status XQueryTree(4mdisplay24m, 4mw24m, 4mroot_return24m, 4mparent_return24m, 4mchildren_return24m, 4mnchildren_return24m) Display *4mdisplay24m; Window 4mw24m; Window *4mroot_return24m; Window *4mparent_return24m; Window **4mchildren_return24m; unsigned int *4mnchildren_return24m; 4mdisplay24m Specifies the connection to the X server. 4mw24m Specifies the window whose list of children, root, parent, and number of children you want to obtain. 4mroot_return0m Returns the root window. 4mparent_return0m Returns the parent window. 4mchildren_return0m Returns the list of children. 4mnchildren_return0m Returns the number of children. __ The 4mXQueryTree24m function returns the root ID, the parent win- dow 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). 4mXQueryTree24m returns zero if it fails and nonzero if it succeeds. To free a non-NULL children list when it is no longer needed, use 4mXFree24m. 4mXQueryTree24m can generate a 4mBadWindow24m error. To obtain the current attributes of a given window, use 4mXGetWindowAttributes24m. 1m820m 1mXlib C Library X11, Release 6.9/7.00m __ Status XGetWindowAttributes(4mdisplay24m, 4mw24m, 4mwindow_attributes_return24m) Display *4mdisplay24m; Window 4mw24m; XWindowAttributes *4mwindow_attributes_return24m; 4mdisplay24m Specifies the connection to the X server. 4mw24m Specifies the window whose current attributes you want to obtain. 4mwindow_attributes_return0m Returns the specified windows attributes in the 4mXWindowAttributes24m structure. __ The 4mXGetWindowAttributes24m function returns the current attributes for the specified window to an 4mXWindowAttributes0m structure. __ typedef struct { int x, y; /* location of window */ int width, height; /* width and height of window */ int border_width; /* border width of window */ int depth; /* depth of window */ Visual *visual; /* the associated visual structure */ Window root; /* root of screen containing window */ int class; /* InputOutput, InputOnly*/ int bit_gravity; /* one of the bit gravity values */ int win_gravity; /* one of the window gravity values */ int backing_store; /* NotUseful, WhenMapped, Always */ unsigned long backing_planes;/* planes to be preserved if possible */ unsigned long backing_pixel;/* value to be used when restoring planes */ Bool save_under; /* boolean, should bits under be saved? */ Colormap colormap; /* color map to be associated with window */ Bool map_installed; /* boolean, is color map currently installed*/ int map_state; /* IsUnmapped, IsUnviewable, IsViewable */ long all_event_masks; /* set of events all people have interest in*/ long your_event_mask; /* my event mask */ long do_not_propagate_mask;/* set of events that should not propagate */ Bool override_redirect; /* boolean value for override-redirect */ Screen *screen; /* back pointer to correct screen */ } XWindowAttributes; __ The x and y members are set to the upper-left outer corner relative to the parent windows 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 windows border width in pixels. The depth member is set to 1m830m 1mXlib C Library X11, Release 6.9/7.00m the depth of the window (that is, bits per pixel for the object). The visual member is a pointer to the screens associated 4mVisual24m structure. The root member is set to the root window of the screen containing the window. The class member is set to the windows class and can be either 4mInputOutput24m or 4mInputOnly24m. The bit_gravity member is set to the windows bit gravity and can be one of the following: 4mForgetGravity24m 4mEastGravity0m 4mNorthWestGrav-24m 4mSouthWestGrav-0m 4mity24m 4mity0m 4mNorthGravity24m 4mSouthGravity0m 4mNorthEastGrav-24m 4mSouthEastGrav-0m 4mity24m 4mity0m 4mWestGravity24m 4mStaticGravity0m 4mCenterGravity0m The win_gravity member is set to the windows window gravity and can be one of the following: 4mUnmapGravity24m 4mEastGravity0m 4mNorthWestGrav-24m 4mSouthWestGrav-0m 4mity24m 4mity0m 4mNorthGravity24m 4mSouthGravity0m 4mNorthEastGrav-24m 4mSouthEastGrav-0m 4mity24m 4mity0m 4mWestGravity24m 4mStaticGravity0m 4mCenterGravity0m 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 4mWhen-0m 4mMapped24m, 4mAlways24m, or 4mNotUseful24m. 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 back- ing_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 4mTrue24m or 4mFalse24m. The colormap member is set to the colormap for the specified window and can be a colormap ID or 4mNone24m. The map_installed member is set to indicate whether the colormap is currently installed and can be 4mTrue24m or 4mFalse24m. The map_state member is set to indicate the state of the window and can be 4mIsUnmapped24m, 4mIsUnviewable24m, or 4mIsViewable24m. 4mIsUnviewable24m is used if the window is mapped but some ancestor is unmapped. 1m840m 1mXlib C Library X11, Release 6.9/7.00m 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 4mTrue24m or 4mFalse24m. Window manager clients should ignore the window if this member is 4mTrue24m. 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. 4mXGetWindowAttributes24m can generate 4mBadDrawable24m and 4mBadWindow0m errors. To obtain the current geometry of a given drawable, use 4mXGetGeometry24m. 1m850m 1mXlib C Library X11, Release 6.9/7.00m __ Status XGetGeometry(4mdisplay24m, 4md24m, 4mroot_return24m, 4mx_return24m, 4my_return24m, 4mwidth_return24m, 4mheight_return24m, 4mborder_width_return24m, 4mdepth_return24m) Display *4mdisplay24m; Drawable 4md24m; Window *4mroot_return24m; int *4mx_return24m, *4my_return24m; unsigned int *4mwidth_return24m, *4mheight_return24m; unsigned int *4mborder_width_return24m; unsigned int *4mdepth_return24m; 4mdisplay24m Specifies the connection to the X server. 4md24m Specifies the drawable, which can be a window or a pixmap. 4mroot_return0m Returns the root window. 4mx_return0m 4my_return24m Return the x and y coordinates that define the location of the drawable. For a window, these coordinates specify the upper-left outer corner relative to its parents origin. For pixmaps, these coordinates are always zero. 4mwidth_return0m 4mheight_return0m Return the drawables dimensions (width and height). For a window, these dimensions specify the inside size, not including the border. 4mborder_width_return0m Returns the border width in pixels. If the draw- able is a pixmap, it returns zero. 4mdepth_return0m Returns the depth of the drawable (bits per pixel for the object). __ The 4mXGetGeometry24m function returns the root window and the current geometry of the drawable. The geometry of the draw- able includes the x and y coordinates, width and height, border width, and depth. These are described in the argu- ment list. It is legal to pass to this function a window whose class is 4mInputOnly24m. 4mXGetGeometry24m can generate a 4mBadDrawable24m error. 1m860m 1mXlib C Library X11, Release 6.9/7.00m 1m4.2. Translating Screen Coordinates0m Applications sometimes need to perform a coordinate trans- formation from the coordinate space of one window to another window or need to determine which window the pointing device is in. 4mXTranslateCoordinates24m and 4mXQueryPointer24m 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 4mXTranslateCoordinates24m. __ Bool XTranslateCoordinates(4mdisplay24m, 4msrc_w24m, 4mdest_w24m, 4msrc_x24m, 4msrc_y24m, 4mdest_x_return24m, 4mdest_y_return24m, 4mchild_return24m) Display *4mdisplay24m; Window 4msrc_w24m, 4mdest_w24m; int 4msrc_x24m, 4msrc_y24m; int *4mdest_x_return24m, *4mdest_y_return24m; Window *4mchild_return24m; 4mdisplay24m Specifies the connection to the X server. 4msrc_w24m Specifies the source window. 4mdest_w24m Specifies the destination window. 4msrc_x0m 4msrc_y24m Specify the x and y coordinates within the source window. 4mdest_x_return0m 4mdest_y_return0m Return the x and y coordinates within the destina- tion window. 4mchild_return0m Returns the child if the coordinates are contained in a mapped child of the destination window. __ If 4mXTranslateCoordinates24m returns 4mTrue24m, it takes the src_x and src_y coordinates relative to the source windows origin and returns these coordinates to dest_x_return and dest_y_return relative to the destination windows origin. If 4mXTranslateCoordinates24m returns 4mFalse24m, 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 4mNone24m. 1m870m 1mXlib C Library X11, Release 6.9/7.00m 4mXTranslateCoordinates24m can generate a 4mBadWindow24m error. To obtain the screen coordinates of the pointer or to deter- mine the pointer coordinates relative to a specified window, use 4mXQueryPointer24m. __ Bool XQueryPointer(4mdisplay24m, 4mw24m, 4mroot_return24m, 4mchild_return24m, 4mroot_x_return24m, 4mroot_y_return24m, 4mwin_x_return24m, 4mwin_y_return24m, 4mmask_return24m) Display *4mdisplay24m; Window 4mw24m; Window *4mroot_return24m, *4mchild_return24m; int *4mroot_x_return24m, *4mroot_y_return24m; int *4mwin_x_return24m, *4mwin_y_return24m; unsigned int *4mmask_return24m; 4mdisplay24m Specifies the connection to the X server. 4mw24m Specifies the window. 4mroot_return0m Returns the root window that the pointer is in. 4mchild_return0m Returns the child window that the pointer is located in, if any. 4mroot_x_return0m 4mroot_y_return0m Return the pointer coordinates relative to the root windows origin. 4mwin_x_return0m 4mwin_y_return0m Return the pointer coordinates relative to the specified window. 4mmask_return0m Returns the current state of the modifier keys and pointer buttons. __ The 4mXQueryPointer24m function returns the root window the pointer is logically on and the pointer coordinates relative to the root windows origin. If 4mXQueryPointer24m returns 4mFalse24m, the pointer is not on the same screen as the speci- fied window, and 4mXQueryPointer24m returns 4mNone24m to child_return and zero to win_x_return and win_y_return. If 4mXQueryPointer0m returns 4mTrue24m, the pointer coordinates returned to win_x_return and win_y_return are relative to the origin of the specified window. In this case, 4mXQueryPointer24m returns the child that contains the pointer, if any, or else 4mNone24m to 1m880m 1mXlib C Library X11, Release 6.9/7.00m child_return. 4mXQueryPointer24m returns the current logical state of the key- board 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). 4mXQueryPointer24m can generate a 4mBadWindow24m error. 1m4.3. Properties and Atoms0m 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. 4mXInternAtom24m can be used to obtain the atom for property names. A property is also stored in one of several possible for- mats. The X server can store the information as 8-bit quan- tities, 16-bit quantities, or 32-bit quantities. This per- mits 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 com- monly used functions. The atoms for these properties are defined in <4mX11/Xatom.h24m>. To avoid name clashes with user symbols, the 4m#define24m 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 1m890m 1mXlib C Library X11, Release 6.9/7.00m 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 4mInter-Client24m 4mCommunication24m 4mConven-0m 4mtions24m 4mManual24m and the 4mX24m 4mLogical24m 4mFont24m 4mDescription24m 4mConventions24m. You can use properties to communicate other information between applications. The functions described in this sec- tion let you define new properties and get the unique atom IDs in your applications. Although any particular atom can have some client interpre- tation within each of the name spaces, atoms occur in five distinct name spaces within the protocol: Selections Property names Property types Font properties Type of a 4mClientMessage24m event (none are built into the X server) 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 1m900m 1mXlib C Library X11, Release 6.9/7.00m 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 4mXInternAtom24m. 1m910m 1mXlib C Library X11, Release 6.9/7.00m __ Atom XInternAtom(4mdisplay24m, 4matom_name24m, 4monly_if_exists24m) Display *4mdisplay24m; char *4matom_name24m; Bool 4monly_if_exists24m; 4mdisplay24m Specifies the connection to the X server. 4matom_name24m Specifies the name associated with the atom you want returned. 4monly_if_exists0m Specifies a Boolean value that indicates whether the atom must be created. __ The 4mXInternAtom24m function returns the atom identifier associ- ated with the specified atom_name string. If only_if_exists is 4mFalse24m, the atom is created if it does not exist. There- fore, 4mXInternAtom24m can return 4mNone24m. 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 desig- nate different atoms. The atom will remain defined even after the clients connection closes. It will become unde- fined only when the last connection to the X server closes. 4mXInternAtom24m can generate 4mBadAlloc24m and 4mBadValue24m errors. To return atoms for an array of names, use 4mXInternAtoms24m. 1m920m 1mXlib C Library X11, Release 6.9/7.00m __ Status XInternAtoms(4mdisplay24m, 4mnames24m, 4mcount24m, 4monly_if_exists24m, 4matoms_return24m) Display *4mdisplay24m; char **4mnames24m; int 4mcount24m; Bool 4monly_if_exists24m; Atom *4matoms_return24m; 4mdisplay24m Specifies the connection to the X server. 4mnames24m Specifies the array of atom names. 4mcount24m Specifies the number of atom names in the array. 4monly_if_exists0m Specifies a Boolean value that indicates whether the atom must be created. 4matoms_return0m Returns the atoms. __ The 4mXInternAtoms24m function returns the atom identifiers asso- ciated with the specified names. The atoms are stored in the atoms_return array supplied by the caller. Calling this function is equivalent to calling 4mXInternAtom24m 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. 4mXInternAtoms24m can generate 4mBadAlloc24m and 4mBadValue24m errors. To return a name for a given atom identifier, use 4mXGetAtom-0m 4mName24m. __ char *XGetAtomName(4mdisplay24m, 4matom24m) Display *4mdisplay24m; Atom 4matom24m; 4mdisplay24m Specifies the connection to the X server. 4matom24m Specifies the atom for the property name you want returned. __ The 4mXGetAtomName24m function returns the name associated with 1m930m 1mXlib C Library X11, Release 6.9/7.00m 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. Other- wise, the result is implementation-dependent. To free the resulting string, call 4mXFree24m. 4mXGetAtomName24m can generate a 4mBadAtom24m error. To return the names for an array of atom identifiers, use 4mXGetAtomNames24m. __ Status XGetAtomNames(4mdisplay24m, 4matoms24m, 4mcount24m, 4mnames_return24m) Display *4mdisplay24m; Atom *4matoms24m; int 4mcount24m; char **4mnames_return24m; 4mdisplay24m Specifies the connection to the X server. 4matoms24m Specifies the array of atoms. 4mcount24m Specifies the number of atoms in the array. 4mnames_return0m Returns the atom names. __ The 4mXGetAtomNames24m 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 4mXGetAtomName24m 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. 4mXGetAtomNames24m can generate a 4mBadAtom24m error. 1m4.4. Obtaining and Changing Window Properties0m You can attach a property list to every window. Each prop- erty 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 4mchar0m is used to represent 8-bit quantities, the type 4mshort24m is used to represent 16-bit quantities, and the type 4mlong24m is used to represent 32-bit quantities. 1m940m 1mXlib C Library X11, Release 6.9/7.00m 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 communica- tion (see chapter 14). To obtain the type, format, and value of a property of a given window, use 4mXGetWindowProperty24m. 1m950m 1mXlib C Library X11, Release 6.9/7.00m __ int XGetWindowProperty(4mdisplay24m, 4mw24m, 4mproperty24m, 4mlong_offset24m, 4mlong_length24m, 4mdelete24m, 4mreq_type24m, 4mactual_type_return24m, 4mactual_format_return24m, 4mnitems_return24m, 4mbytes_after_return24m, 4mprop_return24m) Display *4mdisplay24m; Window 4mw24m; Atom 4mproperty24m; long 4mlong_offset24m, 4mlong_length24m; Bool 4mdelete24m; Atom 4mreq_type24m; Atom *4mactual_type_return24m; int *4mactual_format_return24m; unsigned long *4mnitems_return24m; unsigned long *4mbytes_after_return24m; unsigned char **4mprop_return24m; 4mdisplay24m Specifies the connection to the X server. 4mw24m Specifies the window whose property you want to obtain. 4mproperty24m Specifies the property name. 4mlong_offset0m Specifies the offset in the specified property (in 32-bit quantities) where the data is to be retrieved. 4mlong_length0m Specifies the length in 32-bit multiples of the data to be retrieved. 4mdelete24m Specifies a Boolean value that determines whether the property is deleted. 4mreq_type24m Specifies the atom identifier associated with the property type or 4mAnyPropertyType24m. 4mactual_type_return0m Returns the atom identifier that defines the actual type of the property. 4mactual_format_return0m Returns the actual format of the property. 4mnitems_return0m Returns the actual number of 8-bit, 16-bit, or 32-bit items stored in the prop_return data. 4mbytes_after_return0m Returns the number of bytes remaining to be read in the property if a partial read was performed. 1m960m 1mXlib C Library X11, Release 6.9/7.00m 4mprop_return0m Returns the data in the specified format. __ The 4mXGetWindowProperty24m 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. 4mXGetWindowProperty24m sets the return arguments as follows: If the specified property does not exist for the speci- fied window, 4mXGetWindowProperty24m returns 4mNone24m to actual_type_return and the value zero to actual_for- mat_return and bytes_after_return. The nitems_return argument is empty. In this case, the delete argument is ignored. If the specified property exists but its type does not match the specified type, 4mXGetWindowProperty24m returns the actual property type to actual_type_return, the actual property format (never zero) to actual_for- mat_return, and the property length in bytes (even if the actual_format_return is 16 or 32) to bytes_after_return. It also ignores the delete argu- ment. The nitems_return argument is empty. If the specified property exists and either you assign 4mAnyPropertyType24m to the req_type argument or the speci- fied type matches the actual property type, 4mXGetWindow-0m 4mProperty24m returns the actual property type to actual_type_return and the actual property format (never zero) to actual_format_return. It also returns a value to bytes_after_return and nitems_return, by defining the following values: N = actual length of the stored property in bytes (even if the format is 16 or 32) I = 4 * long_offset T = N - I L = MINIMUM(T, 4 * long_length) A = N - (I + L) The returned value starts at byte index I in the prop- erty (indexing from zero), and its length in bytes is L. If the value for long_offset causes L to be nega- tive, a 4mBadValue24m 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 repre- sented as a 4mchar24m array. If the returned format is 16, the returned data is represented as a 4mshort24m array and should be cast to that type to obtain the elements. If the returned 1m970m 1mXlib C Library X11, Release 6.9/7.00m format is 32, the returned data is represented as a 4mlong0m array and should be cast to that type to obtain the ele- ments. 4mXGetWindowProperty24m 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 charac- ters do not have to be copied into yet another string before use. If delete is 4mTrue24m and bytes_after_return is zero, 4mXGetWin-0m 4mdowProperty24m deletes the property from the window and gener- ates a 4mPropertyNotify24m event on the window. The function returns 4mSuccess24m if it executes successfully. To free the resulting data, use 4mXFree24m. 4mXGetWindowProperty24m can generate 4mBadAtom24m, 4mBadValue24m, and 4mBad-0m 4mWindow24m errors. To obtain a given windows property list, use 4mXListProper-0m 4mties24m. __ Atom *XListProperties(4mdisplay24m, 4mw24m, 4mnum_prop_return24m) Display *4mdisplay24m; Window 4mw24m; int *4mnum_prop_return24m; 4mdisplay24m Specifies the connection to the X server. 4mw24m Specifies the window whose property list you want to obtain. 4mnum_prop_return0m Returns the length of the properties array. __ The 4mXListProperties24m 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 4mXFree24m. 4mXListProperties24m can generate a 4mBadWindow24m error. To change a property of a given window, use 4mXChangeProperty24m. 1m980m 1mXlib C Library X11, Release 6.9/7.00m __ XChangeProperty(4mdisplay24m, 4mw24m, 4mproperty24m, 4mtype24m, 4mformat24m, 4mmode24m, 4mdata24m, 4mnelements24m) Display *4mdisplay24m; Window 4mw24m; Atom 4mproperty24m, 4mtype24m; int 4mformat24m; int 4mmode24m; unsigned char *4mdata24m; int 4mnelements24m; 4mdisplay24m Specifies the connection to the X server. 4mw24m Specifies the window whose property you want to change. 4mproperty24m Specifies the property name. 4mtype24m Specifies the type of the property. The X server does not interpret the type but simply passes it back to an application that later calls 4mXGetWin-0m 4mdowProperty24m. 4mformat24m Specifies whether the data should be viewed as a 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 4mXChangeProperty24m. 4mmode24m Specifies the mode of the operation. You can pass 4mPropModeReplace24m, 4mPropModePrepend24m, or 4mPropModeAp-0m 4mpend24m. 4mdata24m Specifies the property data. 4mnelements24m Specifies the number of elements of the specified data format. __ The 4mXChangeProperty24m function alters the property for the specified window and causes the X server to generate a 4mProp-0m 4mertyNotify24m event on that window. 4mXChangeProperty24m performs the following: If mode is 4mPropModeReplace24m, 4mXChangeProperty24m discards the previous property value and stores the new data. If mode is 4mPropModePrepend24m or 4mPropModeAppend24m, 4mXChange-0m 4mProperty24m inserts the specified data before the begin- ning of the existing data or onto the end of the exist- ing data, respectively. The type and format must match 1m990m 1mXlib C Library X11, Release 6.9/7.00m the existing property value, or a 4mBadMatch24m error results. If the property is undefined, it is treated as defined with the correct type and format with zero- length data. If the specified format is 8, the property data must be a 4mchar24m array. If the specified format is 16, the property data must be a 4mshort24m array. If the specified format is 32, the property data must be a 4mlong24m 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 4mBadAlloc24m error results.) 4mXChangeProperty24m can generate 4mBadAlloc24m, 4mBadAtom24m, 4mBadMatch24m, 4mBadValue24m, and 4mBadWindow24m errors. To rotate a windows property list, use 4mXRotateWindowProper-0m 4mties24m. __ XRotateWindowProperties(4mdisplay24m, 4mw24m, 4mproperties24m, 4mnum_prop24m, 4mnpositions24m) Display *4mdisplay24m; Window 4mw24m; Atom 4mproperties24m[]; int 4mnum_prop24m; int 4mnpositions24m; 4mdisplay24m Specifies the connection to the X server. 4mw24m Specifies the window. 4mproperties0m Specifies the array of properties that are to be rotated. 4mnum_prop24m Specifies the length of the properties array. 4mnpositions0m Specifies the rotation amount. __ The 4mXRotateWindowProperties24m function allows you to rotate properties on a window and causes the X server to generate 4mPropertyNotify24m events. If the property names in the proper- ties array are viewed as being numbered starting from zero 1m1000m 1mXlib C Library X11, Release 6.9/7.00m 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 nposi- tions). If npositions mod N is nonzero, the X server gener- ates a 4mPropertyNotify24m 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 4mBadMatch24m error results. If a 4mBadAtom24m or 4mBadMatch24m error results, no properties are changed. 4mXRotateWindowProperties24m can generate 4mBadAtom24m, 4mBadMatch24m, and 4mBadWindow24m errors. To delete a property on a given window, use 4mXDeleteProperty24m. __ XDeleteProperty(4mdisplay24m, 4mw24m, 4mproperty24m) Display *4mdisplay24m; Window 4mw24m; Atom 4mproperty24m; 4mdisplay24m Specifies the connection to the X server. 4mw24m Specifies the window whose property you want to delete. 4mproperty24m Specifies the property name. __ The 4mXDeleteProperty24m function deletes the specified property only if the property was defined on the specified window and causes the X server to generate a 4mPropertyNotify24m event on the window unless the property does not exist. 4mXDeleteProperty24m can generate 4mBadAtom24m and 4mBadWindow24m errors. 1m4.5. Selections0m 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 main- tained 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. 1m1010m 1mXlib C Library X11, Release 6.9/7.00m 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 selec- tion 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 spec- ifies 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 para- graph 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 4mXSetSelectionOwner24m. __ XSetSelectionOwner(4mdisplay24m, 4mselection24m, 4mowner24m, 4mtime24m) Display *4mdisplay24m; Atom 4mselection24m; Window 4mowner24m; Time 4mtime24m; 4mdisplay24m Specifies the connection to the X server. 4mselection24m Specifies the selection atom. 4mowner24m Specifies the owner of the specified selection atom. You can pass a window or 4mNone24m. 4mtime24m Specifies the time. You can pass either a times- tamp or 4mCurrentTime24m. __ The 4mXSetSelectionOwner24m 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 4mCurrentTime24m replaced by the current server time. If the owner window is specified as 4mNone24m, then the owner of the selection becomes 4mNone24m (that is, no owner). 1m1020m 1mXlib C Library X11, Release 6.9/7.00m Otherwise, the owner of the selection becomes the client executing the request. If the new owner (whether a client or 4mNone24m) is not the same as the current owner of the selection and the current owner is not 4mNone24m, the current owner is sent a 4mSelectionClear0m 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 4mNone24m, but the last-change time is not affected. The selection atom is uninterpreted by the X server. 4mXGetSelec-0m 4mtionOwner24m returns the owner window, which is reported in 4mSelectionRequest24m and 4mSelectionClear24m events. Selections are global to the X server. 4mXSetSelectionOwner24m can generate 4mBadAtom24m and 4mBadWindow0m errors. To return the selection owner, use 4mXGetSelectionOwner24m. __ Window XGetSelectionOwner(4mdisplay24m, 4mselection24m) Display *4mdisplay24m; Atom 4mselection24m; 4mdisplay24m Specifies the connection to the X server. 4mselection24m Specifies the selection atom whose owner you want returned. __ The 4mXGetSelectionOwner24m function returns the window ID asso- ciated with the window that currently owns the specified selection. If no selection was specified, the function returns the constant 4mNone24m. If 4mNone24m is returned, there is no owner for the selection. 4mXGetSelectionOwner24m can generate a 4mBadAtom24m error. To request conversion of a selection, use 4mXConvertSelection24m. 1m1030m 1mXlib C Library X11, Release 6.9/7.00m __ XConvertSelection(4mdisplay24m, 4mselection24m, 4mtarget24m, 4mproperty24m, 4mrequestor24m, 4mtime24m) Display *4mdisplay24m; Atom 4mselection24m, 4mtarget24m; Atom 4mproperty24m; Window 4mrequestor24m; Time 4mtime24m; 4mdisplay24m Specifies the connection to the X server. 4mselection24m Specifies the selection atom. 4mtarget24m Specifies the target atom. 4mproperty24m Specifies the property name. You also can pass 4mNone24m. 4mrequestor24m Specifies the requestor. 4mtime24m Specifies the time. You can pass either a times- tamp or 4mCurrentTime24m. __ 4mXConvertSelection24m requests that the specified selection be converted to the specified target type: If the specified selection has an owner, the X server sends a 4mSelectionRequest24m event to that owner. If no owner for the specified selection exists, the X server generates a 4mSelectionNotify24m event to the requestor with property 4mNone24m. The arguments are passed on unchanged in either of the events. There are two predefined selection atoms: PRIMARY and SECONDARY. 4mXConvertSelection24m can generate 4mBadAtom24m and 4mBadWindow24m errors. 1m1040m 1mXlib C Library X11, Release 6.9/7.00m 1mChapter 50m 1mPixmap and Cursor Functions0m Once you have connected to an X server, you can use the Xlib functions to: Create and free pixmaps Create, recolor, and free cursors 1m5.1. Creating and Freeing Pixmaps0m 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 pat- terns 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 4mXCreatePixmap24m. __ Pixmap XCreatePixmap(4mdisplay24m, 4md24m, 4mwidth24m, 4mheight24m, 4mdepth24m) Display *4mdisplay24m; Drawable 4md24m; unsigned int 4mwidth24m, 4mheight24m; unsigned int 4mdepth24m; 4mdisplay24m Specifies the connection to the X server. 4md24m Specifies which screen the pixmap is created on. 4mwidth0m 4mheight24m Specify the width and height, which define the dimensions of the pixmap. 4mdepth24m Specifies the depth of the pixmap. __ The 4mXCreatePixmap24m 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 4mInputOnly24m window to the drawable argument. The width and height arguments must be nonzero, or a 4mBadValue24m error results. The depth argument must be one of the depths supported by the screen of the specified drawable, or a 4mBadValue24m error results. 1m1050m 1mXlib C Library X11, Release 6.9/7.00m 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 4mXCopyPlane24m for an exception to this rule). The initial contents of the pixmap are undefined. 4mXCreatePixmap24m can generate 4mBadAlloc24m, 4mBadDrawable24m, and 4mBad-0m 4mValue24m errors. To free all storage associated with a specified pixmap, use 4mXFreePixmap24m. __ XFreePixmap(4mdisplay24m, 4mpixmap24m) Display *4mdisplay24m; Pixmap 4mpixmap24m; 4mdisplay24m Specifies the connection to the X server. 4mpixmap24m Specifies the pixmap. __ The 4mXFreePixmap24m 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. 4mXFreePixmap24m can generate a 4mBadPixmap24m error. 1m5.2. Creating, Recoloring, and Freeing Cursors0m 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 Xs 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. 4mXQueryBestCursor24m can be used to find out what sizes are pos- sible. 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 1m1060m 1mXlib C Library X11, Release 6.9/7.00m 4mXCreateFontCursor24m. __ #include Cursor XCreateFontCursor(4mdisplay24m, 4mshape24m) Display *4mdisplay24m; unsigned int 4mshape24m; 4mdisplay24m Specifies the connection to the X server. 4mshape24m Specifies the shape of the cursor. __ 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 cus- tomized 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 4mXRecolorCursor24m). For further information about cursor shapes, see appendix B. 4mXCreateFontCursor24m can generate 4mBadAlloc24m and 4mBadValue24m errors. To create a cursor from font glyphs, use 4mXCreateGlyphCursor24m. 1m1070m 1mXlib C Library X11, Release 6.9/7.00m __ Cursor XCreateGlyphCursor(4mdisplay24m, 4msource_font24m, 4mmask_font24m, 4msource_char24m, 4mmask_char24m, 4mforeground_color24m, 4mbackground_color24m) Display *4mdisplay24m; Font 4msource_font24m, 4mmask_font24m; unsigned int 4msource_char24m, 4mmask_char24m; XColor *4mforeground_color24m; XColor *4mbackground_color24m; 4mdisplay24m Specifies the connection to the X server. 4msource_font0m Specifies the font for the source glyph. 4mmask_font24m Specifies the font for the mask glyph or 4mNone24m. 4msource_char0m Specifies the character glyph for the source. 4mmask_char24m Specifies the glyph character for the mask. 4mforeground_color0m Specifies the RGB values for the foreground of the source. 4mbackground_color0m Specifies the RGB values for the background of the source. __ The 4mXCreateGlyphCursor24m function is similar to 4mXCre-0m 4matePixmapCursor24m 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 4mBadValue24m error results. If mask_font is given, mask_char must be a defined glyph in mask_font, or a 4mBadValue24m 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 rel- ative 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 4mXFreeFont24m if no further explicit ref- erences 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. 4mXCreateGlyphCursor24m can generate 4mBadAlloc24m, 4mBadFont24m, and 4mBad-0m 4mValue24m errors. 1m1080m 1mXlib C Library X11, Release 6.9/7.00m To create a cursor from two bitmaps, use 4mXCreatePixmapCur-0m 4msor24m. __ Cursor XCreatePixmapCursor(4mdisplay24m, 4msource24m, 4mmask24m, 4mforeground_color24m, 4mbackground_color24m, 4mx24m, 4my24m) Display *4mdisplay24m; Pixmap 4msource24m; Pixmap 4mmask24m; XColor *4mforeground_color24m; XColor *4mbackground_color24m; unsigned int 4mx24m, 4my24m; 4mdisplay24m Specifies the connection to the X server. 4msource24m Specifies the shape of the source cursor. 4mmask24m Specifies the cursors source bits to be displayed or 4mNone24m. 4mforeground_color0m Specifies the RGB values for the foreground of the source. 4mbackground_color0m Specifies the RGB values for the background of the source. 4mx0m 4my24m Specify the x and y coordinates, which indicate the hotspot relative to the sources origin. __ The 4mXCreatePixmapCursor24m function creates a cursor and returns the cursor ID associated with it. The foreground and background RGB values must be specified using fore- ground_color and background_color, even if the X server only has a 4mStaticGray24m or 4mGrayScale24m screen. The foreground color is used for the pixels set to 1 in the source, and the back- ground color is used for the pixels set to 0. Both source and mask, if specified, must have depth one (or a 4mBadMatch0m 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 pix- els 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 4mBadMatch24m error results. The hotspot must be a point within the source, or a 4mBadMatch24m error results. The components of the cursor can be transformed arbitrarily to meet display limitations. The pixmaps can be freed imme- diately if no further explicit references to them are to be 1m1090m 1mXlib C Library X11, Release 6.9/7.00m 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. 4mXCreatePixmapCursor24m can generate 4mBadAlloc24m and 4mBadPixmap0m errors. To determine useful cursor sizes, use 4mXQueryBestCursor24m. __ Status XQueryBestCursor(4mdisplay24m, 4md24m, 4mwidth24m, 4mheight24m, 4mwidth_return24m, 4mheight_return24m) Display *4mdisplay24m; Drawable 4md24m; unsigned int 4mwidth24m, 4mheight24m; unsigned int *4mwidth_return24m, *4mheight_return24m; 4mdisplay24m Specifies the connection to the X server. 4md24m Specifies the drawable, which indicates the screen. 4mwidth0m 4mheight24m Specify the width and height of the cursor that you want the size information for. 4mwidth_return0m 4mheight_return0m Return the best width and height that is closest to the specified width and height. __ Some displays allow larger cursors than other displays. The 4mXQueryBestCursor24m 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. Applica- tions should be prepared to use smaller cursors on displays that cannot support large ones. 4mXQueryBestCursor24m can generate a 4mBadDrawable24m error. To change the color of a given cursor, use 4mXRecolorCursor24m. 1m1100m 1mXlib C Library X11, Release 6.9/7.00m __ XRecolorCursor(4mdisplay24m, 4mcursor24m, 4mforeground_color24m, 4mbackground_color24m) Display *4mdisplay24m; Cursor 4mcursor24m; XColor *4mforeground_color24m, *4mbackground_color24m; 4mdisplay24m Specifies the connection to the X server. 4mcursor24m Specifies the cursor. 4mforeground_color0m Specifies the RGB values for the foreground of the source. 4mbackground_color0m Specifies the RGB values for the background of the source. __ The 4mXRecolorCursor24m function changes the color of the speci- fied cursor, and if the cursor is being displayed on a screen, the change is visible immediately. The pixel mem- bers of the 4mXColor24m structures are ignored; only the RGB val- ues are used. 4mXRecolorCursor24m can generate a 4mBadCursor24m error. To free (destroy) a given cursor, use 4mXFreeCursor24m. __ XFreeCursor(4mdisplay24m, 4mcursor24m) Display *4mdisplay24m; Cursor 4mcursor24m; 4mdisplay24m Specifies the connection to the X server. 4mcursor24m Specifies the cursor. __ The 4mXFreeCursor24m 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. 4mXFreeCursor24m can generate a 4mBadCursor24m error. 1m1110m 1mXlib C Library X11, Release 6.9/7.00m 1mChapter 60m 1mColor Management Functions0m Each X window always has an associated colormap that pro- vides 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 differ- ing 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: Create, copy, and destroy a colormap Specify colors by name or value Allocate, modify, and free color cells Read entries in a colormap Convert between color spaces Control aspects of color conversion Query the color gamut of a screen Add new color spaces All functions, types, and symbols in this chapter with the prefix Xcms are defined in <4mX11/Xcms.h24m>. The remaining functions and types are defined in <4mX11/Xlib.h24m>. 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 num- ber of significant bits in these values. As each pixel is read out of display memory, the pixel is looked up in a col- ormap. The RGB value of the cell determines what color is 1m1120m 1mXlib C Library X11, Release 6.9/7.00m displayed on the screen. On a grayscale display with a black-and-white monitor, the values are combined to deter- mine 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 unal- located 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 dis- played 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 dis- play with true colors, and windows using other colormaps generally display with incorrect colors. You can control the set of installed colormaps by using 4mXInstallColormap24m and 4mXUninstallColormap24m. 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 4mDefaultColormap24m macro returns the default colormap. The 4mDefaultVisual24m macro returns the default visual type for the specified screen. Possible visual types are 4mStaticGray24m, 4mGrayScale24m, 4mStaticColor24m, 4mPseudoColor24m, 4mTrueColor24m, or 4mDirect-0m 4mColor24m (see section 3.1). 1m6.1. Color Structures0m Functions that operate only on RGB color space values use an 4mXColor24m structure, which contains: 1m1130m 1mXlib C Library X11, Release 6.9/7.00m __ typedef struct { unsigned long pixel;/* pixel value */ unsigned short red, green, blue;/* rgb values */ char flags; /* DoRed, DoGreen, DoBlue */ char pad; } 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 val- ues down to the range used by the hardware. Black is repre- sented 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 4mDoRed24m, 4mDoGreen24m, and 4mDoBlue24m. Functions that operate on all color space values use an 4mXcm-0m 4msColor24m structure. This structure contains a union of sub- structures, each supporting color specification encoding for a particular color space. Like the 4mXColor24m structure, the 4mXcmsColor24m structure contains pixel and color specification information (the spec member in the 4mXcmsColor24m structure). __ typedef unsigned long XcmsColorFormat;/* Color Specification Format */ typedef struct { union { XcmsRGB RGB; XcmsRGBi RGBi; XcmsCIEXYZ CIEXYZ; XcmsCIEuvY CIEuvY; XcmsCIExyY CIExyY; XcmsCIELab CIELab; XcmsCIELuv CIELuv; XcmsTekHVC TekHVC; XcmsPad Pad; } spec; unsigned long pixel; XcmsColorFormat format; } XcmsColor; /* Xcms Color Structure */ __ Because the color specification can be encoded for the vari- ous color spaces, encoding for the spec member is identified by the format member, which is of type 4mXcmsColorFormat24m. The following macros define standard formats. 1m1140m 1mXlib C Library X11, Release 6.9/7.00m __ #define 4mXcmsUndefined-24m 0x00000000 4mFormat0m #define 4mXcmsCIEXYZFormat24m 0x00000001 /* CIE XYZ */ #define 4mXcmsCIEuvYFormat24m 0x00000002 /* CIE uvY */ #define 4mXcmsCIExyYFormat24m 0x00000003 /* CIE xyY */ #define 4mXcmsCIELabFormat24m 0x00000004 /* CIE L*a*b* */ #define 4mXcmsCIELuvFormat24m 0x00000005 /* CIE L*u*v* */ #define 4mXcmsTekHVCFormat24m 0x00000006 /* TekHVC */ #define 4mXcmsRGBFormat24m 0x80000000 /* RGB Device */ #define 4mXcmsRGBiFormat24m 0x80000001 /* RGB Inten- sity */ __ Formats for device-independent color spaces are distinguish- able from those for device-dependent spaces by the 32nd bit. If this bit is set, it indicates that the color specifica- tion is in a device-dependent form; otherwise, it is in a device-independent form. If the 31st bit is set, this indi- cates 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 pro- gram 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 4mXcmsFormatOfPrefix24m and 4mXcm-0m 4msPrefixOfFormat24m). Data types that describe the color specification encoding for the various color spaces are defined as follows: 1m1150m 1mXlib C Library X11, Release 6.9/7.00m __ typedef double XcmsFloat; typedef struct { unsigned short red; /* 0x0000 to 0xffff */ unsigned short green;/* 0x0000 to 0xffff */ unsigned short blue;/* 0x0000 to 0xffff */ } XcmsRGB; /* RGB Device */ typedef struct { XcmsFloat red; /* 0.0 to 1.0 */ XcmsFloat green; /* 0.0 to 1.0 */ XcmsFloat blue; /* 0.0 to 1.0 */ } XcmsRGBi; /* RGB Intensity */ typedef struct { XcmsFloat X; XcmsFloat Y; /* 0.0 to 1.0 */ XcmsFloat Z; } XcmsCIEXYZ; /* CIE XYZ */ typedef struct { XcmsFloat u_prime; /* 0.0 to ~0.6 */ XcmsFloat v_prime; /* 0.0 to ~0.6 */ XcmsFloat Y; /* 0.0 to 1.0 */ } XcmsCIEuvY; /* CIE uvY */ typedef struct { XcmsFloat x; /* 0.0 to ~.75 */ XcmsFloat y; /* 0.0 to ~.85 */ XcmsFloat Y; /* 0.0 to 1.0 */ } XcmsCIExyY; /* CIE xyY */ typedef struct { XcmsFloat L_star; /* 0.0 to 100.0 */ XcmsFloat a_star; XcmsFloat b_star; } XcmsCIELab; /* CIE L*a*b* */ typedef struct { XcmsFloat L_star; /* 0.0 to 100.0 */ 1m1160m 1mXlib C Library X11, Release 6.9/7.00m XcmsFloat u_star; XcmsFloat v_star; } XcmsCIELuv; /* CIE L*u*v* */ typedef struct { XcmsFloat H; /* 0.0 to 360.0 */ XcmsFloat V; /* 0.0 to 100.0 */ XcmsFloat C; /* 0.0 to 100.0 */ } XcmsTekHVC; /* TekHVC */ typedef struct { XcmsFloat pad0; XcmsFloat pad1; XcmsFloat pad2; XcmsFloat pad3; } XcmsPad; /* four doubles */ __ The device-dependent formats provided allow color specifica- tion in: RGB Intensity (4mXcmsRGBi24m) 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. RGB Device (4mXcmsRGB24m) Red, green, and blue values appropriate for the speci- fied output device. 4mXcmsRGB24m values are of type unsigned short, scaled from 0 to 65535 inclusive, and are interchangeable with the red, green, and blue val- ues in an 4mXColor24m structure. It is important to note that RGB Intensity values are not gamma corrected values. In contrast, RGB Device values gen- erated 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 4mRGB24m 4mvalue0m in this manual always refers to an RGB Device value. 1m6.2. Color Strings0m 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. 1m1170m 1mXlib C Library X11, Release 6.9/7.00m Color strings are used in the following functions: 4mXAllocNamedColor0m 4mXcmsAllocNamedColor0m 4mXLookupColor0m 4mXcmsLookupColor0m 4mXParseColor0m 4mXStoreNamedColor0m 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 servers 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: __ 4m24m:4m/.../0m __ 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 sec- tions. 1m6.2.1. RGB Device String Specification0m An RGB Device specification is identified by the prefix rgb: and conforms to the following syntax: rgb:4m//0m 1m1180m 1mXlib C Library X11, Release 6.9/7.00m 4m24m, 4m24m, 4m24m := 4mh24m | 4mhh24m | 4mhhh24m | 4mhhhh0m 4mh24m := single hexadecimal digits (case insignificant) Note that 4mh24m indicates the value scaled in 4 bits, 4mhh24m the value scaled in 8 bits, 4mhhh24m the value scaled in 12 bits, and 4mhhhh24m 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: #RGB (4 bits each) #RRGGBB (8 bits each) #RRRGGGBBB (12 bits each) #RRRRGGGGBBBB (16 bits each) 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: syn- tax, in which values are scaled). For example, the string #3a7 is the same as #3000a0007000. 1m6.2.2. RGB Intensity String Specification0m An RGB intensity specification is identified by the prefix rgbi: and conforms to the following syntax: rgbi:4m//0m 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. 1m6.2.3. Device-Independent String Specifications0m The standard device-independent string specifications have the following syntax: CIEXYZ:4m//0m 1m1190m 1mXlib C Library X11, Release 6.9/7.00m CIEuvY:4m//0m CIExyY:4m//0m CIELab:4m//0m CIELuv:4m//0m TekHVC:4m//0m 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. 1m6.3. Color Conversion Contexts and Gamut Mapping0m When Xlib converts device-independent color specifications into device-dependent specifications and vice versa, it uses knowledge about the color limitations of the screen hard- ware. This information, typically called the device pro- file, 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 compression occurs when conversion of device- independent color specifications to device-dependent color specifications results in a color out of the tar- get screens gamut. White adjustment occurs when the inherent white point of the screen differs from the white point assumed by the client. Gamut handling methods are stored as callbacks in the CCC, which in turn are used by the color space conversion rou- tines. Client data is also stored in the CCC for each call- back. 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 per- forming 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 transpar- ently generated by Xlib. Therefore, when you specify a col- ormap as an argument to an Xlib function, you are indirectly specifying a CCC. There is a default CCC associated with 1m1200m 1mXlib C Library X11, Release 6.9/7.00m 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 4mSta-0m 4mtus24m and have specific status values defined for them, as follows: 4mXcmsFailure24m indicates that the function failed. 4mXcmsSuccess24m indicates that the function succeeded. In addition, if the function performed any color conver- sion, the colors did not need to be compressed. 4mXcmsSuccessWithCompression24m indicates the function per- formed color conversion and at least one of the colors needed to be compressed. The gamut compression method is determined by the gamut compression procedure in the CCC that is specified directly as a function argument or in the CCC indirectly specified by means of the col- ormap argument. 1m6.4. Creating, Copying, and Destroying Colormaps0m To create a colormap for a screen, use 4mXCreateColormap24m. __ Colormap XCreateColormap(4mdisplay24m, 4mw24m, 4mvisual24m, 4malloc24m) Display *4mdisplay24m; Window 4mw24m; Visual *4mvisual24m; int 4malloc24m; 4mdisplay24m Specifies the connection to the X server. 4mw24m Specifies the window on whose screen you want to create a colormap. 4mvisual24m Specifies a visual type supported on the screen. If the visual type is not one supported by the screen, a 4mBadMatch24m error results. 4malloc24m Specifies the colormap entries to be allocated. You can pass 4mAllocNone24m or 4mAllocAll24m. __ The 4mXCreateColormap24m function creates a colormap of the spec- ified visual type for the screen on which the specified win- dow resides and returns the colormap ID associated with it. Note that the specified window is only used to determine the screen. 1m1210m 1mXlib C Library X11, Release 6.9/7.00m The initial values of the colormap entries are undefined for the visual classes 4mGrayScale24m, 4mPseudoColor24m, and 4mDirectColor24m. For 4mStaticGray24m, 4mStaticColor24m, and 4mTrueColor24m, the entries have defined values, but those values are specific to the visual and are not defined by X. For 4mStaticGray24m, 4mStaticColor24m, and 4mTrueColor24m, alloc must be 4mAllocNone24m, or a 4mBadMatch24m error results. For the other visual classes, if alloc is 4mAlloc-0m 4mNone24m, 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 4mAllocAll24m, the entire colormap is allocated writable. The initial values of all allocated entries are undefined. For 4mGrayScale24m and 4mPseudoColor24m, the effect is as if an 4mXAllocColorCells24m call returned all pixel values from zero to N 1, where N is the colormap entries value in the specified visual. For 4mDirectColor24m, the effect is as if an 4mXAllocColorPlanes24m 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 4mXFreeColors24m. 4mXCreateColormap24m can generate 4mBadAlloc24m, 4mBadMatch24m, 4mBadValue24m, and 4mBadWindow24m errors. To create a new colormap when the allocation out of a previ- ously shared colormap has failed because of resource exhaus- tion, use 4mXCopyColormapAndFree24m. __ Colormap XCopyColormapAndFree(4mdisplay24m, 4mcolormap24m) Display *4mdisplay24m; Colormap 4mcolormap24m; 4mdisplay24m Specifies the connection to the X server. 4mcolormap24m Specifies the colormap. __ The 4mXCopyColormapAndFree24m 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 clients existing allocation from the specified col- ormap 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 4mAllocAll24m, the new colormap is also created with 4mAllocAll24m, all color values for all entries are copied from the speci- fied colormap, and then all entries in the specified 1m1220m 1mXlib C Library X11, Release 6.9/7.00m colormap are freed. If the specified colormap was not cre- ated by the client with 4mAllocAll24m, the allocations to be moved are all those pixels and planes that have been allo- cated by the client using 4mXAllocColor24m, 4mXAllocNamedColor24m, 4mXAllocColorCells24m, or 4mXAllocColorPlanes24m and that have not been freed since they were allocated. 4mXCopyColormapAndFree24m can generate 4mBadAlloc24m and 4mBadColor0m errors. To destroy a colormap, use 4mXFreeColormap24m. __ XFreeColormap(4mdisplay24m, 4mcolormap24m) Display *4mdisplay24m; Colormap 4mcolormap24m; 4mdisplay24m Specifies the connection to the X server. 4mcolormap24m Specifies the colormap that you want to destroy. __ The 4mXFreeColormap24m function deletes the association between the colormap resource ID and the colormap and frees the col- ormap 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 4mXUnin-0m 4mstallColormap24m). If the specified colormap is defined as the colormap for a window (by 4mXCreateWindow24m, 4mXSetWindowColormap24m, or 4mXChangeWindowAttributes24m), 4mXFreeColormap24m changes the col- ormap associated with the window to 4mNone24m and generates a 4mColormapNotify24m event. X does not define the colors dis- played for a window with a colormap of 4mNone24m. 4mXFreeColormap24m can generate a 4mBadColor24m error. 1m6.5. Mapping Color Names to Values0m To map a color name to an RGB value, use 4mXLookupColor24m. 1m1230m 1mXlib C Library X11, Release 6.9/7.00m __ Status XLookupColor(4mdisplay24m, 4mcolormap24m, 4mcolor_name24m, 4mexact_def_return24m, 4mscreen_def_return24m) Display *4mdisplay24m; Colormap 4mcolormap24m; char *4mcolor_name24m; XColor *4mexact_def_return24m, *4mscreen_def_return24m; 4mdisplay24m Specifies the connection to the X server. 4mcolormap24m Specifies the colormap. 4mcolor_name0m Specifies the color name string (for example, red) whose color definition structure you want returned. 4mexact_def_return0m Returns the exact RGB values. 4mscreen_def_return0m Returns the closest RGB values provided by the hardware. __ The 4mXLookupColor24m function looks up the string name of a color with respect to the screen associated with the speci- fied 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. 4mXLookupColor24m returns nonzero if the name is resolved; otherwise, it returns zero. 4mXLookupColor24m can generate a 4mBadColor24m error. To map a color name to the exact RGB value, use 4mXParseColor24m. 1m1240m 1mXlib C Library X11, Release 6.9/7.00m __ Status XParseColor(4mdisplay24m, 4mcolormap24m, 4mspec24m, 4mexact_def_return24m) Display *4mdisplay24m; Colormap 4mcolormap24m; char *4mspec24m; XColor *4mexact_def_return24m; 4mdisplay24m Specifies the connection to the X server. 4mcolormap24m Specifies the colormap. 4mspec24m Specifies the color name string; case is ignored. 4mexact_def_return0m Returns the exact color value for later use and sets the 4mDoRed24m, 4mDoGreen24m, and 4mDoBlue24m flags. __ The 4mXParseColor24m 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. 4mXParseColor24m returns nonzero if the name is resolved; otherwise, it returns zero. 4mXParseColor24m can generate a 4mBadColor24m error. To map a color name to a value in an arbitrary color space, use 4mXcmsLookupColor24m. 1m1250m 1mXlib C Library X11, Release 6.9/7.00m __ Status XcmsLookupColor(4mdisplay24m, 4mcolormap24m, 4mcolor_string24m, 4mcolor_exact_return24m, 4mcolor_screen_return24m, 4mresult_format24m) Display *4mdisplay24m; Colormap 4mcolormap24m; char *4mcolor_string24m; XcmsColor *4mcolor_exact_return24m, *4mcolor_screen_return24m; XcmsColorFormat 4mresult_format24m; 4mdisplay24m Specifies the connection to the X server. 4mcolormap24m Specifies the colormap. 4mcolor_string0m Specifies the color string. 4mcolor_exact_return0m Returns the color specification parsed from the color string or parsed from the corresponding string found in a color-name database. 4mcolor_screen_return0m Returns the color that can be reproduced on the screen. 4mresult_format0m Specifies the color format for the returned color specifications (color_screen_return and color_exact_return arguments). If the format is 4mXcmsUndefinedFormat24m and the color string contains a numerical color specification, the specification is returned in the format used in that numerical color specification. If the format is 4mXcmsUnde-0m 4mfinedFormat24m and the color string contains a color name, the specification is returned in the format used to store the color in the database. __ The 4mXcmsLookupColor24m function looks up the string name of a color with respect to the screen associated with the speci- fied 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. 4mXcmsLookupColor24m returns 4mXcmsSuc-0m 4mcess24m or 4mXcmsSuccessWithCompression24m if the name is resolved; otherwise, it returns 4mXcmsFailure24m. If 4mXcmsSuccessWithCom-0m 4mpression24m is returned, the color specification returned in color_screen_return is the result of gamut compression. 1m1260m 1mXlib C Library X11, Release 6.9/7.00m 1m6.6. Allocating and Freeing Color Cells0m 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 con- sidered 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 4mXAllocColor24m. __ Status XAllocColor(4mdisplay24m, 4mcolormap24m, 4mscreen_in_out24m) Display *4mdisplay24m; Colormap 4mcolormap24m; XColor *4mscreen_in_out24m; 4mdisplay24m Specifies the connection to the X server. 4mcolormap24m Specifies the colormap. 4mscreen_in_out0m Specifies and returns the values actually used in the colormap. __ The 4mXAllocColor24m function allocates a read-only colormap entry corresponding to the closest RGB value supported by the hardware. 4mXAllocColor24m 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 cor- responding colormap cell is read-only. In addition, 4mXAlloc-0m 4mColor24m 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. 4mXAllocColor24m does not use or affect the flags in the 4mXColor24m structure. 1m1270m 1mXlib C Library X11, Release 6.9/7.00m 4mXAllocColor24m can generate a 4mBadColor24m error. To allocate a read-only color cell with a color in arbitrary format, use 4mXcmsAllocColor24m. __ Status XcmsAllocColor(4mdisplay24m, 4mcolormap24m, 4mcolor_in_out24m, 4mresult_format24m) Display *4mdisplay24m; Colormap 4mcolormap24m; XcmsColor *4mcolor_in_out24m; XcmsColorFormat 4mresult_format24m; 4mdisplay24m Specifies the connection to the X server. 4mcolormap24m Specifies the colormap. 4mcolor_in_out0m Specifies the color to allocate and returns the pixel and color that is actually used in the col- ormap. 4mresult_format0m Specifies the color format for the returned color specification. __ The 4mXcmsAllocColor24m function is similar to 4mXAllocColor24m except the color can be specified in any format. The 4mXcmsAlloc-0m 4mColor24m function ultimately calls 4mXAllocColor24m to allocate a read-only color cell (colormap entry) with the specified color. 4mXcmsAllocColor24m first converts the color specified to an RGB value and then passes this to 4mXAllocColor24m. 4mXcmsAl-0m 4mlocColor24m 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 4mXAllocColor24m 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 4mXcmsRGBFormat24m. The cor- responding colormap cell is read-only. If this routine returns 4mXcmsFailure24m, the color_in_out color specification is left unchanged. 4mXcmsAllocColor24m can generate a 4mBadColor24m 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 4mXAllocNamedColor24m. 1m1280m 1mXlib C Library X11, Release 6.9/7.00m __ Status XAllocNamedColor(4mdisplay24m, 4mcolormap24m, 4mcolor_name24m, 4mscreen_def_return24m, 4mexact_def_return24m) Display *4mdisplay24m; Colormap 4mcolormap24m; char *4mcolor_name24m; XColor *4mscreen_def_return24m, *4mexact_def_return24m; 4mdisplay24m Specifies the connection to the X server. 4mcolormap24m Specifies the colormap. 4mcolor_name0m Specifies the color name string (for example, red) whose color definition structure you want returned. 4mscreen_def_return0m Returns the closest RGB values provided by the hardware. 4mexact_def_return0m Returns the exact RGB values. __ The 4mXAllocNamedColor24m 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. 4mXAllocNamedColor24m returns nonzero if a cell is allocated; otherwise, it returns zero. 4mXAllocNamedColor24m can generate a 4mBadColor24m 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 4mXcmsAllocNamedColor24m. 1m1290m 1mXlib C Library X11, Release 6.9/7.00m __ Status XcmsAllocNamedColor(4mdisplay24m, 4mcolormap24m, 4mcolor_string24m, 4mcolor_screen_return24m, 4mcolor_exact_return24m, 4mresult_format24m) Display *4mdisplay24m; Colormap 4mcolormap24m; char *4mcolor_string24m; XcmsColor *4mcolor_screen_return24m; XcmsColor *4mcolor_exact_return24m; XcmsColorFormat 4mresult_format24m; 4mdisplay24m Specifies the connection to the X server. 4mcolormap24m Specifies the colormap. 4mcolor_string0m Specifies the color string whose color definition structure is to be returned. 4mcolor_screen_return0m Returns the pixel value of the color cell and color specification that actually is stored for that cell. 4mcolor_exact_return0m Returns the color specification parsed from the color string or parsed from the corresponding string found in a color-name database. 4mresult_format0m Specifies the color format for the returned color specifications (color_screen_return and color_exact_return arguments). If the format is 4mXcmsUndefinedFormat24m and the color string contains a numerical color specification, the specification is returned in the format used in that numerical color specification. If the format is 4mXcmsUnde-0m 4mfinedFormat24m and the color string contains a color name, the specification is returned in the format used to store the color in the database. __ The 4mXcmsAllocNamedColor24m function is similar to 4mXAllocNamed-0m 4mColor24m except that the color returned can be in any format specified. This function ultimately calls 4mXAllocColor24m to allocate a read-only color cell with the color specified by a color string. The color string is parsed into an 4mXcms-0m 4mColor24m structure (see 4mXcmsLookupColor24m), converted to an RGB value, and finally passed to 4mXAllocColor24m. 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. 1m1300m 1mXlib C Library X11, Release 6.9/7.00m 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 4mXAllocColor24m 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 4mXcmsRGBFormat24m. 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. 4mXcmsAllocNamedColor24m can generate a 4mBadColor24m error. To allocate read/write color cell and color plane combina- tions for a 4mPseudoColor24m model, use 4mXAllocColorCells24m. __ Status XAllocColorCells(4mdisplay24m, 4mcolormap24m, 4mcontig24m, 4mplane_masks_return24m, 4mnplanes24m, 4mpixels_return24m, 4mnpixels24m) Display *4mdisplay24m; Colormap 4mcolormap24m; Bool 4mcontig24m; unsigned long 4mplane_masks_return24m[]; unsigned int 4mnplanes24m; unsigned long 4mpixels_return24m[]; unsigned int 4mnpixels24m; 4mdisplay24m Specifies the connection to the X server. 4mcolormap24m Specifies the colormap. 4mcontig24m Specifies a Boolean value that indicates whether the planes must be contiguous. 4mplane_mask_return0m Returns an array of plane masks. 4mnplanes24m Specifies the number of plane masks that are to be returned in the plane masks array. 4mpixels_return0m Returns an array of pixel values. 4mnpixels24m Specifies the number of pixel values that are to be returned in the pixels_return array. __ The 4mXAllocColorCells24m function allocates read/write color cells. The number of colors must be positive and the number of planes nonnegative, or a 4mBadValue24m error results. If 1m1310m 1mXlib C Library X11, Release 6.9/7.00m 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 * 24mnplanes24m distinct pixels can be produced. All of these are allocated writable by the request. For 4mGrayScale24m or 4mPseudoColor24m, each mask has exactly one bit set to 1. For 4mDirectColor24m, each has exactly three bits set to 1. If contig is 4mTrue24m and if all masks are ORed together, a single contiguous set of bits set to 1 will be formed for 4mGrayScale24m or 4mPseudoColor24m and three contiguous sets of bits set to 1 (one within each pixel subfield) for 4mDirectColor24m. The RGB values of the allocated entries are undefined. 4mXAl-0m 4mlocColorCells24m returns nonzero if it succeeded or zero if it failed. 4mXAllocColorCells24m can generate 4mBadColor24m and 4mBadValue24m errors. To allocate read/write color resources for a 4mDirectColor0m model, use 4mXAllocColorPlanes24m. 1m1320m 1mXlib C Library X11, Release 6.9/7.00m __ Status XAllocColorPlanes(4mdisplay24m, 4mcolormap24m, 4mcontig24m, 4mpixels_return24m, 4mncolors24m, 4mnreds24m, 4mngreens24m, 4mnblues24m, 4mrmask_return24m, 4mgmask_return24m, 4mbmask_return24m) Display *4mdisplay24m; Colormap 4mcolormap24m; Bool 4mcontig24m; unsigned long 4mpixels_return24m[]; int 4mncolors24m; int 4mnreds24m, 4mngreens24m, 4mnblues24m; unsigned long *4mrmask_return24m, *4mgmask_return24m, *4mbmask_return24m; 4mdisplay24m Specifies the connection to the X server. 4mcolormap24m Specifies the colormap. 4mcontig24m Specifies a Boolean value that indicates whether the planes must be contiguous. 4mpixels_return0m Returns an array of pixel values. 4mXAllocColor-0m 4mPlanes24m returns the pixel values in this array. 4mncolors24m Specifies the number of pixel values that are to be returned in the pixels_return array. 4mnreds0m 4mngreens0m 4mnblues0m Specify the number of red, green, and blue planes. The value you pass must be nonnegative. 4mrmask_return0m 4mgmask_return0m 4mbmask_return0m 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 4mBadValue24m 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, respec- tively. If contig is 4mTrue24m, 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 4mDirectColor24m, each mask will lie within the corresponding pixel subfield. By ORing together subsets of masks with each pixel value, ncolors * 2(4mnreds24m+4mngreens24m+4mnblues24m) distinct pixel values can be produced. All of these are allocated by the request. However, in the colormap, there are only ncol- ors * 24mnreds24m independent red entries, ncolors * 24mngreens0m 1m1330m 1mXlib C Library X11, Release 6.9/7.00m independent green entries, and ncolors * 24mnblues24m independent blue entries. This is true even for 4mPseudoColor24m. When the colormap entry of a pixel value is changed (using 4mXStoreCol-0m 4mors24m, 4mXStoreColor24m, or 4mXStoreNamedColor24m), the pixel is decom- posed according to the masks, and the corresponding indepen- dent entries are updated. 4mXAllocColorPlanes24m returns nonzero if it succeeded or zero if it failed. 4mXAllocColorPlanes24m can generate 4mBadColor24m and 4mBadValue24m errors. To free colormap cells, use 4mXFreeColors24m. __ XFreeColors(4mdisplay24m, 4mcolormap24m, 4mpixels24m, 4mnpixels24m, 4mplanes24m) Display *4mdisplay24m; Colormap 4mcolormap24m; unsigned long 4mpixels24m[]; int 4mnpixels24m; unsigned long 4mplanes24m; 4mdisplay24m Specifies the connection to the X server. 4mcolormap24m Specifies the colormap. 4mpixels24m Specifies an array of pixel values that map to the cells in the specified colormap. 4mnpixels24m Specifies the number of pixels. 4mplanes24m Specifies the planes you want to free. __ The 4mXFreeColors24m function frees the cells represented by pix- els whose values are in the pixels array. The planes argu- ment 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 4mXAllocColor24m, 4mXAllocNamedColor24m, 4mXAllocCol-0m 4morCells24m, and 4mXAllocColorPlanes24m). Note that freeing an indi- vidual pixel obtained from 4mXAllocColorPlanes24m may not actu- ally allow it to be reused until all of its related pixels are also freed. Similarly, a read-only entry is not actu- ally 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 4mBadValue24m error results. If a specified pixel is 1m1340m 1mXlib C Library X11, Release 6.9/7.00m 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 4mAllocAll24m to 4mXCreateColormap24m), a 4mBadAccess24m error results. If more than one pixel is in error, the one that gets reported is arbi- trary. 4mXFreeColors24m can generate 4mBadAccess24m, 4mBadColor24m, and 4mBadValue0m errors. 1m6.7. Modifying and Querying Colormap Cells0m To store an RGB value in a single colormap cell, use 4mXStore-0m 4mColor24m. __ XStoreColor(4mdisplay24m, 4mcolormap24m, 4mcolor24m) Display *4mdisplay24m; Colormap 4mcolormap24m; XColor *4mcolor24m; 4mdisplay24m Specifies the connection to the X server. 4mcolormap24m Specifies the colormap. 4mcolor24m Specifies the pixel and RGB values. __ The 4mXStoreColor24m function changes the colormap entry of the pixel value specified in the pixel member of the 4mXColor0m structure. You specified this value in the pixel member of the 4mXColor24m 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 4mBadValue0m error results. 4mXStoreColor24m also changes the red, green, and/or blue color components. You specify which color com- ponents are to be changed by setting 4mDoRed24m, 4mDoGreen24m, and/or 4mDoBlue24m in the flags member of the 4mXColor24m structure. If the colormap is an installed map for its screen, the changes are visible immediately. 4mXStoreColor24m can generate 4mBadAccess24m, 4mBadColor24m, and 4mBadValue0m errors. To store multiple RGB values in multiple colormap cells, use 4mXStoreColors24m. 1m1350m 1mXlib C Library X11, Release 6.9/7.00m __ XStoreColors(4mdisplay24m, 4mcolormap24m, 4mcolor24m, 4mncolors24m) Display *4mdisplay24m; Colormap 4mcolormap24m; XColor 4mcolor24m[]; int 4mncolors24m; 4mdisplay24m Specifies the connection to the X server. 4mcolormap24m Specifies the colormap. 4mcolor24m Specifies an array of color definition structures to be stored. 4mncolors24m Specifies the number of 4mXColor24m structures in the color definition array. __ The 4mXStoreColors24m function changes the colormap entries of the pixel values specified in the pixel members of the 4mXColor24m structures. You specify which color components are to be changed by setting 4mDoRed24m, 4mDoGreen24m, and/or 4mDoBlue24m in the flags member of the 4mXColor24m structures. If the colormap is an installed map for its screen, the changes are visible immediately. 4mXStoreColors24m changes the specified pixels if they are allocated writable in the colormap by any client, even if one or more pixels generates an error. If a speci- fied pixel is not a valid index into the colormap, a 4mBad-0m 4mValue24m error results. If a specified pixel either is unallo- cated or is allocated read-only, a 4mBadAccess24m error results. If more than one pixel is in error, the one that gets reported is arbitrary. 4mXStoreColors24m can generate 4mBadAccess24m, 4mBadColor24m, and 4mBadValue0m errors. To store a color of arbitrary format in a single colormap cell, use 4mXcmsStoreColor24m. 1m1360m 1mXlib C Library X11, Release 6.9/7.00m __ Status XcmsStoreColor(4mdisplay24m, 4mcolormap24m, 4mcolor24m) Display *4mdisplay24m; Colormap 4mcolormap24m; XcmsColor *4mcolor24m; 4mdisplay24m Specifies the connection to the X server. 4mcolormap24m Specifies the colormap. 4mcolor24m Specifies the color cell and the color to store. Values specified in this 4mXcmsColor24m structure remain unchanged on return. __ The 4mXcmsStoreColor24m function converts the color specified in the 4mXcmsColor24m structure into RGB values. It then uses this RGB specification in an 4mXColor24m structure, whose three flags (4mDoRed24m, 4mDoGreen24m, and 4mDoBlue24m) are set, in a call to 4mXStore-0m 4mColor24m to change the color cell specified by the pixel member of the 4mXcmsColor24m structure. This pixel value must be a valid index for the specified colormap, and the color cell specified by the pixel value must be a read/write cell. If the pixel value is not a valid index, a 4mBadValue24m error results. If the color cell is unallocated or is allocated read-only, a 4mBadAccess24m error results. If the colormap is an installed map for its screen, the changes are visible imme- diately. Note that 4mXStoreColor24m has no return value; therefore, an 4mXcmsSuccess24m return value from this function indicates that the conversion to RGB succeeded and the call to 4mXStoreColor0m was made. To obtain the actual color stored, use 4mXcmsQuery-0m 4mColor24m. Because of the screens hardware limitations or gamut compression, the color stored in the colormap may not be identical to the color specified. 4mXcmsStoreColor24m can generate 4mBadAccess24m, 4mBadColor24m, and 4mBad-0m 4mValue24m errors. To store multiple colors of arbitrary format in multiple colormap cells, use 4mXcmsStoreColors24m. 1m1370m 1mXlib C Library X11, Release 6.9/7.00m __ Status XcmsStoreColors(4mdisplay24m, 4mcolormap24m, 4mcolors24m, 4mncolors24m, 4mcompression_flags_return24m) Display *4mdisplay24m; Colormap 4mcolormap24m; XcmsColor 4mcolors24m[]; int 4mncolors24m; Bool 4mcompression_flags_return24m[]; 4mdisplay24m Specifies the connection to the X server. 4mcolormap24m Specifies the colormap. 4mcolors24m Specifies the color specification array of 4mXcms-0m 4mColor24m structures, each specifying a color cell and the color to store in that cell. Values specified in the array remain unchanged upon return. 4mncolors24m Specifies the number of 4mXcmsColor24m structures in the color-specification array. 4mcompression_flags_return0m Returns an array of Boolean values indicating com- pression status. If a non-NULL pointer is sup- plied, each element of the array is set to 4mTrue24m if the corresponding color was compressed and 4mFalse0m otherwise. Pass NULL if the compression status is not useful. __ The 4mXcmsStoreColors24m function converts the colors specified in the array of 4mXcmsColor24m structures into RGB values and then uses these RGB specifications in 4mXColor24m structures, whose three flags (4mDoRed24m, 4mDoGreen24m, and 4mDoBlue24m) are set, in a call to 4mXStoreColors24m to change the color cells specified by the pixel member of the corresponding 4mXcmsColor24m structure. Each pixel value must be a valid index for the specified colormap, and the color cell specified by each pixel value must be a read/write cell. If a pixel value is not a valid index, a 4mBadValue24m error results. If a color cell is unallo- cated or is allocated read-only, a 4mBadAccess24m error results. If more than one pixel is in error, the one that gets reported is arbitrary. If the colormap is an installed map for its screen, the changes are visible immediately. Note that 4mXStoreColors24m has no return value; therefore, an 4mXcmsSuccess24m return value from this function indicates that conversions to RGB succeeded and the call to 4mXStoreColors0m was made. To obtain the actual colors stored, use 4mXcms-0m 4mQueryColors24m. Because of the screens hardware limitations or gamut compression, the colors stored in the colormap may not be identical to the colors specified. 1m1380m 1mXlib C Library X11, Release 6.9/7.00m 4mXcmsStoreColors24m can generate 4mBadAccess24m, 4mBadColor24m, and 4mBad-0m 4mValue24m errors. To store a color specified by name in a single colormap cell, use 4mXStoreNamedColor24m. __ XStoreNamedColor(4mdisplay24m, 4mcolormap24m, 4mcolor24m, 4mpixel24m, 4mflags24m) Display *4mdisplay24m; Colormap 4mcolormap24m; char *4mcolor24m; unsigned long 4mpixel24m; int 4mflags24m; 4mdisplay24m Specifies the connection to the X server. 4mcolormap24m Specifies the colormap. 4mcolor24m Specifies the color name string (for example, red). 4mpixel24m Specifies the entry in the colormap. 4mflags24m Specifies which red, green, and blue components are set. __ The 4mXStoreNamedColor24m function looks up the named color with respect to the screen associated with the colormap and stores the result in the specified colormap. The pixel argument determines the entry in the colormap. The flags argument determines which of the red, green, and blue compo- nents are set. You can set this member to the bitwise inclusive OR of the bits 4mDoRed24m, 4mDoGreen24m, and 4mDoBlue24m. 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 the specified pixel is not a valid index into the colormap, a 4mBadValue24m error results. If the specified pixel either is unallocated or is allocated read-only, a 4mBadAccess24m error results. 4mXStoreNamedColor24m can generate 4mBadAccess24m, 4mBadColor24m, 4mBadName24m, and 4mBadValue24m errors. The 4mXQueryColor24m and 4mXQueryColors24m functions take pixel values in the pixel member of 4mXColor24m structures and store in the structures the RGB values for those pixels from the speci- fied colormap. The values returned for an unallocated entry are undefined. These functions also set the flags member in the 4mXColor24m structure to all three colors. If a pixel is not a valid index into the specified colormap, a 4mBadValue24m error results. If more than one pixel is in error, the one that 1m1390m 1mXlib C Library X11, Release 6.9/7.00m gets reported is arbitrary. To query the RGB value of a single colormap cell, use 4mXQueryColor24m. __ XQueryColor(4mdisplay24m, 4mcolormap24m, 4mdef_in_out24m) Display *4mdisplay24m; Colormap 4mcolormap24m; XColor *4mdef_in_out24m; 4mdisplay24m Specifies the connection to the X server. 4mcolormap24m Specifies the colormap. 4mdef_in_out0m Specifies and returns the RGB values for the pixel specified in the structure. __ The 4mXQueryColor24m function returns the current RGB value for the pixel in the 4mXColor24m structure and sets the 4mDoRed24m, 4mDoGreen24m, and 4mDoBlue24m flags. 4mXQueryColor24m can generate 4mBadColor24m and 4mBadValue24m errors. To query the RGB values of multiple colormap cells, use 4mXQueryColors24m. __ XQueryColors(4mdisplay24m, 4mcolormap24m, 4mdefs_in_out24m, 4mncolors24m) Display *4mdisplay24m; Colormap 4mcolormap24m; XColor 4mdefs_in_out24m[]; int 4mncolors24m; 4mdisplay24m Specifies the connection to the X server. 4mcolormap24m Specifies the colormap. 4mdefs_in_out0m Specifies and returns an array of color definition structures for the pixel specified in the struc- ture. 4mncolors24m Specifies the number of 4mXColor24m structures in the color definition array. __ The 4mXQueryColors24m function returns the RGB value for each 1m1400m 1mXlib C Library X11, Release 6.9/7.00m pixel in each 4mXColor24m structure and sets the 4mDoRed24m, 4mDoGreen24m, and 4mDoBlue24m flags in each structure. 4mXQueryColors24m can generate 4mBadColor24m and 4mBadValue24m errors. To query the color of a single colormap cell in an arbitrary format, use 4mXcmsQueryColor24m. __ Status XcmsQueryColor(4mdisplay24m, 4mcolormap24m, 4mcolor_in_out24m, 4mresult_format24m) Display *4mdisplay24m; Colormap 4mcolormap24m; XcmsColor *4mcolor_in_out24m; XcmsColorFormat 4mresult_format24m; 4mdisplay24m Specifies the connection to the X server. 4mcolormap24m Specifies the colormap. 4mcolor_in_out0m Specifies the pixel member that indicates the color cell to query. The color specification stored for the color cell is returned in this 4mXcm-0m 4msColor24m structure. 4mresult_format0m Specifies the color format for the returned color specification. __ The 4mXcmsQueryColor24m function obtains the RGB value for the pixel value in the pixel member of the specified 4mXcmsColor0m structure and then converts the value to the target format as specified by the result_format argument. If the pixel is not a valid index in the specified colormap, a 4mBadValue0m error results. 4mXcmsQueryColor24m can generate 4mBadColor24m and 4mBadValue24m errors. To query the color of multiple colormap cells in an arbi- trary format, use 4mXcmsQueryColors24m. 1m1410m 1mXlib C Library X11, Release 6.9/7.00m __ Status XcmsQueryColors(4mdisplay24m, 4mcolormap24m, 4mcolors_in_out24m, 4mncolors24m, 4mresult_format24m) Display *4mdisplay24m; Colormap 4mcolormap24m; XcmsColor 4mcolors_in_out24m[]; unsigned int 4mncolors24m; XcmsColorFormat 4mresult_format24m; 4mdisplay24m Specifies the connection to the X server. 4mcolormap24m Specifies the colormap. 4mcolors_in_out0m Specifies an array of 4mXcmsColor24m structures, each pixel member indicating the color cell to query. The color specifications for the color cells are returned in these structures. 4mncolors24m Specifies the number of 4mXcmsColor24m structures in the color-specification array. 4mresult_format0m Specifies the color format for the returned color specification. __ The 4mXcmsQueryColors24m function obtains the RGB values for pixel values in the pixel members of 4mXcmsColor24m structures and then converts the values to the target format as speci- fied by the result_format argument. If a pixel is not a valid index into the specified colormap, a 4mBadValue24m error results. If more than one pixel is in error, the one that gets reported is arbitrary. 4mXcmsQueryColors24m can generate 4mBadColor24m and 4mBadValue24m errors. 1m6.8. Color Conversion Context Functions0m This section describes functions to create, modify, and query Color Conversion Contexts (CCCs). Associated with each colormap is an initial CCC transpar- ently generated by Xlib. Therefore, when you specify a col- ormap as an argument to a function, you are indirectly spec- ifying a CCC. The CCC attributes that can be modified by the X client are: Client White Point Gamut compression procedure and client data White point adjustment procedure and client data 1m1420m 1mXlib C Library X11, Release 6.9/7.00m The initial values for these attributes are implementation specific. The CCC attributes for subsequently created CCCs can be defined by changing the CCC attributes of the default CCC. There is a default CCC associated with each screen. 1m6.8.1. Getting and Setting the Color Conversion Context of0m 1ma Colormap0m To obtain the CCC associated with a colormap, use 4mXcmsCCCOf-0m 4mColormap24m. __ XcmsCCC XcmsCCCOfColormap(4mdisplay24m, 4mcolormap24m) Display *4mdisplay24m; Colormap 4mcolormap24m; 4mdisplay24m Specifies the connection to the X server. 4mcolormap24m Specifies the colormap. __ The 4mXcmsCCCOfColormap24m function returns the CCC associated with the specified colormap. Once obtained, the CCC attributes can be queried or modified. Unless the CCC asso- ciated with the specified colormap is changed with 4mXcmsSetC-0m 4mCCOfColormap24m, this CCC is used when the specified colormap is used as an argument to color functions. To change the CCC associated with a colormap, use 4mXcmsSetCC-0m 4mCOfColormap24m. __ XcmsCCC XcmsSetCCCOfColormap(4mdisplay24m, 4mcolormap24m, 4mccc24m) Display *4mdisplay24m; Colormap 4mcolormap24m; XcmsCCC 4mccc24m; 4mdisplay24m Specifies the connection to the X server. 4mcolormap24m Specifies the colormap. 4mccc24m Specifies the CCC. __ The 4mXcmsSetCCCOfColormap24m function changes the CCC associated with the specified colormap. It returns the CCC previously associated with the colormap. If they are not used again in the application, CCCs should be freed by calling 4mXcms-0m 4mFreeCCC24m. Several colormaps may share the same CCC without restriction; this includes the CCCs generated by Xlib with 1m1430m 1mXlib C Library X11, Release 6.9/7.00m each colormap. Xlib, however, creates a new CCC with each new colormap. 1m6.8.2. Obtaining the Default Color Conversion Context0m You can change the default CCC attributes for subsequently created CCCs by changing the CCC attributes of the default CCC. A default CCC is associated with each screen. To obtain the default CCC for a screen, use 4mXcmsDefaultCCC24m. __ XcmsCCC XcmsDefaultCCC(4mdisplay24m, 4mscreen_number24m) Display *4mdisplay24m; int 4mscreen_number24m; 4mdisplay24m Specifies the connection to the X server. 4mscreen_number0m Specifies the appropriate screen number on the host server. __ The 4mXcmsDefaultCCC24m function returns the default CCC for the specified screen. Its visual is the default visual of the screen. Its initial gamut compression and white point adjustment procedures as well as the associated client data are implementation specific. 1m6.8.3. Color Conversion Context Macros0m Applications should not directly modify any part of the 4mXcm-0m 4msCCC24m. The following lists the C language macros, their cor- responding function equivalents for other language bindings, and what data they both can return. __ DisplayOfCCC(4mccc24m) XcmsCCC 4mccc24m; Display *XcmsDisplayOfCCC(4mccc24m) XcmsCCC 4mccc24m; 4mccc24m Specifies the CCC. __ Both return the display associated with the specified CCC. 1m1440m 1mXlib C Library X11, Release 6.9/7.00m __ VisualOfCCC(4mccc24m) XcmsCCC 4mccc24m; Visual *XcmsVisualOfCCC(4mccc24m) XcmsCCC 4mccc24m; 4mccc24m Specifies the CCC. __ Both return the visual associated with the specified CCC. __ ScreenNumberOfCCC(4mccc24m) XcmsCCC 4mccc24m; int XcmsScreenNumberOfCCC(4mccc24m) XcmsCCC 4mccc24m; 4mccc24m Specifies the CCC. __ Both return the number of the screen associated with the specified CCC. __ ScreenWhitePointOfCCC(4mccc24m) XcmsCCC 4mccc24m; XcmsColor *XcmsScreenWhitePointOfCCC(4mccc24m) XcmsCCC 4mccc24m; 4mccc24m Specifies the CCC. __ Both return the white point of the screen associated with the specified CCC. 1m1450m 1mXlib C Library X11, Release 6.9/7.00m __ ClientWhitePointOfCCC(4mccc24m) XcmsCCC 4mccc24m; XcmsColor *XcmsClientWhitePointOfCCC(4mccc24m) XcmsCCC 4mccc24m; 4mccc24m Specifies the CCC. __ Both return the Client White Point of the specified CCC. 1m6.8.4. Modifying Attributes of a Color Conversion Context0m To set the Client White Point in the CCC, use 4mXcmsSetWhite-0m 4mPoint24m. __ Status XcmsSetWhitePoint(4mccc24m, 4mcolor24m) XcmsCCC 4mccc24m; XcmsColor *4mcolor24m; 4mccc24m Specifies the CCC. 4mcolor24m Specifies the new Client White Point. __ The 4mXcmsSetWhitePoint24m function changes the Client White Point in the specified CCC. Note that the pixel member is ignored and that the color specification is left unchanged upon return. The format for the new white point must be 4mXcmsCIEXYZFormat24m, 4mXcmsCIEuvYFormat24m, 4mXcmsCIExyYFormat24m, or 4mXcmsUndefinedFormat24m. If the color argument is NULL, this function sets the format component of the Client White Point specification to 4mXcmsUndefinedFormat24m, indicating that the Client White Point is assumed to be the same as the Screen White Point. This function returns nonzero status if the format for the new white point is valid; otherwise, it returns zero. To set the gamut compression procedure and corresponding client data in a specified CCC, use 4mXcmsSetCompressionProc24m. 1m1460m 1mXlib C Library X11, Release 6.9/7.00m __ XcmsCompressionProc XcmsSetCompressionProc(4mccc24m, 4mcompression_proc24m, 4mclient_data24m) XcmsCCC 4mccc24m; XcmsCompressionProc 4mcompression_proc24m; XPointer 4mclient_data24m; 4mccc24m Specifies the CCC. 4mcompression_proc0m Specifies the gamut compression procedure that is to be applied when a color lies outside the screens color gamut. If NULL is specified and a function using this CCC must convert a color spec- ification to a device-dependent format and encoun- ters a color that lies outside the screens color gamut, that function will return 4mXcmsFailure24m. 4mclient_data0m Specifies client data for the gamut compression procedure or NULL. __ The 4mXcmsSetCompressionProc24m function first sets the gamut compression procedure and client data in the specified CCC with the newly specified procedure and client data and then returns the old procedure. To set the white point adjustment procedure and correspond- ing client data in a specified CCC, use 4mXcmsSetWhiteAdjust-0m 4mProc24m. __ XcmsWhiteAdjustProc XcmsSetWhiteAdjustProc(4mccc24m, 4mwhite_adjust_proc24m, 4mclient_data24m) XcmsCCC 4mccc24m; XcmsWhiteAdjustProc 4mwhite_adjust_proc24m; XPointer 4mclient_data24m; 4mccc24m Specifies the CCC. 4mwhite_adjust_proc0m Specifies the white point adjustment procedure. 4mclient_data0m Specifies client data for the white point adjust- ment procedure or NULL. __ The 4mXcmsSetWhiteAdjustProc24m function first sets the white point adjustment procedure and client data in the specified CCC with the newly specified procedure and client data and then returns the old procedure. 1m1470m 1mXlib C Library X11, Release 6.9/7.00m 1m6.8.5. Creating and Freeing a Color Conversion Context0m You can explicitly create a CCC within your application by calling 4mXcmsCreateCCC24m. These created CCCs can then be used by those functions that explicitly call for a CCC argument. Old CCCs that will not be used by the application should be freed using 4mXcmsFreeCCC24m. To create a CCC, use 4mXcmsCreateCCC24m. 1m1480m 1mXlib C Library X11, Release 6.9/7.00m __ XcmsCCC XcmsCreateCCC(4mdisplay24m, 4mscreen_number24m, 4mvisual24m, 4mclient_white_point24m, 4mcompression_proc24m, 4mcompression_client_data24m, 4mwhite_adjust_proc24m, 4mwhite_adjust_client_data24m) Display *4mdisplay24m; int 4mscreen_number24m; Visual *4mvisual24m; XcmsColor *4mclient_white_point24m; XcmsCompressionProc 4mcompression_proc24m; XPointer 4mcompression_client_data24m; XcmsWhiteAdjustProc 4mwhite_adjust_proc24m; XPointer 4mwhite_adjust_client_data24m; 4mdisplay24m Specifies the connection to the X server. 4mscreen_number0m Specifies the appropriate screen number on the host server. 4mvisual24m Specifies the visual type. 4mclient_white_point0m Specifies the Client White Point. If NULL is specified, the Client White Point is to be assumed to be the same as the Screen White Point. Note that the pixel member is ignored. 4mcompression_proc0m Specifies the gamut compression procedure that is to be applied when a color lies outside the screens color gamut. If NULL is specified and a function using this CCC must convert a color spec- ification to a device-dependent format and encoun- ters a color that lies outside the screens color gamut, that function will return 4mXcmsFailure24m. 4mcompression_client_data0m Specifies client data for use by the gamut com- pression procedure or NULL. 4mwhite_adjust_proc0m Specifies the white adjustment procedure that is to be applied when the Client White Point differs from the Screen White Point. NULL indicates that no white point adjustment is desired. 4mwhite_adjust_client_data0m Specifies client data for use with the white point adjustment procedure or NULL. __ The 4mXcmsCreateCCC24m function creates a CCC for the specified display, screen, and visual. 1m1490m 1mXlib C Library X11, Release 6.9/7.00m To free a CCC, use 4mXcmsFreeCCC24m. __ void XcmsFreeCCC(4mccc24m) XcmsCCC 4mccc24m; 4mccc24m Specifies the CCC. __ The 4mXcmsFreeCCC24m function frees the memory used for the spec- ified CCC. Note that default CCCs and those currently asso- ciated with colormaps are ignored. 1m6.9. Converting between Color Spaces0m To convert an array of color specifications in arbitrary color formats to a single destination format, use 4mXcmsCon-0m 4mvertColors24m. 1m1500m 1mXlib C Library X11, Release 6.9/7.00m __ Status XcmsConvertColors(4mccc24m, 4mcolors_in_out24m, 4mncolors24m, 4mtarget_format24m, 4mcompression_flags_return24m) XcmsCCC 4mccc24m; XcmsColor 4mcolors_in_out24m[]; unsigned int 4mncolors24m; XcmsColorFormat 4mtarget_format24m; Bool 4mcompression_flags_return24m[]; 4mccc24m Specifies the CCC. If conversion is between device-independent color spaces only (for example, TekHVC to CIELuv), the CCC is necessary only to specify the Client White Point. 4mcolors_in_out0m Specifies an array of color specifications. Pixel members are ignored and remain unchanged upon return. 4mncolors24m Specifies the number of 4mXcmsColor24m structures in the color-specification array. 4mtarget_format0m Specifies the target color specification format. 4mcompression_flags_return0m Returns an array of Boolean values indicating com- pression status. If a non-NULL pointer is sup- plied, each element of the array is set to 4mTrue24m if the corresponding color was compressed and 4mFalse0m otherwise. Pass NULL if the compression status is not useful. __ The 4mXcmsConvertColors24m function converts the color specifica- tions in the specified array of 4mXcmsColor24m structures from their current format to a single target format, using the specified CCC. When the return value is 4mXcmsFailure24m, the contents of the color specification array are left unchanged. The array may contain a mixture of color specification for- mats (for example, 3 CIE XYZ, 2 CIE Luv, and so on). When the array contains both device-independent and device-depen- dent color specifications and the target_format argument specifies a device-dependent format (for example, 4mXcmsRGBi-0m 4mFormat24m, 4mXcmsRGBFormat24m), all specifications are converted to CIE XYZ format and then to the target device-dependent for- mat. 1m6.10. Callback Functions0m This section describes the gamut compression and white point adjustment callbacks. 1m1510m 1mXlib C Library X11, Release 6.9/7.00m The gamut compression procedure specified in the CCC is called when an attempt to convert a color specification from 4mXcmsCIEXYZ24m to a device-dependent format (typically 4mXcmsRGBi24m) results in a color that lies outside the screens color gamut. If the gamut compression procedure requires client data, this data is passed via the gamut compression client data in the CCC. During color specification conversion between device-inde- pendent and device-dependent color spaces, if a white point adjustment procedure is specified in the CCC, it is trig- gered when the Client White Point and Screen White Point differ. If required, the client data is obtained from the CCC. 1m6.10.1. Prototype Gamut Compression Procedure0m The gamut compression callback interface must adhere to the following: 1m1520m 1mXlib C Library X11, Release 6.9/7.00m __ typedef Status (*XcmsCompressionProc)(4mccc24m, 4mcolors_in_out24m, 4mncolors24m, 4mindex24m, 4mcompression_flags_return24m) XcmsCCC 4mccc24m; XcmsColor 4mcolors_in_out[]24m; unsigned int 4mncolors24m; unsigned int 4mindex24m; Bool 4mcompression_flags_return[]24m; 4mccc24m Specifies the CCC. 4mcolors_in_out0m Specifies an array of color specifications. Pixel members should be ignored and must remain unchanged upon return. 4mncolors24m Specifies the number of 4mXcmsColor24m structures in the color-specification array. 4mindex24m Specifies the index into the array of 4mXcmsColor0m structures for the encountered color specification that lies outside the screens color gamut. Valid values are 0 (for the first element) to ncolors 1. 4mcompression_flags_return0m Returns an array of Boolean values for indicating compression status. If a non-NULL pointer is sup- plied and a color at a given index is compressed, then 4mTrue24m should be stored at the corresponding index in this array; otherwise, the array should not be modified. __ When implementing a gamut compression procedure, consider the following rules and assumptions: The gamut compression procedure can attempt to compress one or multiple specifications at a time. When called, elements 0 to index 1 in the color spec- ification array can be assumed to fall within the screens color gamut. In addition, these color speci- fications are already in some device-dependent format (typically 4mXcmsRGBi24m). If any modifications are made to these color specifications, they must be in their ini- tial device-dependent format upon return. When called, the element in the color specification array specified by the index argument contains the color specification outside the screens color gamut encountered by the calling routine. In addition, this color specification can be assumed to be in 4mXcmsCIEXYZ24m. Upon return, this color specification must be in 1m1530m 1mXlib C Library X11, Release 6.9/7.00m 4mXcmsCIEXYZ24m. When called, elements from index to ncolors 1 in the color specification array may or may not fall within the screens color gamut. In addition, these color specifications can be assumed to be in 4mXcmsCIEXYZ24m. If any modifications are made to these color specifica- tions, they must be in 4mXcmsCIEXYZ24m upon return. The color specifications passed to the gamut compres- sion procedure have already been adjusted to the Screen White Point. This means that at this point the color specifications white point is the Screen White Point. If the gamut compression procedure uses a device-inde- pendent color space not initially accessible for use in the color management system, use 4mXcmsAddColorSpace24m to ensure that it is added. 1m6.10.2. Supplied Gamut Compression Procedures0m The following equations are useful in describing gamut com- pression functions: 4mCIELabPsychometricChroma24m=4msqrt24m(4ma24m_4mstar24m2+4mb24m_4mstar24m2) 4mCIELabPsychometricHue24m=tan1[4m_24m4m_____24m] 4mCIELuvPsychometricChroma24m=4msqrt24m(4mu24m_4mstar24m2+4mv24m_4mstar24m2) 4mCIELuvPsychometricHue24m=tan1[4m_24m4m_____24m] The gamut compression callback procedures provided by Xlib are as follows: 4mXcmsCIELabClipL0m This brings the encountered out-of-gamut color specifi- cation into the screens color gamut by reducing or increasing CIE metric lightness (L*) in the CIE L*a*b* color space until the color is within the gamut. If the Psychometric Chroma of the color specification is beyond maximum for the Psychometric Hue Angle, then while maintaining the same Psychometric Hue Angle, the color will be clipped to the CIE L*a*b* coordinates of maximum Psychometric Chroma. See 4mXcmsCIELabQueryMaxC24m. No client data is necessary. 4mXcmsCIELabClipab0m 1m1540m 1mXlib C Library X11, Release 6.9/7.00m This brings the encountered out-of-gamut color specifi- cation into the screens color gamut by reducing Psy- chometric Chroma, while maintaining Psychometric Hue Angle, until the color is within the gamut. No client data is necessary. 4mXcmsCIELabClipLab0m This brings the encountered out-of-gamut color specifi- cation into the screens color gamut by replacing it with CIE L*a*b* coordinates that fall within the color gamut while maintaining the original Psychometric Hue Angle and whose vector to the original coordinates is the shortest attainable. No client data is necessary. 4mXcmsCIELuvClipL0m This brings the encountered out-of-gamut color specifi- cation into the screens color gamut by reducing or increasing CIE metric lightness (L*) in the CIE L*u*v* color space until the color is within the gamut. If the Psychometric Chroma of the color specification is beyond maximum for the Psychometric Hue Angle, then, while maintaining the same Psychometric Hue Angle, the color will be clipped to the CIE L*u*v* coordinates of maximum Psychometric Chroma. See 4mXcmsCIELuvQueryMaxC24m. No client data is necessary. 4mXcmsCIELuvClipuv0m This brings the encountered out-of-gamut color specifi- cation into the screens color gamut by reducing Psy- chometric Chroma, while maintaining Psychometric Hue Angle, until the color is within the gamut. No client data is necessary. 4mXcmsCIELuvClipLuv0m This brings the encountered out-of-gamut color specifi- cation into the screens color gamut by replacing it with CIE L*u*v* coordinates that fall within the color gamut while maintaining the original Psychometric Hue Angle and whose vector to the original coordinates is the shortest attainable. No client data is necessary. 4mXcmsTekHVCClipV0m This brings the encountered out-of-gamut color specifi- cation into the screens color gamut by reducing or increasing the Value dimension in the TekHVC color space until the color is within the gamut. If Chroma of the color specification is beyond maximum for the particular Hue, then, while maintaining the same Hue, the color will be clipped to the Value and Chroma 1m1550m 1mXlib C Library X11, Release 6.9/7.00m coordinates that represent maximum Chroma for that par- ticular Hue. No client data is necessary. 4mXcmsTekHVCClipC0m This brings the encountered out-of-gamut color specifi- cation into the screens color gamut by reducing the Chroma dimension in the TekHVC color space until the color is within the gamut. No client data is neces- sary. 4mXcmsTekHVCClipVC0m This brings the encountered out-of-gamut color specifi- cation into the screens color gamut by replacing it with TekHVC coordinates that fall within the color gamut while maintaining the original Hue and whose vec- tor to the original coordinates is the shortest attain- able. No client data is necessary. 1m6.10.3. Prototype White Point Adjustment Procedure0m The white point adjustment procedure interface must adhere to the following: 1m1560m 1mXlib C Library X11, Release 6.9/7.00m __ typedef Status (*XcmsWhiteAdjustProc)(4mccc24m, 4minitial_white_point24m, 4mtarget_white_point24m, 4mtarget_format24m, 4mcolors_in_out24m, 4mncolors24m, 4mcompression_flags_return24m) XcmsCCC 4mccc24m; XcmsColor *4minitial_white_point24m; XcmsColor *4mtarget_white_point24m; XcmsColorFormat 4mtarget_format24m; XcmsColor 4mcolors_in_out[]24m; unsigned int 4mncolors24m; Bool 4mcompression_flags_return[]24m; 4mccc24m Specifies the CCC. 4minitial_white_point0m Specifies the initial white point. 4mtarget_white_point0m Specifies the target white point. 4mtarget_format0m Specifies the target color specification format. 4mcolors_in_out0m Specifies an array of color specifications. Pixel members should be ignored and must remain unchanged upon return. 4mncolors24m Specifies the number of 4mXcmsColor24m structures in the color-specification array. 4mcompression_flags_return0m Returns an array of Boolean values for indicating compression status. If a non-NULL pointer is sup- plied and a color at a given index is compressed, then 4mTrue24m should be stored at the corresponding index in this array; otherwise, the array should not be modified. __ 1m6.10.4. Supplied White Point Adjustment Procedures0m White point adjustment procedures provided by Xlib are as follows: 4mXcmsCIELabWhiteShiftColors0m This uses the CIE L*a*b* color space for adjusting the chromatic character of colors to compensate for the chromatic differences between the source and destina- tion white points. This procedure simply converts the color specifications to 4mXcmsCIELab24m using the source white point and then converts to the target 1m1570m 1mXlib C Library X11, Release 6.9/7.00m specification format using the destinations white point. No client data is necessary. 4mXcmsCIELuvWhiteShiftColors0m This uses the CIE L*u*v* color space for adjusting the chromatic character of colors to compensate for the chromatic differences between the source and destina- tion white points. This procedure simply converts the color specifications to 4mXcmsCIELuv24m using the source white point and then converts to the target specifica- tion format using the destinations white point. No client data is necessary. 4mXcmsTekHVCWhiteShiftColors0m This uses the TekHVC color space for adjusting the chromatic character of colors to compensate for the chromatic differences between the source and destina- tion white points. This procedure simply converts the color specifications to 4mXcmsTekHVC24m using the source white point and then converts to the target specifica- tion format using the destinations white point. An advantage of this procedure over those previously described is an attempt to minimize hue shift. No client data is necessary. From an implementation point of view, these white point adjustment procedures convert the color specifications to a device-independent but white-point-dependent color space (for example, CIE L*u*v*, CIE L*a*b*, TekHVC) using one white point and then converting those specifications to the target color space using another white point. In other words, the specification goes in the color space with one white point but comes out with another white point, result- ing in a chromatic shift based on the chromatic displacement between the initial white point and target white point. The CIE color spaces that are assumed to be white-point-indepen- dent are CIE uvY, CIE XYZ, and CIE xyY. When developing a custom white point adjustment procedure that uses a device- independent color space not initially accessible for use in the color management system, use 4mXcmsAddColorSpace24m to ensure that it is added. As an example, if the CCC specifies a white point adjustment procedure and if the Client White Point and Screen White Point differ, the 4mXcmsAllocColor24m function will use the white point adjustment procedure twice: Once to convert to 4mXcmsRGB0m A second time to convert from 4mXcmsRGB0m 1m1580m 1mXlib C Library X11, Release 6.9/7.00m For example, assume the specification is in 4mXcmsCIEuvY24m and the adjustment procedure is 4mXcmsCIELuvWhiteShiftColors24m. During conversion to 4mXcmsRGB24m, the call to 4mXcmsAllocColor0m results in the following series of color specification con- versions: From 4mXcmsCIEuvY24m to 4mXcmsCIELuv24m using the Client White Point From 4mXcmsCIELuv24m to 4mXcmsCIEuvY24m using the Screen White Point From 4mXcmsCIEuvY24m to 4mXcmsCIEXYZ24m (CIE uvY and XYZ are white-point-independent color spaces) From 4mXcmsCIEXYZ24m to 4mXcmsRGBi0m From 4mXcmsRGBi24m to 4mXcmsRGB0m The resulting RGB specification is passed to 4mXAllocColor24m, and the RGB specification returned by 4mXAllocColor24m is con- verted back to 4mXcmsCIEuvY24m by reversing the color conversion sequence. 1m6.11. Gamut Querying Functions0m This section describes the gamut querying functions that Xlib provides. These functions allow the client to query the boundary of the screens color gamut in terms of the CIE L*a*b*, CIE L*u*v*, and TekHVC color spaces. Functions are also provided that allow you to query the color specifica- tion of: White (full-intensity red, green, and blue) Red (full-intensity red while green and blue are zero) Green (full-intensity green while red and blue are zero) Blue (full-intensity blue while red and green are zero) Black (zero-intensity red, green, and blue) The white point associated with color specifications passed to and returned from these gamut querying functions is assumed to be the Screen White Point. This is a reasonable assumption, because the client is trying to query the screens color gamut. The following naming convention is used for the Max and Min functions: 1m1590m 1mXlib C Library X11, Release 6.9/7.00m Xcms4m24mQueryMax4m0m Xcms4m24mQueryMin4m0m The consists of a letter or letters that iden- tify the dimensions of the color space that are not fixed. For example, 4mXcmsTekHVCQueryMaxC24m is given a fixed Hue and Value for which maximum Chroma is found. 1m6.11.1. Red, Green, and Blue Queries0m To obtain the color specification for black (zero-intensity red, green, and blue), use 4mXcmsQueryBlack24m. __ Status XcmsQueryBlack(4mccc24m, 4mtarget_format24m, 4mcolor_return24m) XcmsCCC 4mccc24m; XcmsColorFormat 4mtarget_format24m; XcmsColor *4mcolor_return24m; 4mccc24m Specifies the CCC. The CCCs Client White Point and white point adjustment procedures are ignored. 4mtarget_format0m Specifies the target color specification format. 4mcolor_return0m Returns the color specification in the specified target format for zero-intensity red, green, and blue. The white point associated with the returned color specification is the Screen White Point. The value returned in the pixel member is undefined. __ The 4mXcmsQueryBlack24m function returns the color specification in the specified target format for zero-intensity red, green, and blue. To obtain the color specification for blue (full-intensity blue while red and green are zero), use 4mXcmsQueryBlue24m. 1m1600m 1mXlib C Library X11, Release 6.9/7.00m __ Status XcmsQueryBlue(4mccc24m, 4mtarget_format24m, 4mcolor_return24m) XcmsCCC 4mccc24m; XcmsColorFormat 4mtarget_format24m; XcmsColor *4mcolor_return24m; 4mccc24m Specifies the CCC. The CCCs Client White Point and white point adjustment procedures are ignored. 4mtarget_format0m Specifies the target color specification format. 4mcolor_return0m Returns the color specification in the specified target format for full-intensity blue while red and green are zero. The white point associated with the returned color specification is the Screen White Point. The value returned in the pixel member is undefined. __ The 4mXcmsQueryBlue24m function returns the color specification in the specified target format for full-intensity blue while red and green are zero. To obtain the color specification for green (full-intensity green while red and blue are zero), use 4mXcmsQueryGreen24m. __ Status XcmsQueryGreen(4mccc24m, 4mtarget_format24m, 4mcolor_return24m) XcmsCCC 4mccc24m; XcmsColorFormat 4mtarget_format24m; XcmsColor *4mcolor_return24m; 4mccc24m Specifies the CCC. The CCCs Client White Point and white point adjustment procedures are ignored. 4mtarget_format0m Specifies the target color specification format. 4mcolor_return0m Returns the color specification in the specified target format for full-intensity green while red and blue are zero. The white point associated with the returned color specification is the Screen White Point. The value returned in the pixel member is undefined. __ The 4mXcmsQueryGreen24m function returns the color specification in the specified target format for full-intensity green 1m1610m 1mXlib C Library X11, Release 6.9/7.00m while red and blue are zero. To obtain the color specification for red (full-intensity red while green and blue are zero), use 4mXcmsQueryRed24m. __ Status XcmsQueryRed(4mccc24m, 4mtarget_format24m, 4mcolor_return24m) XcmsCCC 4mccc24m; XcmsColorFormat 4mtarget_format24m; XcmsColor *4mcolor_return24m; 4mccc24m Specifies the CCC. The CCCs Client White Point and white point adjustment procedures are ignored. 4mtarget_format0m Specifies the target color specification format. 4mcolor_return0m Returns the color specification in the specified target format for full-intensity red while green and blue are zero. The white point associated with the returned color specification is the Screen White Point. The value returned in the pixel member is undefined. __ The 4mXcmsQueryRed24m function returns the color specification in the specified target format for full-intensity red while green and blue are zero. To obtain the color specification for white (full-intensity red, green, and blue), use 4mXcmsQueryWhite24m. 1m1620m 1mXlib C Library X11, Release 6.9/7.00m __ Status XcmsQueryWhite(4mccc24m, 4mtarget_format24m, 4mcolor_return24m) XcmsCCC 4mccc24m; XcmsColorFormat 4mtarget_format24m; XcmsColor *4mcolor_return24m; 4mccc24m Specifies the CCC. The CCCs Client White Point and white point adjustment procedures are ignored. 4mtarget_format0m Specifies the target color specification format. 4mcolor_return0m Returns the color specification in the specified target format for full-intensity red, green, and blue. The white point associated with the returned color specification is the Screen White Point. The value returned in the pixel member is undefined. __ The 4mXcmsQueryWhite24m function returns the color specification in the specified target format for full-intensity red, green, and blue. 1m6.11.2. CIELab Queries0m The following equations are useful in describing the CIELab query functions: 4mCIELabPsychometricChroma24m=4msqrt24m(4ma24m_4mstar24m2+4mb24m_4mstar24m2) 4mCIELabPsychometricHue24m=tan1[4m_24m4m_____24m] To obtain the CIE L*a*b* coordinates of maximum Psychometric Chroma for a given Psychometric Hue Angle and CIE metric lightness (L*), use 4mXcmsCIELabQueryMaxC24m. 1m1630m 1mXlib C Library X11, Release 6.9/7.00m __ Status XcmsCIELabQueryMaxC(4mccc24m, 4mhue_angle24m, 4mL_star24m, 4mcolor_return24m) XcmsCCC 4mccc24m; XcmsFloat 4mhue_angle24m; XcmsFloat 4mL_star24m; XcmsColor *4mcolor_return24m; 4mccc24m Specifies the CCC. The CCCs Client White Point and white point adjustment procedures are ignored. 4mhue_angle24m Specifies the hue angle (in degrees) at which to find maximum chroma. 4mL_star24m Specifies the lightness (L*) at which to find max- imum chroma. 4mcolor_return0m Returns the CIE L*a*b* coordinates of maximum chroma displayable by the screen for the given hue angle and lightness. The white point associated with the returned color specification is the Screen White Point. The value returned in the pixel member is undefined. __ The 4mXcmsCIELabQueryMaxC24m function, given a hue angle and lightness, finds the point of maximum chroma displayable by the screen. It returns this point in CIE L*a*b* coordi- nates. To obtain the CIE L*a*b* coordinates of maximum CIE metric lightness (L*) for a given Psychometric Hue Angle and Psy- chometric Chroma, use 4mXcmsCIELabQueryMaxL24m. 1m1640m 1mXlib C Library X11, Release 6.9/7.00m __ Status XcmsCIELabQueryMaxL(4mccc24m, 4mhue_angle24m, 4mchroma24m, 4mcolor_return24m) XcmsCCC 4mccc24m; XcmsFloat 4mhue_angle24m; XcmsFloat 4mchroma24m; XcmsColor *4mcolor_return24m; 4mccc24m Specifies the CCC. The CCCs Client White Point and white point adjustment procedures are ignored. 4mhue_angle24m Specifies the hue angle (in degrees) at which to find maximum lightness. 4mchroma24m Specifies the chroma at which to find maximum lightness. 4mcolor_return0m Returns the CIE L*a*b* coordinates of maximum lightness displayable by the screen for the given hue angle and chroma. The white point associated with the returned color specification is the Screen White Point. The value returned in the pixel member is undefined. __ The 4mXcmsCIELabQueryMaxL24m function, given a hue angle and chroma, finds the point in CIE L*a*b* color space of maximum lightness (L*) displayable by the screen. It returns this point in CIE L*a*b* coordinates. An 4mXcmsFailure24m return value usually indicates that the given chroma is beyond max- imum for the given hue angle. To obtain the CIE L*a*b* coordinates of maximum Psychometric Chroma for a given Psychometric Hue Angle, use 4mXcmsCIELab-0m 4mQueryMaxLC24m. 1m1650m 1mXlib C Library X11, Release 6.9/7.00m __ Status XcmsCIELabQueryMaxLC(4mccc24m, 4mhue_angle24m, 4mcolor_return24m) XcmsCCC 4mccc24m; XcmsFloat 4mhue_angle24m; XcmsColor *4mcolor_return24m; 4mccc24m Specifies the CCC. The CCCs Client White Point and white point adjustment procedures are ignored. 4mhue_angle24m Specifies the hue angle (in degrees) at which to find maximum chroma. 4mcolor_return0m Returns the CIE L*a*b* coordinates of maximum chroma displayable by the screen for the given hue angle. The white point associated with the returned color specification is the Screen White Point. The value returned in the pixel member is undefined. __ The 4mXcmsCIELabQueryMaxLC24m function, given a hue angle, finds the point of maximum chroma displayable by the screen. It returns this point in CIE L*a*b* coordinates. To obtain the CIE L*a*b* coordinates of minimum CIE metric lightness (L*) for a given Psychometric Hue Angle and Psy- chometric Chroma, use 4mXcmsCIELabQueryMinL24m. 1m1660m 1mXlib C Library X11, Release 6.9/7.00m __ Status XcmsCIELabQueryMinL(4mccc24m, 4mhue_angle24m, 4mchroma24m, 4mcolor_return24m) XcmsCCC 4mccc24m; XcmsFloat 4mhue_angle24m; XcmsFloat 4mchroma24m; XcmsColor *4mcolor_return24m; 4mccc24m Specifies the CCC. The CCCs Client White Point and white point adjustment procedures are ignored. 4mhue_angle24m Specifies the hue angle (in degrees) at which to find minimum lightness. 4mchroma24m Specifies the chroma at which to find minimum lightness. 4mcolor_return0m Returns the CIE L*a*b* coordinates of minimum lightness displayable by the screen for the given hue angle and chroma. The white point associated with the returned color specification is the Screen White Point. The value returned in the pixel member is undefined. __ The 4mXcmsCIELabQueryMinL24m function, given a hue angle and chroma, finds the point of minimum lightness (L*) dis- playable by the screen. It returns this point in CIE L*a*b* coordinates. An 4mXcmsFailure24m return value usually indicates that the given chroma is beyond maximum for the given hue angle. 1m6.11.3. CIELuv Queries0m The following equations are useful in describing the CIELuv query functions: 4mCIELuvPsychometricChroma24m=4msqrt24m(4mu24m_4mstar24m2+4mv24m_4mstar24m2) 4mCIELuvPsychometricHue24m=tan1[4m_24m4m_____24m] To obtain the CIE L*u*v* coordinates of maximum Psychometric Chroma for a given Psychometric Hue Angle and CIE metric lightness (L*), use 4mXcmsCIELuvQueryMaxC24m. 1m1670m 1mXlib C Library X11, Release 6.9/7.00m __ Status XcmsCIELuvQueryMaxC(4mccc24m, 4mhue_angle24m, 4mL_star24m, 4mcolor_return24m) XcmsCCC 4mccc24m; XcmsFloat 4mhue_angle24m; XcmsFloat 4mL_star24m; XcmsColor *4mcolor_return24m; 4mccc24m Specifies the CCC. The CCCs Client White Point and white point adjustment procedures are ignored. 4mhue_angle24m Specifies the hue angle (in degrees) at which to find maximum chroma. 4mL_star24m Specifies the lightness (L*) at which to find max- imum chroma. 4mcolor_return0m Returns the CIE L*u*v* coordinates of maximum chroma displayable by the screen for the given hue angle and lightness. The white point associated with the returned color specification is the Screen White Point. The value returned in the pixel member is undefined. __ The 4mXcmsCIELuvQueryMaxC24m function, given a hue angle and lightness, finds the point of maximum chroma displayable by the screen. It returns this point in CIE L*u*v* coordi- nates. To obtain the CIE L*u*v* coordinates of maximum CIE metric lightness (L*) for a given Psychometric Hue Angle and Psy- chometric Chroma, use 4mXcmsCIELuvQueryMaxL24m. 1m1680m 1mXlib C Library X11, Release 6.9/7.00m __ Status XcmsCIELuvQueryMaxL(4mccc24m, 4mhue_angle24m, 4mchroma24m, 4mcolor_return24m) XcmsCCC 4mccc24m; XcmsFloat 4mhue_angle24m; XcmsFloat 4mchroma24m; XcmsColor *4mcolor_return24m; 4mccc24m Specifies the CCC. The CCCs Client White Point and white point adjustment procedures are ignored. 4mhue_angle24m Specifies the hue angle (in degrees) at which to find maximum lightness. 4mL_star24m Specifies the lightness (L*) at which to find max- imum lightness. 4mcolor_return0m Returns the CIE L*u*v* coordinates of maximum lightness displayable by the screen for the given hue angle and chroma. The white point associated with the returned color specification is the Screen White Point. The value returned in the pixel member is undefined. __ The 4mXcmsCIELuvQueryMaxL24m function, given a hue angle and chroma, finds the point in CIE L*u*v* color space of maximum lightness (L*) displayable by the screen. It returns this point in CIE L*u*v* coordinates. An 4mXcmsFailure24m return value usually indicates that the given chroma is beyond max- imum for the given hue angle. To obtain the CIE L*u*v* coordinates of maximum Psychometric Chroma for a given Psychometric Hue Angle, use 4mXcmsCIELuv-0m 4mQueryMaxLC24m. 1m1690m 1mXlib C Library X11, Release 6.9/7.00m __ Status XcmsCIELuvQueryMaxLC(4mccc24m, 4mhue_angle24m, 4mcolor_return24m) XcmsCCC 4mccc24m; XcmsFloat 4mhue_angle24m; XcmsColor *4mcolor_return24m; 4mccc24m Specifies the CCC. The CCCs Client White Point and white point adjustment procedures are ignored. 4mhue_angle24m Specifies the hue angle (in degrees) at which to find maximum chroma. 4mcolor_return0m Returns the CIE L*u*v* coordinates of maximum chroma displayable by the screen for the given hue angle. The white point associated with the returned color specification is the Screen White Point. The value returned in the pixel member is undefined. __ The 4mXcmsCIELuvQueryMaxLC24m function, given a hue angle, finds the point of maximum chroma displayable by the screen. It returns this point in CIE L*u*v* coordinates. To obtain the CIE L*u*v* coordinates of minimum CIE metric lightness (L*) for a given Psychometric Hue Angle and Psy- chometric Chroma, use 4mXcmsCIELuvQueryMinL24m. 1m1700m 1mXlib C Library X11, Release 6.9/7.00m __ Status XcmsCIELuvQueryMinL(4mccc24m, 4mhue_angle24m, 4mchroma24m, 4mcolor_return24m) XcmsCCC 4mccc24m; XcmsFloat 4mhue_angle24m; XcmsFloat 4mchroma24m; XcmsColor *4mcolor_return24m; 4mccc24m Specifies the CCC. The CCCs Client White Point and white point adjustment procedures are ignored. 4mhue_angle24m Specifies the hue angle (in degrees) at which to find minimum lightness. 4mchroma24m Specifies the chroma at which to find minimum lightness. 4mcolor_return0m Returns the CIE L*u*v* coordinates of minimum lightness displayable by the screen for the given hue angle and chroma. The white point associated with the returned color specification is the Screen White Point. The value returned in the pixel member is undefined. __ The 4mXcmsCIELuvQueryMinL24m function, given a hue angle and chroma, finds the point of minimum lightness (L*) dis- playable by the screen. It returns this point in CIE L*u*v* coordinates. An 4mXcmsFailure24m return value usually indicates that the given chroma is beyond maximum for the given hue angle. 1m6.11.4. TekHVC Queries0m To obtain the maximum Chroma for a given Hue and Value, use 4mXcmsTekHVCQueryMaxC24m. 1m1710m 1mXlib C Library X11, Release 6.9/7.00m __ Status XcmsTekHVCQueryMaxC(4mccc24m, 4mhue24m, 4mvalue24m, 4mcolor_return24m) XcmsCCC 4mccc24m; XcmsFloat 4mhue24m; XcmsFloat 4mvalue24m; XcmsColor *4mcolor_return24m; 4mccc24m Specifies the CCC. The CCCs Client White Point and white point adjustment procedures are ignored. 4mhue24m Specifies the Hue in which to find the maximum Chroma. 4mvalue24m Specifies the Value in which to find the maximum Chroma. 4mcolor_return0m Returns the maximum Chroma along with the actual Hue and Value at which the maximum Chroma was found. The white point associated with the returned color specification is the Screen White Point. The value returned in the pixel member is undefined. __ The 4mXcmsTekHVCQueryMaxC24m function, given a Hue and Value, determines the maximum Chroma in TekHVC color space dis- playable by the screen. It returns the maximum Chroma along with the actual Hue and Value at which the maximum Chroma was found. To obtain the maximum Value for a given Hue and Chroma, use 4mXcmsTekHVCQueryMaxV24m. 1m1720m 1mXlib C Library X11, Release 6.9/7.00m __ Status XcmsTekHVCQueryMaxV(4mccc24m, 4mhue24m, 4mchroma24m, 4mcolor_return24m) XcmsCCC 4mccc24m; XcmsFloat 4mhue24m; XcmsFloat 4mchroma24m; XcmsColor *4mcolor_return24m; 4mccc24m Specifies the CCC. The CCCs Client White Point and white point adjustment procedures are ignored. 4mhue24m Specifies the Hue in which to find the maximum Value. 4mchroma24m Specifies the chroma at which to find maximum Value. 4mcolor_return0m Returns the maximum Value along with the Hue and Chroma at which the maximum Value was found. The white point associated with the returned color specification is the Screen White Point. The value returned in the pixel member is undefined. __ The 4mXcmsTekHVCQueryMaxV24m function, given a Hue and Chroma, determines the maximum Value in TekHVC color space dis- playable by the screen. It returns the maximum Value and the actual Hue and Chroma at which the maximum Value was found. To obtain the maximum Chroma and Value at which it is reached for a specified Hue, use 4mXcmsTekHVCQueryMaxVC24m. 1m1730m 1mXlib C Library X11, Release 6.9/7.00m __ Status XcmsTekHVCQueryMaxVC(4mccc24m, 4mhue24m, 4mcolor_return24m) XcmsCCC 4mccc24m; XcmsFloat 4mhue24m; XcmsColor *4mcolor_return24m; 4mccc24m Specifies the CCC. The CCCs Client White Point and white point adjustment procedures are ignored. 4mhue24m Specifies the Hue in which to find the maximum Chroma. 4mcolor_return0m Returns the color specification in XcmsTekHVC for the maximum Chroma, the Value at which that maxi- mum Chroma is reached, and the actual Hue at which the maximum Chroma was found. The white point associated with the returned color specification is the Screen White Point. The value returned in the pixel member is undefined. __ The 4mXcmsTekHVCQueryMaxVC24m function, given a Hue, determines the maximum Chroma in TekHVC color space displayable by the screen and the Value at which that maximum Chroma is reached. It returns the maximum Chroma, the Value at which that maximum Chroma is reached, and the actual Hue for which the maximum Chroma was found. To obtain a specified number of TekHVC specifications such that they contain maximum Values for a specified Hue and the Chroma at which the maximum Values are reached, use 4mXcm-0m 4msTekHVCQueryMaxVSamples24m. 1m1740m 1mXlib C Library X11, Release 6.9/7.00m __ Status XcmsTekHVCQueryMaxVSamples(4mccc24m, 4mhue24m, 4mcolors_return24m, 4mnsamples24m) XcmsCCC 4mccc24m; XcmsFloat 4mhue24m; XcmsColor 4mcolors_return[]24m; unsigned int 4mnsamples24m; 4mccc24m Specifies the CCC. The CCCs Client White Point and white point adjustment procedures are ignored. 4mhue24m Specifies the Hue for maximum Chroma/Value sam- ples. 4mnsamples24m Specifies the number of samples. 4mcolors_return0m Returns nsamples of color specifications in Xcm- sTekHVC such that the Chroma is the maximum attainable for the Value and Hue. The white point associated with the returned color specification is the Screen White Point. The value returned in the pixel member is undefined. __ The 4mXcmsTekHVCQueryMaxVSamples24m returns nsamples of maximum Value, the Chroma at which that maximum Value is reached, and the actual Hue for which the maximum Chroma was found. These sample points may then be used to plot the maximum Value/Chroma boundary of the screens color gamut for the specified Hue in TekHVC color space. To obtain the minimum Value for a given Hue and Chroma, use 4mXcmsTekHVCQueryMinV24m. 1m1750m 1mXlib C Library X11, Release 6.9/7.00m __ Status XcmsTekHVCQueryMinV(4mccc24m, 4mhue24m, 4mchroma24m, 4mcolor_return24m) XcmsCCC 4mccc24m; XcmsFloat 4mhue24m; XcmsFloat 4mchroma24m; XcmsColor *4mcolor_return24m; 4mccc24m Specifies the CCC. The CCCs Client White Point and white point adjustment procedures are ignored. 4mhue24m Specifies the Hue in which to find the minimum Value. 4mvalue24m Specifies the Value in which to find the minimum Value. 4mcolor_return0m Returns the minimum Value and the actual Hue and Chroma at which the minimum Value was found. The white point associated with the returned color specification is the Screen White Point. The value returned in the pixel member is undefined. __ The 4mXcmsTekHVCQueryMinV24m function, given a Hue and Chroma, determines the minimum Value in TekHVC color space dis- playable by the screen. It returns the minimum Value and the actual Hue and Chroma at which the minimum Value was found. 1m6.12. Color Management Extensions0m The Xlib color management facilities can be extended in two ways: Device-Independent Color Spaces Device-independent color spaces that are derivable to CIE XYZ space can be added using the 4mXcmsAddColorSpace0m function. Color Characterization Function Set A Color Characterization Function Set consists of device-dependent color spaces and their functions that convert between these color spaces and the CIE XYZ color space, bundled together for a specific class of output devices. A function set can be added using the 4mXcmsAddFunctionSet24m function. 1m1760m 1mXlib C Library X11, Release 6.9/7.00m 1m6.12.1. Color Spaces0m The CIE XYZ color space serves as the hub for all conver- sions between device-independent and device-dependent color spaces. Therefore, the knowledge to convert an 4mXcmsColor0m structure to and from CIE XYZ format is associated with each color space. For example, conversion from CIE L*u*v* to RGB requires the knowledge to convert from CIE L*u*v* to CIE XYZ and from CIE XYZ to RGB. This knowledge is stored as an array of functions that, when applied in series, will con- vert the 4mXcmsColor24m structure to or from CIE XYZ format. This color specification conversion mechanism facilitates the addition of color spaces. Of course, when converting between only device-independent color spaces or only device-dependent color spaces, short- cuts are taken whenever possible. For example, conversion from TekHVC to CIE L*u*v* is performed by intermediate con- version to CIE u*v*Y and then to CIE L*u*v*, thus bypassing conversion between CIE u*v*Y and CIE XYZ. 1m6.12.2. Adding Device-Independent Color Spaces0m To add a device-independent color space, use 4mXcmsAddCol-0m 4morSpace24m. __ Status XcmsAddColorSpace(4mcolor_space24m) XcmsColorSpace *4mcolor_space24m; 4mcolor_space0m Specifies the device-independent color space to add. __ The 4mXcmsAddColorSpace24m function makes a device-independent color space (actually an 4mXcmsColorSpace24m structure) accessi- ble by the color management system. Because format values for unregistered color spaces are assigned at run time, they should be treated as private to the client. If references to an unregistered color space must be made outside the client (for example, storing color specifications in a file using the unregistered color space), then reference should be made by color space prefix (see 4mXcmsFormatOfPrefix24m and 4mXcmsPrefixOfFormat24m). If the 4mXcmsColorSpace24m structure is already accessible in the color management system, 4mXcmsAddColorSpace24m returns 4mXcmsSuc-0m 4mcess24m. Note that added 4mXcmsColorSpaces24m must be retained for refer- ence by Xlib. 1m1770m 1mXlib C Library X11, Release 6.9/7.00m 1m6.12.3. Querying Color Space Format and Prefix0m To obtain the format associated with the color space associ- ated with a specified color string prefix, use 4mXcmsFormatOf-0m 4mPrefix24m. __ XcmsColorFormat XcmsFormatOfPrefix(4mprefix24m) char *4mprefix24m; 4mprefix24m Specifies the string that contains the color space prefix. __ The 4mXcmsFormatOfPrefix24m function returns the format for the specified color space prefix (for example, the string CIEXYZ). The prefix is case-insensitive. If the color space is not accessible in the color management system, 4mXcmsFormatOfPrefix24m returns 4mXcmsUndefinedFormat24m. To obtain the color string prefix associated with the color space specified by a color format, use 4mXcmsPrefixOfFormat24m. __ char *XcmsPrefixOfFormat(4mformat24m) XcmsColorFormat 4mformat24m; 4mformat24m Specifies the color specification format. __ The 4mXcmsPrefixOfFormat24m function returns the string prefix associated with the color specification encoding specified by the format argument. Otherwise, if no encoding is found, it returns NULL. The returned string must be treated as read-only. 1m6.12.4. Creating Additional Color Spaces0m Color space specific information necessary for color space conversion and color string parsing is stored in an 4mXcmsCol-0m 4morSpace24m structure. Therefore, a new structure containing this information is required for each additional color space. In the case of device-independent color spaces, a handle to this new structure (that is, by means of a global variable) is usually made accessible to the client program for use with the 4mXcmsAddColorSpace24m function. If a new 4mXcmsColorSpace24m structure specifies a color space not registered with the X Consortium, they should be treated as private to the client because format values for unregis- tered color spaces are assigned at run time. If references 1m1780m 1mXlib C Library X11, Release 6.9/7.00m to an unregistered color space must be made outside the client (for example, storing color specifications in a file using the unregistered color space), then reference should be made by color space prefix (see 4mXcmsFormatOfPrefix24m and 4mXcmsPrefixOfFormat24m). __ typedef (*XcmsConversionProc)(); typedef XcmsConversionProc *XcmsFuncListPtr; /* A NULL terminated list of function pointers*/ typedef struct _XcmsColorSpace { char *prefix; XcmsColorFormat format; XcmsParseStringProc parseString; XcmsFuncListPtr to_CIEXYZ; XcmsFuncListPtr from_CIEXYZ; int inverse_flag; } XcmsColorSpace; __ The prefix member specifies the prefix that indicates a color string is in this color spaces string format. For example, the strings ciexyz or CIEXYZ for CIE XYZ, and rgb or RGB for RGB. The prefix is case insensi- tive. The format member specifies the color specification format. Formats for unregistered color spaces are assigned at run time. The parseString member contains a pointer to the function that can parse a color string into an 4mXcmsColor0m structure. This function returns an integer (int): nonzero if it succeeded and zero otherwise. The to_CIEXYZ and from_CIEXYZ members contain pointers, each to a NULL termi- nated list of function pointers. When the list of functions is executed in series, it will convert the color specified in an 4mXcmsColor24m structure from/to the current color space format to/from the CIE XYZ format. Each function returns an integer (int): nonzero if it succeeded and zero otherwise. The white point to be associated with the colors is speci- fied explicitly, even though white points can be found in the CCC. The inverse_flag member, if nonzero, specifies that for each function listed in to_CIEXYZ, its inverse function can be found in from_CIEXYZ such that: Given: n = number of functions in each list for each i, such that 0 <= i < n from_CIEXYZ[n - i - 1] is the inverse of to_CIEXYZ[i]. This allows Xlib to use the shortest conversion path, thus bypassing CIE XYZ if possible (for example, TekHVC to CIE 1m1790m 1mXlib C Library X11, Release 6.9/7.00m L*u*v*). 1m6.12.5. Parse String Callback0m The callback in the 4mXcmsColorSpace24m structure for parsing a color string for the particular color space must adhere to the following software interface specification: __ typedef int (*XcmsParseStringProc)(4mcolor_string24m, 4mcolor_return24m) char *4mcolor_string24m; XcmsColor *4mcolor_return24m; 4mcolor_string0m Specifies the color string to parse. 4mcolor_return0m Returns the color specification in the color spaces format. __ 1m6.12.6. Color Specification Conversion Callback0m Callback functions in the 4mXcmsColorSpace24m structure for con- verting a color specification between device-independent spaces must adhere to the following software interface spec- ification: 1m1800m 1mXlib C Library X11, Release 6.9/7.00m __ Status ConversionProc(4mccc24m, 4mwhite_point24m, 4mcolors_in_out24m, 4mncolors24m) XcmsCCC 4mccc24m; XcmsColor *4mwhite_point24m; XcmsColor *4mcolors_in_out24m; unsigned int 4mncolors24m; 4mccc24m Specifies the CCC. 4mwhite_point0m Specifies the white point associated with color specifications. The pixel member should be ignored, and the entire structure remain unchanged upon return. 4mcolors_in_out0m Specifies an array of color specifications. Pixel members should be ignored and must remain unchanged upon return. 4mncolors24m Specifies the number of 4mXcmsColor24m structures in the color-specification array. __ Callback functions in the 4mXcmsColorSpace24m structure for con- verting a color specification to or from a device-dependent space must adhere to the following software interface speci- fication: 1m1810m 1mXlib C Library X11, Release 6.9/7.00m __ Status ConversionProc(4mccc24m, 4mcolors_in_out24m, 4mncolors24m, 4mcompression_flags_return24m) XcmsCCC 4mccc24m; XcmsColor *4mcolors_in_out24m; unsigned int 4mncolors24m; Bool 4mcompression_flags_return24m[]; 4mccc24m Specifies the CCC. 4mcolors_in_out0m Specifies an array of color specifications. Pixel members should be ignored and must remain unchanged upon return. 4mncolors24m Specifies the number of 4mXcmsColor24m structures in the color-specification array. 4mcompression_flags_return0m Returns an array of Boolean values for indicating compression status. If a non-NULL pointer is sup- plied and a color at a given index is compressed, then 4mTrue24m should be stored at the corresponding index in this array; otherwise, the array should not be modified. __ Conversion functions are available globally for use by other color spaces. The conversion functions provided by Xlib are: ------------------------------------------------------------- 1mFunction Converts from Converts to0m ------------------------------------------------------------- 4mXcmsCIELabToCIEXYZ24m 4mXcmsCIELabFormat24m 4mXcmsCIEXYZFormat0m 4mXcmsCIELuvToCIEuvY24m 4mXcmsCIELuvFormat24m 4mXcmsCIEuvYFormat0m 4mXcmsCIEXYZToCIELab24m 4mXcmsCIEXYZFormat24m 4mXcmsCIELabFormat0m 4mXcmsCIEXYZToCIEuvY24m 4mXcmsCIEXYZFormat24m 4mXcmsCIEuvYFormat0m 4mXcmsCIEXYZToCIExyY24m 4mXcmsCIEXYZFormat24m 4mXcmsCIExyYFormat0m 4mXcmsCIEXYZToRGBi24m 4mXcmsCIEXYZFormat24m 4mXcmsRGBiFormat0m 4mXcmsCIEuvYToCIELuv24m 4mXcmsCIEuvYFormat24m 4mXcmsCIELabFormat0m 4mXcmsCIEuvYToCIEXYZ24m 4mXcmsCIEuvYFormat24m 4mXcmsCIEXYZFormat0m 4mXcmsCIEuvYToTekHVC24m 4mXcmsCIEuvYFormat24m 4mXcmsTekHVCFormat0m 4mXcmsCIExyYToCIEXYZ24m 4mXcmsCIExyYFormat24m 4mXcmsCIEXYZFormat0m 4mXcmsRGBToRGBi24m 4mXcmsRGBFormat24m 4mXcmsRGBiFormat0m 4mXcmsRGBiToCIEXYZ24m 4mXcmsRGBiFormat24m 4mXcmsCIEXYZFormat0m 4mXcmsRGBiToRGB24m 4mXcmsRGBiFormat24m 4mXcmsRGBFormat0m 4mXcmsTekHVCToCIEuvY24m 4mXcmsTekHVCFormat24m 4mXcmsCIEuvYFormat0m ------------------------------------------------------------- 1m1820m 1mXlib C Library X11, Release 6.9/7.00m 1m6.12.7. Function Sets0m Functions to convert between device-dependent color spaces and CIE XYZ may differ for different classes of output devices (for example, color versus gray monitors). There- fore, the notion of a Color Characterization Function Set has been developed. A function set consists of device- dependent color spaces and the functions that convert color specifications between these device-dependent color spaces and the CIE XYZ color space appropriate for a particular class of output devices. The function set also contains a function that reads color characterization data off root window properties. It is this characterization data that will differ between devices within a class of output devices. For details about how color characterization data is stored in root window properties, see the section on Device Color Characterization in the 4mInter-Client24m 4mCommunica-0m 4mtion24m 4mConventions24m 4mManual24m. The LINEAR_RGB function set is provided by Xlib and will support most color monitors. Function sets may require data that differs from those needed for the LINEAR_RGB function set. In that case, its corresponding data may be stored on different root window properties. 1m6.12.8. Adding Function Sets0m To add a function set, use 4mXcmsAddFunctionSet24m. __ Status XcmsAddFunctionSet(4mfunction_set24m) XcmsFunctionSet *4mfunction_set24m; 4mfunction_set0m Specifies the function set to add. __ The 4mXcmsAddFunctionSet24m function adds a function set to the color management system. If the function set uses device- dependent 4mXcmsColorSpace24m structures not accessible in the color management system, 4mXcmsAddFunctionSet24m adds them. If an added 4mXcmsColorSpace24m structure is for a device-dependent color space not registered with the X Consortium, they should be treated as private to the client because format values for unregistered color spaces are assigned at run time. If references to an unregistered color space must be made outside the client (for example, storing color specifi- cations in a file using the unregistered color space), then reference should be made by color space prefix (see 4mXcmsFor-0m 4mmatOfPrefix24m and 4mXcmsPrefixOfFormat24m). Additional function sets should be added before any calls to other Xlib routines are made. If not, the 4mXcmsPerScrnInfo0m member of a previously created 4mXcmsCCC24m does not have the 1m1830m 1mXlib C Library X11, Release 6.9/7.00m opportunity to initialize with the added function set. 1m6.12.9. Creating Additional Function Sets0m The creation of additional function sets should be required only when an output device does not conform to existing function sets or when additional device-dependent color spaces are necessary. A function set consists primarily of a collection of device-dependent 4mXcmsColorSpace24m structures and a means to read and store a screens color characteriza- tion data. This data is stored in an 4mXcmsFunctionSet24m struc- ture. A handle to this structure (that is, by means of global variable) is usually made accessible to the client program for use with 4mXcmsAddFunctionSet24m. If a function set uses new device-dependent 4mXcmsColorSpace0m structures, they will be transparently processed into the color management system. Function sets can share an 4mXcms-0m 4mColorSpace24m structure for a device-dependent color space. In addition, multiple 4mXcmsColorSpace24m structures are allowed for a device-dependent color space; however, a function set can reference only one of them. These 4mXcmsColorSpace24m structures will differ in the functions to convert to and from CIE XYZ, thus tailored for the specific function set. __ typedef struct _XcmsFunctionSet { XcmsColorSpace **DDColorSpaces; XcmsScreenInitProc screenInitProc; XcmsScreenFreeProc screenFreeProc; } XcmsFunctionSet; __ The DDColorSpaces member is a pointer to a NULL terminated list of pointers to 4mXcmsColorSpace24m structures for the device-dependent color spaces that are supported by the function set. The screenInitProc member is set to the call- back procedure (see the following interface specification) that initializes the 4mXcmsPerScrnInfo24m structure for a partic- ular screen. The screen initialization callback must adhere to the fol- lowing software interface specification: 1m1840m 1mXlib C Library X11, Release 6.9/7.00m __ typedef Status (*XcmsScreenInitProc)(4mdisplay24m, 4mscreen_number24m, 4mscreen_info24m) Display *4mdisplay24m; int 4mscreen_number24m; XcmsPerScrnInfo *4mscreen_info24m; 4mdisplay24m Specifies the connection to the X server. 4mscreen_number0m Specifies the appropriate screen number on the host server. 4mscreen_info0m Specifies the 4mXcmsPerScrnInfo24m structure, which contains the per screen information. __ The screen initialization callback in the 4mXcmsFunctionSet0m structure fetches the color characterization data (device profile) for the specified screen, typically off properties on the screens root window. It then initializes the speci- fied 4mXcmsPerScrnInfo24m structure. If successful, the proce- dure fills in the 4mXcmsPerScrnInfo24m structure as follows: It sets the screenData member to the address of the created device profile data structure (contents known only by the function set). It next sets the screenWhitePoint member. It next sets the functionSet member to the address of the 4mXcmsFunctionSet24m structure. It then sets the state member to 4mXcmsInitSuccess24m and finally returns 4mXcmsSuccess24m. If unsuccessful, the procedure sets the state member to 4mXcm-0m 4msInitFailure24m and returns 4mXcmsFailure24m. The 4mXcmsPerScrnInfo24m structure contains: 1m1850m 1mXlib C Library X11, Release 6.9/7.00m __ typedef struct _XcmsPerScrnInfo { XcmsColor screenWhitePoint; XPointer functionSet; XPointer screenData; unsigned char state; char pad[3]; } XcmsPerScrnInfo; __ The screenWhitePoint member specifies the white point inher- ent to the screen. The functionSet member specifies the appropriate function set. The screenData member specifies the device profile. The state member is set to one of the following: 4mXcmsInitNone24m indicates initialization has not been pre- viously attempted. 4mXcmsInitFailure24m indicates initialization has been pre- viously attempted but failed. 4mXcmsInitSuccess24m indicates initialization has been pre- viously attempted and succeeded. The screen free callback must adhere to the following soft- ware interface specification: __ typedef void (*XcmsScreenFreeProc)(4mscreenData24m) XPointer 4mscreenData24m; 4mscreenData0m Specifies the data to be freed. __ This function is called to free the screenData stored in an 4mXcmsPerScrnInfo24m structure. 1m1860m 1mXlib C Library X11, Release 6.9/7.00m 1mChapter 70m 1mGraphics Context Functions0m A number of resources are used when performing graphics operations in X. Most information about performing graphics (for example, foreground color, background color, line style, and so on) is stored in resources called graphics contexts (GCs). Most graphics operations (see chapter 8) take a GC as an argument. Although in theory the X protocol permits sharing of GCs between applications, it is expected that applications will use their own GCs when performing operations. Sharing of GCs is highly discouraged because the library may cache GC state. Graphics operations can be performed to either windows or pixmaps, which collectively are called drawables. Each drawable exists on a single screen. A GC is created for a specific screen and drawable depth and can only be used with drawables of matching screen and depth. This chapter discusses how to: Manipulate graphics context/state Use graphics context convenience functions 1m7.1. Manipulating Graphics Context/State0m Most attributes of graphics operations are stored in GCs. These include line width, line style, plane mask, fore- ground, background, tile, stipple, clipping region, end style, join style, and so on. Graphics operations (for example, drawing lines) use these values to determine the actual drawing operation. Extensions to X may add addi- tional components to GCs. The contents of a GC are private to Xlib. Xlib implements a write-back cache for all elements of a GC that are not resource IDs to allow Xlib to implement the transparent coalescing of changes to GCs. For example, a call to 4mXSetForeground24m of a GC followed by a call to 4mXSet-0m 4mLineAttributes24m results in only a single-change GC protocol request to the server. GCs are neither expected nor encour- aged to be shared between client applications, so this write-back caching should present no problems. Applications cannot share GCs without external synchronization. There- fore, sharing GCs between applications is highly discour- aged. 1m1870m 1mXlib C Library X11, Release 6.9/7.00m To set an attribute of a GC, set the appropriate member of the 4mXGCValues24m structure and OR in the corresponding value bitmask in your subsequent calls to 4mXCreateGC24m. The symbols for the value mask bits and the 4mXGCValues24m structure are: 1m1880m 1mXlib C Library X11, Release 6.9/7.00m __ /* GC attribute value mask bits */ #define 4mGCFunction24m (1L<<0) #define 4mGCPlaneMask24m (1L<<1) #define 4mGCForeground24m (1L<<2) #define 4mGCBackground24m (1L<<3) #define 4mGCLineWidth24m (1L<<4) #define 4mGCLineStyle24m (1L<<5) #define 4mGCCapStyle24m (1L<<6) #define 4mGCJoinStyle24m (1L<<7) #define 4mGCFillStyle24m (1L<<8) #define 4mGCFillRule24m (1L<<9) #define 4mGCTile24m (1L<<10) #define 4mGCStipple24m (1L<<11) #define 4mGCTileStipXOrigin24m (1L<<12) #define 4mGCTileStipYOrigin24m (1L<<13) #define 4mGCFont24m (1L<<14) #define 4mGCSubwindowMode24m (1L<<15) #define 4mGCGraphicsExposures24m (1L<<16) #define 4mGCClipXOrigin24m (1L<<17) #define 4mGCClipYOrigin24m (1L<<18) #define 4mGCClipMask24m (1L<<19) #define 4mGCDashOffset24m (1L<<20) #define 4mGCDashList24m (1L<<21) #define 4mGCArcMode24m (1L<<22) /* Values */ typedef struct { int function; /* logical operation */ unsigned long plane_mask;/* plane mask */ unsigned long foreground;/* foreground pixel */ unsigned long background;/* background pixel */ int line_width; /* line width (in pixels) */ int line_style; /* LineSolid, LineOnOffDash, LineDoubleDash */ int cap_style; /* CapNotLast, CapButt, CapRound, CapProjecting */ int join_style; /* JoinMiter, JoinRound, JoinBevel */ int fill_style; /* FillSolid, FillTiled, FillStippled FillOpaqueStippled*/ int fill_rule; /* EvenOddRule, WindingRule */ int arc_mode; /* ArcChord, ArcPieSlice */ Pixmap tile; /* tile pixmap for tiling operations */ Pixmap stipple; /* stipple 1 plane pixmap for stippling */ int ts_x_origin; /* offset for tile or stipple operations */ int ts_y_origin; Font font; /* default text font for text operations */ int subwindow_mode; /* ClipByChildren, IncludeInferiors */ Bool graphics_exposures; /* boolean, should exposures be generated */ int clip_x_origin; /* origin for clipping */ int clip_y_origin; Pixmap clip_mask; /* bitmap clipping; other calls for rects */ int dash_offset; /* patterned/dashed line information */ char dashes; 1m1890m 1mXlib C Library X11, Release 6.9/7.00m } XGCValues; __ The default GC values are: ---------------------------------------------------------------------------------- 1mComponent Default0m ---------------------------------------------------------------------------------- function 4mGXcopy0m plane_mask All ones foreground 0 background 1 line_width 0 line_style 4mLineSolid0m cap_style 4mCapButt0m join_style 4mJoinMiter0m fill_style 4mFillSolid0m fill_rule 4mEvenOddRule0m arc_mode 4mArcPieSlice0m tile Pixmap of unspecified size filled with foreground pixel (that is, client specified pixel if any, else 0) (subsequent changes to foreground do not affect this pixmap) stipple Pixmap of unspecified size filled with ones ts_x_origin 0 ts_y_origin 0 font subwindow_mode 4mClipByChildren0m graphics_exposures 4mTrue0m clip_x_origin 0 clip_y_origin 0 clip_mask 4mNone0m dash_offset 0 dashes 4 (that is, the list [4, 4]) ---------------------------------------------------------------------------------- Note that foreground and background are not set to any val- ues likely to be useful in a window. The function attributes of a GC are used when you update a section of a drawable (the destination) with bits from some- where else (the source). The function in a GC defines how the new destination bits are to be computed from the source bits and the old destination bits. 4mGXcopy24m is typically the most useful because it will work on a color display, but special applications may use other functions, particularly in concert with particular planes of a color display. The 16 GC functions, defined in <4mX11/X.h24m>, are: 1m1900m 1mXlib C Library X11, Release 6.9/7.00m ----------------------------------------------- 1mFunction Name Value Operation0m ----------------------------------------------- 4mGXclear24m 0x0 0 4mGXand24m 0x1 src AND dst 4mGXandReverse24m 0x2 src AND NOT dst 4mGXcopy24m 0x3 src 4mGXandInverted24m 0x4 (NOT src) AND dst 4mGXnoop24m 0x5 dst 4mGXxor24m 0x6 src XOR dst 4mGXor24m 0x7 src OR dst 4mGXnor24m 0x8 (NOT src) AND (NOT dst) 4mGXequiv24m 0x9 (NOT src) XOR dst 4mGXinvert24m 0xa NOT dst 4mGXorReverse24m 0xb src OR (NOT dst) 4mGXcopyInverted24m 0xc NOT src 4mGXorInverted24m 0xd (NOT src) OR dst 4mGXnand24m 0xe (NOT src) OR (NOT dst) 4mGXset24m 0xf 1 ----------------------------------------------- Many graphics operations depend on either pixel values or planes in a GC. The planes attribute is of type long, and it specifies which planes of the destination are to be modi- fied, one bit per plane. A monochrome display has only one plane and will be the least significant bit of the word. As planes are added to the display hardware, they will occupy more significant bits in the plane mask. In graphics operations, given a source and destination pixel, the result is computed bitwise on corresponding bits of the pixels. That is, a Boolean operation is performed in each bit plane. The plane_mask restricts the operation to a subset of planes. A macro constant 4mAllPlanes24m can be used to refer to all planes of the screen simultaneously. The result is computed by the following: ((src FUNC dst) AND plane-mask) OR (dst AND (NOT plane-mask)) Range checking is not performed on the values for fore- ground, background, or plane_mask. They are simply trun- cated to the appropriate number of bits. The line-width is measured in pixels and either can be greater than or equal to one (wide line) or can be the special value zero (thin line). Wide lines are drawn centered on the path described by the graphics request. Unless otherwise specified by the join- style or cap-style, the bounding box of a wide line with 1m1910m 1mXlib C Library X11, Release 6.9/7.00m endpoints [x1, y1], [x2, y2] and width w is a rectangle with vertices at the following real coordinates: [x1-(w*sn/2), y1+(w*cs/2)], [x1+(w*sn/2), y1-(w*cs/2)], [x2-(w*sn/2), y2+(w*cs/2)], [x2+(w*sn/2), y2-(w*cs/2)] Here sn is the sine of the angle of the line, and cs is the cosine of the angle of the line. A pixel is part of the line and so is drawn if the center of the pixel is fully inside the bounding box (which is viewed as having infinitely thin edges). If the center of the pixel is exactly on the bounding box, it is part of the line if and only if the interior is immediately to its right (x increas- ing direction). Pixels with centers on a horizontal edge are a special case and are part of the line if and only if the interior or the boundary is immediately below (y increasing direction) and the interior or the boundary is immediately to the right (x increasing direction). Thin lines (zero line-width) are one-pixel-wide lines drawn using an unspecified, device-dependent algorithm. There are only two constraints on this algorithm. 1. If a line is drawn unclipped from [x1,y1] to [x2,y2] and if another line is drawn unclipped from [x1+dx,y1+dy] to [x2+dx,y2+dy], a point [x,y] is touched by drawing the first line if and only if the point [x+dx,y+dy] is touched by drawing the second line. 2. The effective set of points comprising a line cannot be affected by clipping. That is, a point is touched in a clipped line if and only if the point lies inside the clipping region and the point would be touched by the line when drawn unclipped. A wide line drawn from [x1,y1] to [x2,y2] always draws the same pixels as a wide line drawn from [x2,y2] to [x1,y1], not counting cap-style and join-style. It is recommended that this property be true for thin lines, but this is not required. A line-width of zero may differ from a line-width of one in which pixels are drawn. This permits the use of many manufacturers line drawing hardware, which may run many times faster than the more precisely specified wide lines. In general, drawing a thin line will be faster than drawing a wide line of width one. However, because of their differ- ent drawing algorithms, thin lines may not mix well aesthet- ically with wide lines. If it is desirable to obtain pre- cise and uniform results across all displays, a client should always use a line-width of one rather than a line- 1m1920m 1mXlib C Library X11, Release 6.9/7.00m width of zero. The line-style defines which sections of a line are drawn: 4mLineSolid24m The full path of the line is drawn. 4mLineDou-24m The full path of the line is drawn, but the 4mbleDash24m even dashes are filled differently from the odd dashes (see fill-style) with 4mCapButt0m style used where even and odd dashes meet. 4mLineOnOffDash24m Only the even dashes are drawn, and cap-style applies to all internal ends of the individ- ual dashes, except 4mCapNotLast24m is treated as 4mCapButt24m. The cap-style defines how the endpoints of a path are drawn: 4mCapNotLast24m This is equivalent to 4mCapButt24m except that for a line-width of zero the final endpoint is not drawn. 4mCapButt24m The line is square at the endpoint (perpen- dicular to the slope of the line) with no projection beyond. 4mCapRound24m The line has a circular arc with the diameter equal to the line-width, centered on the end- point. (This is equivalent to 4mCapButt24m for line-width of zero). 4mCapProjecting24m The line is square at the end, but the path continues beyond the endpoint for a distance equal to half the line-width. (This is equivalent to 4mCapButt24m for line-width of zero). The join-style defines how corners are drawn for wide lines: 4mJoinMiter24m The outer edges of two lines extend to meet at an angle. However, if the angle is less than 11 degrees, then a 4mJoinBevel24m join-style is used instead. 4mJoinRound24m The corner is a circular arc with the diame- ter equal to the line-width, centered on the joinpoint. 4mJoinBevel24m The corner has 4mCapButt24m endpoint styles with the triangular notch filled. For a line with coincident endpoints (x1=x2, y1=y2), when the cap-style is applied to both endpoints, the semantics depends on the line-width and the cap-style: 1m1930m 1mXlib C Library X11, Release 6.9/7.00m 4mCapNotLast24m thin The results are device dependent, but the desired effect is that nothing is drawn. 4mCapButt24m thin The results are device dependent, but the desired effect is that a single pixel is drawn. 4mCapRound24m thin The results are the same as for 4mCap-0m 4mButt24m/thin. 4mCapProjecting24m thin The results are the same as for 4mCap-0m 4mButt24m/thin. 4mCapButt24m wide Nothing is drawn. 4mCapRound24m wide The closed path is a circle, centered at the endpoint, and with the diameter equal to the line-width. 4mCapProjecting24m wide The closed path is a square, aligned with the coordinate axes, centered at the endpoint, and with the sides equal to the line-width. For a line with coincident endpoints (x1=x2, y1=y2), when the join-style is applied at one or both endpoints, the effect is as if the line was removed from the overall path. However, if the total path consists of or is reduced to a single point joined with itself, the effect is the same as when the cap-style is applied at both endpoints. The tile/stipple represents an infinite two-dimensional plane, with the tile/stipple replicated in all dimensions. When that plane is superimposed on the drawable for use in a graphics operation, the upper-left corner of some instance of the tile/stipple is at the coordinates within the draw- able specified by the tile/stipple origin. The tile/stipple and clip origins are interpreted relative to the origin of whatever destination drawable is specified in a graphics request. The tile pixmap must have the same root and depth as the GC, or a 4mBadMatch24m error results. The stipple pixmap must have depth one and must have the same root as the GC, or a 4mBadMatch24m error results. For stipple operations where the fill-style is 4mFillStippled24m but not 4mFillOpaqueStippled24m, the stipple pattern is tiled in a single plane and acts as an additional clip mask to be ANDed with the clip-mask. Although some sizes may be faster to use than others, any size pixmap can be used for tiling or stippling. The fill-style defines the contents of the source for line, text, and fill requests. For all text and fill requests (for example, 4mXDrawText24m, 4mXDrawText1624m, 4mXFillRectangle24m, 4mXFillPolygon24m, and 4mXFillArc24m); for line requests with line- style 4mLineSolid24m (for example, 4mXDrawLine24m, 4mXDrawSegments24m, 4mXDrawRectangle24m, 4mXDrawArc24m); and for the even dashes for line requests with line-style 4mLineOnOffDash24m or 4mLineDoubleDash24m, the following apply: 1m1940m 1mXlib C Library X11, Release 6.9/7.00m 4mFillSolid24m Foreground 4mFillTiled24m Tile 4mFillOpaqueStippled24m A tile with the same width and height as stipple, but with background everywhere stipple has a zero and with foreground everywhere stipple has a one 4mFillStippled24m Foreground masked by stipple When drawing lines with line-style 4mLineDoubleDash24m, the odd dashes are controlled by the fill-style in the following manner: 4mFillSolid24m Background 4mFillTiled24m Same as for even dashes 4mFillOpaqueStippled24m Same as for even dashes 4mFillStippled24m Background masked by stipple Storing a pixmap in a GC might or might not result in a copy being made. If the pixmap is later used as the destination for a graphics request, the change might or might not be reflected in the GC. If the pixmap is used simultaneously in a graphics request both as a destination and as a tile or stipple, the results are undefined. For optimum performance, you should draw as much as possible with the same GC (without changing its components). The costs of changing GC components relative to using different GCs depend on the display hardware and the server implemen- tation. It is quite likely that some amount of GC informa- tion will be cached in display hardware and that such hard- ware can only cache a small number of GCs. The dashes value is actually a simplified form of the more general patterns that can be set with 4mXSetDashes24m. Specify- ing a value of N is equivalent to specifying the two-element list [N, N] in 4mXSetDashes24m. The value must be nonzero, or a 4mBadValue24m error results. The clip-mask restricts writes to the destination drawable. If the clip-mask is set to a pixmap, it must have depth one and have the same root as the GC, or a 4mBadMatch24m error results. If clip-mask is set to 4mNone24m, the pixels are always drawn regardless of the clip origin. The clip-mask also can be set by calling the 4mXSetClipRectangles24m or 4mXSetRegion24m func- tions. Only pixels where the clip-mask has a bit set to 1 are drawn. Pixels are not drawn outside the area covered by the clip-mask or where the clip-mask has a bit set to 0. The clip-mask affects all graphics requests. The clip-mask does not clip sources. The clip-mask origin is interpreted relative to the origin of whatever destination drawable is specified in a graphics request. 1m1950m 1mXlib C Library X11, Release 6.9/7.00m You can set the subwindow-mode to 4mClipByChildren24m or 4mInclude-0m 4mInferiors24m. For 4mClipByChildren24m, both source and destination windows are additionally clipped by all viewable 4mInputOutput0m children. For 4mIncludeInferiors24m, neither source nor destina- tion window is clipped by inferiors. This will result in including subwindow contents in the source and drawing through subwindow boundaries of the destination. The use of 4mIncludeInferiors24m on a window of one depth with mapped infe- riors of differing depth is not illegal, but the semantics are undefined by the core protocol. The fill-rule defines what pixels are inside (drawn) for paths given in 4mXFillPolygon24m requests and can be set to 4mEven-0m 4mOddRule24m or 4mWindingRule24m. For 4mEvenOddRule24m, a point is inside if an infinite ray with the point as origin crosses the path an odd number of times. For 4mWindingRule24m, a point is inside if an infinite ray with the point as origin crosses an unequal number of clockwise and counterclockwise directed path segments. A clockwise directed path segment is one that crosses the ray from left to right as observed from the point. A counterclockwise segment is one that crosses the ray from right to left as observed from the point. The case where a directed line segment is coincident with the ray is uninteresting because you can simply choose a different ray that is not coincident with a segment. For both 4mEvenOddRule24m and 4mWindingRule24m, a point is infinitely small, and the path is an infinitely thin line. A pixel is inside if the center point of the pixel is inside and the center point is not on the boundary. If the center point is on the boundary, the pixel is inside if and only if the polygon interior is immediately to its right (x increasing direction). Pixels with centers on a horizontal edge are a special case and are inside if and only if the polygon inte- rior is immediately below (y increasing direction). The arc-mode controls filling in the 4mXFillArcs24m function and can be set to 4mArcPieSlice24m or 4mArcChord24m. For 4mArcPieSlice24m, the arcs are pie-slice filled. For 4mArcChord24m, the arcs are chord filled. The graphics-exposure flag controls 4mGraphicsExpose24m event generation for 4mXCopyArea24m and 4mXCopyPlane24m requests (and any similar requests defined by extensions). To create a new GC that is usable on a given screen with a depth of drawable, use 4mXCreateGC24m. 1m1960m 1mXlib C Library X11, Release 6.9/7.00m __ GC XCreateGC(4mdisplay24m, 4md24m, 4mvaluemask24m, 4mvalues24m) Display *4mdisplay24m; Drawable 4md24m; unsigned long 4mvaluemask24m; XGCValues *4mvalues24m; 4mdisplay24m Specifies the connection to the X server. 4md24m Specifies the drawable. 4mvaluemask24m Specifies which components in the GC are to be set using the information in the specified values structure. This argument is the bitwise inclusive OR of zero or more of the valid GC component mask bits. 4mvalues24m Specifies any values as specified by the value- mask. __ The 4mXCreateGC24m function creates a graphics context and returns a GC. The GC can be used with any destination draw- able having the same root and depth as the specified draw- able. Use with other drawables results in a 4mBadMatch24m error. 4mXCreateGC24m can generate 4mBadAlloc24m, 4mBadDrawable24m, 4mBadFont24m, 4mBad-0m 4mMatch24m, 4mBadPixmap24m, and 4mBadValue24m errors. To copy components from a source GC to a destination GC, use 4mXCopyGC24m. __ XCopyGC(4mdisplay24m, 4msrc24m, 4mvaluemask24m, 4mdest24m) Display *4mdisplay24m; GC 4msrc24m, 4mdest24m; unsigned long 4mvaluemask24m; 4mdisplay24m Specifies the connection to the X server. 4msrc24m Specifies the components of the source GC. 4mvaluemask24m Specifies which components in the GC are to be copied to the destination GC. This argument is the bitwise inclusive OR of zero or more of the valid GC component mask bits. 4mdest24m Specifies the destination GC. __ The 4mXCopyGC24m function copies the specified components from 1m1970m 1mXlib C Library X11, Release 6.9/7.00m the source GC to the destination GC. The source and desti- nation GCs must have the same root and depth, or a 4mBadMatch0m error results. The valuemask specifies which component to copy, as for 4mXCreateGC24m. 4mXCopyGC24m can generate 4mBadAlloc24m, 4mBadGC24m, and 4mBadMatch24m errors. To change the components in a given GC, use 4mXChangeGC24m. __ XChangeGC(4mdisplay24m, 4mgc24m, 4mvaluemask24m, 4mvalues24m) Display *4mdisplay24m; GC 4mgc24m; unsigned long 4mvaluemask24m; XGCValues *4mvalues24m; 4mdisplay24m Specifies the connection to the X server. 4mgc24m Specifies the GC. 4mvaluemask24m Specifies which components in the GC are to be changed using information in the specified values structure. This argument is the bitwise inclusive OR of zero or more of the valid GC component mask bits. 4mvalues24m Specifies any values as specified by the value- mask. __ The 4mXChangeGC24m function changes the components specified by valuemask for the specified GC. The values argument con- tains the values to be set. The values and restrictions are the same as for 4mXCreateGC24m. Changing the clip-mask overrides any previous 4mXSetClipRectangles24m request on the context. Changing the dash-offset or dash-list overrides any previous 4mXSetDashes24m request on the context. The order in which com- ponents are verified and altered is server dependent. If an error is generated, a subset of the components may have been altered. 4mXChangeGC24m can generate 4mBadAlloc24m, 4mBadFont24m, 4mBadGC24m, 4mBadMatch24m, 4mBadPixmap24m, and 4mBadValue24m errors. To obtain components of a given GC, use 4mXGetGCValues24m. 1m1980m 1mXlib C Library X11, Release 6.9/7.00m __ Status XGetGCValues(4mdisplay24m, 4mgc24m, 4mvaluemask24m, 4mvalues_return24m) Display *4mdisplay24m; GC 4mgc24m; unsigned long 4mvaluemask24m; XGCValues *4mvalues_return24m; 4mdisplay24m Specifies the connection to the X server. 4mgc24m Specifies the GC. 4mvaluemask24m Specifies which components in the GC are to be returned in the values_return argument. This argument is the bitwise inclusive OR of zero or more of the valid GC component mask bits. 4mvalues_return0m Returns the GC values in the specified 4mXGCValues0m structure. __ The 4mXGetGCValues24m function returns the components specified by valuemask for the specified GC. If the valuemask con- tains a valid set of GC mask bits (4mGCFunction24m, 4mGCPlaneMask24m, 4mGCForeground24m, 4mGCBackground24m, 4mGCLineWidth24m, 4mGCLineStyle24m, 4mGCCap-0m 4mStyle24m, 4mGCJoinStyle24m, 4mGCFillStyle24m, 4mGCFillRule24m, 4mGCTile24m, 4mGCStip-0m 4mple24m, 4mGCTileStipXOrigin24m, 4mGCTileStipYOrigin24m, 4mGCFont24m, 4mGCSubwin-0m 4mdowMode24m, 4mGCGraphicsExposures24m, 4mGCClipXOrigin24m, 4mGCCLipYOrigin24m, 4mGCDashOffset24m, or 4mGCArcMode24m) and no error occurs, 4mXGetGCVal-0m 4mues24m sets the requested components in values_return and returns a nonzero status. Otherwise, it returns a zero sta- tus. Note that the clip-mask and dash-list (represented by the 4mGCClipMask24m and 4mGCDashList24m bits, respectively, in the valuemask) cannot be requested. Also note that an invalid resource ID (with one or more of the three most significant bits set to 1) will be returned for 4mGCFont24m, 4mGCTile24m, and 4mGCStipple24m if the component has never been explicitly set by the client. To free a given GC, use 4mXFreeGC24m. 1m1990m 1mXlib C Library X11, Release 6.9/7.00m __ XFreeGC(4mdisplay24m, 4mgc24m) Display *4mdisplay24m; GC 4mgc24m; 4mdisplay24m Specifies the connection to the X server. 4mgc24m Specifies the GC. __ The 4mXFreeGC24m function destroys the specified GC as well as all the associated storage. 4mXFreeGC24m can generate a 4mBadGC24m error. To obtain the 4mGContext24m resource ID for a given GC, use 4mXGContextFromGC24m. __ GContext XGContextFromGC(4mgc24m) GC 4mgc24m; 4mgc24m Specifies the GC for which you want the resource ID. __ Xlib usually defers sending changes to the components of a GC to the server until a graphics function is actually called with that GC. This permits batching of component changes into a single server request. In some circum- stances, however, it may be necessary for the client to explicitly force sending the changes to the server. An example might be when a protocol extension uses the GC indi- rectly, in such a way that the extension interface cannot know what GC will be used. To force sending GC component changes, use 4mXFlushGC24m. __ void XFlushGC(4mdisplay24m, 4mgc24m) Display *4mdisplay24m; GC 4mgc24m; 4mdisplay24m Specifies the connection to the X server. 4mgc24m Specifies the GC. __ 1m2000m 1mXlib C Library X11, Release 6.9/7.00m 1m7.2. Using Graphics Context Convenience Routines0m This section discusses how to set the: Foreground, background, plane mask, or function compo- nents Line attributes and dashes components Fill style and fill rule components Fill tile and stipple components Font component Clip region component Arc mode, subwindow mode, and graphics exposure compo- nents 1m7.2.1. Setting the Foreground, Background, Function, or0m 1mPlane Mask0m To set the foreground, background, plane mask, and function components for a given GC, use 4mXSetState24m. 1m2010m 1mXlib C Library X11, Release 6.9/7.00m __ XSetState(4mdisplay24m, 4mgc24m, 4mforeground24m, 4mbackground24m, 4mfunction24m, 4mplane_mask24m) Display *4mdisplay24m; GC 4mgc24m; unsigned long 4mforeground24m, 4mbackground24m; int 4mfunction24m; unsigned long 4mplane_mask24m; 4mdisplay24m Specifies the connection to the X server. 4mgc24m Specifies the GC. 4mforeground0m Specifies the foreground you want to set for the specified GC. 4mbackground0m Specifies the background you want to set for the specified GC. 4mfunction24m Specifies the function you want to set for the specified GC. 4mplane_mask0m Specifies the plane mask. __ 4mXSetState24m can generate 4mBadAlloc24m, 4mBadGC24m, and 4mBadValue24m errors. To set the foreground of a given GC, use 4mXSetForeground24m. __ XSetForeground(4mdisplay24m, 4mgc24m, 4mforeground24m) Display *4mdisplay24m; GC 4mgc24m; unsigned long 4mforeground24m; 4mdisplay24m Specifies the connection to the X server. 4mgc24m Specifies the GC. 4mforeground0m Specifies the foreground you want to set for the specified GC. __ 4mXSetForeground24m can generate 4mBadAlloc24m and 4mBadGC24m errors. To set the background of a given GC, use 4mXSetBackground24m. 1m2020m 1mXlib C Library X11, Release 6.9/7.00m __ XSetBackground(4mdisplay24m, 4mgc24m, 4mbackground24m) Display *4mdisplay24m; GC 4mgc24m; unsigned long 4mbackground24m; 4mdisplay24m Specifies the connection to the X server. 4mgc24m Specifies the GC. 4mbackground0m Specifies the background you want to set for the specified GC. __ 4mXSetBackground24m can generate 4mBadAlloc24m and 4mBadGC24m errors. To set the display function in a given GC, use 4mXSetFunction24m. __ XSetFunction(4mdisplay24m, 4mgc24m, 4mfunction24m) Display *4mdisplay24m; GC 4mgc24m; int 4mfunction24m; 4mdisplay24m Specifies the connection to the X server. 4mgc24m Specifies the GC. 4mfunction24m Specifies the function you want to set for the specified GC. __ 4mXSetFunction24m can generate 4mBadAlloc24m, 4mBadGC24m, and 4mBadValue0m errors. To set the plane mask of a given GC, use 4mXSetPlaneMask24m. 1m2030m 1mXlib C Library X11, Release 6.9/7.00m __ XSetPlaneMask(4mdisplay24m, 4mgc24m, 4mplane_mask24m) Display *4mdisplay24m; GC 4mgc24m; unsigned long 4mplane_mask24m; 4mdisplay24m Specifies the connection to the X server. 4mgc24m Specifies the GC. 4mplane_mask0m Specifies the plane mask. __ 4mXSetPlaneMask24m can generate 4mBadAlloc24m and 4mBadGC24m errors. 1m7.2.2. Setting the Line Attributes and Dashes0m To set the line drawing components of a given GC, use 4mXSet-0m 4mLineAttributes24m. 1m2040m 1mXlib C Library X11, Release 6.9/7.00m __ XSetLineAttributes(4mdisplay24m, 4mgc24m, 4mline_width24m, 4mline_style24m, 4mcap_style24m, 4mjoin_style24m) Display *4mdisplay24m; GC 4mgc24m; unsigned int 4mline_width24m; int 4mline_style24m; int 4mcap_style24m; int 4mjoin_style24m; 4mdisplay24m Specifies the connection to the X server. 4mgc24m Specifies the GC. 4mline_width0m Specifies the line-width you want to set for the specified GC. 4mline_style0m Specifies the line-style you want to set for the specified GC. You can pass 4mLineSolid24m, 4mLineOnOff-0m 4mDash24m, or 4mLineDoubleDash24m. 4mcap_style24m Specifies the line-style and cap-style you want to set for the specified GC. You can pass 4mCapNot-0m 4mLast24m, 4mCapButt24m, 4mCapRound24m, or 4mCapProjecting24m. 4mjoin_style0m Specifies the line join-style you want to set for the specified GC. You can pass 4mJoinMiter24m, 4mJoin-0m 4mRound24m, or 4mJoinBevel24m. __ 4mXSetLineAttributes24m can generate 4mBadAlloc24m, 4mBadGC24m, and 4mBad-0m 4mValue24m errors. To set the dash-offset and dash-list for dashed line styles of a given GC, use 4mXSetDashes24m. 1m2050m 1mXlib C Library X11, Release 6.9/7.00m __ XSetDashes(4mdisplay24m, 4mgc24m, 4mdash_offset24m, 4mdash_list24m, 4mn24m) Display *4mdisplay24m; GC 4mgc24m; int 4mdash_offset24m; char 4mdash_list24m[]; int 4mn24m; 4mdisplay24m Specifies the connection to the X server. 4mgc24m Specifies the GC. 4mdash_offset0m Specifies the phase of the pattern for the dashed line-style you want to set for the specified GC. 4mdash_list24m Specifies the dash-list for the dashed line-style you want to set for the specified GC. 4mn24m Specifies the number of elements in dash_list. __ The 4mXSetDashes24m function sets the dash-offset and dash-list attributes for dashed line styles in the specified GC. There must be at least one element in the specified dash_list, or a 4mBadValue24m error results. The initial and alternating elements (second, fourth, and so on) of the dash_list are the even dashes, and the others are the odd dashes. Each element specifies a dash length in pixels. All of the elements must be nonzero, or a 4mBadValue24m error results. Specifying an odd-length list is equivalent to specifying the same list concatenated with itself to produce an even-length list. The dash-offset defines the phase of the pattern, specifying how many pixels into the dash-list the pattern should actu- ally begin in any single graphics request. Dashing is con- tinuous through path elements combined with a join-style but is reset to the dash-offset between each sequence of joined lines. The unit of measure for dashes is the same for the ordinary coordinate system. Ideally, a dash length is measured along the slope of the line, but implementations are only required to match this ideal for horizontal and vertical lines. Failing the ideal semantics, it is suggested that the length be measured along the major axis of the line. The major axis is defined as the x axis for lines drawn at an angle of between 45 and +45 degrees or between 135 and 225 degrees from the x axis. For all other lines, the major axis is the y axis. 1m2060m 1mXlib C Library X11, Release 6.9/7.00m 4mXSetDashes24m can generate 4mBadAlloc24m, 4mBadGC24m, and 4mBadValue0m errors. 1m7.2.3. Setting the Fill Style and Fill Rule0m To set the fill-style of a given GC, use 4mXSetFillStyle24m. __ XSetFillStyle(4mdisplay24m, 4mgc24m, 4mfill_style24m) Display *4mdisplay24m; GC 4mgc24m; int 4mfill_style24m; 4mdisplay24m Specifies the connection to the X server. 4mgc24m Specifies the GC. 4mfill_style0m Specifies the fill-style you want to set for the specified GC. You can pass 4mFillSolid24m, 4mFillTiled24m, 4mFillStippled24m, or 4mFillOpaqueStippled24m. __ 4mXSetFillStyle24m can generate 4mBadAlloc24m, 4mBadGC24m, and 4mBadValue0m errors. To set the fill-rule of a given GC, use 4mXSetFillRule24m. __ XSetFillRule(4mdisplay24m, 4mgc24m, 4mfill_rule24m) Display *4mdisplay24m; GC 4mgc24m; int 4mfill_rule24m; 4mdisplay24m Specifies the connection to the X server. 4mgc24m Specifies the GC. 4mfill_rule24m Specifies the fill-rule you want to set for the specified GC. You can pass 4mEvenOddRule24m or 4mWindin-0m 4mgRule24m. __ 4mXSetFillRule24m can generate 4mBadAlloc24m, 4mBadGC24m, and 4mBadValue0m errors. 1m7.2.4. Setting the Fill Tile and Stipple0m Some displays have hardware support for tiling or stippling with patterns of specific sizes. Tiling and stippling oper- ations that restrict themselves to those specific sizes run 1m2070m 1mXlib C Library X11, Release 6.9/7.00m much faster than such operations with arbitrary size pat- terns. Xlib provides functions that you can use to deter- mine the best size, tile, or stipple for the display as well as to set the tile or stipple shape and the tile or stipple origin. To obtain the best size of a tile, stipple, or cursor, use 4mXQueryBestSize24m. __ Status XQueryBestSize(4mdisplay24m, 4mclass24m, 4mwhich_screen24m, 4mwidth24m, 4mheight24m, 4mwidth_return24m, 4mheight_return24m) Display *4mdisplay24m; int 4mclass24m; Drawable 4mwhich_screen24m; unsigned int 4mwidth24m, 4mheight24m; unsigned int *4mwidth_return24m, *4mheight_return24m; 4mdisplay24m Specifies the connection to the X server. 4mclass24m Specifies the class that you are interested in. You can pass 4mTileShape24m, 4mCursorShape24m, or 4mStipple-0m 4mShape24m. 4mwhich_screen0m Specifies any drawable on the screen. 4mwidth0m 4mheight24m Specify the width and height. 4mwidth_return0m 4mheight_return0m Return the width and height of the object best supported by the display hardware. __ The 4mXQueryBestSize24m function returns the best or closest size to the specified size. For 4mCursorShape24m, this is the largest size that can be fully displayed on the screen specified by which_screen. For 4mTileShape24m, this is the size that can be tiled fastest. For 4mStippleShape24m, this is the size that can be stippled fastest. For 4mCursorShape24m, the drawable indi- cates the desired screen. For 4mTileShape24m and 4mStippleShape24m, the drawable indicates the screen and possibly the window class and depth. An 4mInputOnly24m window cannot be used as the drawable for 4mTileShape24m or 4mStippleShape24m, or a 4mBadMatch24m error results. 4mXQueryBestSize24m can generate 4mBadDrawable24m, 4mBadMatch24m, and 4mBad-0m 4mValue24m errors. To obtain the best fill tile shape, use 4mXQueryBestTile24m. 1m2080m 1mXlib C Library X11, Release 6.9/7.00m __ Status XQueryBestTile(4mdisplay24m, 4mwhich_screen24m, 4mwidth24m, 4mheight24m, 4mwidth_return24m, 4mheight_return24m) Display *4mdisplay24m; Drawable 4mwhich_screen24m; unsigned int 4mwidth24m, 4mheight24m; unsigned int *4mwidth_return24m, *4mheight_return24m; 4mdisplay24m Specifies the connection to the X server. 4mwhich_screen0m Specifies any drawable on the screen. 4mwidth0m 4mheight24m Specify the width and height. 4mwidth_return0m 4mheight_return0m Return the width and height of the object best supported by the display hardware. __ The 4mXQueryBestTile24m function returns the best or closest size, that is, the size that can be tiled fastest on the screen specified by which_screen. The drawable indicates the screen and possibly the window class and depth. If an 4mInputOnly24m window is used as the drawable, a 4mBadMatch24m error results. 4mXQueryBestTile24m can generate 4mBadDrawable24m and 4mBadMatch24m errors. To obtain the best stipple shape, use 4mXQueryBestStipple24m. 1m2090m 1mXlib C Library X11, Release 6.9/7.00m __ Status XQueryBestStipple(4mdisplay24m, 4mwhich_screen24m, 4mwidth24m, 4mheight24m, 4mwidth_return24m, 4mheight_return24m) Display *4mdisplay24m; Drawable 4mwhich_screen24m; unsigned int 4mwidth24m, 4mheight24m; unsigned int *4mwidth_return24m, *4mheight_return24m; 4mdisplay24m Specifies the connection to the X server. 4mwhich_screen0m Specifies any drawable on the screen. 4mwidth0m 4mheight24m Specify the width and height. 4mwidth_return0m 4mheight_return0m Return the width and height of the object best supported by the display hardware. __ The 4mXQueryBestStipple24m function returns the best or closest size, that is, the size that can be stippled fastest on the screen specified by which_screen. The drawable indicates the screen and possibly the window class and depth. If an 4mInputOnly24m window is used as the drawable, a 4mBadMatch24m error results. 4mXQueryBestStipple24m can generate 4mBadDrawable24m and 4mBadMatch0m errors. To set the fill tile of a given GC, use 4mXSetTile24m. __ XSetTile(4mdisplay24m, 4mgc24m, 4mtile24m) Display *4mdisplay24m; GC 4mgc24m; Pixmap 4mtile24m; 4mdisplay24m Specifies the connection to the X server. 4mgc24m Specifies the GC. 4mtile24m Specifies the fill tile you want to set for the specified GC. __ The tile and GC must have the same depth, or a 4mBadMatch0m error results. 1m2100m 1mXlib C Library X11, Release 6.9/7.00m 4mXSetTile24m can generate 4mBadAlloc24m, 4mBadGC24m, 4mBadMatch24m, and 4mBad-0m 4mPixmap24m errors. To set the stipple of a given GC, use 4mXSetStipple24m. __ XSetStipple(4mdisplay24m, 4mgc24m, 4mstipple24m) Display *4mdisplay24m; GC 4mgc24m; Pixmap 4mstipple24m; 4mdisplay24m Specifies the connection to the X server. 4mgc24m Specifies the GC. 4mstipple24m Specifies the stipple you want to set for the specified GC. __ The stipple must have a depth of one, or a 4mBadMatch24m error results. 4mXSetStipple24m can generate 4mBadAlloc24m, 4mBadGC24m, 4mBadMatch24m, and 4mBad-0m 4mPixmap24m errors. To set the tile or stipple origin of a given GC, use 4mXSetTSOrigin24m. __ XSetTSOrigin(4mdisplay24m, 4mgc24m, 4mts_x_origin24m, 4mts_y_origin24m) Display *4mdisplay24m; GC 4mgc24m; int 4mts_x_origin24m, 4mts_y_origin24m; 4mdisplay24m Specifies the connection to the X server. 4mgc24m Specifies the GC. 4mts_x_origin0m 4mts_y_origin0m Specify the x and y coordinates of the tile and stipple origin. __ When graphics requests call for tiling or stippling, the parents origin will be interpreted relative to whatever destination drawable is specified in the graphics request. 4mXSetTSOrigin24m can generate 4mBadAlloc24m and 4mBadGC24m errors. 1m2110m 1mXlib C Library X11, Release 6.9/7.00m 1m7.2.5. Setting the Current Font0m To set the current font of a given GC, use 4mXSetFont24m. __ XSetFont(4mdisplay24m, 4mgc24m, 4mfont24m) Display *4mdisplay24m; GC 4mgc24m; Font 4mfont24m; 4mdisplay24m Specifies the connection to the X server. 4mgc24m Specifies the GC. 4mfont24m Specifies the font. __ 4mXSetFont24m can generate 4mBadAlloc24m, 4mBadFont24m, and 4mBadGC24m errors. 1m7.2.6. Setting the Clip Region0m Xlib provides functions that you can use to set the clip- origin and the clip-mask or set the clip-mask to a list of rectangles. To set the clip-origin of a given GC, use 4mXSetClipOrigin24m. __ XSetClipOrigin(4mdisplay24m, 4mgc24m, 4mclip_x_origin24m, 4mclip_y_origin24m) Display *4mdisplay24m; GC 4mgc24m; int 4mclip_x_origin24m, 4mclip_y_origin24m; 4mdisplay24m Specifies the connection to the X server. 4mgc24m Specifies the GC. 4mclip_x_origin0m 4mclip_y_origin0m Specify the x and y coordinates of the clip-mask origin. __ The clip-mask origin is interpreted relative to the origin of whatever destination drawable is specified in the graph- ics request. 4mXSetClipOrigin24m can generate 4mBadAlloc24m and 4mBadGC24m errors. To set the clip-mask of a given GC to the specified pixmap, 1m2120m 1mXlib C Library X11, Release 6.9/7.00m use 4mXSetClipMask24m. __ XSetClipMask(4mdisplay24m, 4mgc24m, 4mpixmap24m) Display *4mdisplay24m; GC 4mgc24m; Pixmap 4mpixmap24m; 4mdisplay24m Specifies the connection to the X server. 4mgc24m Specifies the GC. 4mpixmap24m Specifies the pixmap or 4mNone24m. __ If the clip-mask is set to 4mNone24m, the pixels are always drawn (regardless of the clip-origin). 4mXSetClipMask24m can generate 4mBadAlloc24m, 4mBadGC24m, 4mBadMatch24m, and 4mBadPixmap24m errors. To set the clip-mask of a given GC to the specified list of rectangles, use 4mXSetClipRectangles24m. 1m2130m 1mXlib C Library X11, Release 6.9/7.00m __ XSetClipRectangles(4mdisplay24m, 4mgc24m, 4mclip_x_origin24m, 4mclip_y_origin24m, 4mrectangles24m, 4mn24m, 4mordering24m) Display *4mdisplay24m; GC 4mgc24m; int 4mclip_x_origin24m, 4mclip_y_origin24m; XRectangle 4mrectangles24m[]; int 4mn24m; int 4mordering24m; 4mdisplay24m Specifies the connection to the X server. 4mgc24m Specifies the GC. 4mclip_x_origin0m 4mclip_y_origin0m Specify the x and y coordinates of the clip-mask origin. 4mrectangles0m Specifies an array of rectangles that define the clip-mask. 4mn24m Specifies the number of rectangles. 4mordering24m Specifies the ordering relations on the rectan- gles. You can pass 4mUnsorted24m, 4mYSorted24m, 4mYXSorted24m, or 4mYXBanded24m. __ The 4mXSetClipRectangles24m function changes the clip-mask in the specified GC to the specified list of rectangles and sets the clip origin. The output is clipped to remain contained within the rectangles. The clip-origin is interpreted rela- tive to the origin of whatever destination drawable is spec- ified in a graphics request. The rectangle coordinates are interpreted relative to the clip-origin. The rectangles should be nonintersecting, or the graphics results will be undefined. Note that the list of rectangles can be empty, which effectively disables output. This is the opposite of passing 4mNone24m as the clip-mask in 4mXCreateGC24m, 4mXChangeGC24m, and 4mXSetClipMask24m. If known by the client, ordering relations on the rectangles can be specified with the ordering argument. This may pro- vide faster operation by the server. If an incorrect order- ing is specified, the X server may generate a 4mBadMatch0m error, but it is not required to do so. If no error is gen- erated, the graphics results are undefined. 4mUnsorted24m means the rectangles are in arbitrary order. 4mYSorted24m means that the rectangles are nondecreasing in their Y origin. 4mYXSorted24m additionally constrains 4mYSorted24m order in that all rectangles with an equal Y origin are nondecreasing in their X origin. 4mYXBanded24m additionally constrains 4mYXSorted24m by 1m2140m 1mXlib C Library X11, Release 6.9/7.00m requiring that, for every possible Y scanline, all rectan- gles that include that scanline have an identical Y origins and Y extents. 4mXSetClipRectangles24m can generate 4mBadAlloc24m, 4mBadGC24m, 4mBadMatch24m, and 4mBadValue24m errors. Xlib provides a set of basic functions for performing region arithmetic. For information about these functions, see sec- tion 16.5. 1m7.2.7. Setting the Arc Mode, Subwindow Mode, and Graphics0m 1mExposure0m To set the arc mode of a given GC, use 4mXSetArcMode24m. __ XSetArcMode(4mdisplay24m, 4mgc24m, 4marc_mode24m) Display *4mdisplay24m; GC 4mgc24m; int 4marc_mode24m; 4mdisplay24m Specifies the connection to the X server. 4mgc24m Specifies the GC. 4marc_mode24m Specifies the arc mode. You can pass 4mArcChord24m or 4mArcPieSlice24m. __ 4mXSetArcMode24m can generate 4mBadAlloc24m, 4mBadGC24m, and 4mBadValue0m errors. To set the subwindow mode of a given GC, use 4mXSetSubwindow-0m 4mMode24m. 1m2150m 1mXlib C Library X11, Release 6.9/7.00m __ XSetSubwindowMode(4mdisplay24m, 4mgc24m, 4msubwindow_mode24m) Display *4mdisplay24m; GC 4mgc24m; int 4msubwindow_mode24m; 4mdisplay24m Specifies the connection to the X server. 4mgc24m Specifies the GC. 4msubwindow_mode0m Specifies the subwindow mode. You can pass 4mClip-0m 4mByChildren24m or 4mIncludeInferiors24m. __ 4mXSetSubwindowMode24m can generate 4mBadAlloc24m, 4mBadGC24m, and 4mBadValue0m errors. To set the graphics-exposures flag of a given GC, use 4mXSet-0m 4mGraphicsExposures24m. __ XSetGraphicsExposures(4mdisplay24m, 4mgc24m, 4mgraphics_exposures24m) Display *4mdisplay24m; GC 4mgc24m; Bool 4mgraphics_exposures24m; 4mdisplay24m Specifies the connection to the X server. 4mgc24m Specifies the GC. 4mgraphics_exposures0m Specifies a Boolean value that indicates whether you want 4mGraphicsExpose24m and 4mNoExpose24m events to be reported when calling 4mXCopyArea24m and 4mXCopyPlane0m with this GC. __ 4mXSetGraphicsExposures24m can generate 4mBadAlloc24m, 4mBadGC24m, and 4mBad-0m 4mValue24m errors. 1m2160m 1mXlib C Library X11, Release 6.9/7.00m 1mChapter 80m 1mGraphics Functions0m Once you have established a connection to a display, you can use the Xlib graphics functions to: Clear and copy areas Draw points, lines, rectangles, and arcs Fill areas Manipulate fonts Draw text Transfer images between clients and the server If the same drawable and GC is used for each call, Xlib batches back-to-back calls to 4mXDrawPoint24m, 4mXDrawLine24m, 4mXDrawRectangle24m, 4mXFillArc24m, and 4mXFillRectangle24m. Note that this reduces the total number of requests sent to the server. 1m8.1. Clearing Areas0m Xlib provides functions that you can use to clear an area or the entire window. Because pixmaps do not have defined backgrounds, they cannot be filled by using the functions described in this section. Instead, to accomplish an analo- gous operation on a pixmap, you should use 4mXFillRectangle24m, which sets the pixmap to a known value. To clear a rectangular area of a given window, use 4mXClear-0m 4mArea24m. 1m2170m 1mXlib C Library X11, Release 6.9/7.00m __ XClearArea(4mdisplay24m, 4mw24m, 4mx24m, 4my24m, 4mwidth24m, 4mheight24m, 4mexposures24m) Display *4mdisplay24m; Window 4mw24m; int 4mx24m, 4my24m; unsigned int 4mwidth24m, 4mheight24m; Bool 4mexposures24m; 4mdisplay24m Specifies the connection to the X server. 4mw24m Specifies the window. 4mx0m 4my24m Specify the x and y coordinates, which are rela- tive to the origin of the window and specify the upper-left corner of the rectangle. 4mwidth0m 4mheight24m Specify the width and height, which are the dimen- sions of the rectangle. 4mexposures24m Specifies a Boolean value that indicates if 4mExpose0m events are to be generated. __ The 4mXClearArea24m function paints a rectangular area in the specified window according to the specified dimensions with the windows background pixel or pixmap. The subwindow-mode effectively is 4mClipByChildren24m. If width is zero, it is replaced with the current width of the window minus x. If height is zero, it is replaced with the current height of the window minus y. If the window has a defined background tile, the rectangle clipped by any children is filled with this tile. If the window has background 4mNone24m, the contents of the window are not changed. In either case, if exposures is 4mTrue24m, one or more 4mExpose24m events are generated for regions of the rectangle that are either visible or are being retained in a backing store. If you specify a window whose class is 4mInputOnly24m, a 4mBadMatch24m error results. 4mXClearArea24m can generate 4mBadMatch24m, 4mBadValue24m, and 4mBadWindow0m errors. To clear the entire area in a given window, use 4mXClearWin-0m 4mdow24m. 1m2180m 1mXlib C Library X11, Release 6.9/7.00m __ XClearWindow(4mdisplay24m, 4mw24m) Display *4mdisplay24m; Window 4mw24m; 4mdisplay24m Specifies the connection to the X server. 4mw24m Specifies the window. __ The 4mXClearWindow24m function clears the entire area in the specified window and is equivalent to 4mXClearArea24m (display, w, 0, 0, 0, 0, 4mFalse24m). If the window has a defined back- ground tile, the rectangle is tiled with a plane-mask of all ones and 4mGXcopy24m function. If the window has background 4mNone24m, the contents of the window are not changed. If you specify a window whose class is 4mInputOnly24m, a 4mBadMatch24m error results. 4mXClearWindow24m can generate 4mBadMatch24m and 4mBadWindow24m errors. 1m8.2. Copying Areas0m Xlib provides functions that you can use to copy an area or a bit plane. To copy an area between drawables of the same root and depth, use 4mXCopyArea24m. 1m2190m 1mXlib C Library X11, Release 6.9/7.00m __ XCopyArea(4mdisplay24m, 4msrc24m, 4mdest24m, 4mgc24m, 4msrc_x24m, 4msrc_y24m, 4mwidth24m, 4mheight24m, 4mdest_x24m, 4mdest_y24m) Display *4mdisplay24m; Drawable 4msrc24m, 4mdest24m; GC 4mgc24m; int 4msrc_x24m, 4msrc_y24m; unsigned int 4mwidth24m, 4mheight24m; int 4mdest_x24m, 4mdest_y24m; 4mdisplay24m Specifies the connection to the X server. 4msrc0m 4mdest24m Specify the source and destination rectangles to be combined. 4mgc24m Specifies the GC. 4msrc_x0m 4msrc_y24m Specify the x and y coordinates, which are rela- tive to the origin of the source rectangle and specify its upper-left corner. 4mwidth0m 4mheight24m Specify the width and height, which are the dimen- sions of both the source and destination rectan- gles. 4mdest_x0m 4mdest_y24m Specify the x and y coordinates, which are rela- tive to the origin of the destination rectangle and specify its upper-left corner. __ The 4mXCopyArea24m function combines the specified rectangle of src with the specified rectangle of dest. The drawables must have the same root and depth, or a 4mBadMatch24m error results. If regions of the source rectangle are obscured and have not been retained in backing store or if regions outside the boundaries of the source drawable are specified, those regions are not copied. Instead, the following occurs on all corresponding destination regions that are either visi- ble or are retained in backing store. If the destination is a window with a background other than 4mNone24m, corresponding regions of the destination are tiled with that background (with plane-mask of all ones and 4mGXcopy24m function). Regard- less of tiling or whether the destination is a window or a pixmap, if graphics-exposures is 4mTrue24m, then 4mGraphicsExpose0m events for all corresponding destination regions are gener- ated. If graphics-exposures is 4mTrue24m but no 4mGraphicsExpose0m events are generated, a 4mNoExpose24m event is generated. Note that by default graphics-exposures is 4mTrue24m in new GCs. 1m2200m 1mXlib C Library X11, Release 6.9/7.00m This function uses these GC components: function, plane- mask, subwindow-mode, graphics-exposures, clip-x-origin, clip-y-origin, and clip-mask. 4mXCopyArea24m can generate 4mBadDrawable24m, 4mBadGC24m, and 4mBadMatch0m errors. To copy a single bit plane of a given drawable, use 4mXCopy-0m 4mPlane24m. __ XCopyPlane(4mdisplay24m, 4msrc24m, 4mdest24m, 4mgc24m, 4msrc_x24m, 4msrc_y24m, 4mwidth24m, 4mheight24m, 4mdest_x24m, 4mdest_y24m, 4mplane24m) Display *4mdisplay24m; Drawable 4msrc24m, 4mdest24m; GC 4mgc24m; int 4msrc_x24m, 4msrc_y24m; unsigned int 4mwidth24m, 4mheight24m; int 4mdest_x24m, 4mdest_y24m; unsigned long 4mplane24m; 4mdisplay24m Specifies the connection to the X server. 4msrc0m 4mdest24m Specify the source and destination rectangles to be combined. 4mgc24m Specifies the GC. 4msrc_x0m 4msrc_y24m Specify the x and y coordinates, which are rela- tive to the origin of the source rectangle and specify its upper-left corner. 4mwidth0m 4mheight24m Specify the width and height, which are the dimen- sions of both the source and destination rectan- gles. 4mdest_x0m 4mdest_y24m Specify the x and y coordinates, which are rela- tive to the origin of the destination rectangle and specify its upper-left corner. 4mplane24m Specifies the bit plane. You must set exactly one bit to 1. __ The 4mXCopyPlane24m function uses a single bit plane of the spec- ified source rectangle combined with the specified GC to modify the specified rectangle of dest. The drawables must have the same root but need not have the same depth. If the drawables do not have the same root, a 4mBadMatch24m error 1m2210m 1mXlib C Library X11, Release 6.9/7.00m results. If plane does not have exactly one bit set to 1 and the value of plane is not less than 24mn24m, where 4mn24m is the depth of src, a 4mBadValue24m error results. Effectively, 4mXCopyPlane24m forms a pixmap of the same depth as the rectangle of dest and with a size specified by the source region. It uses the foreground/background pixels in the GC (foreground everywhere the bit plane in src contains a bit set to 1, background everywhere the bit plane in src contains a bit set to 0) and the equivalent of a 4mCopyArea0m protocol request is performed with all the same exposure semantics. This can also be thought of as using the speci- fied region of the source bit plane as a stipple with a fill-style of 4mFillOpaqueStippled24m for filling a rectangular area of the destination. This function uses these GC components: function, plane- mask, foreground, background, subwindow-mode, graphics-expo- sures, clip-x-origin, clip-y-origin, and clip-mask. 4mXCopyPlane24m can generate 4mBadDrawable24m, 4mBadGC24m, 4mBadMatch24m, and 4mBadValue24m errors. 1m8.3. Drawing Points, Lines, Rectangles, and Arcs0m Xlib provides functions that you can use to draw: A single point or multiple points A single line or multiple lines A single rectangle or multiple rectangles A single arc or multiple arcs Some of the functions described in the following sections use these structures: __ typedef struct { short x1, y1, x2, y2; } XSegment; __ 1m2220m 1mXlib C Library X11, Release 6.9/7.00m __ typedef struct { short x, y; } XPoint; __ __ typedef struct { short x, y; unsigned short width, height; } XRectangle; __ __ typedef struct { short x, y; unsigned short width, height; short angle1, angle2; /* Degrees * 64 */ } XArc; __ All x and y members are signed integers. The width and height members are 16-bit unsigned integers. You should be careful not to generate coordinates and sizes out of the 16-bit ranges, because the protocol only has 16-bit fields for these values. 1m8.3.1. Drawing Single and Multiple Points0m To draw a single point in a given drawable, use 4mXDrawPoint24m. 1m2230m 1mXlib C Library X11, Release 6.9/7.00m __ XDrawPoint(4mdisplay24m, 4md24m, 4mgc24m, 4mx24m, 4my24m) Display *4mdisplay24m; Drawable 4md24m; GC 4mgc24m; int 4mx24m, 4my24m; 4mdisplay24m Specifies the connection to the X server. 4md24m Specifies the drawable. 4mgc24m Specifies the GC. 4mx0m 4my24m Specify the x and y coordinates where you want the point drawn. __ To draw multiple points in a given drawable, use 4mXDraw-0m 4mPoints24m. __ XDrawPoints(4mdisplay24m, 4md24m, 4mgc24m, 4mpoints24m, 4mnpoints24m, 4mmode24m) Display *4mdisplay24m; Drawable 4md24m; GC 4mgc24m; XPoint *4mpoints24m; int 4mnpoints24m; int 4mmode24m; 4mdisplay24m Specifies the connection to the X server. 4md24m Specifies the drawable. 4mgc24m Specifies the GC. 4mpoints24m Specifies an array of points. 4mnpoints24m Specifies the number of points in the array. 4mmode24m Specifies the coordinate mode. You can pass 4mCoordModeOrigin24m or 4mCoordModePrevious24m. __ The 4mXDrawPoint24m function uses the foreground pixel and func- tion components of the GC to draw a single point into the specified drawable; 4mXDrawPoints24m draws multiple points this way. 4mCoordModeOrigin24m treats all coordinates as relative to the origin, and 4mCoordModePrevious24m treats all coordinates after the first as relative to the previous point. 4mXDraw-0m 4mPoints24m draws the points in the order listed in the array. 1m2240m 1mXlib C Library X11, Release 6.9/7.00m Both functions use these GC components: function, plane- mask, foreground, subwindow-mode, clip-x-origin, clip-y-ori- gin, and clip-mask. 4mXDrawPoint24m can generate 4mBadDrawable24m, 4mBadGC24m, and 4mBadMatch0m errors. 4mXDrawPoints24m can generate 4mBadDrawable24m, 4mBadGC24m, 4mBad-0m 4mMatch24m, and 4mBadValue24m errors. 1m8.3.2. Drawing Single and Multiple Lines0m To draw a single line between two points in a given draw- able, use 4mXDrawLine24m. __ XDrawLine(4mdisplay24m, 4md24m, 4mgc24m, 4mx124m, 4my124m, 4mx224m, 4my224m) Display *4mdisplay24m; Drawable 4md24m; GC 4mgc24m; int 4mx124m, 4my124m, 4mx224m, 4my224m; 4mdisplay24m Specifies the connection to the X server. 4md24m Specifies the drawable. 4mgc24m Specifies the GC. 4mx10m 4my10m 4mx20m 4my224m Specify the points (x1, y1) and (x2, y2) to be connected. __ To draw multiple lines in a given drawable, use 4mXDrawLines24m. 1m2250m 1mXlib C Library X11, Release 6.9/7.00m __ XDrawLines(4mdisplay24m, 4md24m, 4mgc24m, 4mpoints24m, 4mnpoints24m, 4mmode24m) Display *4mdisplay24m; Drawable 4md24m; GC 4mgc24m; XPoint *4mpoints24m; int 4mnpoints24m; int 4mmode24m; 4mdisplay24m Specifies the connection to the X server. 4md24m Specifies the drawable. 4mgc24m Specifies the GC. 4mpoints24m Specifies an array of points. 4mnpoints24m Specifies the number of points in the array. 4mmode24m Specifies the coordinate mode. You can pass 4mCoordModeOrigin24m or 4mCoordModePrevious24m. __ To draw multiple, unconnected lines in a given drawable, use 4mXDrawSegments24m. __ XDrawSegments(4mdisplay24m, 4md24m, 4mgc24m, 4msegments24m, 4mnsegments24m) Display *4mdisplay24m; Drawable 4md24m; GC 4mgc24m; XSegment *4msegments24m; int 4mnsegments24m; 4mdisplay24m Specifies the connection to the X server. 4md24m Specifies the drawable. 4mgc24m Specifies the GC. 4msegments24m Specifies an array of segments. 4mnsegments24m Specifies the number of segments in the array. __ The 4mXDrawLine24m function uses the components of the specified GC to draw a line between the specified set of points (x1, y1) and (x2, y2). It does not perform joining at coincident endpoints. For any given line, 4mXDrawLine24m does not draw a pixel more than once. If lines intersect, the intersecting pixels are drawn multiple times. 1m2260m 1mXlib C Library X11, Release 6.9/7.00m The 4mXDrawLines24m function uses the components of the specified GC to draw npoints1 lines between each pair of points (point[i], point[i+1]) in the array of 4mXPoint24m structures. It draws the lines in the order listed in the array. The lines join correctly at all intermediate points, and if the first and last points coincide, the first and last lines also join correctly. For any given line, 4mXDrawLines24m does not draw a pixel more than once. If thin (zero line-width) lines intersect, the intersecting pixels are drawn multiple times. If wide lines intersect, the intersecting pixels are drawn only once, as though the entire 4mPolyLine24m protocol request were a single, filled shape. 4mCoordModeOrigin24m treats all coordinates as relative to the origin, and 4mCoordModePre-0m 4mvious24m treats all coordinates after the first as relative to the previous point. The 4mXDrawSegments24m function draws multiple, unconnected lines. For each segment, 4mXDrawSegments24m draws a line between (x1, y1) and (x2, y2). It draws the lines in the order listed in the array of 4mXSegment24m structures and does not per- form joining at coincident endpoints. For any given line, 4mXDrawSegments24m does not draw a pixel more than once. If lines intersect, the intersecting pixels are drawn multiple times. All three functions use these GC components: function, plane-mask, line-width, line-style, cap-style, fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. The 4mXDrawLines24m function also uses the join-style GC compo- nent. All three functions also use these GC mode-dependent components: foreground, background, tile, stipple, tile- stipple-x-origin, tile-stipple-y-origin, dash-offset, and dash-list. 4mXDrawLine24m, 4mXDrawLines24m, and 4mXDrawSegments24m can generate 4mBad-0m 4mDrawable24m, 4mBadGC24m, and 4mBadMatch24m errors. 4mXDrawLines24m also can generate 4mBadValue24m errors. 1m8.3.3. Drawing Single and Multiple Rectangles0m To draw the outline of a single rectangle in a given draw- able, use 4mXDrawRectangle24m. 1m2270m 1mXlib C Library X11, Release 6.9/7.00m __ XDrawRectangle(4mdisplay24m, 4md24m, 4mgc24m, 4mx24m, 4my24m, 4mwidth24m, 4mheight24m) Display *4mdisplay24m; Drawable 4md24m; GC 4mgc24m; int 4mx24m, 4my24m; unsigned int 4mwidth24m, 4mheight24m; 4mdisplay24m Specifies the connection to the X server. 4md24m Specifies the drawable. 4mgc24m Specifies the GC. 4mx0m 4my24m Specify the x and y coordinates, which specify the upper-left corner of the rectangle. 4mwidth0m 4mheight24m Specify the width and height, which specify the dimensions of the rectangle. __ To draw the outline of multiple rectangles in a given draw- able, use 4mXDrawRectangles24m. __ XDrawRectangles(4mdisplay24m, 4md24m, 4mgc24m, 4mrectangles24m, 4mnrectangles24m) Display *4mdisplay24m; Drawable 4md24m; GC 4mgc24m; XRectangle 4mrectangles24m[]; int 4mnrectangles24m; 4mdisplay24m Specifies the connection to the X server. 4md24m Specifies the drawable. 4mgc24m Specifies the GC. 4mrectangles0m Specifies an array of rectangles. 4mnrectangles0m Specifies the number of rectangles in the array. __ The 4mXDrawRectangle24m and 4mXDrawRectangles24m functions draw the outlines of the specified rectangle or rectangles as if a five-point 4mPolyLine24m protocol request were specified for each rectangle: 1m2280m 1mXlib C Library X11, Release 6.9/7.00m [x,y] [x+width,y] [x+width,y+height] [x,y+height] [x,y] For the specified rectangle or rectangles, these functions do not draw a pixel more than once. 4mXDrawRectangles24m draws the rectangles in the order listed in the array. If rectan- gles intersect, the intersecting pixels are drawn multiple times. Both functions use these GC components: function, plane- mask, line-width, line-style, cap-style, join-style, fill- style, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. They also use these GC mode-dependent compo- nents: foreground, background, tile, stipple, tile-stipple- x-origin, tile-stipple-y-origin, dash-offset, and dash-list. 4mXDrawRectangle24m and 4mXDrawRectangles24m can generate 4mBadDrawable24m, 4mBadGC24m, and 4mBadMatch24m errors. 1m8.3.4. Drawing Single and Multiple Arcs0m To draw a single arc in a given drawable, use 4mXDrawArc24m. 1m2290m 1mXlib C Library X11, Release 6.9/7.00m __ XDrawArc(4mdisplay24m, 4md24m, 4mgc24m, 4mx24m, 4my24m, 4mwidth24m, 4mheight24m, 4mangle124m, 4mangle224m) Display *4mdisplay24m; Drawable 4md24m; GC 4mgc24m; int 4mx24m, 4my24m; unsigned int 4mwidth24m, 4mheight24m; int 4mangle124m, 4mangle224m; 4mdisplay24m Specifies the connection to the X server. 4md24m Specifies the drawable. 4mgc24m Specifies the GC. 4mx0m 4my24m Specify the x and y coordinates, which are rela- tive to the origin of the drawable and specify the upper-left corner of the bounding rectangle. 4mwidth0m 4mheight24m Specify the width and height, which are the major and minor axes of the arc. 4mangle124m Specifies the start of the arc relative to the three-oclock position from the center, in units of degrees * 64. 4mangle224m Specifies the path and extent of the arc relative to the start of the arc, in units of degrees * 64. __ To draw multiple arcs in a given drawable, use 4mXDrawArcs24m. 1m2300m 1mXlib C Library X11, Release 6.9/7.00m __ XDrawArcs(4mdisplay24m, 4md24m, 4mgc24m, 4marcs24m, 4mnarcs24m) Display *4mdisplay24m; Drawable 4md24m; GC 4mgc24m; XArc *4marcs24m; int 4mnarcs24m; 4mdisplay24m Specifies the connection to the X server. 4md24m Specifies the drawable. 4mgc24m Specifies the GC. 4marcs24m Specifies an array of arcs. 4mnarcs24m Specifies the number of arcs in the array. __ 4mXDrawArc24m draws a single circular or elliptical arc, and 4mXDrawArcs24m draws multiple circular or elliptical arcs. Each arc is specified by a rectangle and two angles. The center of the circle or ellipse is the center of the rectangle, and the major and minor axes are specified by the width and height. Positive angles indicate counterclockwise motion, and negative angles indicate clockwise motion. If the mag- nitude of angle2 is greater than 360 degrees, 4mXDrawArc24m or 4mXDrawArcs24m truncates it to 360 degrees. For an arc specified as [4mx24m,4my24m,4mwidth24m,4mheight24m,4mangle24m1,4mangle24m2], the origin of the major and minor axes is at [4mx24m+4m__24m4m___24m,4my24m+4m___24m4m___24m], and the infinitely thin path describing the entire circle or ellipse intersects the horizontal axis at [4mx24m,4my24m+4m___24m4m___24m] and [4mx24m+4mwidth24m,4my24m+4m___24m4m___24m] and intersects the vertical axis at [4mx24m+4m__24m4m___24m,4my24m] and [4mx24m+4m__24m4m___24m,4my24m+4mheight24m]. These coordinates can be fractional and so are not truncated to discrete coordinates. The path should be defined by the ideal mathematical path. For a wide line with line-width lw, the bounding outlines for filling are given by the two infinitely thin paths consisting of all points whose perpen- dicular distance from the path of the circle/ellipse is equal to lw/2 (which may be a fractional value). The cap- style and join-style are applied the same as for a line cor- responding to the tangent of the circle/ellipse at the end- point. For an arc specified as [4mx24m,4my24m,4mwidth24m,4mheight24m,4mangle24m1,4mangle24m2], the angles must be specified in the effectively skewed coor- dinate system of the ellipse (for a circle, the angles and coordinate systems are identical). The relationship between these angles and angles expressed in the normal coordinate system of the screen (as measured with a protractor) is as 1m2310m 1mXlib C Library X11, Release 6.9/7.00m follows: skewed-angle=4matan24m(tan(normal-angle)*4m______24m)+4madjust0m The skewed-angle and normal-angle are expressed in radians (rather than in degrees scaled by 64) in the range [0,2] and where atan returns a value in the range 4m_24m4m_24m] and adjust is: 0 for normal-angle in the range [04m_24m] for normal-angle in the range 4m_24m,4m_244m_24m] 2 for normal-angle in the range [4m_244m_24m,2] For any given arc, 4mXDrawArc24m and 4mXDrawArcs24m do not draw a pixel more than once. If two arcs join correctly and if the line-width is greater than zero and the arcs intersect, 4mXDrawArc24m and 4mXDrawArcs24m do not draw a pixel more than once. Otherwise, the intersecting pixels of intersecting arcs are drawn multiple times. Specifying an arc with one endpoint and a clockwise extent draws the same pixels as specifying the other endpoint and an equivalent counterclockwise extent, except as it affects joins. If the last point in one arc coincides with the first point in the following arc, the two arcs will join correctly. If the first point in the first arc coincides with the last point in the last arc, the two arcs will join correctly. By specifying one axis to be zero, a horizontal or vertical line can be drawn. Angles are computed based solely on the coordinate system and ignore the aspect ratio. Both functions use these GC components: function, plane- mask, line-width, line-style, cap-style, join-style, fill- style, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. They also use these GC mode-dependent compo- nents: foreground, background, tile, stipple, tile-stipple- x-origin, tile-stipple-y-origin, dash-offset, and dash-list. 4mXDrawArc24m and 4mXDrawArcs24m can generate 4mBadDrawable24m, 4mBadGC24m, and 4mBadMatch24m errors. 1m8.4. Filling Areas0m Xlib provides functions that you can use to fill: A single rectangle or multiple rectangles A single polygon 1m2320m 1mXlib C Library X11, Release 6.9/7.00m A single arc or multiple arcs 1m8.4.1. Filling Single and Multiple Rectangles0m To fill a single rectangular area in a given drawable, use 4mXFillRectangle24m. __ XFillRectangle(4mdisplay24m, 4md24m, 4mgc24m, 4mx24m, 4my24m, 4mwidth24m, 4mheight24m) Display *4mdisplay24m; Drawable 4md24m; GC 4mgc24m; int 4mx24m, 4my24m; unsigned int 4mwidth24m, 4mheight24m; 4mdisplay24m Specifies the connection to the X server. 4md24m Specifies the drawable. 4mgc24m Specifies the GC. 4mx0m 4my24m Specify the x and y coordinates, which are rela- tive to the origin of the drawable and specify the upper-left corner of the rectangle. 4mwidth0m 4mheight24m Specify the width and height, which are the dimen- sions of the rectangle to be filled. __ To fill multiple rectangular areas in a given drawable, use 4mXFillRectangles24m. 1m2330m 1mXlib C Library X11, Release 6.9/7.00m __ XFillRectangles(4mdisplay24m, 4md24m, 4mgc24m, 4mrectangles24m, 4mnrectangles24m) Display *4mdisplay24m; Drawable 4md24m; GC 4mgc24m; XRectangle *4mrectangles24m; int 4mnrectangles24m; 4mdisplay24m Specifies the connection to the X server. 4md24m Specifies the drawable. 4mgc24m Specifies the GC. 4mrectangles0m Specifies an array of rectangles. 4mnrectangles0m Specifies the number of rectangles in the array. __ The 4mXFillRectangle24m and 4mXFillRectangles24m functions fill the specified rectangle or rectangles as if a four-point 4mFillPolygon24m protocol request were specified for each rectan- gle: [x,y] [x+width,y] [x+width,y+height] [x,y+height] Each function uses the x and y coordinates, width and height dimensions, and GC you specify. 4mXFillRectangles24m fills the rectangles in the order listed in the array. For any given rectangle, 4mXFillRectangle24m and 4mXFillRectangles24m do not draw a pixel more than once. If rectangles intersect, the intersecting pixels are drawn mul- tiple times. Both functions use these GC components: function, plane- mask, fill-style, subwindow-mode, clip-x-origin, clip-y-ori- gin, and clip-mask. They also use these GC mode-dependent components: foreground, background, tile, stipple, tile- stipple-x-origin, and tile-stipple-y-origin. 4mXFillRectangle24m and 4mXFillRectangles24m can generate 4mBadDrawable24m, 4mBadGC24m, and 4mBadMatch24m errors. 1m8.4.2. Filling a Single Polygon0m To fill a polygon area in a given drawable, use 4mXFillPoly-0m 4mgon24m. 1m2340m 1mXlib C Library X11, Release 6.9/7.00m __ XFillPolygon(4mdisplay24m, 4md24m, 4mgc24m, 4mpoints24m, 4mnpoints24m, 4mshape24m, 4mmode24m) Display *4mdisplay24m; Drawable 4md24m; GC 4mgc24m; XPoint *4mpoints24m; int 4mnpoints24m; int 4mshape24m; int 4mmode24m; 4mdisplay24m Specifies the connection to the X server. 4md24m Specifies the drawable. 4mgc24m Specifies the GC. 4mpoints24m Specifies an array of points. 4mnpoints24m Specifies the number of points in the array. 4mshape24m Specifies a shape that helps the server to improve performance. You can pass 4mComplex24m, 4mConvex24m, or 4mNonconvex24m. 4mmode24m Specifies the coordinate mode. You can pass 4mCoordModeOrigin24m or 4mCoordModePrevious24m. __ 4mXFillPolygon24m fills the region closed by the specified path. The path is closed automatically if the last point in the list does not coincide with the first point. 4mXFillPolygon0m does not draw a pixel of the region more than once. 4mCoord-0m 4mModeOrigin24m treats all coordinates as relative to the origin, and 4mCoordModePrevious24m treats all coordinates after the first as relative to the previous point. Depending on the specified shape, the following occurs: If shape is 4mComplex24m, the path may self-intersect. Note that contiguous coincident points in the path are not treated as self-intersection. If shape is 4mConvex24m, for every pair of points inside the polygon, the line segment connecting them does not intersect the path. If known by the client, specifying 4mConvex24m can improve performance. If you specify 4mConvex0m for a path that is not convex, the graphics results are undefined. If shape is 4mNonconvex24m, the path does not self-inter- sect, but the shape is not wholly convex. If known by the client, specifying 4mNonconvex24m instead of 4mComplex24m may improve performance. If you specify 4mNonconvex24m for a 1m2350m 1mXlib C Library X11, Release 6.9/7.00m self-intersecting path, the graphics results are unde- fined. The fill-rule of the GC controls the filling behavior of self-intersecting polygons. This function uses these GC components: function, plane- mask, fill-style, fill-rule, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. It also uses these GC mode- dependent components: foreground, background, tile, stipple, tile-stipple-x-origin, and tile-stipple-y-origin. 4mXFillPolygon24m can generate 4mBadDrawable24m, 4mBadGC24m, 4mBadMatch24m, and 4mBadValue24m errors. 1m8.4.3. Filling Single and Multiple Arcs0m To fill a single arc in a given drawable, use 4mXFillArc24m. __ XFillArc(4mdisplay24m, 4md24m, 4mgc24m, 4mx24m, 4my24m, 4mwidth24m, 4mheight24m, 4mangle124m, 4mangle224m) Display *4mdisplay24m; Drawable 4md24m; GC 4mgc24m; int 4mx24m, 4my24m; unsigned int 4mwidth24m, 4mheight24m; int 4mangle124m, 4mangle224m; 4mdisplay24m Specifies the connection to the X server. 4md24m Specifies the drawable. 4mgc24m Specifies the GC. 4mx0m 4my24m Specify the x and y coordinates, which are rela- tive to the origin of the drawable and specify the upper-left corner of the bounding rectangle. 4mwidth0m 4mheight24m Specify the width and height, which are the major and minor axes of the arc. 4mangle124m Specifies the start of the arc relative to the three-oclock position from the center, in units of degrees * 64. 4mangle224m Specifies the path and extent of the arc relative to the start of the arc, in units of degrees * 64. __ To fill multiple arcs in a given drawable, use 4mXFillArcs24m. 1m2360m 1mXlib C Library X11, Release 6.9/7.00m __ XFillArcs(4mdisplay24m, 4md24m, 4mgc24m, 4marcs24m, 4mnarcs24m) Display *4mdisplay24m; Drawable 4md24m; GC 4mgc24m; XArc *4marcs24m; int 4mnarcs24m; 4mdisplay24m Specifies the connection to the X server. 4md24m Specifies the drawable. 4mgc24m Specifies the GC. 4marcs24m Specifies an array of arcs. 4mnarcs24m Specifies the number of arcs in the array. __ For each arc, 4mXFillArc24m or 4mXFillArcs24m fills the region closed by the infinitely thin path described by the specified arc and, depending on the arc-mode specified in the GC, one or two line segments. For 4mArcChord24m, the single line segment joining the endpoints of the arc is used. For 4mArcPieSlice24m, the two line segments joining the endpoints of the arc with the center point are used. 4mXFillArcs24m fills the arcs in the order listed in the array. For any given arc, 4mXFillArc24m and 4mXFillArcs24m do not draw a pixel more than once. If regions intersect, the intersecting pixels are drawn multiple times. Both functions use these GC components: function, plane- mask, fill-style, arc-mode, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. They also use these GC mode- dependent components: foreground, background, tile, stipple, tile-stipple-x-origin, and tile-stipple-y-origin. 4mXFillArc24m and 4mXFillArcs24m can generate 4mBadDrawable24m, 4mBadGC24m, and 4mBadMatch24m errors. 1m8.5. Font Metrics0m A font is a graphical description of a set of characters that are used to increase efficiency whenever a set of small, similar sized patterns are repeatedly used. This section discusses how to: Load and free fonts Obtain and free font names Compute character string sizes 1m2370m 1mXlib C Library X11, Release 6.9/7.00m Compute logical extents Query character string sizes The X server loads fonts whenever a program requests a new font. The server can cache fonts for quick lookup. Fonts are global across all screens in a server. Several levels are possible when dealing with fonts. Most applications simply use 4mXLoadQueryFont24m to load a font and query the font metrics. Characters in fonts are regarded as masks. Except for image text requests, the only pixels modified are those in which bits are set to 1 in the character. This means that it makes sense to draw text using stipples or tiles (for exam- ple, many menus gray-out unusable entries). 1m2380m 1mXlib C Library X11, Release 6.9/7.00m __ The 4mXFontStruct24m structure contains all of the information for the font and consists of the font-specific information as well as a pointer to an array of 4mXCharStruct24m structures for the characters contained in the font. The 4mXFontStruct24m, 4mXFontProp24m, and 4mXCharStruct24m structures contain: typedef struct { short lbearing; /* origin to left edge of raster */ short rbearing; /* origin to right edge of raster */ short width; /* advance to next chars origin */ short ascent; /* baseline to top edge of raster */ short descent; /* baseline to bottom edge of raster */ unsigned short attributes;/* per char flags (not predefined) */ } XCharStruct; typedef struct { Atom name; unsigned long card32; } XFontProp; typedef struct { /* normal 16 bit characters are two bytes */ unsigned char byte1; unsigned char byte2; } XChar2b; typedef struct { XExtData *ext_data; /* hook for extension to hang data */ Font fid; /* Font id for this font */ unsigned direction; /* hint about the direction font is painted */ unsigned min_char_or_byte2;/* first character */ unsigned max_char_or_byte2;/* last character */ unsigned min_byte1; /* first row that exists */ unsigned max_byte1; /* last row that exists */ Bool all_chars_exist; /* flag if all characters have nonzero size */ unsigned default_char; /* char to print for undefined character */ int n_properties; /* how many properties there are */ XFontProp *properties; /* pointer to array of additional properties */ XCharStruct min_bounds; /* minimum bounds over all existing char */ XCharStruct max_bounds; /* maximum bounds over all existing char */ XCharStruct *per_char; /* first_char to last_char information */ int ascent; /* logical extent above baseline for spacing */ int descent; /* logical descent below baseline for spacing */ } XFontStruct; __ X supports single byte/character, two bytes/character 1m2390m 1mXlib C Library X11, Release 6.9/7.00m matrix, and 16-bit character text operations. Note that any of these forms can be used with a font, but a single byte/character text request can only specify a single byte (that is, the first row of a 2-byte font). You should view 2-byte fonts as a two-dimensional matrix of defined charac- ters: byte1 specifies the range of defined rows and byte2 defines the range of defined columns of the font. Single byte/character fonts have one row defined, and the byte2 range specified in the structure defines a range of charac- ters. The bounding box of a character is defined by the 4mXCharStruct24m of that character. When characters are absent from a font, the default_char is used. When fonts have all characters of the same size, only the information in the 4mXFontStruct24m min and max bounds are used. The members of the 4mXFontStruct24m have the following semantics: The direction member can be either 4mFontLeftToRight24m or 4mFontRightToLeft24m. It is just a hint as to whether most 4mXCharStruct24m elements have a positive (4mFontLeftToRight24m) or a negative (4mFontRightToLeft24m) character width metric. The core protocol defines no support for vertical text. If the min_byte1 and max_byte1 members are both zero, min_char_or_byte2 specifies the linear character index corresponding to the first element of the per_char array, and max_char_or_byte2 specifies the linear char- acter index of the last element. If either min_byte1 or max_byte1 are nonzero, both min_char_or_byte2 and max_char_or_byte2 are less than 256, and the 2-byte character index values correspond- ing to the per_char array element N (counting from 0) are: byte1 = N/D + min_byte1 byte2 = N\D + min_char_or_byte2 where: D = max_char_or_byte2 min_char_or_byte2 + 1 / = integer division \ = integer modulus If the per_char pointer is NULL, all glyphs between the first and last character indexes inclusive have the same information, as given by both min_bounds and max_bounds. If all_chars_exist is 4mTrue24m, all characters in the per_char array have nonzero bounding boxes. 1m2400m 1mXlib C Library X11, Release 6.9/7.00m The default_char member specifies the character that will be used when an undefined or nonexistent character is printed. The default_char is a 16-bit character (not a 2-byte character). For a font using 2-byte matrix format, the default_char has byte1 in the most- significant byte and byte2 in the least significant byte. If the default_char itself specifies an unde- fined or nonexistent character, no printing is per- formed for an undefined or nonexistent character. The min_bounds and max_bounds members contain the most extreme values of each individual 4mXCharStruct24m component over all elements of this array (and ignore nonexistent characters). The bounding box of the font (the small- est rectangle enclosing the shape obtained by superim- posing all of the characters at the same origin [x,y]) has its upper-left coordinate at: [x + min_bounds.lbearing, y max_bounds.ascent] Its width is: max_bounds.rbearing min_bounds.lbearing Its height is: max_bounds.ascent + max_bounds.descent The ascent member is the logical extent of the font above the baseline that is used for determining line spacing. Specific characters may extend beyond this. The descent member is the logical extent of the font at or below the baseline that is used for determining line spacing. Specific characters may extend beyond this. If the baseline is at Y-coordinate y, the logical extent of the font is inclusive between the Y-coordi- nate values (y font.ascent) and (y + font.descent 1). Typically, the minimum interline spacing between rows of text is given by ascent + descent. For a character origin at [x,y], the bounding box of a char- acter (that is, the smallest rectangle that encloses the characters shape) described in terms of 4mXCharStruct24m compo- nents is a rectangle with its upper-left corner at: [x + lbearing, y ascent] 1m2410m 1mXlib C Library X11, Release 6.9/7.00m Its width is: rbearing lbearing Its height is: ascent + descent The origin for the next character is defined to be: [x + width, y] The lbearing member defines the extent of the left edge of the character ink from the origin. The rbearing member defines the extent of the right edge of the character ink from the origin. The ascent member defines the extent of the top edge of the character ink from the origin. The descent member defines the extent of the bottom edge of the character ink from the origin. The width member defines the logical width of the character. Note that the baseline (the y position of the character ori- gin) is logically viewed as being the scanline just below nondescending characters. When descent is zero, only pixels with Y-coordinates less than y are drawn, and the origin is logically viewed as being coincident with the left edge of a nonkerned character. When lbearing is zero, no pixels with X-coordinate less than x are drawn. Any of the 4mXCharStruct0m metric members could be negative. If the width is negative, the next character will be placed to the left of the current origin. The X protocol does not define the interpretation of the attributes member in the 4mXCharStruct24m structure. A nonexis- tent character is represented with all members of its 4mXCharStruct24m set to zero. A font is not guaranteed to have any properties. The inter- pretation of the property value (for example, long or unsigned long) must be derived from 4ma24m 4mpriori24m knowledge of the property. A basic set of font properties is specified in the X Consortium standard 4mX24m 4mLogical24m 4mFont24m 4mDescription24m 4mCon-0m 4mventions24m. 1m8.5.1. Loading and Freeing Fonts0m Xlib provides functions that you can use to load fonts, get font information, unload fonts, and free font information. 1m2420m 1mXlib C Library X11, Release 6.9/7.00m A few font functions use a 4mGContext24m resource ID or a font ID interchangeably. To load a given font, use 4mXLoadFont24m. __ Font XLoadFont(4mdisplay24m, 4mname24m) Display *4mdisplay24m; char *4mname24m; 4mdisplay24m Specifies the connection to the X server. 4mname24m Specifies the name of the font, which is a null- terminated string. __ The 4mXLoadFont24m function loads the specified font and returns its associated font ID. If the font name is not in the Host Portable Character Encoding, the result is implementation- dependent. Use of uppercase or lowercase does not matter. When the characters ? and * are used in a font name, a pattern match is performed and any matching font is used. In the pattern, the ? character will match any single character, and the * character will match any number of characters. A structured format for font names is specified in the X Consortium standard 4mX24m 4mLogical24m 4mFont24m 4mDescription24m 4mCon-0m 4mventions24m. If 4mXLoadFont24m was unsuccessful at loading the specified font, a 4mBadName24m error results. Fonts are not associated with a particular screen and can be stored as a component of any GC. When the font is no longer needed, call 4mXUnloadFont24m. 4mXLoadFont24m can generate 4mBadAlloc24m and 4mBadName24m errors. To return information about an available font, use 4mXQuery-0m 4mFont24m. __ XFontStruct *XQueryFont(4mdisplay24m, 4mfont_ID24m) Display *4mdisplay24m; XID 4mfont_ID24m; 4mdisplay24m Specifies the connection to the X server. 4mfont_ID24m Specifies the font ID or the 4mGContext24m ID. __ The 4mXQueryFont24m function returns a pointer to the 4mXFontStruct0m structure, which contains information associated with the font. You can query a font or the font stored in a GC. The 1m2430m 1mXlib C Library X11, Release 6.9/7.00m font ID stored in the 4mXFontStruct24m structure will be the 4mGContext24m ID, and you need to be careful when using this ID in other functions (see 4mXGContextFromGC24m). If the font does not exist, 4mXQueryFont24m returns NULL. To free this data, use 4mXFreeFontInfo24m. To perform a 4mXLoadFont24m and 4mXQueryFont24m in a single operation, use 4mXLoadQueryFont24m. __ XFontStruct *XLoadQueryFont(4mdisplay24m, 4mname24m) Display *4mdisplay24m; char *4mname24m; 4mdisplay24m Specifies the connection to the X server. 4mname24m Specifies the name of the font, which is a null- terminated string. __ The 4mXLoadQueryFont24m function provides the most common way for accessing a font. 4mXLoadQueryFont24m both opens (loads) the specified font and returns a pointer to the appropriate 4mXFontStruct24m structure. If the font name is not in the Host Portable Character Encoding, the result is implementation- dependent. If the font does not exist, 4mXLoadQueryFont0m returns NULL. 4mXLoadQueryFont24m can generate a 4mBadAlloc24m error. To unload the font and free the storage used by the font structure that was allocated by 4mXQueryFont24m or 4mXLoadQuery-0m 4mFont24m, use 4mXFreeFont24m. __ XFreeFont(4mdisplay24m, 4mfont_struct24m) Display *4mdisplay24m; XFontStruct *4mfont_struct24m; 4mdisplay24m Specifies the connection to the X server. 4mfont_struct0m Specifies the storage associated with the font. __ The 4mXFreeFont24m function deletes the association between the font resource ID and the specified font and frees the 4mXFontStruct24m structure. The font itself will be freed when no other resource references it. The data and the font should not be referenced again. 1m2440m 1mXlib C Library X11, Release 6.9/7.00m 4mXFreeFont24m can generate a 4mBadFont24m error. To return a given font property, use 4mXGetFontProperty24m. __ Bool XGetFontProperty(4mfont_struct24m, 4matom24m, 4mvalue_return24m) XFontStruct *4mfont_struct24m; Atom 4matom24m; unsigned long *4mvalue_return24m; 4mfont_struct0m Specifies the storage associated with the font. 4matom24m Specifies the atom for the property name you want returned. 4mvalue_return0m Returns the value of the font property. __ Given the atom for that property, the 4mXGetFontProperty24m func- tion returns the value of the specified font property. 4mXGetFontProperty24m also returns 4mFalse24m if the property was not defined or 4mTrue24m if it was defined. A set of predefined atoms exists for font properties, which can be found in <4mX11/Xatom.h24m>. This set contains the standard properties associated with a font. Although it is not guaranteed, it is likely that the predefined font properties will be present. To unload a font that was loaded by 4mXLoadFont24m, use 4mXUnload-0m 4mFont24m. __ XUnloadFont(4mdisplay24m, 4mfont24m) Display *4mdisplay24m; Font 4mfont24m; 4mdisplay24m Specifies the connection to the X server. 4mfont24m Specifies the font. __ The 4mXUnloadFont24m function deletes the association between the font resource ID and the specified font. The font itself will be freed when no other resource references it. The font should not be referenced again. 4mXUnloadFont24m can generate a 4mBadFont24m error. 1m2450m 1mXlib C Library X11, Release 6.9/7.00m 1m8.5.2. Obtaining and Freeing Font Names and Information0m You obtain font names and information by matching a wildcard specification when querying a font type for a list of avail- able sizes and so on. To return a list of the available font names, use 4mXList-0m 4mFonts24m. __ char **XListFonts(4mdisplay24m, 4mpattern24m, 4mmaxnames24m, 4mactual_count_return24m) Display *4mdisplay24m; char *4mpattern24m; int 4mmaxnames24m; int *4mactual_count_return24m; 4mdisplay24m Specifies the connection to the X server. 4mpattern24m Specifies the null-terminated pattern string that can contain wildcard characters. 4mmaxnames24m Specifies the maximum number of names to be returned. 4mactual_count_return0m Returns the actual number of font names. __ The 4mXListFonts24m function returns an array of available font names (as controlled by the font search path; see 4mXSetFont-0m 4mPath24m) that match the string you passed to the pattern argu- ment. The pattern string can contain any characters, but each asterisk (*) is a wildcard for any number of charac- ters, and each question mark (?) is a wildcard for a single character. If the pattern string is not in the Host Portable Character Encoding, the result is implementation- dependent. Use of uppercase or lowercase does not matter. Each returned string is null-terminated. If the data returned by the server is in the Latin Portable Character Encoding, then the returned strings are in the Host Portable Character Encoding. Otherwise, the result is implementa- tion-dependent. If there are no matching font names, 4mXList-0m 4mFonts24m returns NULL. The client should call 4mXFreeFontNames0m when finished with the result to free the memory. To free a font name array, use 4mXFreeFontNames24m. 1m2460m 1mXlib C Library X11, Release 6.9/7.00m __ XFreeFontNames(4mlist24m) char *4mlist24m[]; 4mlist24m Specifies the array of strings you want to free. __ The 4mXFreeFontNames24m function frees the array and strings returned by 4mXListFonts24m or 4mXListFontsWithInfo24m. To obtain the names and information about available fonts, use 4mXListFontsWithInfo24m. __ char **XListFontsWithInfo(4mdisplay24m, 4mpattern24m, 4mmaxnames24m, 4mcount_return24m, 4minfo_return24m) Display *4mdisplay24m; char *4mpattern24m; int 4mmaxnames24m; int *4mcount_return24m; XFontStruct **4minfo_return24m; 4mdisplay24m Specifies the connection to the X server. 4mpattern24m Specifies the null-terminated pattern string that can contain wildcard characters. 4mmaxnames24m Specifies the maximum number of names to be returned. 4mcount_return0m Returns the actual number of matched font names. 4minfo_return0m Returns the font information. __ The 4mXListFontsWithInfo24m function returns a list of font names that match the specified pattern and their associated font information. The list of names is limited to size specified by maxnames. The information returned for each font is identical to what 4mXLoadQueryFont24m would return except that the per-character metrics are not returned. The pattern string can contain any characters, but each asterisk (*) is a wildcard for any number of characters, and each question mark (?) is a wildcard for a single character. If the pat- tern string is not in the Host Portable Character Encoding, the result is implementation-dependent. Use of uppercase or lowercase does not matter. Each returned string is null- terminated. If the data returned by the server is in the Latin Portable Character Encoding, then the returned strings are in the Host Portable Character Encoding. Otherwise, the 1m2470m 1mXlib C Library X11, Release 6.9/7.00m result is implementation-dependent. If there are no match- ing font names, 4mXListFontsWithInfo24m returns NULL. To free only the allocated name array, the client should call 4mXFreeFontNames24m. To free both the name array and the font information array or to free just the font information array, the client should call 4mXFreeFontInfo24m. To free font structures and font names, use 4mXFreeFontInfo24m. __ XFreeFontInfo(4mnames24m, 4mfree_info24m, 4mactual_count24m) char **4mnames24m; XFontStruct *4mfree_info24m; int 4mactual_count24m; 4mnames24m Specifies the list of font names. 4mfree_info24m Specifies the font information. 4mactual_count0m Specifies the actual number of font names. __ The 4mXFreeFontInfo24m function frees a font structure or an array of font structures and optionally an array of font names. If NULL is passed for names, no font names are freed. If a font structure for an open font (returned by 4mXLoadQueryFont24m) is passed, the structure is freed, but the font is not closed; use 4mXUnloadFont24m to close the font. 1m8.5.3. Computing Character String Sizes0m Xlib provides functions that you can use to compute the width, the logical extents, and the server information about 8-bit and 2-byte text strings. The width is computed by adding the character widths of all the characters. It does not matter if the font is an 8-bit or 2-byte font. These functions return the sum of the character metrics in pixels. To determine the width of an 8-bit character string, use 4mXTextWidth24m. 1m2480m 1mXlib C Library X11, Release 6.9/7.00m __ int XTextWidth(4mfont_struct24m, 4mstring24m, 4mcount24m) XFontStruct *4mfont_struct24m; char *4mstring24m; int 4mcount24m; 4mfont_struct0m Specifies the font used for the width computation. 4mstring24m Specifies the character string. 4mcount24m Specifies the character count in the specified string. __ To determine the width of a 2-byte character string, use 4mXTextWidth1624m. __ int XTextWidth16(4mfont_struct24m, 4mstring24m, 4mcount24m) XFontStruct *4mfont_struct24m; XChar2b *4mstring24m; int 4mcount24m; 4mfont_struct0m Specifies the font used for the width computation. 4mstring24m Specifies the character string. 4mcount24m Specifies the character count in the specified string. __ 1m8.5.4. Computing Logical Extents0m To compute the bounding box of an 8-bit character string in a given font, use 4mXTextExtents24m. 1m2490m 1mXlib C Library X11, Release 6.9/7.00m __ XTextExtents(4mfont_struct24m, 4mstring24m, 4mnchars24m, 4mdirection_return24m, 4mfont_ascent_return24m, 4mfont_descent_return24m, 4moverall_return24m) XFontStruct *4mfont_struct24m; char *4mstring24m; int 4mnchars24m; int *4mdirection_return24m; int *4mfont_ascent_return24m, *4mfont_descent_return24m; XCharStruct *4moverall_return24m; 4mfont_struct0m Specifies the 4mXFontStruct24m structure. 4mstring24m Specifies the character string. 4mnchars24m Specifies the number of characters in the charac- ter string. 4mdirection_return0m Returns the value of the direction hint (4mFontLeft-0m 4mToRight24m or 4mFontRightToLeft24m). 4mfont_ascent_return0m Returns the font ascent. 4mfont_descent_return0m Returns the font descent. 4moverall_return0m Returns the overall size in the specified 4mXCharStruct24m structure. __ To compute the bounding box of a 2-byte character string in a given font, use 4mXTextExtents1624m. 1m2500m 1mXlib C Library X11, Release 6.9/7.00m __ XTextExtents16(4mfont_struct24m, 4mstring24m, 4mnchars24m, 4mdirection_return24m, 4mfont_ascent_return24m, 4mfont_descent_return24m, 4moverall_return24m) XFontStruct *4mfont_struct24m; XChar2b *4mstring24m; int 4mnchars24m; int *4mdirection_return24m; int *4mfont_ascent_return24m, *4mfont_descent_return24m; XCharStruct *4moverall_return24m; 4mfont_struct0m Specifies the 4mXFontStruct24m structure. 4mstring24m Specifies the character string. 4mnchars24m Specifies the number of characters in the charac- ter string. 4mdirection_return0m Returns the value of the direction hint (4mFontLeft-0m 4mToRight24m or 4mFontRightToLeft24m). 4mfont_ascent_return0m Returns the font ascent. 4mfont_descent_return0m Returns the font descent. 4moverall_return0m Returns the overall size in the specified 4mXCharStruct24m structure. __ The 4mXTextExtents24m and 4mXTextExtents1624m functions perform the size computation locally and, thereby, avoid the round-trip overhead of 4mXQueryTextExtents24m and 4mXQueryTextExtents1624m. Both functions return an 4mXCharStruct24m structure, whose members are set to the values as follows. The ascent member is set to the maximum of the ascent met- rics of all characters in the string. The descent member is set to the maximum of the descent metrics. The width member is set to the sum of the character-width metrics of all characters in the string. For each character in the string, let W be the sum of the character-width metrics of all char- acters preceding it in the string. Let L be the left-side- bearing metric of the character plus W. Let R be the right- side-bearing metric of the character plus W. The lbearing member is set to the minimum L of all characters in the string. The rbearing member is set to the maximum R. 1m2510m 1mXlib C Library X11, Release 6.9/7.00m For fonts defined with linear indexing rather than 2-byte matrix indexing, each 4mXChar2b24m structure is interpreted as a 16-bit number with byte1 as the most significant byte. If the font has no defined default character, undefined charac- ters in the string are taken to have all zero metrics. 1m8.5.5. Querying Character String Sizes0m To query the server for the bounding box of an 8-bit charac- ter string in a given font, use 4mXQueryTextExtents24m. __ XQueryTextExtents(4mdisplay24m, 4mfont_ID24m, 4mstring24m, 4mnchars24m, 4mdirection_return24m, 4mfont_ascent_return24m, 4mfont_descent_return24m, 4moverall_return24m) Display *4mdisplay24m; XID 4mfont_ID24m; char *4mstring24m; int 4mnchars24m; int *4mdirection_return24m; int *4mfont_ascent_return24m, *4mfont_descent_return24m; XCharStruct *4moverall_return24m; 4mdisplay24m Specifies the connection to the X server. 4mfont_ID24m Specifies either the font ID or the 4mGContext24m ID that contains the font. 4mstring24m Specifies the character string. 4mnchars24m Specifies the number of characters in the charac- ter string. 4mdirection_return0m Returns the value of the direction hint (4mFontLeft-0m 4mToRight24m or 4mFontRightToLeft24m). 4mfont_ascent_return0m Returns the font ascent. 4mfont_descent_return0m Returns the font descent. 4moverall_return0m Returns the overall size in the specified 4mXCharStruct24m structure. __ To query the server for the bounding box of a 2-byte charac- ter string in a given font, use 4mXQueryTextExtents1624m. 1m2520m 1mXlib C Library X11, Release 6.9/7.00m __ XQueryTextExtents16(4mdisplay24m, 4mfont_ID24m, 4mstring24m, 4mnchars24m, 4mdirection_return24m, 4mfont_ascent_return24m, 4mfont_descent_return24m, 4moverall_return24m) Display *4mdisplay24m; XID 4mfont_ID24m; XChar2b *4mstring24m; int 4mnchars24m; int *4mdirection_return24m; int *4mfont_ascent_return24m, *4mfont_descent_return24m; XCharStruct *4moverall_return24m; 4mdisplay24m Specifies the connection to the X server. 4mfont_ID24m Specifies either the font ID or the 4mGContext24m ID that contains the font. 4mstring24m Specifies the character string. 4mnchars24m Specifies the number of characters in the charac- ter string. 4mdirection_return0m Returns the value of the direction hint (4mFontLeft-0m 4mToRight24m or 4mFontRightToLeft24m). 4mfont_ascent_return0m Returns the font ascent. 4mfont_descent_return0m Returns the font descent. 4moverall_return0m Returns the overall size in the specified 4mXCharStruct24m structure. __ The 4mXQueryTextExtents24m and 4mXQueryTextExtents1624m functions return the bounding box of the specified 8-bit and 16-bit character string in the specified font or the font contained in the specified GC. These functions query the X server and, therefore, suffer the round-trip overhead that is avoided by 4mXTextExtents24m and 4mXTextExtents1624m. Both functions return a 4mXCharStruct24m structure, whose members are set to the values as follows. The ascent member is set to the maximum of the ascent met- rics of all characters in the string. The descent member is set to the maximum of the descent metrics. The width member is set to the sum of the character-width metrics of all characters in the string. For each character in the string, let W be the sum of the character-width metrics of all char- acters preceding it in the string. Let L be the left-side- bearing metric of the character plus W. Let R be the right- 1m2530m 1mXlib C Library X11, Release 6.9/7.00m side-bearing metric of the character plus W. The lbearing member is set to the minimum L of all characters in the string. The rbearing member is set to the maximum R. For fonts defined with linear indexing rather than 2-byte matrix indexing, each 4mXChar2b24m structure is interpreted as a 16-bit number with byte1 as the most significant byte. If the font has no defined default character, undefined charac- ters in the string are taken to have all zero metrics. Characters with all zero metrics are ignored. If the font has no defined default_char, the undefined characters in the string are also ignored. 4mXQueryTextExtents24m and 4mXQueryTextExtents1624m can generate 4mBad-0m 4mFont24m and 4mBadGC24m errors. 1m8.6. Drawing Text0m This section discusses how to draw: Complex text Text characters Image text characters The fundamental text functions 4mXDrawText24m and 4mXDrawText1624m use the following structures: __ typedef struct { char *chars; /* pointer to string */ int nchars; /* number of characters */ int delta; /* delta between strings */ Font font; /* Font to print it in, None dont change */ } XTextItem; typedef struct { XChar2b *chars; /* pointer to two-byte characters */ int nchars; /* number of characters */ int delta; /* delta between strings */ Font font; /* font to print it in, None dont change */ } XTextItem16; __ If the font member is not 4mNone24m, the font is changed before printing and also is stored in the GC. If an error was gen- erated during text drawing, the previous items may have been drawn. The baseline of the characters are drawn starting at 1m2540m 1mXlib C Library X11, Release 6.9/7.00m the x and y coordinates that you pass in the text drawing functions. For example, consider the background rectangle drawn by 4mXDrawImageString24m. If you want the upper-left corner of the background rectangle to be at pixel coordinate (x,y), pass the (x,y + ascent) as the baseline origin coordinates to the text functions. The ascent is the font ascent, as given in the 4mXFontStruct24m structure. If you want the lower-left cor- ner of the background rectangle to be at pixel coordinate (x,y), pass the (x,y descent + 1) as the baseline origin coordinates to the text functions. The descent is the font descent, as given in the 4mXFontStruct24m structure. 1m8.6.1. Drawing Complex Text0m To draw 8-bit characters in a given drawable, use 4mXDrawText24m. __ XDrawText(4mdisplay24m, 4md24m, 4mgc24m, 4mx24m, 4my24m, 4mitems24m, 4mnitems24m) Display *4mdisplay24m; Drawable 4md24m; GC 4mgc24m; int 4mx24m, 4my24m; XTextItem *4mitems24m; int 4mnitems24m; 4mdisplay24m Specifies the connection to the X server. 4md24m Specifies the drawable. 4mgc24m Specifies the GC. 4mx0m 4my24m Specify the x and y coordinates, which are rela- tive to the origin of the specified drawable and define the origin of the first character. 4mitems24m Specifies an array of text items. 4mnitems24m Specifies the number of text items in the array. __ To draw 2-byte characters in a given drawable, use 4mXDraw-0m 4mText1624m. 1m2550m 1mXlib C Library X11, Release 6.9/7.00m __ XDrawText16(4mdisplay24m, 4md24m, 4mgc24m, 4mx24m, 4my24m, 4mitems24m, 4mnitems24m) Display *4mdisplay24m; Drawable 4md24m; GC 4mgc24m; int 4mx24m, 4my24m; XTextItem16 *4mitems24m; int 4mnitems24m; 4mdisplay24m Specifies the connection to the X server. 4md24m Specifies the drawable. 4mgc24m Specifies the GC. 4mx0m 4my24m Specify the x and y coordinates, which are rela- tive to the origin of the specified drawable and define the origin of the first character. 4mitems24m Specifies an array of text items. 4mnitems24m Specifies the number of text items in the array. __ The 4mXDrawText1624m function is similar to 4mXDrawText24m except that it uses 2-byte or 16-bit characters. Both functions allow complex spacing and font shifts between counted strings. Each text item is processed in turn. A font member other than 4mNone24m in an item causes the font to be stored in the GC and used for subsequent text. A text element delta speci- fies an additional change in the position along the x axis before the string is drawn. The delta is always added to the character origin and is not dependent on any character- istics of the font. Each character image, as defined by the font in the GC, is treated as an additional mask for a fill operation on the drawable. The drawable is modified only where the font character has a bit set to 1. If a text item generates a 4mBadFont24m error, the previous text items may have been drawn. For fonts defined with linear indexing rather than 2-byte matrix indexing, each 4mXChar2b24m structure is interpreted as a 16-bit number with byte1 as the most significant byte. Both functions use these GC components: function, plane- mask, fill-style, font, subwindow-mode, clip-x-origin, clip- y-origin, and clip-mask. They also use these GC mode-depen- dent components: foreground, background, tile, stipple, tile-stipple-x-origin, and tile-stipple-y-origin. 1m2560m 1mXlib C Library X11, Release 6.9/7.00m 4mXDrawText24m and 4mXDrawText1624m can generate 4mBadDrawable24m, 4mBadFont24m, 4mBadGC24m, and 4mBadMatch24m errors. 1m8.6.2. Drawing Text Characters0m To draw 8-bit characters in a given drawable, use 4mXDraw-0m 4mString24m. __ XDrawString(4mdisplay24m, 4md24m, 4mgc24m, 4mx24m, 4my24m, 4mstring24m, 4mlength24m) Display *4mdisplay24m; Drawable 4md24m; GC 4mgc24m; int 4mx24m, 4my24m; char *4mstring24m; int 4mlength24m; 4mdisplay24m Specifies the connection to the X server. 4md24m Specifies the drawable. 4mgc24m Specifies the GC. 4mx0m 4my24m Specify the x and y coordinates, which are rela- tive to the origin of the specified drawable and define the origin of the first character. 4mstring24m Specifies the character string. 4mlength24m Specifies the number of characters in the string argument. __ To draw 2-byte characters in a given drawable, use 4mXDraw-0m 4mString1624m. 1m2570m 1mXlib C Library X11, Release 6.9/7.00m __ XDrawString16(4mdisplay24m, 4md24m, 4mgc24m, 4mx24m, 4my24m, 4mstring24m, 4mlength24m) Display *4mdisplay24m; Drawable 4md24m; GC 4mgc24m; int 4mx24m, 4my24m; XChar2b *4mstring24m; int 4mlength24m; 4mdisplay24m Specifies the connection to the X server. 4md24m Specifies the drawable. 4mgc24m Specifies the GC. 4mx0m 4my24m Specify the x and y coordinates, which are rela- tive to the origin of the specified drawable and define the origin of the first character. 4mstring24m Specifies the character string. 4mlength24m Specifies the number of characters in the string argument. __ Each character image, as defined by the font in the GC, is treated as an additional mask for a fill operation on the drawable. The drawable is modified only where the font character has a bit set to 1. For fonts defined with 2-byte matrix indexing and used with 4mXDrawString1624m, each byte is used as a byte2 with a byte1 of zero. Both functions use these GC components: function, plane- mask, fill-style, font, subwindow-mode, clip-x-origin, clip- y-origin, and clip-mask. They also use these GC mode-depen- dent components: foreground, background, tile, stipple, tile-stipple-x-origin, and tile-stipple-y-origin. 4mXDrawString24m and 4mXDrawString1624m can generate 4mBadDrawable24m, 4mBadGC24m, and 4mBadMatch24m errors. 1m8.6.3. Drawing Image Text Characters0m Some applications, in particular terminal emulators, need to print image text in which both the foreground and background bits of each character are painted. This prevents annoying flicker on many displays. To draw 8-bit image text characters in a given drawable, use 4mXDrawImageString24m. 1m2580m 1mXlib C Library X11, Release 6.9/7.00m __ XDrawImageString(4mdisplay24m, 4md24m, 4mgc24m, 4mx24m, 4my24m, 4mstring24m, 4mlength24m) Display *4mdisplay24m; Drawable 4md24m; GC 4mgc24m; int 4mx24m, 4my24m; char *4mstring24m; int 4mlength24m; 4mdisplay24m Specifies the connection to the X server. 4md24m Specifies the drawable. 4mgc24m Specifies the GC. 4mx0m 4my24m Specify the x and y coordinates, which are rela- tive to the origin of the specified drawable and define the origin of the first character. 4mstring24m Specifies the character string. 4mlength24m Specifies the number of characters in the string argument. __ To draw 2-byte image text characters in a given drawable, use 4mXDrawImageString1624m. 1m2590m 1mXlib C Library X11, Release 6.9/7.00m __ XDrawImageString16(4mdisplay24m, 4md24m, 4mgc24m, 4mx24m, 4my24m, 4mstring24m, 4mlength24m) Display *4mdisplay24m; Drawable 4md24m; GC 4mgc24m; int 4mx24m, 4my24m; XChar2b *4mstring24m; int 4mlength24m; 4mdisplay24m Specifies the connection to the X server. 4md24m Specifies the drawable. 4mgc24m Specifies the GC. 4mx0m 4my24m Specify the x and y coordinates, which are rela- tive to the origin of the specified drawable and define the origin of the first character. 4mstring24m Specifies the character string. 4mlength24m Specifies the number of characters in the string argument. __ The 4mXDrawImageString1624m function is similar to 4mXDrawIm-0m 4mageString24m except that it uses 2-byte or 16-bit characters. Both functions also use both the foreground and background pixels of the GC in the destination. The effect is first to fill a destination rectangle with the background pixel defined in the GC and then to paint the text with the foreground pixel. The upper-left corner of the filled rectangle is at: [x, y font-ascent] The width is: overall-width The height is: font-ascent + font-descent 1m2600m 1mXlib C Library X11, Release 6.9/7.00m The overall-width, font-ascent, and font-descent are as would be returned by 4mXQueryTextExtents24m using gc and string. The function and fill-style defined in the GC are ignored for these functions. The effective function is 4mGXcopy24m, and the effective fill-style is 4mFillSolid24m. For fonts defined with 2-byte matrix indexing and used with 4mXDrawImageString24m, each byte is used as a byte2 with a byte1 of zero. Both functions use these GC components: plane-mask, fore- ground, background, font, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. 4mXDrawImageString24m and 4mXDrawImageString1624m can generate 4mBad-0m 4mDrawable24m, 4mBadGC24m, and 4mBadMatch24m errors. 1m8.7. Transferring Images between Client and Server0m Xlib provides functions that you can use to transfer images between a client and the server. Because the server may require diverse data formats, Xlib provides an image object that fully describes the data in memory and that provides for basic operations on that data. You should reference the data through the image object rather than referencing the data directly. However, some implementations of the Xlib library may efficiently deal with frequently used data for- mats by replacing functions in the procedure vector with special case functions. Supported operations include destroying the image, getting a pixel, storing a pixel, extracting a subimage of an image, and adding a constant to an image (see section 16.8). All the image manipulation functions discussed in this sec- tion make use of the 4mXImage24m structure, which describes an image as it exists in the clients memory. 1m2610m 1mXlib C Library X11, Release 6.9/7.00m __ typedef struct _XImage { int width, height; /* size of image */ int xoffset; /* number of pixels offset in X direction */ int format; /* XYBitmap, XYPixmap, ZPixmap */ char *data; /* pointer to image data */ int byte_order; /* data byte order, LSBFirst, MSBFirst */ int bitmap_unit; /* quant. of scanline 8, 16, 32 */ int bitmap_bit_order; /* LSBFirst, MSBFirst */ int bitmap_pad; /* 8, 16, 32 either XY or ZPixmap */ int depth; /* depth of image */ int bytes_per_line; /* accelerator to next scanline */ int bits_per_pixel; /* bits per pixel (ZPixmap) */ unsigned long red_mask; /* bits in z arrangement */ unsigned long green_mask; unsigned long blue_mask; XPointer obdata; /* hook for the object routines to hang on */ struct funcs { /* image manipulation routines */ struct _XImage *(*create_image)(); int (*destroy_image)(); unsigned long (*get_pixel)(); int (*put_pixel)(); struct _XImage *(*sub_image)(); int (*add_pixel)(); } f; } XImage; __ To initialize the image manipulation routines of an image structure, use 4mXInitImage24m. __ Status XInitImage(4mimage24m) XImage *4mimage24m; 4mximage24m Specifies the image. __ The 4mXInitImage24m function initializes the internal image manipulation routines of an image structure, based on the values of the various structure members. All fields other than the manipulation routines must already be initialized. If the bytes_per_line member is zero, 4mXInitImage24m will assume the image data is contiguous in memory and set the bytes_per_line member to an appropriate value based on the other members; otherwise, the value of bytes_per_line is not changed. All of the manipulation routines are initialized to functions that other Xlib image manipulation functions need to operate on the type of image specified by the rest of the structure. 1m2620m 1mXlib C Library X11, Release 6.9/7.00m This function must be called for any image constructed by the client before passing it to any other Xlib function. Image structures created or returned by Xlib do not need to be initialized in this fashion. This function returns a nonzero status if initialization of the structure is successful. It returns zero if it detected some error or inconsistency in the structure, in which case the image is not changed. To combine an image with a rectangle of a drawable on the display, use 4mXPutImage24m. __ XPutImage(4mdisplay24m, 4md24m, 4mgc24m, 4mimage24m, 4msrc_x24m, 4msrc_y24m, 4mdest_x24m, 4mdest_y24m, 4mwidth24m, 4mheight24m) Display *4mdisplay24m; Drawable 4md24m; GC 4mgc24m; XImage *4mimage24m; int 4msrc_x24m, 4msrc_y24m; int 4mdest_x24m, 4mdest_y24m; unsigned int 4mwidth24m, 4mheight24m; 4mdisplay24m Specifies the connection to the X server. 4md24m Specifies the drawable. 4mgc24m Specifies the GC. 4mimage24m Specifies the image you want combined with the rectangle. 4msrc_x24m Specifies the offset in X from the left edge of the image defined by the 4mXImage24m structure. 4msrc_y24m Specifies the offset in Y from the top edge of the image defined by the 4mXImage24m structure. 4mdest_x0m 4mdest_y24m Specify the x and y coordinates, which are rela- tive to the origin of the drawable and are the coordinates of the subimage. 4mwidth0m 4mheight24m Specify the width and height of the subimage, which define the dimensions of the rectangle. __ The 4mXPutImage24m function combines an image with a rectangle of the specified drawable. The section of the image defined by the src_x, src_y, width, and height arguments is drawn on the specified part of the drawable. If 4mXYBitmap24m format is 1m2630m 1mXlib C Library X11, Release 6.9/7.00m used, the depth of the image must be one, or a 4mBadMatch0m error results. The foreground pixel in the GC defines the source for the one bits in the image, and the background pixel defines the source for the zero bits. For 4mXYPixmap0m and 4mZPixmap24m, the depth of the image must match the depth of the drawable, or a 4mBadMatch24m error results. If the characteristics of the image (for example, byte_order and bitmap_unit) differ from what the server requires, 4mXPutImage24m automatically makes the appropriate conversions. This function uses these GC components: function, plane- mask, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. It also uses these GC mode-dependent components: foreground and background. 4mXPutImage24m can generate 4mBadDrawable24m, 4mBadGC24m, 4mBadMatch24m, and 4mBadValue24m errors. To return the contents of a rectangle in a given drawable on the display, use 4mXGetImage24m. This function specifically sup- ports rudimentary screen dumps. 1m2640m 1mXlib C Library X11, Release 6.9/7.00m __ XImage *XGetImage(4mdisplay24m, 4md24m, 4mx24m, 4my24m, 4mwidth24m, 4mheight24m, 4mplane_mask24m, 4mformat24m) Display *4mdisplay24m; Drawable 4md24m; int 4mx24m, 4my24m; unsigned int 4mwidth24m, 4mheight24m; unsigned long 4mplane_mask24m; int 4mformat24m; 4mdisplay24m Specifies the connection to the X server. 4md24m Specifies the drawable. 4mx0m 4my24m Specify the x and y coordinates, which are rela- tive to the origin of the drawable and define the upper-left corner of the rectangle. 4mwidth0m 4mheight24m Specify the width and height of the subimage, which define the dimensions of the rectangle. 4mplane_mask0m Specifies the plane mask. 4mformat24m Specifies the format for the image. You can pass 4mXYPixmap24m or 4mZPixmap24m. __ The 4mXGetImage24m function returns a pointer to an 4mXImage24m struc- ture. This structure provides you with the contents of the specified rectangle of the drawable in the format you spec- ify. If the format argument is 4mXYPixmap24m, the image contains only the bit planes you passed to the plane_mask argument. If the plane_mask argument only requests a subset of the planes of the display, the depth of the returned image will be the number of planes requested. If the format argument is 4mZPixmap24m, 4mXGetImage24m returns as zero the bits in all planes not specified in the plane_mask argument. The function per- forms no range checking on the values in plane_mask and ignores extraneous bits. 4mXGetImage24m returns the depth of the image to the depth member of the 4mXImage24m structure. The depth of the image is as spec- ified when the drawable was created, except when getting a subset of the planes in 4mXYPixmap24m format, when the depth is given by the number of bits set to 1 in plane_mask. If the drawable is a pixmap, the given rectangle must be wholly contained within the pixmap, or a 4mBadMatch24m error results. If the drawable is a window, the window must be viewable, and it must be the case that if there were no inferiors or overlapping windows, the specified rectangle of 1m2650m 1mXlib C Library X11, Release 6.9/7.00m the window would be fully visible on the screen and wholly contained within the outside edges of the window, or a 4mBad-0m 4mMatch24m error results. Note that the borders of the window can be included and read with this request. If the window has backing-store, the backing-store contents are returned for regions of the window that are obscured by noninferior windows. If the window does not have backing-store, the returned contents of such obscured regions are undefined. The returned contents of visible regions of inferiors of a different depth than the specified windows depth are also undefined. The pointer cursor image is not included in the returned contents. If a problem occurs, 4mXGetImage24m returns NULL. 4mXGetImage24m can generate 4mBadDrawable24m, 4mBadMatch24m, and 4mBadValue0m errors. To copy the contents of a rectangle on the display to a location within a preexisting image structure, use 4mXGet-0m 4mSubImage24m. 1m2660m 1mXlib C Library X11, Release 6.9/7.00m __ XImage *XGetSubImage(4mdisplay24m, 4md24m, 4mx24m, 4my24m, 4mwidth24m, 4mheight24m, 4mplane_mask24m, 4mformat24m, 4mdest_image24m, 4mdest_x24m, 4mdest_y24m) Display *4mdisplay24m; Drawable 4md24m; int 4mx24m, 4my24m; unsigned int 4mwidth24m, 4mheight24m; unsigned long 4mplane_mask24m; int 4mformat24m; XImage *4mdest_image24m; int 4mdest_x24m, 4mdest_y24m; 4mdisplay24m Specifies the connection to the X server. 4md24m Specifies the drawable. 4mx0m 4my24m Specify the x and y coordinates, which are rela- tive to the origin of the drawable and define the upper-left corner of the rectangle. 4mwidth0m 4mheight24m Specify the width and height of the subimage, which define the dimensions of the rectangle. 4mplane_mask0m Specifies the plane mask. 4mformat24m Specifies the format for the image. You can pass 4mXYPixmap24m or 4mZPixmap24m. 4mdest_image0m Specifies the destination image. 4mdest_x0m 4mdest_y24m Specify the x and y coordinates, which are rela- tive to the origin of the destination rectangle, specify its upper-left corner, and determine where the subimage is placed in the destination image. __ The 4mXGetSubImage24m function updates dest_image with the speci- fied subimage in the same manner as 4mXGetImage24m. If the for- mat argument is 4mXYPixmap24m, the image contains only the bit planes you passed to the plane_mask argument. If the format argument is 4mZPixmap24m, 4mXGetSubImage24m returns as zero the bits in all planes not specified in the plane_mask argument. The function performs no range checking on the values in plane_mask and ignores extraneous bits. As a convenience, 4mXGetSubImage24m returns a pointer to the same 4mXImage24m structure specified by dest_image. 1m2670m 1mXlib C Library X11, Release 6.9/7.00m The depth of the destination 4mXImage24m structure must be the same as that of the drawable. If the specified subimage does not fit at the specified location on the destination image, the right and bottom edges are clipped. If the draw- able is a pixmap, the given rectangle must be wholly con- tained within the pixmap, or a 4mBadMatch24m error results. If the drawable is a window, the window must be viewable, and it must be the case that if there were no inferiors or over- lapping windows, the specified rectangle of the window would be fully visible on the screen and wholly contained within the outside edges of the window, or a 4mBadMatch24m error results. If the window has backing-store, then the backing- store contents are returned for regions of the window that are obscured by noninferior windows. If the window does not have backing-store, the returned contents of such obscured regions are undefined. The returned contents of visible regions of inferiors of a different depth than the specified windows depth are also undefined. If a problem occurs, 4mXGetSubImage24m returns NULL. 4mXGetSubImage24m can generate 4mBadDrawable24m, 4mBadGC24m, 4mBadMatch24m, and 4mBadValue24m errors. 1m2680m 1mXlib C Library X11, Release 6.9/7.00m 1mChapter 90m 1mWindow and Session Manager Functions0m Although it is difficult to categorize functions as exclu- sively for an application, a window manager, or a session manager, the functions in this chapter are most often used by window managers and session managers. It is not expected that these functions will be used by most application pro- grams. Xlib provides management functions to: Change the parent of a window Control the lifetime of a window Manage installed colormaps Set and retrieve the font search path Grab the server Kill a client Control the screen saver Control host access 1m9.1. Changing the Parent of a Window0m To change a windows parent to another window on the same screen, use 4mXReparentWindow24m. There is no way to move a win- dow between screens. 1m2690m 1mXlib C Library X11, Release 6.9/7.00m __ XReparentWindow(4mdisplay24m, 4mw24m, 4mparent24m, 4mx24m, 4my24m) Display *4mdisplay24m; Window 4mw24m; Window 4mparent24m; int 4mx24m, 4my24m; 4mdisplay24m Specifies the connection to the X server. 4mw24m Specifies the window. 4mparent24m Specifies the parent window. 4mx0m 4my24m Specify the x and y coordinates of the position in the new parent window. __ If the specified window is mapped, 4mXReparentWindow24m automati- cally performs an 4mUnmapWindow24m request on it, removes it from its current position in the hierarchy, and inserts it as the child of the specified parent. The window is placed in the stacking order on top with respect to sibling windows. After reparenting the specified window, 4mXReparentWindow0m causes the X server to generate a 4mReparentNotify24m event. The override_redirect member returned in this event is set to the windows corresponding attribute. Window manager clients usually should ignore this window if this member is set to 4mTrue24m. Finally, if the specified window was origi- nally mapped, the X server automatically performs a 4mMapWin-0m 4mdow24m request on it. The X server performs normal exposure processing on formerly obscured windows. The X server might not generate 4mExpose0m events for regions from the initial 4mUnmapWindow24m request that are immediately obscured by the final 4mMapWindow24m request. A 4mBadMatch24m error results if: The new parent window is not on the same screen as the old parent window. The new parent window is the specified window or an inferior of the specified window. The new parent is 4mInputOnly24m, and the window is not. The specified window has a 4mParentRelative24m background, and the new parent window is not the same depth as the specified window. 4mXReparentWindow24m can generate 4mBadMatch24m and 4mBadWindow24m errors. 1m2700m 1mXlib C Library X11, Release 6.9/7.00m 1m9.2. Controlling the Lifetime of a Window0m The save-set of a client is a list of other clients windows that, if they are inferiors of one of the clients windows at connection close, should not be destroyed and should be remapped if they are unmapped. For further information about close-connection processing, see section 2.6. To allow an applications window to survive when a window man- ager that has reparented a window fails, Xlib provides the save-set functions that you can use to control the longevity of subwindows that are normally destroyed when the parent is destroyed. For example, a window manager that wants to add decoration to a window by adding a frame might reparent an applications window. When the frame is destroyed, the applications window should not be destroyed but be returned to its previous place in the window hierarchy. The X server automatically removes windows from the save-set when they are destroyed. To add or remove a window from the clients save-set, use 4mXChangeSaveSet24m. __ XChangeSaveSet(4mdisplay24m, 4mw24m, 4mchange_mode24m) Display *4mdisplay24m; Window 4mw24m; int 4mchange_mode24m; 4mdisplay24m Specifies the connection to the X server. 4mw24m Specifies the window that you want to add to or delete from the clients save-set. 4mchange_mode0m Specifies the mode. You can pass 4mSetModeInsert24m or 4mSetModeDelete24m. __ Depending on the specified mode, 4mXChangeSaveSet24m either inserts or deletes the specified window from the clients save-set. The specified window must have been created by some other client, or a 4mBadMatch24m error results. 4mXChangeSaveSet24m can generate 4mBadMatch24m, 4mBadValue24m, and 4mBadWin-0m 4mdow24m errors. To add a window to the clients save-set, use 4mXAddToSaveSet24m. 1m2710m 1mXlib C Library X11, Release 6.9/7.00m __ XAddToSaveSet(4mdisplay24m, 4mw24m) Display *4mdisplay24m; Window 4mw24m; 4mdisplay24m Specifies the connection to the X server. 4mw24m Specifies the window that you want to add to the clients save-set. __ The 4mXAddToSaveSet24m function adds the specified window to the clients save-set. The specified window must have been cre- ated by some other client, or a 4mBadMatch24m error results. 4mXAddToSaveSet24m can generate 4mBadMatch24m and 4mBadWindow24m errors. To remove a window from the clients save-set, use 4mXRemove-0m 4mFromSaveSet24m. __ XRemoveFromSaveSet(4mdisplay24m, 4mw24m) Display *4mdisplay24m; Window 4mw24m; 4mdisplay24m Specifies the connection to the X server. 4mw24m Specifies the window that you want to delete from the clients save-set. __ The 4mXRemoveFromSaveSet24m function removes the specified window from the clients save-set. The specified window must have been created by some other client, or a 4mBadMatch24m error results. 4mXRemoveFromSaveSet24m can generate 4mBadMatch24m and 4mBadWindow0m errors. 1m9.3. Managing Installed Colormaps0m The X server maintains a list of installed colormaps. Win- dows using these colormaps are guaranteed to display with correct colors; windows using other colormaps may or may not display with correct colors. Xlib provides functions that you can use to install a colormap, uninstall a colormap, and obtain a list of installed colormaps. At any time, there is a subset of the installed maps that is viewed as an ordered list and is called the required list. The length of the required list is at most M, where M is the 1m2720m 1mXlib C Library X11, Release 6.9/7.00m minimum number of installed colormaps specified for the screen in the connection setup. The required list is main- tained as follows. When a colormap is specified to 4mXIn-0m 4mstallColormap24m, it is added to the head of the list; the list is truncated at the tail, if necessary, to keep its length to at most M. When a colormap is specified to 4mXUninstall-0m 4mColormap24m and it is in the required list, it is removed from the list. A colormap is not added to the required list when it is implicitly installed by the X server, and the X server cannot implicitly uninstall a colormap that is in the required list. To install a colormap, use 4mXInstallColormap24m. __ XInstallColormap(4mdisplay24m, 4mcolormap24m) Display *4mdisplay24m; Colormap 4mcolormap24m; 4mdisplay24m Specifies the connection to the X server. 4mcolormap24m Specifies the colormap. __ The 4mXInstallColormap24m function installs the specified col- ormap for its associated screen. All windows associated with this colormap immediately display with true colors. You associated the windows with this colormap when you cre- ated them by calling 4mXCreateWindow24m, 4mXCreateSimpleWindow24m, 4mXChangeWindowAttributes24m, or 4mXSetWindowColormap24m. If the specified colormap is not already an installed col- ormap, the X server generates a 4mColormapNotify24m event on each window that has that colormap. In addition, for every other colormap that is installed as a result of a call to 4mXIn-0m 4mstallColormap24m, the X server generates a 4mColormapNotify24m event on each window that has that colormap. 4mXInstallColormap24m can generate a 4mBadColor24m error. To uninstall a colormap, use 4mXUninstallColormap24m. 1m2730m 1mXlib C Library X11, Release 6.9/7.00m __ XUninstallColormap(4mdisplay24m, 4mcolormap24m) Display *4mdisplay24m; Colormap 4mcolormap24m; 4mdisplay24m Specifies the connection to the X server. 4mcolormap24m Specifies the colormap. __ The 4mXUninstallColormap24m function removes the specified col- ormap from the required list for its screen. As a result, the specified colormap might be uninstalled, and the X server might implicitly install or uninstall additional col- ormaps. Which colormaps get installed or uninstalled is server dependent except that the required list must remain installed. If the specified colormap becomes uninstalled, the X server generates a 4mColormapNotify24m event on each window that has that colormap. In addition, for every other colormap that is installed or uninstalled as a result of a call to 4mXUnin-0m 4mstallColormap24m, the X server generates a 4mColormapNotify24m event on each window that has that colormap. 4mXUninstallColormap24m can generate a 4mBadColor24m error. To obtain a list of the currently installed colormaps for a given screen, use 4mXListInstalledColormaps24m. __ Colormap *XListInstalledColormaps(4mdisplay24m, 4mw24m, 4mnum_return24m) Display *4mdisplay24m; Window 4mw24m; int *4mnum_return24m; 4mdisplay24m Specifies the connection to the X server. 4mw24m Specifies the window that determines the screen. 4mnum_return0m Returns the number of currently installed col- ormaps. __ The 4mXListInstalledColormaps24m function returns a list of the currently installed colormaps for the screen of the speci- fied window. The order of the colormaps in the list is not significant and is no explicit indication of the required list. When the allocated list is no longer needed, free it by using 4mXFree24m. 1m2740m 1mXlib C Library X11, Release 6.9/7.00m 4mXListInstalledColormaps24m can generate a 4mBadWindow24m error. 1m9.4. Setting and Retrieving the Font Search Path0m The set of fonts available from a server depends on a font search path. Xlib provides functions to set and retrieve the search path for a server. To set the font search path, use 4mXSetFontPath24m. __ XSetFontPath(4mdisplay24m, 4mdirectories24m, 4mndirs24m) Display *4mdisplay24m; char **4mdirectories24m; int 4mndirs24m; 4mdisplay24m Specifies the connection to the X server. 4mdirectories0m Specifies the directory path used to look for a font. Setting the path to the empty list restores the default path defined for the X server. 4mndirs24m Specifies the number of directories in the path. __ The 4mXSetFontPath24m function defines the directory search path for font lookup. There is only one search path per X server, not one per client. The encoding and interpretation of the strings are implementation-dependent, but typically they specify directories or font servers to be searched in the order listed. An X server is permitted to cache font information internally; for example, it might cache an entire font from a file and not check on subsequent opens of that font to see if the underlying font file has changed. However, when the font path is changed, the X server is guaranteed to flush all cached information about fonts for which there currently are no explicit resource IDs allo- cated. The meaning of an error from this request is imple- mentation-dependent. 4mXSetFontPath24m can generate a 4mBadValue24m error. To get the current font search path, use 4mXGetFontPath24m. 1m2750m 1mXlib C Library X11, Release 6.9/7.00m __ char **XGetFontPath(4mdisplay24m, 4mnpaths_return24m) Display *4mdisplay24m; int *4mnpaths_return24m; 4mdisplay24m Specifies the connection to the X server. 4mnpaths_return0m Returns the number of strings in the font path array. __ The 4mXGetFontPath24m function allocates and returns an array of strings containing the search path. The contents of these strings are implementation-dependent and are not intended to be interpreted by client applications. When it is no longer needed, the data in the font path should be freed by using 4mXFreeFontPath24m. To free data returned by 4mXGetFontPath24m, use 4mXFreeFontPath24m. __ XFreeFontPath(4mlist24m) char **4mlist24m; 4mlist24m Specifies the array of strings you want to free. __ The 4mXFreeFontPath24m function frees the data allocated by 4mXGet-0m 4mFontPath24m. 1m9.5. Grabbing the Server0m Xlib provides functions that you can use to grab and ungrab the server. These functions can be used to control process- ing of output on other connections by the window system server. While the server is grabbed, no processing of requests or close downs on any other connection will occur. A client closing its connection automatically ungrabs the server. Although grabbing the server is highly discouraged, it is sometimes necessary. To grab the server, use 4mXGrabServer24m. 1m2760m 1mXlib C Library X11, Release 6.9/7.00m __ XGrabServer(4mdisplay24m) Display *4mdisplay24m; 4mdisplay24m Specifies the connection to the X server. __ The 4mXGrabServer24m function disables processing of requests and close downs on all other connections than the one this request arrived on. You should not grab the X server any more than is absolutely necessary. To ungrab the server, use 4mXUngrabServer24m. __ XUngrabServer(4mdisplay24m) Display *4mdisplay24m; 4mdisplay24m Specifies the connection to the X server. __ The 4mXUngrabServer24m function restarts processing of requests and close downs on other connections. You should avoid grabbing the X server as much as possible. 1m9.6. Killing Clients0m Xlib provides a function to cause the connection to a client to be closed and its resources to be destroyed. To destroy a client, use 4mXKillClient24m. __ XKillClient(4mdisplay24m, 4mresource24m) Display *4mdisplay24m; XID 4mresource24m; 4mdisplay24m Specifies the connection to the X server. 4mresource24m Specifies any resource associated with the client that you want to destroy or 4mAllTemporary24m. __ The 4mXKillClient24m function forces a close down of the client that created the resource if a valid resource is specified. If the client has already terminated in either 4mRetainPerma-0m 4mnent24m or 4mRetainTemporary24m mode, all of the clients resources are destroyed. If 4mAllTemporary24m is specified, the resources of all clients that have terminated in 4mRetainTemporary24m are destroyed (see section 2.5). This permits implementation of window manager facilities that aid debugging. A client can 1m2770m 1mXlib C Library X11, Release 6.9/7.00m set its close-down mode to 4mRetainTemporary24m. If the client then crashes, its windows would not be destroyed. The pro- grammer can then inspect the applications window tree and use the window manager to destroy the zombie windows. 4mXKillClient24m can generate a 4mBadValue24m error. 1m9.7. Controlling the Screen Saver0m Xlib provides functions that you can use to set or reset the mode of the screen saver, to force or activate the screen saver, or to obtain the current screen saver values. To set the screen saver mode, use 4mXSetScreenSaver24m. __ XSetScreenSaver(4mdisplay24m, 4mtimeout24m, 4minterval24m, 4mprefer_blanking24m, 4mallow_exposures24m) Display *4mdisplay24m; int 4mtimeout24m, 4minterval24m; int 4mprefer_blanking24m; int 4mallow_exposures24m; 4mdisplay24m Specifies the connection to the X server. 4mtimeout24m Specifies the timeout, in seconds, until the screen saver turns on. 4minterval24m Specifies the interval, in seconds, between screen saver alterations. 4mprefer_blanking0m Specifies how to enable screen blanking. You can pass 4mDontPreferBlanking24m, 4mPreferBlanking24m, or 4mDefaultBlanking24m. 4mallow_exposures0m Specifies the screen save control values. You can pass 4mDontAllowExposures24m, 4mAllowExposures24m, or 4mDefaultExposures24m. __ Timeout and interval are specified in seconds. A timeout of 0 disables the screen saver (but an activated screen saver is not deactivated), and a timeout of 1 restores the default. Other negative values generate a 4mBadValue24m error. If the timeout value is nonzero, 4mXSetScreenSaver24m enables the screen saver. An interval of 0 disables the random-pattern motion. If no input from devices (keyboard, mouse, and so on) is generated for the specified number of timeout seconds once the screen saver is enabled, the screen saver is acti- vated. 1m2780m 1mXlib C Library X11, Release 6.9/7.00m For each screen, if blanking is preferred and the hardware supports video blanking, the screen simply goes blank. Oth- erwise, if either exposures are allowed or the screen can be regenerated without sending 4mExpose24m events to clients, the screen is tiled with the root window background tile ran- domly re-origined each interval seconds. Otherwise, the screens state do not change, and the screen saver is not activated. The screen saver is deactivated, and all screen states are restored at the next keyboard or pointer input or at the next call to 4mXForceScreenSaver24m with mode 4mScreenSaver-0m 4mReset24m. If the server-dependent screen saver method supports peri- odic change, the interval argument serves as a hint about how long the change period should be, and zero hints that no periodic change should be made. Examples of ways to change the screen include scrambling the colormap periodically, moving an icon image around the screen periodically, or tiling the screen with the root window background tile, ran- domly re-origined periodically. 4mXSetScreenSaver24m can generate a 4mBadValue24m error. To force the screen saver on or off, use 4mXForceScreenSaver24m. __ XForceScreenSaver(4mdisplay24m, 4mmode24m) Display *4mdisplay24m; int 4mmode24m; 4mdisplay24m Specifies the connection to the X server. 4mmode24m Specifies the mode that is to be applied. You can pass 4mScreenSaverActive24m or 4mScreenSaverReset24m. __ If the specified mode is 4mScreenSaverActive24m and the screen saver currently is deactivated, 4mXForceScreenSaver24m activates the screen saver even if the screen saver had been disabled with a timeout of zero. If the specified mode is 4mScreen-0m 4mSaverReset24m and the screen saver currently is enabled, 4mXForceScreenSaver24m deactivates the screen saver if it was activated, and the activation timer is reset to its initial state (as if device input had been received). 4mXForceScreenSaver24m can generate a 4mBadValue24m error. To activate the screen saver, use 4mXActivateScreenSaver24m. 1m2790m 1mXlib C Library X11, Release 6.9/7.00m __ XActivateScreenSaver(4mdisplay24m) Display *4mdisplay24m; 4mdisplay24m Specifies the connection to the X server. __ To reset the screen saver, use 4mXResetScreenSaver24m. __ XResetScreenSaver(4mdisplay24m) Display *4mdisplay24m; 4mdisplay24m Specifies the connection to the X server. __ To get the current screen saver values, use 4mXGetScreenSaver24m. __ XGetScreenSaver(4mdisplay24m, 4mtimeout_return24m, 4minterval_return24m, 4mprefer_blanking_return24m, 4mallow_exposures_return24m) Display *4mdisplay24m; int *4mtimeout_return24m, *4minterval_return24m; int *4mprefer_blanking_return24m; int *4mallow_exposures_return24m; 4mdisplay24m Specifies the connection to the X server. 4mtimeout_return0m Returns the timeout, in seconds, until the screen saver turns on. 4minterval_return0m Returns the interval between screen saver invoca- tions. 4mprefer_blanking_return0m Returns the current screen blanking preference (4mDontPreferBlanking24m, 4mPreferBlanking24m, or 4mDefault-0m 4mBlanking24m). 4mallow_exposures_return0m Returns the current screen save control value (4mDontAllowExposures24m, 4mAllowExposures24m, or 4mDefaultEx-0m 4mposures24m). __ 1m2800m 1mXlib C Library X11, Release 6.9/7.00m 1m9.8. Controlling Host Access0m This section discusses how to: Add, get, or remove hosts from the access control list Change, enable, or disable access X does not provide any protection on a per-window basis. If you find out the resource ID of a resource, you can manipu- late it. To provide some minimal level of protection, how- ever, connections are permitted only from machines you trust. This is adequate on single-user workstations but obviously breaks down on timesharing machines. Although provisions exist in the X protocol for proper connection authentication, the lack of a standard authentication server leaves host-level access control as the only common mecha- nism. The initial set of hosts allowed to open connections typi- cally consists of: The host the window system is running on. On POSIX-conformant systems, each host listed in the 4m/etc/X?.hosts24m file. The ? indicates the number of the display. This file should consist of host names sepa- rated by newlines. DECnet nodes must terminate in :: to distinguish them from Internet hosts. If a host is not in the access control list when the access control mechanism is enabled and if the host attempts to establish a connection, the server refuses the connection. To change the access list, the client must reside on the same host as the server and/or must have been granted per- mission in the initial authorization at connection setup. Servers also can implement other access control policies in addition to or in place of this host access facility. For further information about other access control implementa- tions, see X Window System Protocol. 1m9.8.1. Adding, Getting, or Removing Hosts0m Xlib provides functions that you can use to add, get, or remove hosts from the access control list. All the host access control functions use the 4mXHostAddress24m structure, which contains: 1m2810m 1mXlib C Library X11, Release 6.9/7.00m __ typedef struct { int family; /* for example FamilyInternet */ int length; /* length of address, in bytes */ char *address; /* pointer to where to find the address */ } XHostAddress; __ The family member specifies which protocol address family to use (for example, TCP/IP or DECnet) and can be 4mFamilyInter-0m 4mnet24m, 4mFamilyInternet624m, 4mFamilyServerInterpreted24m, 4mFamilyDECnet24m, or 4mFamilyChaos24m. The length member specifies the length of the address in bytes. The address member specifies a pointer to the address. For TCP/IP, the address should be in network byte order. For IP version 4 addresses, the family should be FamilyIn- ternet and the length should be 4 bytes. For IP version 6 addresses, the family should be FamilyInternet6 and the length should be 16 bytes. For the DECnet family, the server performs no automatic swapping on the address bytes. A Phase IV address is 2 bytes long. The first byte contains the least significant 8 bits of the node number. The second byte contains the most significant 2 bits of the node number in the least signifi- cant 2 bits of the byte and the area in the most significant 6 bits of the byte. For the ServerInterpreted family, the length is ignored and the address member is a pointer to a 4mXServerInterpretedAd-0m 4mdress24m structure, which contains: __ typedef struct { int typelength; /* length of type string, in bytes */ int valuelength;/* length of value string, in bytes */ char *type; /* pointer to where to find the type string */ char *value; /* pointer to where to find the address */ } XServerInterpretedAddress; __ The type and value members point to strings representing the type and value of the server interpreted entry. These strings may not be NULL-terminated so care should be used when accessing them. The typelength and valuelength members specify the length in byte of the type and value strings. To add a single host, use 4mXAddHost24m. 1m2820m 1mXlib C Library X11, Release 6.9/7.00m __ XAddHost(4mdisplay24m, 4mhost24m) Display *4mdisplay24m; XHostAddress *4mhost24m; 4mdisplay24m Specifies the connection to the X server. 4mhost24m Specifies the host that is to be added. __ The 4mXAddHost24m function adds the specified host to the access control list for that display. The server must be on the same host as the client issuing the command, or a 4mBadAccess0m error results. 4mXAddHost24m can generate 4mBadAccess24m and 4mBadValue24m errors. To add multiple hosts at one time, use 4mXAddHosts24m. __ XAddHosts(4mdisplay24m, 4mhosts24m, 4mnum_hosts24m) Display *4mdisplay24m; XHostAddress *4mhosts24m; int 4mnum_hosts24m; 4mdisplay24m Specifies the connection to the X server. 4mhosts24m Specifies each host that is to be added. 4mnum_hosts24m Specifies the number of hosts. __ The 4mXAddHosts24m function adds each specified host to the access control list for that display. The server must be on the same host as the client issuing the command, or a 4mBadAc-0m 4mcess24m error results. 4mXAddHosts24m can generate 4mBadAccess24m and 4mBadValue24m errors. To obtain a host list, use 4mXListHosts24m. 1m2830m 1mXlib C Library X11, Release 6.9/7.00m __ XHostAddress *XListHosts(4mdisplay24m, 4mnhosts_return24m, 4mstate_return24m) Display *4mdisplay24m; int *4mnhosts_return24m; Bool *4mstate_return24m; 4mdisplay24m Specifies the connection to the X server. 4mnhosts_return0m Returns the number of hosts currently in the access control list. 4mstate_return0m Returns the state of the access control. __ The 4mXListHosts24m function returns the current access control list as well as whether the use of the list at connection setup was enabled or disabled. 4mXListHosts24m allows a program to find out what machines can make connections. It also returns a pointer to a list of host structures that were allocated by the function. When no longer needed, this mem- ory should be freed by calling 4mXFree24m. To remove a single host, use 4mXRemoveHost24m. __ XRemoveHost(4mdisplay24m, 4mhost24m) Display *4mdisplay24m; XHostAddress *4mhost24m; 4mdisplay24m Specifies the connection to the X server. 4mhost24m Specifies the host that is to be removed. __ The 4mXRemoveHost24m function removes the specified host from the access control list for that display. The server must be on the same host as the client process, or a 4mBadAccess24m error results. If you remove your machine from the access list, you can no longer connect to that server, and this operation cannot be reversed unless you reset the server. 4mXRemoveHost24m can generate 4mBadAccess24m and 4mBadValue24m errors. To remove multiple hosts at one time, use 4mXRemoveHosts24m. 1m2840m 1mXlib C Library X11, Release 6.9/7.00m __ XRemoveHosts(4mdisplay24m, 4mhosts24m, 4mnum_hosts24m) Display *4mdisplay24m; XHostAddress *4mhosts24m; int 4mnum_hosts24m; 4mdisplay24m Specifies the connection to the X server. 4mhosts24m Specifies each host that is to be removed. 4mnum_hosts24m Specifies the number of hosts. __ The 4mXRemoveHosts24m function removes each specified host from the access control list for that display. The X server must be on the same host as the client process, or a 4mBadAccess0m error results. If you remove your machine from the access list, you can no longer connect to that server, and this operation cannot be reversed unless you reset the server. 4mXRemoveHosts24m can generate 4mBadAccess24m and 4mBadValue24m errors. 1m9.8.2. Changing, Enabling, or Disabling Access Control0m Xlib provides functions that you can use to enable, disable, or change access control. For these functions to execute successfully, the client application must reside on the same host as the X server and/or have been given permission in the initial authoriza- tion at connection setup. To change access control, use 4mXSetAccessControl24m. __ XSetAccessControl(4mdisplay24m, 4mmode24m) Display *4mdisplay24m; int 4mmode24m; 4mdisplay24m Specifies the connection to the X server. 4mmode24m Specifies the mode. You can pass 4mEnableAccess24m or 4mDisableAccess24m. __ The 4mXSetAccessControl24m function either enables or disables the use of the access control list at each connection setup. 4mXSetAccessControl24m can generate 4mBadAccess24m and 4mBadValue0m errors. 1m2850m 1mXlib C Library X11, Release 6.9/7.00m To enable access control, use 4mXEnableAccessControl24m. __ XEnableAccessControl(4mdisplay24m) Display *4mdisplay24m; 4mdisplay24m Specifies the connection to the X server. __ The 4mXEnableAccessControl24m function enables the use of the access control list at each connection setup. 4mXEnableAccessControl24m can generate a 4mBadAccess24m error. To disable access control, use 4mXDisableAccessControl24m. __ XDisableAccessControl(4mdisplay24m) Display *4mdisplay24m; 4mdisplay24m Specifies the connection to the X server. __ The 4mXDisableAccessControl24m function disables the use of the access control list at each connection setup. 4mXDisableAccessControl24m can generate a 4mBadAccess24m error. 1m2860m 1mXlib C Library X11, Release 6.9/7.00m 1mChapter 100m 1mEvents0m A client application communicates with the X server through the connection you establish with the 4mXOpenDisplay24m function. A client application sends requests to the X server over this connection. These requests are made by the Xlib func- tions that are called in the client application. Many Xlib functions cause the X server to generate events, and the users typing or moving the pointer can generate events asynchronously. The X server returns events to the client on the same connection. This chapter discusses the following topics associated with events: Event types Event structures Event masks Event processing Functions for handling events are dealt with in the next chapter. 1m10.1. Event Types0m An event is data generated asynchronously by the X server as a result of some device activity or as side effects of a request sent by an Xlib function. Device-related events propagate from the source window to ancestor windows until some client application has selected that event type or until the event is explicitly discarded. The X server gen- erally sends an event to a client application only if the client has specifically asked to be informed of that event type, typically by setting the event-mask attribute of the window. The mask can also be set when you create a window or by changing the windows event-mask. You can also mask out events that would propagate to ancestor windows by manipulating the do-not-propagate mask of the windows attributes. However, 4mMappingNotify24m events are always sent to all clients. An event type describes a specific event generated by the X server. For each event type, a corresponding constant name is defined in <4mX11/X.h24m>, which is used when referring to an event type. The following table lists the event category 1m2870m 1mXlib C Library X11, Release 6.9/7.00m and its associated event type or types. The processing associated with these events is discussed in section 10.5. ------------------------------------------------------------- 1mEvent Category Event Type0m ------------------------------------------------------------- Keyboard events 4mKeyPress24m, 4mKeyRelease0m Pointer events 4mButtonPress24m, 4mButtonRelease24m, 4mMotion-0m 4mNotify0m Window crossing events 4mEnterNotify24m, 4mLeaveNotify0m Input focus events 4mFocusIn24m, 4mFocusOut0m Keymap state notifica- 4mKeymapNotify0m tion event Exposure events 4mExpose24m, 4mGraphicsExpose24m, 4mNoExpose0m Structure control 4mCirculateRequest24m, 4mConfigureRequest24m, events 4mMapRequest24m, 4mResizeRequest0m Window state notifica- 4mCirculateNotify24m, 4mConfigureNotify24m, tion events 4mCreateNotify24m, 4mDestroyNotify24m, 4mGravi-0m 4mtyNotify24m, 4mMapNotify24m, 4mMappingNotify24m, 4mReparentNotify24m, 4mUnmapNotify24m, 4mVisibilityNotify0m Colormap state notifi- 4mColormapNotify0m cation event Client communication 4mClientMessage24m, 4mPropertyNotify24m, events 4mSelectionClear24m, 4mSelectionNotify24m, 4mSelectionRequest0m ------------------------------------------------------------- 1m10.2. Event Structures0m For each event type, a corresponding structure is declared in <4mX11/Xlib.h24m>. All the event structures have the follow- ing common members: __ typedef struct { int type; unsigned long serial; /* # of last request processed by server */ Bool send_event; /* true if this came from a SendEvent request */ Display *display; /* Display the event was read from */ Window window; } XAnyEvent; __ The type member is set to the event type constant name that uniquely identifies it. For example, when the X server reports a 4mGraphicsExpose24m event to a client application, it sends an 4mXGraphicsExposeEvent24m structure with the type member set to 4mGraphicsExpose24m. The display member is set to a 1m2880m 1mXlib C Library X11, Release 6.9/7.00m pointer to the display the event was read on. The send_event member is set to 4mTrue24m if the event came from a 4mSendEvent24m protocol request. The serial member is set from the serial number reported in the protocol but expanded from the 16-bit least-significant bits to a full 32-bit value. The window member is set to the window that is most useful to toolkit dispatchers. The X server can send events at any time in the input stream. Xlib stores any events received while waiting for a reply in an event queue for later use. Xlib also provides functions that allow you to check events in the event queue (see section 11.3). In addition to the individual structures declared for each event type, the 4mXEvent24m structure is a union of the individ- ual structures declared for each event type. Depending on the type, you should access members of each event by using the 4mXEvent24m union. 1m2890m 1mXlib C Library X11, Release 6.9/7.00m __ typedef union _XEvent { int type; /* must not be changed */ XAnyEvent xany; XKeyEvent xkey; XButtonEvent xbutton; XMotionEvent xmotion; XCrossingEvent xcrossing; XFocusChangeEvent xfocus; XExposeEvent xexpose; XGraphicsExposeEvent xgraphicsexpose; XNoExposeEvent xnoexpose; XVisibilityEvent xvisibility; XCreateWindowEvent xcreatewindow; XDestroyWindowEvent xdestroywindow; XUnmapEvent xunmap; XMapEvent xmap; XMapRequestEvent xmaprequest; XReparentEvent xreparent; XConfigureEvent xconfigure; XGravityEvent xgravity; XResizeRequestEvent xresizerequest; XConfigureRequestEvent xconfigurerequest; XCirculateEvent xcirculate; XCirculateRequestEvent xcirculaterequest; XPropertyEvent xproperty; XSelectionClearEvent xselectionclear; XSelectionRequestEvent xselectionrequest; XSelectionEvent xselection; XColormapEvent xcolormap; XClientMessageEvent xclient; XMappingEvent xmapping; XErrorEvent xerror; XKeymapEvent xkeymap; long pad[24]; } XEvent; __ An 4mXEvent24m structures first entry always is the type member, which is set to the event type. The second member always is the serial number of the protocol request that generated the event. The third member always is send_event, which is a 4mBool24m that indicates if the event was sent by a different client. The fourth member always is a display, which is the display that the event was read from. Except for keymap events, the fifth member always is a window, which has been carefully selected to be useful to toolkit dispatchers. To avoid breaking toolkits, the order of these first five entries is not to change. Most events also contain a time member, which is the time at which an event occurred. In addition, a pointer to the generic event must be cast before it is used to access any other information in the structure. 1m2900m 1mXlib C Library X11, Release 6.9/7.00m 1m10.3. Event Masks0m Clients select event reporting of most events relative to a window. To do this, pass an event mask to an Xlib event- handling function that takes an event_mask argument. The bits of the event mask are defined in <4mX11/X.h24m>. Each bit in the event mask maps to an event mask name, which describes the event or events you want the X server to return to a client application. Unless the client has specifically asked for them, most events are not reported to clients when they are generated. Unless the client suppresses them by setting graphics-expo- sures in the GC to 4mFalse24m, 4mGraphicsExpose24m and 4mNoExpose24m are reported by default as a result of 4mXCopyPlane24m and 4mXCopyArea24m. 4mSelectionClear24m, 4mSelectionRequest24m, 4mSelectionNotify24m, or 4mClientMessage24m cannot be masked. Selection-related events are only sent to clients cooperating with selections (see section 4.5). When the keyboard or pointer mapping is changed, 4mMappingNotify24m is always sent to clients. The following table lists the event mask constants you can pass to the event_mask argument and the circumstances in which you would want to specify the event mask: ----------------------------------------------------------- 1mEvent Mask Circumstances0m ----------------------------------------------------------- 4mNoEventMask24m No events wanted 4mKeyPressMask24m Keyboard down events wanted 4mKeyReleaseMask24m Keyboard up events wanted 4mButtonPressMask24m Pointer button down events wanted 4mButtonReleaseMask24m Pointer button up events wanted 4mEnterWindowMask24m Pointer window entry events wanted 4mLeaveWindowMask24m Pointer window leave events wanted 4mPointerMotionMask24m Pointer motion events wanted 4mPointerMotionHint-24m Pointer motion hints wanted 4mMask0m 4mButton1MotionMask24m Pointer motion while button 1 down 4mButton2MotionMask24m Pointer motion while button 2 down 4mButton3MotionMask24m Pointer motion while button 3 down 4mButton4MotionMask24m Pointer motion while button 4 down 4mButton5MotionMask24m Pointer motion while button 5 down 4mButtonMotionMask24m Pointer motion while any button down 4mKeymapStateMask24m Keyboard state wanted at window entry and focus in 4mExposureMask24m Any exposure wanted 4mVisibilityChangeMask24m Any change in visibility wanted 4mStructureNotifyMask24m Any change in window structure wanted 4mResizeRedirectMask24m Redirect resize of this window 1m2910m 1mXlib C Library X11, Release 6.9/7.00m ----------------------------------------------------------- 1mEvent Mask Circumstances0m ----------------------------------------------------------- 4mSubstructureNotify-24m Substructure notification wanted 4mMask0m 4mSubstructureRedi-24m Redirect structure requests on 4mrectMask24m children 4mFocusChangeMask24m Any change in input focus wanted 4mPropertyChangeMask24m Any change in property wanted 4mColormapChangeMask24m Any change in colormap wanted 4mOwnerGrabButtonMask24m Automatic grabs should activate with owner_events set to 4mTrue0m ----------------------------------------------------------- 1m10.4. Event Processing Overview0m The event reported to a client application during event pro- cessing depends on which event masks you provide as the event-mask attribute for a window. For some event masks, there is a one-to-one correspondence between the event mask constant and the event type constant. For example, if you pass the event mask 4mButtonPressMask24m, the X server sends back only 4mButtonPress24m events. Most events contain a time member, which is the time at which an event occurred. In other cases, one event mask constant can map to several event type constants. For example, if you pass the event mask 4mSubstructureNotifyMask24m, the X server can send back 4mCir-0m 4mculateNotify24m, 4mConfigureNotify24m, 4mCreateNotify24m, 4mDestroyNotify24m, 4mGravityNotify24m, 4mMapNotify24m, 4mReparentNotify24m, or 4mUnmapNotify0m events. In another case, two event masks can map to one event type. For example, if you pass either 4mPointerMotionMask24m or 4mButton-0m 4mMotionMask24m, the X server sends back a 4mMotionNotify24m event. The following table lists the event mask, its associated event type or types, and the structure name associated with the event type. Some of these structures actually are type- defs to a generic structure that is shared between two event types. Note that N.A. appears in columns for which the information is not applicable. ------------------------------------------------------------------------------------------ 1mEvent Mask Event Type Structure Generic Structure0m ------------------------------------------------------------------------------------------ ButtonMotionMask MotionNotify XPointerMovedEvent XMotionEvent Button1MotionMask Button2MotionMask Button3MotionMask 1m2920m 1mXlib C Library X11, Release 6.9/7.00m ------------------------------------------------------------------------------------------ 1mEvent Mask Event Type Structure Generic Structure0m ------------------------------------------------------------------------------------------ Button4MotionMask Button5MotionMask ButtonPressMask ButtonPress XButtonPressedEvent XButtonEvent ButtonReleaseMask ButtonRelease XButtonReleasedEvent XButtonEvent ColormapChangeMask ColormapNotify XColormapEvent EnterWindowMask EnterNotify XEnterWindowEvent XCrossingEvent LeaveWindowMask LeaveNotify XLeaveWindowEvent XCrossingEvent ExposureMask Expose XExposeEvent GCGraphicsExposures in GC GraphicsExpose XGraphicsExposeEvent NoExpose XNoExposeEvent FocusChangeMask FocusIn XFocusInEvent XFocusChangeEvent FocusOut XFocusOutEvent XFocusChangeEvent KeymapStateMask KeymapNotify XKeymapEvent KeyPressMask KeyPress XKeyPressedEvent XKeyEvent KeyReleaseMask KeyRelease XKeyReleasedEvent XKeyEvent OwnerGrabButtonMask N.A. N.A. PointerMotionMask MotionNotify XPointerMovedEvent XMotionEvent PointerMotionHintMask N.A. N.A. PropertyChangeMask PropertyNotify XPropertyEvent ResizeRedirectMask ResizeRequest XResizeRequestEvent StructureNotifyMask CirculateNotify XCirculateEvent ConfigureNotify XConfigureEvent DestroyNotify XDestroyWindowEvent GravityNotify XGravityEvent MapNotify XMapEvent ReparentNotify XReparentEvent UnmapNotify XUnmapEvent SubstructureNotifyMask CirculateNotify XCirculateEvent ConfigureNotify XConfigureEvent CreateNotify XCreateWindowEvent DestroyNotify XDestroyWindowEvent GravityNotify XGravityEvent MapNotify XMapEvent ReparentNotify XReparentEvent UnmapNotify XUnmapEvent SubstructureRedirectMask CirculateRequest XCirculateRequestEvent ConfigureRequest XConfigureRequestEvent MapRequest XMapRequestEvent N.A. ClientMessage XClientMessageEvent N.A. MappingNotify XMappingEvent N.A. SelectionClear XSelectionClearEvent N.A. SelectionNotify XSelectionEvent N.A. SelectionRequest XSelectionRequestEvent VisibilityChangeMask VisibilityNotify XVisibilityEvent ------------------------------------------------------------------------------------------ The sections that follow describe the processing that occurs when you select the different event masks. The sections are organized according to these processing categories: 1m2930m 1mXlib C Library X11, Release 6.9/7.00m Keyboard and pointer events Window crossing events Input focus events Keymap state notification events Exposure events Window state notification events Structure control events Colormap state notification events Client communication events 1m10.5. Keyboard and Pointer Events0m This section discusses: Pointer button events Keyboard and pointer events 1m10.5.1. Pointer Button Events0m The following describes the event processing that occurs when a pointer button press is processed with the pointer in some window w and when no active pointer grab is in progress. The X server searches the ancestors of w from the root down, looking for a passive grab to activate. If no matching pas- sive grab on the button exists, the X server automatically starts an active grab for the client receiving the event and sets the last-pointer-grab time to the current server time. The effect is essentially equivalent to an 4mXGrabButton24m with these client passed arguments: ------------------------------------------------------ 1mArgument Value0m ------------------------------------------------------ 4mw24m The event window 4mevent_mask24m The clients selected pointer events on the event window 4mpointer_mode24m 4mGrabModeAsync0m 4mkeyboard_mode24m 4mGrabModeAsync0m 4mowner_events24m 4mTrue24m, if the client has selected 4mOwnerGrabButtonMask24m on the event window, otherwise 4mFalse0m 4mconfine_to24m 4mNone0m 1m2940m 1mXlib C Library X11, Release 6.9/7.00m ------------------------------------------------------ 1mArgument Value0m ------------------------------------------------------ 4mcursor24m 4mNone0m ------------------------------------------------------ The active grab is automatically terminated when the logical state of the pointer has all buttons released. Clients can modify the active grab by calling 4mXUngrabPointer24m and 4mXChangeActivePointerGrab24m. 1m10.5.2. Keyboard and Pointer Events0m This section discusses the processing that occurs for the keyboard events 4mKeyPress24m and 4mKeyRelease24m and the pointer events 4mButtonPress24m, 4mButtonRelease24m, and 4mMotionNotify24m. For information about the keyboard event-handling utilities, see chapter 11. The X server reports 4mKeyPress24m or 4mKeyRelease24m events to clients wanting information about keys that logically change state. Note that these events are generated for all keys, even those mapped to modifier bits. The X server reports 4mButtonPress24m or 4mButtonRelease24m events to clients wanting information about buttons that logically change state. The X server reports 4mMotionNotify24m events to clients wanting information about when the pointer logically moves. The X server generates this event whenever the pointer is moved and the pointer motion begins and ends in the window. The granularity of 4mMotionNotify24m events is not guaranteed, but a client that selects this event type is guaranteed to receive at least one event when the pointer moves and then rests. The generation of the logical changes lags the physical changes if device event processing is frozen. To receive 4mKeyPress24m, 4mKeyRelease24m, 4mButtonPress24m, and 4mButtonRe-0m 4mlease24m events, set 4mKeyPressMask24m, 4mKeyReleaseMask24m, 4mButtonPress-0m 4mMask24m, and 4mButtonReleaseMask24m bits in the event-mask attribute of the window. To receive 4mMotionNotify24m events, set one or more of the fol- lowing event masks bits in the event-mask attribute of the window. 4mButton1MotionMask24m 4mButton5MotionMask0m The client application receives 4mMotionNotify24m events only when one or more of the specified buttons is pressed. 1m2950m 1mXlib C Library X11, Release 6.9/7.00m 4mButtonMotionMask0m The client application receives 4mMotionNotify24m events only when at least one button is pressed. 4mPointerMotionMask0m The client application receives 4mMotionNotify24m events independent of the state of the pointer buttons. 4mPointerMotionHintMask0m If 4mPointerMotionHintMask24m is selected in combination with one or more of the above masks, the X server is free to send only one 4mMotionNotify24m event (with the is_hint member of the 4mXPointerMovedEvent24m structure set to 4mNotifyHint24m) to the client for the event window, until either the key or button state changes, the pointer leaves the event window, or the client calls 4mXQueryPointer24m or 4mXGetMotionEvents24m. The server still may send 4mMotionNotify24m events without is_hint set to 4mNotifyHint24m. The source of the event is the viewable window that the pointer is in. The window used by the X server to report these events depends on the windows position in the window hierarchy and whether any intervening window prohibits the generation of these events. Starting with the source win- dow, the X server searches up the window hierarchy until it locates the first window specified by a client as having an interest in these events. If one of the intervening windows has its do-not-propagate-mask set to prohibit generation of the event type, the events of those types will be sup- pressed. Clients can modify the actual window used for reporting by performing active grabs and, in the case of keyboard events, by using the focus window. The structures for these event types contain: 1m2960m 1mXlib C Library X11, Release 6.9/7.00m __ typedef struct { int type; /* ButtonPress or ButtonRelease */ unsigned long serial; /* # of last request processed by server */ Bool send_event; /* true if this came from a SendEvent request */ Display *display; /* Display the event was read from */ Window window; /* event window it is reported relative to */ Window root; /* root window that the event occurred on */ Window subwindow; /* child window */ Time time; /* milliseconds */ int x, y; /* pointer x, y coordinates in event window */ int x_root, y_root; /* coordinates relative to root */ unsigned int state; /* key or button mask */ unsigned int button; /* detail */ Bool same_screen; /* same screen flag */ } XButtonEvent; typedef XButtonEvent XButtonPressedEvent; typedef XButtonEvent XButtonReleasedEvent; typedef struct { int type; /* KeyPress or KeyRelease */ unsigned long serial; /* # of last request processed by server */ Bool send_event; /* true if this came from a SendEvent request */ Display *display; /* Display the event was read from */ Window window; /* event window it is reported relative to */ Window root; /* root window that the event occurred on */ Window subwindow; /* child window */ Time time; /* milliseconds */ int x, y; /* pointer x, y coordinates in event window */ int x_root, y_root; /* coordinates relative to root */ unsigned int state; /* key or button mask */ unsigned int keycode; /* detail */ Bool same_screen; /* same screen flag */ } XKeyEvent; typedef XKeyEvent XKeyPressedEvent; typedef XKeyEvent XKeyReleasedEvent; typedef struct { int type; /* MotionNotify */ unsigned long serial; /* # of last request processed by server */ Bool send_event; /* true if this came from a SendEvent request */ Display *display; /* Display the event was read from */ Window window; /* event window reported relative to */ Window root; /* root window that the event occurred on */ Window subwindow; /* child window */ Time time; /* milliseconds */ int x, y; /* pointer x, y coordinates in event window */ int x_root, y_root; /* coordinates relative to root */ unsigned int state; /* key or button mask */ char is_hint; /* detail */ 1m2970m 1mXlib C Library X11, Release 6.9/7.00m Bool same_screen; /* same screen flag */ } XMotionEvent; typedef XMotionEvent XPointerMovedEvent; __ These structures have the following common members: window, root, subwindow, time, x, y, x_root, y_root, state, and same_screen. The window member is set to the window on which the event was generated and is referred to as the event window. As long as the conditions previously dis- cussed are met, this is the window used by the X server to report the event. The root member is set to the source win- dows root window. The x_root and y_root members are set to the pointers coordinates relative to the root windows ori- gin at the time of the event. The same_screen member is set to indicate whether the event window is on the same screen as the root window and can be either 4mTrue24m or 4mFalse24m. If 4mTrue24m, the event and root windows are on the same screen. If 4mFalse24m, the event and root win- dows are not on the same screen. If the source window is an inferior of the event window, the subwindow member of the structure is set to the child of the event window that is the source window or the child of the event window that is an ancestor of the source window. Oth- erwise, the X server sets the subwindow member to 4mNone24m. The time member is set to the time when the event was generated and is expressed in milliseconds. If the event window is on the same screen as the root win- dow, the x and y members are set to the coordinates relative to the event windows origin. Otherwise, these members are set to zero. The state member is set to indicate the logical state of the pointer buttons and modifier keys just prior to the event, which is the bitwise inclusive OR of one or more of the but- ton or modifier key masks: 4mButton1Mask24m, 4mButton2Mask24m, 4mBut-0m 4mton3Mask24m, 4mButton4Mask24m, 4mButton5Mask24m, 4mShiftMask24m, 4mLockMask24m, 4mControlMask24m, 4mMod1Mask24m, 4mMod2Mask24m, 4mMod3Mask24m, 4mMod4Mask24m, and 4mMod5Mask24m. Each of these structures also has a member that indicates the detail. For the 4mXKeyPressedEvent24m and 4mXKeyReleasedEvent0m structures, this member is called a keycode. It is set to a number that represents a physical key on the keyboard. The keycode is an arbitrary representation for any key on the keyboard (see sections 12.7 and 16.1). For the 4mXButtonPressedEvent24m and 4mXButtonReleasedEvent24m struc- tures, this member is called button. It represents the pointer button that changed state and can be the 4mButton124m, 1m2980m 1mXlib C Library X11, Release 6.9/7.00m 4mButton224m, 4mButton324m, 4mButton424m, or 4mButton524m value. For the 4mXPointerMovedEvent24m structure, this member is called is_hint. It can be set to 4mNotifyNormal24m or 4mNotifyHint24m. Some of the symbols mentioned in this section have fixed values, as follows: ----------------------------------------------------------- 1mSymbol Value0m ----------------------------------------------------------- 4mButton1MotionMask24m (1L<<8) 4mButton2MotionMask24m (1L<<9) 4mButton3MotionMask24m (1L<<10) 4mButton4MotionMask24m (1L<<11) 4mButton5MotionMask24m (1L<<12) 4mButton1Mask24m (1<<8) 4mButton2Mask24m (1<<9) 4mButton3Mask24m (1<<10) 4mButton4Mask24m (1<<11) 4mButton5Mask24m (1<<12) 4mShiftMask24m (1<<0) 4mLockMask24m (1<<1) 4mControlMask24m (1<<2) 4mMod1Mask24m (1<<3) 4mMod2Mask24m (1<<4) 4mMod3Mask24m (1<<5) 4mMod4Mask24m (1<<6) 4mMod5Mask24m (1<<7) 4mButton124m 1 4mButton224m 2 4mButton324m 3 4mButton424m 4 4mButton524m 5 ----------------------------------------------------------- 1m10.6. Window Entry/Exit Events0m This section describes the processing that occurs for the window crossing events 4mEnterNotify24m and 4mLeaveNotify24m. If a pointer motion or a window hierarchy change causes the pointer to be in a different window than before, the X server reports 4mEnterNotify24m or 4mLeaveNotify24m events to clients who have selected for these events. All 4mEnterNotify24m and 4mLeaveNotify24m events caused by a hierarchy change are gener- ated after any hierarchy event (4mUnmapNotify24m, 4mMapNotify24m, 4mCon-0m 4mfigureNotify24m, 4mGravityNotify24m, 4mCirculateNotify24m) caused by that change; however, the X protocol does not constrain the ordering of 4mEnterNotify24m and 4mLeaveNotify24m events with respect to 4mFocusOut24m, 4mVisibilityNotify24m, and 4mExpose24m events. This contrasts with 4mMotionNotify24m events, which are also gen- erated when the pointer moves but only when the pointer motion begins and ends in a single window. An 4mEnterNotify0m 1m2990m 1mXlib C Library X11, Release 6.9/7.00m or 4mLeaveNotify24m event also can be generated when some client application calls 4mXGrabPointer24m and 4mXUngrabPointer24m. To receive 4mEnterNotify24m or 4mLeaveNotify24m events, set the 4mEnter-0m 4mWindowMask24m or 4mLeaveWindowMask24m bits of the event-mask attribute of the window. The structure for these event types contains: __ typedef struct { int type; /* EnterNotify or LeaveNotify */ unsigned long serial; /* # of last request processed by server */ Bool send_event; /* true if this came from a SendEvent request */ Display *display; /* Display the event was read from */ Window window; /* event window reported relative to */ Window root; /* root window that the event occurred on */ Window subwindow; /* child window */ Time time; /* milliseconds */ int x, y; /* pointer x, y coordinates in event window */ int x_root, y_root; /* coordinates relative to root */ int mode; /* NotifyNormal, NotifyGrab, NotifyUngrab */ int detail; /* * NotifyAncestor, NotifyVirtual, NotifyInferior, * NotifyNonlinear,NotifyNonlinearVirtual */ Bool same_screen; /* same screen flag */ Bool focus; /* boolean focus */ unsigned int state; /* key or button mask */ } XCrossingEvent; typedef XCrossingEvent XEnterWindowEvent; typedef XCrossingEvent XLeaveWindowEvent; __ The window member is set to the window on which the 4mEnter-0m 4mNotify24m or 4mLeaveNotify24m event was generated and is referred to as the event window. This is the window used by the X server to report the event, and is relative to the root win- dow on which the event occurred. The root member is set to the root window of the screen on which the event occurred. For a 4mLeaveNotify24m event, if a child of the event window con- tains the initial position of the pointer, the subwindow component is set to that child. Otherwise, the X server sets the subwindow member to 4mNone24m. For an 4mEnterNotify0m event, if a child of the event window contains the final pointer position, the subwindow component is set to that child or 4mNone24m. The time member is set to the time when the event was gener- ated and is expressed in milliseconds. The x and y members 1m3000m 1mXlib C Library X11, Release 6.9/7.00m are set to the coordinates of the pointer position in the event window. This position is always the pointers final position, not its initial position. If the event window is on the same screen as the root window, x and y are the pointer coordinates relative to the event windows origin. Otherwise, x and y are set to zero. The x_root and y_root members are set to the pointers coordinates relative to the root windows origin at the time of the event. The same_screen member is set to indicate whether the event window is on the same screen as the root window and can be either 4mTrue24m or 4mFalse24m. If 4mTrue24m, the event and root windows are on the same screen. If 4mFalse24m, the event and root win- dows are not on the same screen. The focus member is set to indicate whether the event window is the focus window or an inferior of the focus window. The X server can set this member to either 4mTrue24m or 4mFalse24m. If 4mTrue24m, the event window is the focus window or an inferior of the focus window. If 4mFalse24m, the event window is not the focus window or an inferior of the focus window. The state member is set to indicate the state of the pointer buttons and modifier keys just prior to the event. The X server can set this member to the bitwise inclusive OR of one or more of the button or modifier key masks: 4mBut-0m 4mton1Mask24m, 4mButton2Mask24m, 4mButton3Mask24m, 4mButton4Mask24m, 4mBut-0m 4mton5Mask24m, 4mShiftMask24m, 4mLockMask24m, 4mControlMask24m, 4mMod1Mask24m, 4mMod2Mask24m, 4mMod3Mask24m, 4mMod4Mask24m, 4mMod5Mask24m. The mode member is set to indicate whether the events are normal events, pseudo-motion events when a grab activates, or pseudo-motion events when a grab deactivates. The X server can set this member to 4mNotifyNormal24m, 4mNotifyGrab24m, or 4mNotifyUngrab24m. The detail member is set to indicate the notify detail and can be 4mNotifyAncestor24m, 4mNotifyVirtual24m, 4mNotifyInferior24m, 4mNoti-0m 4mfyNonlinear24m, or 4mNotifyNonlinearVirtual24m. 1m10.6.1. Normal Entry/Exit Events0m 4mEnterNotify24m and 4mLeaveNotify24m events are generated when the pointer moves from one window to another window. Normal events are identified by 4mXEnterWindowEvent24m or 4mXLeaveWindow-0m 4mEvent24m structures whose mode member is set to 4mNotifyNormal24m. When the pointer moves from window A to window B and A is an inferior of B, the X server does the following: It generates a 4mLeaveNotify24m event on window A, with the detail member of the 4mXLeaveWindowEvent24m struc- ture set to 4mNotifyAncestor24m. 1m3010m 1mXlib C Library X11, Release 6.9/7.00m It generates a 4mLeaveNotify24m event on each window between window A and window B, exclusive, with the detail member of each 4mXLeaveWindowEvent24m structure set to 4mNotifyVirtual24m. It generates an 4mEnterNotify24m event on window B, with the detail member of the 4mXEnterWindowEvent0m structure set to 4mNotifyInferior24m. When the pointer moves from window A to window B and B is an inferior of A, the X server does the following: It generates a 4mLeaveNotify24m event on window A, with the detail member of the 4mXLeaveWindowEvent24m struc- ture set to 4mNotifyInferior24m. It generates an 4mEnterNotify24m event on each window between window A and window B, exclusive, with the detail member of each 4mXEnterWindowEvent24m structure set to 4mNotifyVirtual24m. It generates an 4mEnterNotify24m event on window B, with the detail member of the 4mXEnterWindowEvent0m structure set to 4mNotifyAncestor24m. When the pointer moves from window A to window B and window C is their least common ancestor, the X server does the following: It generates a 4mLeaveNotify24m event on window A, with the detail member of the 4mXLeaveWindowEvent24m struc- ture set to 4mNotifyNonlinear24m. It generates a 4mLeaveNotify24m event on each window between window A an