1mXlib - C Language X Interface0m 1mX Consortium Standard0m 1mX Version 11, Release 6.7 DRAFT0m 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 Digital's ULTRIX Documentation Group. With good humor and cheer, they took a rough draft and made it an infinitely better and more useful document. The work they have done will help many everywhere. We also would like to thank Hal Murray (Digital SRC) and Peter George (Digital VMS) who contributed much by proofreading the early drafts of this document. Our thanks also goes to Jeff Dike (Digital UEG), Tom Benson, Jackie Granfield, and Vince Orgovan (Digital VMS) who helped with the library utilities implementation; to Hania Gajewska (Digital UEG-WSL) who, along with Ellis Cohen (CMU and Siemens), was instrumental in the semantic design of the window manager properties; and to Dave Rosenthal (Sun Microsystems) who also contributed to the protocol and 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 MIT's resources with the Digital staff in order to make version 11 a reality. Many of the people mentioned here are part of the Western Software Laboratory (Digital UEG-WSL) of the ULTRIX Engineering group and work for Smokey Wallace, who has been vital to the project's 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 W's 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 4m-24m 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 user's 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 4m-24m 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.7 DRAFT0m 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 mono- chrome. There can be multiple screens for each display or workstation. A single X server can provide display services for any number of screens. A set of screens for a single user with one keyboard and one pointer (usually a mouse) is called a display. All the windows in an X server are arranged in strict 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.7 DRAFT0m 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.7 DRAFT0m 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.7 DRAFT0m 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.7 DRAFT0m · <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 appen- dix 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. 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 1m60m 1mXlib - C Library X11, Release 6.7 DRAFT0m information the function requires, these conventions are intended to make the syntax of the functions more pre- dictable. 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. · Where the x, y, width, and height arguments are used together, the x and y arguments always precede the width and height arguments. 1m70m 1mXlib - C Library X11, Release 6.7 DRAFT0m · 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 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 1m80m 1mXlib - C Library X11, Release 6.7 DRAFT0m 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 ISO 8859-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. · UTF-8 Encoding The ASCII compatible character encoding scheme defined by the ISO 10646-1 standard. · 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 4m-24m 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 1m90m 1mXlib - C Library X11, Release 6.7 DRAFT0m defined, function arguments are printed in 4mitalics24m. In the explanatory text that follows, they usually are 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.7 DRAFT0m 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.7 DRAFT0m 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- process communication protocol. If the protocol is speci- fied as "tcp", "inet", or "inet6", or if no protocol is specified and the hostname is a host machine name and a sin- gle colon (:) separates the hostname and display number, 4mXOpenDisplay24m connects using TCP streams. (If the protocol is specified as "inet", TCP over IPv4 is used. If the 1m120m 1mXlib - C Library X11, Release 6.7 DRAFT0m protocol is specified as "inet6", TCP over IPv6 is used. Otherwise, the implementation determines which IP version is used.) If the hostname and protocol are both not specified, Xlib uses whatever it believes is the fastest transport. If the hostname is a host machine name and a double colon (::) separates the hostname and display number, 4mXOpenDisplay24m con- nects using DECnet. A single X server can support any or all of these transport mechanisms simultaneously. A partic- ular 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.7 DRAFT0m 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.7 DRAFT0m __ | 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.7 DRAFT0m __ | 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.7 DRAFT0m __ | 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.7 DRAFT0m __ | 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.7 DRAFT0m __ | 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.7 DRAFT0m 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.7 DRAFT0m __ | 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.7 DRAFT0m __ | 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.7 DRAFT0m __ | 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 vendor's 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.7 DRAFT0m 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.7 DRAFT0m __ | 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 bitmap's 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.7 DRAFT0m __ | 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.7 DRAFT0m __ | 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.7 DRAFT0m __ | 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.7 DRAFT0m __ | 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.7 DRAFT0m __ | 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.7 DRAFT0m __ | 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.7 DRAFT0m __ | 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.7 DRAFT0m __ | 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.7 DRAFT0m 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 client's connection is closed. To change a client's close-down mode, use 4mXSetCloseDownMode24m. 1m340m 1mXlib - C Library X11, Release 6.7 DRAFT0m __ | 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 client's resources at connection close. A connection starts in 4mDestroyAll24m mode. For information on what happens to the client's 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 server's 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 client's resources as follows: · It examines each window in the client's 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.7 DRAFT0m 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.7 DRAFT0m 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.7 DRAFT0m __ | 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.7 DRAFT0m __ | 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.7 DRAFT0m __ | 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.7 DRAFT0m __ | 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.7 DRAFT0m 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.7 DRAFT0m 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.7 DRAFT0m 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.7 DRAFT0m 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 parent's background is used. When windows are first created, they are not visible (not mapped) on the screen. Any output to a window that is not visible on the screen and that does not have backing store will be discarded. An application may wish to create a 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.7 DRAFT0m 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.7 DRAFT0m __ | /* 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.7 DRAFT0m ------------------------------------------------------------- 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 window's background. This pixmap can be of any size, although some sizes may be faster than others. The background-pixel attribute of a window speci- fies a pixel value used to paint a window's 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 window's background-pixmap is used. The child window, however, must have the same depth as its 1m480m 1mXlib - C Library X11, Release 6.7 DRAFT0m 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 window's background-pixmap is not made. The parent's background-pixmap is examined each time the child window's background-pixmap is required. · The background tile origin always aligns with the par- ent window's background tile origin. If the back- ground-pixmap is not 4mParentRelative24m, the background tile origin is the child window's 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 window's 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 window's border. The border-pixel attribute of a window specifies a pixmap of undefined size filled with that pixel be used for a window's border. Range checking is not performed on the background pixel; it simply is truncated to the appropriate number of bits. The border tile origin is always the same as the background tile 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.7 DRAFT0m (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 window's border-pixmap is copied. Subsequent changes to the parent window's border attribute do not affect the child window. However, the child window must have the same depth as the parent window, or a 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 window's border will be set to the border- pixel. Setting a new border, whether by setting border- pixel or by setting border-pixmap, overrides any previous border. Output to a window is always clipped to the inside of the window. Therefore, graphics operations never affect the window border. 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.7 DRAFT0m 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 window's contents are always discarded after a size change, even if a backing store or save under has been requested. The window is tiled with its background and zero or more 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 parent's 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.7 DRAFT0m 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 window's 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.7 DRAFT0m 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- dow's 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.7 DRAFT0m The colormap is copied by sharing the colormap object between the child and parent, not by making a complete copy of the colormap contents. Subsequent changes to the parent window's colormap attribute do not affect the child window. 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 parent's cursor is used when the pointer is in the 4mInputOutput24m or 4mInputOnly24m window, and any change in the parent's 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.7 DRAFT0m 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.7 DRAFT0m __ | 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 window's borders and are relative to the inside of the par- ent window's borders. 4mwidth0m 4mheight24m Specify the width and height, which are the cre- ated window's inside dimensions and do not include the created window's borders. The dimensions must be nonzero, or a 4mBadValue24m error results. 4mborder_width0m Specifies the width of the created window's border in pixels. 4mdepth24m Specifies the window's depth. A depth of 4mCopy-0m 4mFromParent24m means the depth is taken from the par- ent. 4mclass24m Specifies the created window's 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.7 DRAFT0m 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 user's 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.7 DRAFT0m __ | 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 window's bor- ders and are relative to the inside of the parent window's borders. 4mwidth0m 4mheight24m Specify the width and height, which are the cre- ated window's inside dimensions and do not include the created window's borders. The dimensions must be nonzero, or a 4mBadValue24m error results. 4mborder_width0m Specifies the width of the created window's 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.7 DRAFT0m 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.7 DRAFT0m 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.7 DRAFT0m __ | 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 window's 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 client's 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.7 DRAFT0m 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.7 DRAFT0m __ | 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.7 DRAFT0m Xlib provides functions that you can use to move a window, resize a window, move and resize a window, or change a win- dow's 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 window's x and y coordinates, which are relative to the parent's origin and indicate the position of the upper-left outer corner of the window. The width and height members are used to set the inside size of the window, not including the border, and must be nonzero, or a 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 window's 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.7 DRAFT0m 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 window's size actually changes, the window's subwindows move according to their window gravity. Depending on the window's bit gravity, the contents of the window also may be moved (see section 3.2.3). If regions of the window were obscured but now are not, exposure processing is performed on these formerly obscured windows, including the window itself and its inferiors. As a result of increasing the width or height, exposure 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 window's final size and position (as controlled by the other arguments of the request), not its initial position. If a sibling is specified without a stack_mode, a 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.7 DRAFT0m 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 window's 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 window's size, position, border, and stacking order. Values not specified are taken from the existing geometry of the window. If a sibling is specified without a stack_mode or if the window is not actually a sibling, a 4mBadMatch24m error results. Note that the computations for 4mBottomIf24m, 4mTopIf24m, and 4mOpposite0m are performed with respect to the window's 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.7 DRAFT0m 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