From 8179c0025a44a769ab6ad2e5c0a58f545517280c Mon Sep 17 00:00:00 2001 From: Case Duckworth Date: Wed, 17 Jan 2024 00:24:11 -0600 Subject: Change organization and massively refactor --- ref/libX11.txt | 33445 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 33445 insertions(+) create mode 100644 ref/libX11.txt (limited to 'ref') diff --git a/ref/libX11.txt b/ref/libX11.txt new file mode 100644 index 0000000..5540d62 --- /dev/null +++ b/ref/libX11.txt @@ -0,0 +1,33445 @@ +Xlib - C Language X Interface + +X Consortium Standard + +James Gettys + + Digital Equipment Corporation + Cambridge Research Laboratory + +Robert W. Scheifler + + Massachusetts Institute of Technology + Laboratory for Computer Science + +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 + + X Version 11, Release 7.7 + + Copyright © 1985, 1986, 1987, 1988, 1989, 1991, 1994, 1996, + 2002 The Open Group + + Permission is hereby granted, free of charge, to any person + obtaining a copy of this software and associated documentation + files (the "Software"), to deal in the Software without + restriction, including without limitation the rights to use, + copy, modify, merge, publish, distribute, sublicense, and/or + sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following + conditions: + + The above copyright notice and this permission notice shall be + included in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES + OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR + ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF + CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN + CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN + THE SOFTWARE. + + Except as contained in this notice, the name of The Open Group + shall not be used in advertising or otherwise to promote the + sale, use or other dealings in this Software without prior + written authorization from The Open Group. + + Copyright © 1985, 1986, 1987, 1988, 1989, 1991 Digital + Equipment Corporation + + Permission to use, copy, modify and distribute this + documentation for any purpose and without fee is hereby + granted, provided that the above copyright notice appears in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the names of Digital and Tetronix not be used in in advertising + or publicity pertaining to distribution of the software without + specific, written prior permission. Digital and Tetronix make + no representations about the suitability of the software + described herein for any purpose. It is provided "as is" + without express or implied warranty. + + TekHVC is a trademark of Tektronix, Inc. + __________________________________________________________ + + Table of Contents + + Acknowledgments + 1. Introduction to Xlib + + 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 + + 2. Display Functions + + Opening the Display + Obtaining Information about the Display, Image Formats, or + Screens + + Display Macros + Image Format Functions and Macros + Screen Information Macros + + Generating a NoOperation Protocol Request + Freeing Client-Created Data + Closing the Display + Using X Server Connection Close Operations + Using Xlib with Threads + Using Internal Connections + + 3. Window Functions + + Visual Types + Window Attributes + + Background Attribute + Border Attribute + Gravity Attributes + Backing Store Attribute + Save Under Flag + Backing Planes and Backing Pixel Attributes + Event Mask and Do Not Propagate Mask Attributes + Override Redirect Flag + Colormap Attribute + Cursor Attribute + + Creating Windows + Destroying Windows + Mapping Windows + Unmapping Windows + Configuring Windows + Changing Window Stacking Order + Changing Window Attributes + + 4. Window Information Functions + + Obtaining Window Information + Translating Screen Coordinates + Properties and Atoms + Obtaining and Changing Window Properties + Selections + + 5. Pixmap and Cursor Functions + + Creating and Freeing Pixmaps + Creating, Recoloring, and Freeing Cursors + + 6. Color Management Functions + + Color Structures + Color Strings + + RGB Device String Specification + RGB Intensity String Specification + Device-Independent String Specifications + + Color Conversion Contexts and Gamut Mapping + Creating, Copying, and Destroying Colormaps + Mapping Color Names to Values + Allocating and Freeing Color Cells + Modifying and Querying Colormap Cells + Color Conversion Context Functions + + Getting and Setting the Color Conversion Context of + a Colormap + + Obtaining the Default Color Conversion Context + Color Conversion Context Macros + Modifying Attributes of a Color Conversion Context + Creating and Freeing a Color Conversion Context + + Converting between Color Spaces + Callback Functions + + Prototype Gamut Compression Procedure + Supplied Gamut Compression Procedures + Prototype White Point Adjustment Procedure + Supplied White Point Adjustment Procedures + + Gamut Querying Functions + + Red, Green, and Blue Queries + CIELab Queries + CIELuv Queries + TekHVC Queries + + Color Management Extensions + + Color Spaces + Adding Device-Independent Color Spaces + Querying Color Space Format and Prefix + Creating Additional Color Spaces + Parse String Callback + Color Specification Conversion Callback + Function Sets + Adding Function Sets + Creating Additional Function Sets + + 7. Graphics Context Functions + + Manipulating Graphics Context/State + Using Graphics Context Convenience Routines + + Setting the Foreground, Background, Function, or + Plane Mask + + Setting the Line Attributes and Dashes + Setting the Fill Style and Fill Rule + Setting the Fill Tile and Stipple + Setting the Current Font + Setting the Clip Region + Setting the Arc Mode, Subwindow Mode, and Graphics + Exposure + + 8. Graphics Functions + + Clearing Areas + Copying Areas + Drawing Points, Lines, Rectangles, and Arcs + + Drawing Single and Multiple Points + Drawing Single and Multiple Lines + Drawing Single and Multiple Rectangles + Drawing Single and Multiple Arcs + + Filling Areas + + Filling Single and Multiple Rectangles + Filling a Single Polygon + Filling Single and Multiple Arcs + + Font Metrics + + Loading and Freeing Fonts + Obtaining and Freeing Font Names and Information + Computing Character String Sizes + Computing Logical Extents + Querying Character String Sizes + + Drawing Text + + Drawing Complex Text + Drawing Text Characters + Drawing Image Text Characters + + Transferring Images between Client and Server + + 9. Window and Session Manager Functions + + Changing the Parent of a Window + Controlling the Lifetime of a Window + Managing Installed Colormaps + Setting and Retrieving the Font Search Path + Grabbing the Server + Killing Clients + Controlling the Screen Saver + Controlling Host Access + + Adding, Getting, or Removing Hosts + Changing, Enabling, or Disabling Access Control + + 10. Events + + Event Types + Event Structures + Event Masks + Event Processing Overview + Keyboard and Pointer Events + + Pointer Button Events + Keyboard and Pointer Events + + Window Entry/Exit Events + + Normal Entry/Exit Events + Grab and Ungrab Entry/Exit Events + + Input Focus Events + + Normal Focus Events and Focus Events While Grabbed + Focus Events Generated by Grabs + + Key Map State Notification Events + Exposure Events + + Expose Events + GraphicsExpose and NoExpose Events + + Window State Change Events + + CirculateNotify Events + ConfigureNotify Events + CreateNotify Events + DestroyNotify Events + GravityNotify Events + MapNotify Events + MappingNotify Events + ReparentNotify Events + UnmapNotify Events + VisibilityNotify Events + + Structure Control Events + + CirculateRequest Events + ConfigureRequest Events + MapRequest Events + ResizeRequest Events + + Colormap State Change Events + Client Communication Events + + ClientMessage Events + PropertyNotify Events + SelectionClear Events + SelectionRequest Events + SelectionNotify Events + + 11. Event Handling Functions + + Selecting Events + Handling the Output Buffer + Event Queue Management + Manipulating the Event Queue + + Returning the Next Event + Selecting Events Using a Predicate Procedure + Selecting Events Using a Window or Event Mask + + Putting an Event Back into the Queue + Sending Events to Other Applications + Getting Pointer Motion History + Handling Protocol Errors + + Enabling or Disabling Synchronization + Using the Default Error Handlers + + 12. Input Device Functions + + Pointer Grabbing + Keyboard Grabbing + Resuming Event Processing + Moving the Pointer + Controlling Input Focus + Manipulating the Keyboard and Pointer Settings + Manipulating the Keyboard Encoding + + 13. Locales and Internationalized Text Functions + + X Locale Management + Locale and Modifier Dependencies + Variable Argument Lists + Output Methods + + Output Method Overview + Output Method Functions + X Output Method Values + Output Context Functions + Output Context Values + Creating and Freeing a Font Set + Obtaining Font Set Metrics + Drawing Text Using Font Sets + + Input Methods + + Input Method Overview + Input Method Management + Input Method Functions + Input Method Values + Input Context Functions + Input Context Values + Input Method Callback Semantics + Event Filtering + Getting Keyboard Input + Input Method Conventions + + String Constants + + 14. Inter-Client Communication Functions + + Client to Window Manager Communication + + Manipulating Top-Level Windows + Converting String Lists + Setting and Reading Text Properties + Setting and Reading the WM_NAME Property + Setting and Reading the WM_ICON_NAME Property + Setting and Reading the WM_HINTS Property + Setting and Reading the WM_NORMAL_HINTS Property + Setting and Reading the WM_CLASS Property + Setting and Reading the WM_TRANSIENT_FOR Property + Setting and Reading the WM_PROTOCOLS Property + Setting and Reading the WM_COLORMAP_WINDOWS Property + Setting and Reading the WM_ICON_SIZE Property + Using Window Manager Convenience Functions + + Client to Session Manager Communication + + Setting and Reading the WM_COMMAND Property + Setting and Reading the WM_CLIENT_MACHINE Property + + Standard Colormaps + + Standard Colormap Properties and Atoms + Setting and Obtaining Standard Colormaps + + 15. Resource Manager Functions + + Resource File Syntax + Resource Manager Matching Rules + Quarks + Creating and Storing Databases + Merging Resource Databases + Looking Up Resources + Storing into a Resource Database + Enumerating Database Entries + Parsing Command Line Options + + 16. Application Utility Functions + + Using Keyboard Utility Functions + + KeySym Classification Macros + + Using Latin-1 Keyboard Event Functions + Allocating Permanent Storage + Parsing the Window Geometry + Manipulating Regions + + Creating, Copying, or Destroying Regions + Moving or Shrinking Regions + Computing with Regions + Determining if Regions Are Empty or Equal + Locating a Point or a Rectangle in a Region + + Using Cut Buffers + Determining the Appropriate Visual Type + Manipulating Images + Manipulating Bitmaps + Using the Context Manager + + A. Xlib Functions and Protocol Requests + B. X Font Cursors + C. Extensions + + Basic Protocol Support Routines + Hooking into Xlib + + Hooks into the Library + Hooks onto Xlib Data Structures + + GC Caching + Graphics Batching + Writing Extension Stubs + + Requests, Replies, and Xproto.h + Request Format + Starting to Write a Stub Procedure + Locking Data Structures + Sending the Protocol Request and Arguments + Variable Length Arguments + Replies + Synchronous Calling + Allocating and Deallocating Memory + Portability Considerations + Deriving the Correct Extension Opcode + + D. Compatibility Functions + + X Version 11 Compatibility Functions + + Setting Standard Properties + Setting and Getting Window Sizing Hints + Getting and Setting an XStandardColormap Structure + Parsing Window Geometry + Getting the X Environment Defaults + + X Version 10 Compatibility Functions + + Drawing and Filling Polygons and Curves + Associating User Data with a Value + + Glossary + Index + + List of Tables + + A.1. Protocol requests made by each Xlib function + A.2. Xlib functions which use each Protocol Request + +Acknowledgments + + The design and implementation of the first 10 versions of X + were primarily the work of three individuals: Robert Scheifler + of the MIT Laboratory for Computer Science and Jim Gettys of + Digital Equipment Corporation and Ron Newman of MIT, both at + MIT Project Athena. X version 11, however, is the result of the + efforts of dozens of individuals at almost as many locations + and organizations. At the risk of offending some of the players + by exclusion, we would like to acknowledge some of the people + who deserve special credit and recognition for their work on + Xlib. Our apologies to anyone inadvertently overlooked. + +Release 1 + + Our thanks does to Ron Newman (MIT Project Athena), who + contributed substantially to the design and implementation of + the Version 11 Xlib interface. + + Our thanks also goes to Ralph Swick (Project Athena and + Digital) who kept it all together for us during the early + releases. He handled literally thousands of requests from + people everywhere and saved the sanity of at least one of us. + His calm good cheer was a foundation on which we could build. + + Our thanks also goes to Todd Brunhoff (Tektronix) who was + ``loaned'' to Project Athena at exactly the right moment to + provide very capable and much-needed assistance during the + alpha and beta releases. He was responsible for the successful + integration of sources from multiple sites; we would not have + had a release without him. + + Our thanks also goes to Al Mento and Al Wojtas of Digital's + ULTRIX Documentation Group. With good humor and cheer, they + took a rough draft and made it an infinitely better and more + useful document. The work they have done will help many + everywhere. We also would like to thank Hal Murray (Digital + SRC) and Peter George (Digital VMS) who contributed much by + proofreading the early drafts of this document. + + Our thanks also goes to Jeff Dike (Digital UEG), Tom Benson, + Jackie Granfield, and Vince Orgovan (Digital VMS) who helped + with the library utilities implementation; to Hania Gajewska + (Digital UEG-WSL) who, along with Ellis Cohen (CMU and + Siemens), was instrumental in the semantic design of the window + manager properties; and to Dave Rosenthal (Sun Microsystems) + who also contributed to the protocol and provided the sample + generic color frame buffer device-dependent code. + + The alpha and beta test participants deserve special + recognition and thanks as well. It is significant that the bug + reports (and many fixes) during alpha and beta test came almost + exclusively from just a few of the alpha testers, mostly + hardware vendors working on product implementations of X. The + continued public contribution of vendors and universities is + certainly to the benefit of the entire X community. + + Our special thanks must go to Sam Fuller, Vice-President of + Corporate Research at Digital, who has remained committed to + the widest public availability of X and who made it possible to + greatly supplement MIT's resources with the Digital staff in + order to make version 11 a reality. Many of the people + mentioned here are part of the Western Software Laboratory + (Digital UEG-WSL) of the ULTRIX Engineering group and work for + Smokey Wallace, who has been vital to the project's success. + Others not mentioned here worked on the toolkit and are + acknowledged in the X Toolkit documentation. + + Of course, we must particularly thank Paul Asente, formerly of + Stanford University and now of Digital UEG-WSL, who wrote W, + the predecessor to X, and Brian Reid, formerly of Stanford + University and now of Digital WRL, who had much to do with W's + design. + + Finally, our thanks goes to MIT, Digital Equipment Corporation, + and IBM for providing the environment where it could happen. + +Release 4 + + Our thanks go to Jim Fulton (MIT X Consortium) for designing + and specifying the new Xlib functions for Inter-Client + Communication Conventions (ICCCM) support. + + We also thank Al Mento of Digital for his continued effort in + maintaining this document and Jim Fulton and Donna Converse + (MIT X Consortium) for their much-appreciated efforts in + reviewing the changes. + +Release 5 + + The principal authors of the Input Method facilities are Vania + Joloboff (Open Software Foundation) and Bill McMahon + (Hewlett-Packard). The principal author of the rest of the + internationalization facilities is Glenn Widener (Tektronix). + Our thanks to them for keeping their sense of humor through a + long and sometimes difficult design process. Although the words + and much of the design are due to them, many others have + contributed substantially to the design and implementation. Tom + McFarland (HP) and Frank Rojas (IBM) deserve particular + recognition for their contributions. Other contributors were: + Tim Anderson (Motorola), Alka Badshah (OSF), Gabe Beged-Dov + (HP), Chih-Chung Ko (III), Vera Cheng (III), Michael Collins + (Digital), Walt Daniels (IBM), Noritoshi Demizu (OMRON), + Keisuke Fukui (Fujitsu), Hitoshoi Fukumoto (Nihon Sun), Tim + Greenwood (Digital), John Harvey (IBM), Hideki Hiura (Sun), + Fred Horman (AT&T), Norikazu Kaiya (Fujitsu), Yuji Kamata + (IBM), Yutaka Kataoka (Waseda University), Ranee Khubchandani + (Sun), Akira Kon (NEC), Hiroshi Kuribayashi (OMRON), Teruhiko + Kurosaka (Sun), Seiji Kuwari (OMRON), Sandra Martin (OSF), + Narita Masahiko (Fujitsu), Masato Morisaki (NTT), Nelson Ng + (Sun), Takashi Nishimura (NTT America), Makato Nishino (IBM), + Akira Ohsone (Nihon Sun), Chris Peterson (MIT), Sam Shteingart + (AT&T), Manish Sheth (AT&T), Muneiyoshi Suzuki (NTT), Cori + Mehring (Digital), Shoji Sugiyama (IBM), and Eiji Tosa (IBM). + + We are deeply indebted to Tatsuya Kato (NTT), Hiroshi + Kuribayashi (OMRON), Seiji Kuwari (OMRON), Muneiyoshi Suzuki + (NTT), and Li Yuhong (OMRON) for producing one of the first + complete sample implementation of the internationalization + facilities, and Hiromu Inukai (Nihon Sun), Takashi Fujiwara + (Fujitsu), Hideki Hiura (Sun), Yasuhiro Kawai (Oki + Technosystems Laboratory), Kazunori Nishihara (Fuji Xerox), + Masaki Takeuchi (Sony), Katsuhisa Yano (Toshiba), Makoto + Wakamatsu (Sony Corporation) for producing the another complete + sample implementation of the internationalization facilities. + + The principal authors (design and implementation) of the Xcms + color management facilities are Al Tabayoyon (Tektronix) and + Chuck Adams (Tektronix). Joann Taylor (Tektronix), Bob Toole + (Tektronix), and Keith Packard (MIT X Consortium) also + contributed significantly to the design. Others who contributed + are: Harold Boll (Kodak), Ken Bronstein (HP), Nancy Cam (SGI), + Donna Converse (MIT X Consortium), Elias Israel (ISC), Deron + Johnson (Sun), Jim King (Adobe), Ricardo Motta (HP), Chuck Peek + (IBM), Wil Plouffe (IBM), Dave Sternlicht (MIT X Consortium), + Kumar Talluri (AT&T), and Richard Verberg (IBM). + + We also once again thank Al Mento of Digital for his work in + formatting and reformatting text for this manual, and for + producing man pages. Thanks also to Clive Feather (IXI) for + proof-reading and finding a number of small errors. + +Release 6 + + Stephen Gildea (X Consortium) authored the threads support. + Ovais Ashraf (Sun) and Greg Olsen (Sun) contributed + substantially by testing the facilities and reporting bugs in a + timely fashion. + + The principal authors of the internationalization facilities, + including Input and Output Methods, are Hideki Hiura (SunSoft) + and Shigeru Yamada (Fujitsu OSSI). Although the words and much + of the design are due to them, many others have contributed + substantially to the design and implementation. They are: + Takashi Fujiwara (Fujitsu), Yoshio Horiuchi (IBM), Makoto Inada + (Digital), Hiromu Inukai (Nihon SunSoft), Song JaeKyung + (KAIST), Franky Ling (Digital), Tom McFarland (HP), Hiroyuki + Miyamoto (Digital), Masahiko Narita (Fujitsu), Frank Rojas + (IBM), Hidetoshi Tajima (HP), Masaki Takeuchi (Sony), Makoto + Wakamatsu (Sony), Masaki Wakao (IBM), Katsuhisa Yano(Toshiba) + and Jinsoo Yoon (KAIST). + + The principal producers of the sample implementation of the + internationalization facilities are: Jeffrey Bloomfield + (Fujitsu OSSI), Takashi Fujiwara (Fujitsu), Hideki Hiura + (SunSoft), Yoshio Horiuchi (IBM), Makoto Inada (Digital), + Hiromu Inukai (Nihon SunSoft), Song JaeKyung (KAIST), Riki + Kawaguchi (Fujitsu), Franky Ling (Digital), Hiroyuki Miyamoto + (Digital), Hidetoshi Tajima (HP), Toshimitsu Terazono + (Fujitsu), Makoto Wakamatsu (Sony), Masaki Wakao (IBM), Shigeru + Yamada (Fujitsu OSSI) and Katsuhisa Yano (Toshiba). + + The coordinators of the integration, testing, and release of + this implementation of the internationalization facilities are + Nobuyuki Tanaka (Sony) and Makoto Wakamatsu (Sony). + + Others who have contributed to the architectural design or + testing of the sample implementation of the + internationalization facilities are: Hector Chan (Digital), + Michael Kung (IBM), Joseph Kwok (Digital), Hiroyuki Machida + (Sony), Nelson Ng (SunSoft), Frank Rojas (IBM), Yoshiyuki + Segawa (Fujitsu OSSI), Makiko Shimamura (Fujitsu), Shoji + Sugiyama (IBM), Lining Sun (SGI), Masaki Takeuchi (Sony), + Jinsoo Yoon (KAIST) and Akiyasu Zen (HP). + + Jim Gettys + Cambridge Research Laboratory + Digital Equipment Corporation + Robert W. Scheifler + Laboratory for Computer Science + Massachusetts Institute of Technology + +Release 7 + + This document is made available to you in modern formats such + as HTML and PDF thanks to the efforts of Matt Dew, who + converted the original troff sources to DocBook/XML and edited + them into shape; along with Gaetan Nadon and Alan Coopersmith, + who set up the formatting machinery in the libX11 builds and + performed further editing of the DocBook markup. + +Chapter 1. Introduction to Xlib + + Table of Contents + + 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 + + The X Window System is a network-transparent window system that + was designed at MIT. X display servers run on computers with + either monochrome or color bitmap display hardware. The server + distributes user input to and accepts output requests from + various client programs located either on the same machine or + elsewhere in the network. Xlib is a C subroutine library that + application programs (clients) use to interface with the window + system by means of a stream connection. Although a client + usually runs on the same machine as the X server it is talking + to, this need not be the case. + + Xlib - C Language X Interface is a reference guide to the + low-level C language interface to the X Window System protocol. + It is neither a tutorial nor a user's guide to programming the + X Window System. Rather, it provides a detailed description of + each function in the library as well as a discussion of the + related background information. Xlib - C Language X Interface + assumes a basic understanding of a graphics window system and + of the C programming language. Other higher-level abstractions + (for example, those provided by the toolkits for X) are built + on top of the Xlib library. For further information about these + higher-level libraries, see the appropriate toolkit + documentation. The X Window System Protocol provides the + definitive word on the behavior of X. Although additional + information appears here, the protocol document is the ruling + document. + + To provide an introduction to X programming, this chapter + discusses: + * 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 + +Overview of the X Window System + + Some of the terms used in this book are unique to X, and other + terms that are common to other window systems have different + meanings in X. You may find it helpful to refer to the + glossary, which is located at the end of the book. + + The X Window System supports one or more screens containing + overlapping windows or subwindows. A screen is a physical + monitor and hardware that can be color, grayscale, or + monochrome. There can be multiple screens for each display or + workstation. A single X server can provide display services for + any number of screens. A set of screens for a single user with + one keyboard and one pointer (usually a mouse) is called a + display. + + All the windows in an X server are arranged in strict + hierarchies. At the top of each hierarchy is a root window, + which covers each of the display screens. Each root window is + partially or completely covered by child windows. All windows, + except for root windows, have parents. There is usually at + least one window for each application program. Child windows + may in turn have their own children. In this way, an + application program can create an arbitrarily deep tree on each + screen. X provides graphics, text, and raster operations for + windows. + + A child window can be larger than its parent. That is, part or + all of the child window can extend beyond the boundaries of the + parent, but all output to a window is clipped by its parent. If + several children of a window have overlapping locations, one of + the children is considered to be on top of or raised over the + others, thus obscuring them. Output to areas covered by other + windows is suppressed by the window system unless the window + has backing store. If a window is obscured by a second window, + the second window obscures only those ancestors of the second + window that are also ancestors of the first window. + + A window has a border zero or more pixels in width, which can + be any pattern (pixmap) or solid color you like. A window + usually but not always has a background pattern, which will be + repainted by the window system when uncovered. Child windows + obscure their parents, and graphic operations in the parent + window usually are clipped by the children. + + Each window and pixmap has its own coordinate system. The + coordinate system has the X axis horizontal and the Y axis + vertical with the origin [0, 0] at the upper-left corner. + Coordinates are integral, in terms of pixels, and coincide with + pixel centers. For a window, the origin is inside the border at + the inside, upper-left corner. + + X does not guarantee to preserve the contents of windows. When + part or all of a window is hidden and then brought back onto + the screen, its contents may be lost. The server then sends the + client program an Expose event to notify it that part or all of + the window needs to be repainted. Programs must be prepared to + regenerate the contents of windows on demand. + + X also provides off-screen storage of graphics objects, called + pixmaps. Single plane (depth 1) pixmaps are sometimes referred + to as bitmaps. Pixmaps can be used in most graphics functions + interchangeably with windows and are used in various graphics + operations to define patterns or tiles. Windows and pixmaps + together are referred to as drawables. + + Most of the functions in Xlib just add requests to an output + buffer. These requests later execute asynchronously on the X + server. Functions that return values of information stored in + the server do not return (that is, they block) until an + explicit reply is received or an error occurs. You can provide + an error handler, which will be called when the error is + reported. + + If a client does not want a request to execute asynchronously, + it can follow the request with a call to XSync, which blocks + until all previously buffered asynchronous events have been + sent and acted on. As an important side effect, the output + buffer in Xlib is always flushed by a call to any function that + returns a value from the server or waits for input. + + Many Xlib functions will return an integer resource ID, which + allows you to refer to objects stored on the X server. These + can be of type Window, Font, Pixmap, Colormap, Cursor, and + GContext, as defined in the file . These resources are + created by requests and are destroyed (or freed) by requests or + when connections are closed. Most of these resources are + potentially sharable between applications, and in fact, windows + are manipulated explicitly by window manager programs. Fonts + and cursors are shared automatically across multiple screens. + Fonts are loaded and unloaded as needed and are shared by + multiple clients. Fonts are often cached in the server. Xlib + provides no support for sharing graphics contexts between + applications. + + Client programs are informed of events. Events may either be + side effects of a request (for example, restacking windows + generates Expose events) or completely asynchronous (for + example, from the keyboard). A client program asks to be + informed of events. Because other applications can send events + to your application, programs must be prepared to handle (or + ignore) events of all types. + + Input events (for example, a key pressed or the pointer moved) + arrive asynchronously from the server and are queued until they + are requested by an explicit call (for example, XNextEvent or + XWindowEvent). In addition, some library functions (for + example, XRaiseWindow) generate Expose and ConfigureRequest + events. These events also arrive asynchronously, but the client + may wish to explicitly wait for them by calling XSync after + calling a function that can cause the server to generate + events. + +Errors + + Some functions return Status, an integer error indication. If + the function fails, it returns a zero. If the function returns + a status of zero, it has not updated the return arguments. + Because C does not provide multiple return values, many + functions must return their results by writing into + client-passed storage. By default, errors are handled either by + a standard library function or by one that you provide. + Functions that return pointers to strings return NULL pointers + if the string does not exist. + + The X server reports protocol errors at the time that it + detects them. If more than one error could be generated for a + given request, the server can report any of them. + + Because Xlib usually does not transmit requests to the server + immediately (that is, it buffers them), errors can be reported + much later than they actually occur. For debugging purposes, + however, Xlib provides a mechanism for forcing synchronous + behavior (see section 11.8.1). When synchronization is enabled, + errors are reported as they are generated. + + When Xlib detects an error, it calls an error handler, which + your program can provide. If you do not provide an error + handler, the error is printed, and your program terminates. + +Standard Header Files + + The following include files are part of the Xlib standard: + + + + This is the main header file for Xlib. The majority of all Xlib + symbols are declared by including this file. This file also + contains the preprocessor symbol XlibSpecificationRelease. This + symbol is defined to have the 6 in this release of the + standard. (Release 5 of Xlib was the first release to have this + symbol.) + + + + This file declares types and constants for the X protocol that + are to be used by applications. It is included automatically + from so application code should never need to + reference this file directly. + + + + This file contains symbols for much of the color management + facilities described in chapter 6. All functions, types, and + symbols with the prefix "Xcms", plus the Color Conversion + Contexts macros, are declared in this file. must + be included before including this file. + + + + This file declares various functions, types, and symbols used + for inter-client communication and application utility + functions, which are described in chapters 14 and 16. + must be included before including this file. + + + + This file declares all functions, types, and symbols for the + resource manager facilities, which are described in chapter 15. + must be included before including this file. + + + + This file declares all predefined atoms, which are symbols with + the prefix "XA_". + + + + This file declares the cursor symbols for the standard cursor + font, which are listed in Appendix B. All cursor symbols have + the prefix "XC_". + + + + This file declares all standard KeySym values, which are + symbols with the prefix "XK_". The KeySyms are arranged in + groups, and a preprocessor symbol controls inclusion of each + group. The preprocessor symbol must be defined prior to + inclusion of the file to obtain the associated values. The + preprocessor symbols are XK_MISCELLANY, XK_XKB_KEYS, XK_3270, + XK_LATIN1, XK_LATIN2, XK_LATIN3, XK_LATIN4, XK_KATAKANA, + XK_ARABIC, XK_CYRILLIC, XK_GREEK, XK_TECHNICAL, XK_SPECIAL, + XK_PUBLISHING, XK_APL, XK_HEBREW, XK_THAI, and XK_KOREAN. + + + + This file defines the preprocessor symbols XK_MISCELLANY, + XK_XKB_KEYS, XK_LATIN1, XK_LATIN2, XK_LATIN3, XK_LATIN4, and + XK_GREEK and then includes . + + + + This file declares all the functions, types, and symbols used + for extensions, which are described in Appendix C. This file + automatically includes . + + + + This file declares types and symbols for the basic X protocol, + for use in implementing extensions. It is included + automatically from , so application and + extension code should never need to reference this file + directly. + + + + This file declares types and symbols for the basic X protocol, + for use in implementing extensions. It is included + automatically from , so application and extension + code should never need to reference this file directly. + + + + This file declares all the functions, types, and symbols used + for the X10 compatibility functions, which are described in + Appendix D. + +Generic Values and Types + + The following symbols are defined by Xlib and used throughout + the manual: + * Xlib defines the type Bool and the Boolean values True and + False. + * None is the universal null resource ID or atom. + * The type XID is used for generic resource IDs. + * The type XPointer is defined to be char* and is used as a + generic opaque pointer to data. + +Naming and Argument Conventions within Xlib + + Xlib follows a number of conventions for the naming and syntax + of the functions. Given that you remember what information the + function requires, these conventions are intended to make the + syntax of the functions more predictable. + + The major naming conventions are: + * 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 dereference + begins with a capital X. + * Macros and other symbols do not begin with a capital X. To + distinguish them from all user symbols, each word in the + macro is capitalized. + * All elements of or variables in a data structure are in + lowercase. Compound words, where needed, are constructed + with underscores (_). + * The display argument, where used, is always first in the + argument list. + * All resource objects, where used, occur at the beginning 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 arguments + 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. + * Where a mask is accompanied with a structure, the mask + always precedes the pointer to the structure in the + argument list. + +Programming Considerations + + The major programming considerations are: + * Coordinates and sizes in X are actually 16-bit quantities. + This decision was made to minimize the bandwidth required + for a given level of performance. Coordinates usually are + declared as an int in the interface. Values 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 their screen real estate. + Therefore, you should write your applications to react to + window management rather than presume control of the entire + screen. What you do inside of your top-level window, + however, is up to your application. For further + information, see chapter 14 and the Inter-Client + Communication Conventions Manual. + +Character Sets and Encodings + + Some of the Xlib functions make reference to specific character + 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 contains the following + characters: + + a..z A..Z 0..9 !"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~ , + , and + + This set is the left/lower half of the graphic character set of + ISO8859-1 plus space, tab, and newline. It is also the set of + graphic characters in 7-bit ASCII plus the same three control + characters. The actual encoding of these characters on the host + is system dependent. + + Host Portable Character Encoding + + The encoding of the X Portable Character Set on the host. The + encoding itself is not defined by this standard, but the + encoding must be the same in all locales supported by Xlib on + the host. If a string is said to be in the Host Portable + Character Encoding, then it only contains characters from the X + Portable Character Set, in the host encoding. + + Latin-1 + + The coded character set defined by the ISO8859-1 standard. + + Latin Portable Character Encoding + + The encoding of the X Portable Character Set using the Latin-1 + codepoints plus ASCII control characters. If a string is said + to be in the Latin Portable Character Encoding, then it only + contains characters from the X Portable Character Set, not all + of Latin-1. + + STRING Encoding + + Latin-1, plus tab and newline. + + POSIX Portable Filename Character Set + + The set of 65 characters, which can be used in naming files on + a POSIX-compliant host, that are correctly processed in all + locales. The set is: + + a..z A..Z 0..9 ._- + +Formatting Conventions + + Xlib - C Language X Interface uses the following conventions: + * Global symbols are printed in this special font. These can + be either function names, symbols defined in include files, + or structure names. When declared and defined, function + arguments are printed in italics. 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 function + declaration itself follows, and each argument is + specifically explained. Although ANSI C function prototype + syntax is not used, Xlib header files normally declare + functions using function prototypes in ANSI C environments. + General discussion of the function, if any is required, + follows the arguments. Where applicable, the last paragraph + of the explanation lists the possible Xlib error codes that + the function can generate. For a complete discussion of the + Xlib error codes, see section 11.8.2. + * 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 specifies or, in the case of multiple arguments, the + word specify. The explanations for all arguments that are + returned to you start with the word returns or, in the case + of multiple arguments, the word return. The explanations + for all arguments that you can pass and are returned start + with the words specifies and returns. + * Any pointer to a structure that is used to return a value + is designated as such by the _return 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 _in_out suffix. + +Chapter 2. Display Functions + + Table of Contents + + Opening the Display + Obtaining Information about the Display, Image Formats, or + Screens + + Display Macros + Image Format Functions and Macros + Screen Information Macros + + Generating a NoOperation Protocol Request + Freeing Client-Created Data + Closing the Display + Using X Server Connection Close Operations + Using Xlib with Threads + Using Internal Connections + + 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 NoOperation protocol request + * Free client-created data + * Close (disconnect from) a display + * Use X Server connection close operations + * Use Xlib with threads + * Use internal connections + +Opening the Display + + To open a connection to the X server that controls a display, + use XOpenDisplay. + + Display *XOpenDisplay(char *display_name); + + display_name + + Specifies the hardware display name, which determines the + display and communications domain to be used. On a + POSIX-conformant system, if the display_name is NULL, it + defaults to the value of the DISPLAY environment variable. + + The encoding and interpretation of the display name are + implementation-dependent. Strings in the Host Portable + Character Encoding are supported; support for other characters + is implementation-dependent. On POSIX-conformant systems, the + display name or DISPLAY environment variable can be a string in + the format: + + + protocol/hostname:number.screen_number + + protocol + + Specifies a protocol family or an alias for a protocol 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. + + hostname + + 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 (::). + + number + + Specifies the number of the display server on that host + machine. You may optionally follow this display number with a + period (.). A single CPU can have more than one display. + Multiple displays are usually numbered starting with zero. + + screen_number + + Specifies the screen to be used on that server. Multiple + screens can be controlled by a single X server. The + screen_number sets an internal variable that can be accessed by + using the DefaultScreen macro or the XDefaultScreen function if + you are using languages other than C (see section 2.2.1). + + For example, the following would specify screen 1 of display 0 + on the machine named ``dual-headed'': + +dual-headed:0.1 + + The XOpenDisplay function returns a Display structure that + serves as the connection to the X server and that contains all + the information about that X server. XOpenDisplay connects your + application to the X server through TCP or DECnet + communications protocols, or through some local inter-process + communication protocol. If the protocol is specified as "tcp", + "inet", or "inet6", or if no protocol is specified and the + hostname is a host machine name and a single colon (:) + separates the hostname and display number, XOpenDisplay + connects using TCP streams. (If the protocol is specified as + "inet", TCP over IPv4 is used. If the protocol is specified as + "inet6", TCP over IPv6 is used. Otherwise, the implementation + determines which IP version is used.) If the hostname and + protocol are both not specified, Xlib uses whatever it believes + is the fastest transport. If the hostname is a host machine + name and a double colon (::) separates the hostname and display + number, XOpenDisplay connects using DECnet. A single X server + can support any or all of these transport mechanisms + simultaneously. A particular Xlib implementation can support + many more of these transport mechanisms. + + If successful, XOpenDisplay returns a pointer to a Display + structure, which is defined in . If XOpenDisplay + does not succeed, it returns NULL. After a successful call to + XOpenDisplay, all of the screens in the display can be used by + the client. The screen number specified in the display_name + argument is returned by the DefaultScreen macro (or the + XDefaultScreen function). You can access elements of the + Display and Screen structures only by using the information + macros or functions. For information about using macros and + functions to obtain information from the Display structure, see + section 2.2.1. + + X servers may implement various types of access control + mechanisms (see section 9.8). + +Obtaining Information about the Display, Image Formats, or Screens + + The Xlib library provides a number of useful macros and + corresponding functions that return data from the Display + structure. The macros are used for C programming, and their + corresponding function equivalents are for other language + bindings. This section discusses the: + * Display macros + * Image format functions and macros + * Screen information macros + + All other members of the Display structure (that is, those for + which no macros are defined) are private to Xlib and must not + be used. Applications must never directly modify or inspect + these private members of the Display structure. The + XDisplayWidth, XDisplayHeight, XDisplayCells, XDisplayPlanes, + XDisplayWidthMM, and XDisplayHeightMM functions in the next + sections are misnamed. These functions really should be named + Screenwhatever and XScreenwhatever, not Displaywhatever or + XDisplaywhatever. Our apologies for the resulting confusion. + +Display Macros + + Applications should not directly modify any part of the Display + and Screen structures. The members should be considered + read-only, although they may change as the result of other + operations on the display. + + The following lists the C language macros, their corresponding + function equivalents that are for other language bindings, and + what data both can return. +AllPlanes + + unsigned long XAllPlanes(void); + + Both return a value with all bits set to 1 suitable for use in + a plane argument to a procedure. + + Both BlackPixel and WhitePixel can be used in implementing a + monochrome application. These pixel values are for permanently + allocated entries in the default colormap. The actual RGB (red, + green, and blue) values are settable on some screens and, in + any case, may not actually be black or white. The names are + intended to convey the expected relative intensity of the + colors. + + BlackPixel(display, screen_number); + + unsigned long XBlackPixel(Display *display, int screen_number); + + display + + Specifies the connection to the X server. + + screen_number + + Specifies the appropriate screen number on the host server. + + Both return the black pixel value for the specified screen. + + WhitePixel(display, screen_number); + + unsigned long XWhitePixel(Display *display, int screen_number); + + display + + Specifies the connection to the X server. + + screen_number + + Specifies the appropriate screen number on the host server. + + Both return the white pixel value for the specified screen. + + ConnectionNumber(display); + + int XConnectionNumber(Display *display); + + display + + 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(display, screen_number); + + Colormap XDefaultColormap(Display *display, int screen_number); + + display + + Specifies the connection to the X server. + + screen_number + + Specifies the appropriate screen number on the host server. + + Both return the default colormap ID for allocation on the + specified screen. Most routine allocations of color should be + made out of this colormap. + + DefaultDepth(display, screen_number); + + int XDefaultDepth(Display *display, int screen_number); + + display + + Specifies the connection to the X server. + + screen_number + + Specifies the appropriate screen number on the host server. + + Both return the depth (number of planes) of the default root + window for the specified screen. Other depths may also be + supported on this screen (see XMatchVisualInfo). + + To determine the number of depths that are available on a given + screen, use XListDepths. + + int *XListDepths(Display *display, int screen_number, int + *count_return); + + display + + Specifies the connection to the X server. + + screen_number + + Specifies the appropriate screen number on the host server. + + count_return + + Returns the number of depths. + + The XListDepths function returns the array of depths that are + available on the specified screen. If the specified + screen_number is valid and sufficient memory for the array can + be allocated, XListDepths sets count_return to the number of + available depths. Otherwise, it does not set count_return and + returns NULL. To release the memory allocated for the array of + depths, use XFree. + + DefaultGC(display, screen_number); + + GC XDefaultGC(Display *display, int screen_number); + + display + + Specifies the connection to the X server. + + screen_number + + Specifies the appropriate screen number on the host server. + + Both return the default graphics context for the root window of + the specified screen. This GC is created for the convenience of + simple applications and contains the default GC components with + the foreground and background pixel values initialized to the + black and white pixels for the screen, respectively. You can + modify its contents freely because it is not used in any Xlib + function. This GC should never be freed. + + DefaultRootWindow(display); + + Window XDefaultRootWindow(Display *display); + + display + + Specifies the connection to the X server. + + Both return the root window for the default screen. + + DefaultScreenOfDisplay(display); + + Screen *XDefaultScreenOfDisplay(Display *display); + + display + + Specifies the connection to the X server. + + Both return a pointer to the default screen. + + ScreenOfDisplay(display, screen_number); + + Screen *XScreenOfDisplay(Display *display, int screen_number); + + display + + Specifies the connection to the X server. + + screen_number + + Specifies the appropriate screen number on the host server. + + Both return a pointer to the indicated screen. + + DefaultScreen(display); + + int XDefaultScreen(Display *display); + + display + + Specifies the connection to the X server. + + Both return the default screen number referenced by the + XOpenDisplay function. This macro or function should be used to + retrieve the screen number in applications that will use only a + single screen. + + DefaultVisual(display, screen_number); + + Visual *XDefaultVisual(Display *display, int screen_number); + + display + + Specifies the connection to the X server. + + screen_number + + Specifies the appropriate screen number on the host server. + + Both return the default visual type for the specified screen. + For further information about visual types, see section 3.1. + + DisplayCells(display, screen_number); + + int XDisplayCells(Display *display, int screen_number); + + display + + Specifies the connection to the X server. + + screen_number + + Specifies the appropriate screen number on the host server. + + Both return the number of entries in the default colormap. + + DisplayPlanes(display, screen_number); + + int XDisplayPlanes(Display *display, int screen_number); + + display + + Specifies the connection to the X server. + + screen_number + + Specifies the appropriate screen number on the host server. + + Both return the depth of the root window of the specified + screen. For an explanation of depth, see the glossary. + + DisplayString(display); + + char *XDisplayString(Display *display); + + display + + Specifies the connection to the X server. + + Both return the string that was passed to XOpenDisplay when the + current display was opened. On POSIX-conformant systems, if the + passed string was NULL, these return the value of the DISPLAY + environment variable when the current display was opened. These + are useful to applications that invoke the fork system call and + want to open a new connection to the same display from the + child process as well as for printing error messages. + + long XExtendedMaxRequestSize(Display *display); + + display + + Specifies the connection to the X server. + + The XExtendedMaxRequestSize function returns zero if the + specified display does not support an extended-length protocol + encoding; otherwise, it returns the maximum request size (in + 4-byte units) supported by the server using the extended-length + encoding. The Xlib functions XDrawLines, XDrawArcs, + XFillPolygon, XChangeProperty, XSetClipRectangles, and + XSetRegion will use the extended-length encoding as necessary, + if supported by the server. Use of the extended-length encoding + in other Xlib functions (for example, XDrawPoints, + XDrawRectangles, XDrawSegments, XFillArcs, XFillRectangles, + XPutImage) is permitted but not required; an Xlib + implementation may choose to split the data across multiple + smaller requests instead. + + long XMaxRequestSize(Display *display); + + display + + Specifies the connection to the X server. + + The XMaxRequestSize function returns the maximum request size + (in 4-byte units) supported by the server without using an + extended-length protocol encoding. Single protocol requests to + the server can be no larger than this size unless an + extended-length protocol encoding is supported by the server. + The protocol guarantees the size to be no smaller than 4096 + units (16384 bytes). Xlib automatically breaks data up into + multiple protocol requests as necessary for the following + functions: XDrawPoints, XDrawRectangles, XDrawSegments, + XFillArcs, XFillRectangles, and XPutImage. + + LastKnownRequestProcessed(display); + + unsigned long XLastKnownRequestProcessed(Display *display); + + display + + 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(display); + + unsigned long XNextRequest(Display *display); + + display + + 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(display); + + int XProtocolVersion(Display *display); + + display + + Specifies the connection to the X server. + + Both return the major version number (11) of the X protocol + associated with the connected display. + + ProtocolRevision(display); + + int XProtocolRevision(Display *display); + + display + + Specifies the connection to the X server. + + Both return the minor protocol revision number of the X server. + + QLength(display); + + int XQLength(Display *display); + + display + + 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 XEventsQueued). + + RootWindow(display, screen_number); + + Window XRootWindow(Display *display, int screen_number); + + display + + Specifies the connection to the X server. + + screen_number + + Specifies the appropriate screen number on the host server. + + Both return the root window. These are useful with functions + that need a drawable of a particular screen and for creating + top-level windows. + + ScreenCount(display); + + int XScreenCount(Display *display); + + display + + Specifies the connection to the X server. + + Both return the number of available screens. + + ServerVendor(display); + + char *XServerVendor(Display *display); + + display + + Specifies the connection to the X server. + + Both return a pointer to a null-terminated string that provides + some identification of the owner of the X server + implementation. If the data returned by the server is in the + Latin Portable Character Encoding, then the string is in the + Host Portable Character Encoding. Otherwise, the contents of + the string are implementation-dependent. + + VendorRelease(display); + + int XVendorRelease(Display *display); + + display + + Specifies the connection to the X server. + + Both return a number related to a vendor's release of the X + server. + +Image Format Functions and Macros + + Applications are required to present data to the X server in a + format that the server demands. To help simplify applications, + most of the work required to convert the data is provided by + Xlib (see sections 8.7 and 16.8). + + The XPixmapFormatValues structure provides an interface to the + pixmap format information that is returned at the time of a + connection setup. It contains: +typedef struct { + int depth; + int bits_per_pixel; + int scanline_pad; +} XPixmapFormatValues; + + To obtain the pixmap format information for a given display, + use XListPixmapFormats. + + XPixmapFormatValues *XListPixmapFormats(Display *display, int + *count_return); + + display + + Specifies the connection to the X server. + + count_return + + Returns the number of pixmap formats that are supported by the + display. + + The XListPixmapFormats function returns an array of + XPixmapFormatValues structures that describe the types of Z + format images supported by the specified display. If + insufficient memory is available, XListPixmapFormats returns + NULL. To free the allocated storage for the XPixmapFormatValues + structures, use XFree. + + The following lists the C language macros, their corresponding + function equivalents that are for other language bindings, and + what data they both return for the specified server and screen. + These are often used by toolkits as well as by simple + applications. + + ImageByteOrder(display); + + int XImageByteOrder(Display *display); + + display + + 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 LSBFirst or + MSBFirst. + + XBitmapUnit(display); + + int XBitmapUnit(Display *display); + + display + + 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(display); + + int XBitmapBitOrder(Display *display); + + display + + 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 + LSBFirst or MSBFirst. + + BitmapPad(display); + + int XBitmapPad(Display *display); + + display + + Specifies the connection to the X server. + + Each scanline must be padded to a multiple of bits returned by + this macro or function. + + DisplayHeight(display, screen_number); + + int XDisplayHeight(Display *display, int screen_number); + + display + + Specifies the connection to the X server. + + screen_number + + Specifies the appropriate screen number on the host server. + + Both return an integer that describes the height of the screen + in pixels. + + DisplayHeightMM(display, screen_number); + + int XDisplayHeightMM(Display *display, int screen_number); + + display + + Specifies the connection to the X server. + + screen_number + + Specifies the appropriate screen number on the host server. + + Both return the height of the specified screen in millimeters. + + DisplayWidth(display, screen_number); + + int XDisplayWidth(Display *display, int screen_number); + + display + + Specifies the connection to the X server. + + screen_number + + Specifies the appropriate screen number on the host server. + + Both return the width of the screen in pixels. + + DisplayWidthMM(display, screen_number); + + int XDisplayWidthMM(Display *display, int screen_number); + + display + + Specifies the connection to the X server. + + screen_number + + Specifies the appropriate screen number on the host server. + + Both return the width of the specified screen in millimeters. + +Screen Information Macros + + The following lists the C language macros, their corresponding + function equivalents that are for other language bindings, and + what data they both can return. These macros or functions all + take a pointer to the appropriate screen structure. + + BlackPixelOfScreen(screen); + + unsigned long XBlackPixelOfScreen(Screen *screen); + + screen + + Specifies the appropriate Screen structure. + + Both return the black pixel value of the specified screen. + + XWhitePixelOfScreen(screen); + + unsigned long XWhitePixelOfScreen(Screen *screen); + + screen + + Specifies the appropriate Screen structure. + + Both return the white pixel value of the specified screen. + + CellsOfScreen(screen); + + int XCellsOfScreen(Screen *screen); + + screen + + Specifies the appropriate Screen structure. + + Both return the number of colormap cells in the default + colormap of the specified screen. + + DefaultColormapOfScreen(screen); + + Colormap XDefaultColormapOfScreen(Screen *screen); + + screen + + Specifies the appropriate Screen structure. + + Both return the default colormap of the specified screen. + + DefaultDepthOfScreen(screen); + + int XDefaultDepthOfScreen(Screen *screen); + + screen + + Specifies the appropriate Screen structure. + + Both return the depth of the root window. + + DefaultGCOfScreen(screen); + + GC XDefaultGCOfScreen(Screen *screen); + + screen + + Specifies the appropriate Screen 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. + + XDefaultVisualOfScreen(screen); + + Visual *XDefaultVisualOfScreen(Screen *screen); + + screen + + Specifies the appropriate Screen structure. + + Both return the default visual of the specified screen. For + information on visual types, see section 3.1. + + DoesBackingStore(screen); + + int XDoesBackingStore(Screen *screen); + + screen + + Specifies the appropriate Screen structure. + + Both return a value indicating whether the screen supports + backing stores. The value returned can be one of WhenMapped, + NotUseful, or Always (see section 3.2.4). + + DoesSaveUnders(screen); + + Bool XDoesSaveUnders(Screen *screen); + + screen + + Specifies the appropriate Screen structure. + + Both return a Boolean value indicating whether the screen + supports save unders. If True, the screen supports save unders. + If False, the screen does not support save unders (see section + 3.2.5). + + DisplayOfScreen(screen); + + Display *XDisplayOfScreen(Screen *screen); + + screen + + Specifies the appropriate Screen structure. + + Both return the display of the specified screen. + + ScreenNumberOfScreen(screen); + + long XScreenNumberOfScreen(Screen *screen); + + screen + + Specifies the appropriate Screen structure. + + The XScreenNumberOfScreen function returns the screen index + number of the specified screen. + + EventMaskOfScreen(screen); + + long XEventMaskOfScreen(Screen *screen); + + screen + + Specifies the appropriate Screen structure. + + Both return the event mask of the root window for the specified + screen at connection setup time. + + WidthOfScreen(screen); + + int XWidthOfScreen(Screen *screen); + + screen + + Specifies the appropriate Screen structure. + + Both return the width of the specified screen in pixels. + + HeightOfScreen(screen); + + int XHeightOfScreen(Screen *screen); + + screen + + Specifies the appropriate Screen structure. + + Both return the height of the specified screen in pixels. + + WidthMMOfScreen(screen); + + int XWidthMMOfScreen(Screen *screen); + + screen + + Specifies the appropriate Screen structure. + + Both return the width of the specified screen in millimeters. + + HeightMMOfScreen(screen); + + int XHeightMMOfScreen(Screen *screen); + + screen + + Specifies the appropriate Screen structure. + + Both return the height of the specified screen in millimeters. + + MaxCmapsOfScreen(screen); + + int XMaxCmapsOfScreen(Screen *screen); + + screen + + Specifies the appropriate Screen structure. + + Both return the maximum number of installed colormaps supported + by the specified screen (see section 9.3). + + MinCmapsOfScreen(screen); + + int XMinCmapsOfScreen(Screen *screen); + + screen + + Specifies the appropriate Screen structure. + + Both return the minimum number of installed colormaps supported + by the specified screen (see section 9.3). + + PlanesOfScreen(screen); + + int XPlanesOfScreen(Screen *screen); + + screen + + Specifies the appropriate Screen structure. + + Both return the depth of the root window. + + RootWindowOfScreen(screen); + + Window XRootWindowOfScreen(Screen *screen); + + screen + + Specifies the appropriate Screen structure. + + Both return the root window of the specified screen. + +Generating a NoOperation Protocol Request + + To execute a NoOperation protocol request, use XNoOp. + + XNoOp(Display *display); + + display + + Specifies the connection to the X server. + + The XNoOp function sends a NoOperation protocol request to the + X server, thereby exercising the connection. + +Freeing Client-Created Data + + To free in-memory data that was created by an Xlib function, + use XFree. + + XFree(void *data); + + data + + Specifies the data that is to be freed. + + The XFree function is a general-purpose Xlib routine that frees + the specified data. You must use it to free any objects that + were allocated by Xlib, unless an alternate function is + explicitly specified for the object. A NULL pointer cannot be + passed to this function. + +Closing the Display + + To close a display or disconnect from the X server, use + XCloseDisplay. + + XCloseDisplay(Display *display); + + display + + Specifies the connection to the X server. + + The XCloseDisplay function closes the connection to the X + server for the display specified in the Display structure and + destroys all windows, resource IDs (Window, Font, Pixmap, + Colormap, Cursor, and GContext), or other resources that the + client has created on this display, unless the close-down mode + of the client has been changed (see XSetCloseDownMode). + Therefore, these windows, resource IDs, and other resources + should never be referenced again or an error will be generated. + Before exiting, you should call XCloseDisplay explicitly so + that any pending errors are reported as XCloseDisplay performs + a final XSync operation. + + XCloseDisplay can generate a BadGC error. + + Xlib provides a function to permit the resources owned by a + client to survive after the client's connection is closed. To + change a client's close-down mode, use XSetCloseDownMode. + + XSetCloseDownMode(Display *display, int close_mode); + + display + + Specifies the connection to the X server. + + close_mode + + Specifies the client close-down mode. You can pass DestroyAll, + RetainPermanent, or RetainTemporary. + + The XSetCloseDownMode function defines what will happen to the + client's resources at connection close. A connection starts in + DestroyAll mode. For information on what happens to the + client's resources when the close_mode argument is + RetainPermanent or RetainTemporary, see section 2.6. + + XSetCloseDownMode can generate a BadValue error. + +Using X Server Connection Close Operations + + When the X server's connection to a client is closed either by + an explicit call to XCloseDisplay or by a process that exits, + the X server performs the following automatic operations: + * It disowns all selections owned by the client (see + XSetSelectionOwner). + * It performs an XUngrabPointer and XUngrabKeyboard if the + client has actively grabbed the pointer or the keyboard. + * It performs an XUngrabServer 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 temporary, + depending on whether the close-down mode is RetainPermanent + or RetainTemporary. However, this does not prevent other + client applications from explicitly destroying the + resources (see XSetCloseDownMode). + + When the close-down mode is DestroyAll, 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 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 MapWindow 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 nonwindow + resource created by the client in the server (for example, + Font, Pixmap, Cursor, Colormap, and GContext). + * It frees all colors and colormap entries allocated by a + client application. + + Additional processing occurs when the last connection to the X + server closes. An X server goes through a cycle of having no + connections and having some connections. When the last + connection to the X server closes as a result of a connection + closing with the close_mode of DestroyAll, the X server does + the following: + * 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 RetainPermanent or + RetainTemporary mode. + * It deletes all but the predefined atom identifiers. + * It deletes all properties on all root windows (see section + 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 PointerRoot. + + However, the X server does not reset if you close a connection + with a close-down mode set to RetainPermanent or + RetainTemporary. + +Using Xlib with Threads + + On systems that have threads, support may be provided to permit + multiple threads to use Xlib concurrently. + + To initialize support for concurrent threads, use XInitThreads. + + Status XInitThreads(void); + + The XInitThreads function initializes Xlib support for + concurrent threads. This function must be the first Xlib + function a multi-threaded program calls, and it must complete + before any other Xlib call is made. This function returns a + nonzero status if initialization was successful; otherwise, it + returns zero. On systems that do not support threads, this + function always returns zero. + + It is only necessary to call this function if multiple threads + might use Xlib concurrently. If all calls to Xlib functions are + protected by some other access mechanism (for example, a mutual + exclusion lock in a toolkit or through explicit client + programming), Xlib thread initialization is not required. It is + recommended that single-threaded programs not call this + function. + + To lock a display across several Xlib calls, use XLockDisplay. + + XLockDisplay(Display *display); + + display + + Specifies the connection to the X server. + + The XLockDisplay function locks out all other threads from + using the specified display. Other threads attempting to use + the display will block until the display is unlocked by this + thread. Nested calls to XLockDisplay work correctly; the + display will not actually be unlocked until XUnlockDisplay has + been called the same number of times as XLockDisplay. This + function has no effect unless Xlib was successfully initialized + for threads using XInitThreads. + + To unlock a display, use XUnlockDisplay. + + XUnlockDisplay(Display *display); + + display + + Specifies the connection to the X server. + + The XUnlockDisplay function allows other threads to use the + specified display again. Any threads that have blocked on the + display are allowed to continue. Nested locking works + correctly; if XLockDisplay has been called multiple times by a + thread, then XUnlockDisplay must be called an equal number of + times before the display is actually unlocked. This function + has no effect unless Xlib was successfully initialized for + threads using XInitThreads. + +Using Internal Connections + + In addition to the connection to the X server, an Xlib + implementation may require connections to other kinds of + servers (for example, to input method servers as described in + chapter 13). Toolkits and clients that use multiple displays, + or that use displays in combination with other inputs, need to + obtain these additional connections to correctly block until + input is available and need to process that input when it is + available. Simple clients that use a single display and block + for input in an Xlib event function do not need to use these + facilities. + + To track internal connections for a display, use + XAddConnectionWatch. + + typedef void (*XConnectionWatchProc)(Display *display, XPointer + client_data, int fd, Bool opening, XPointer *watch_data); + + Status XAddConnectionWatch(Display *display, + XConnectionWatchProc procedure, XPointer client_data); + + display + + Specifies the connection to the X server. + + procedure + + Specifies the procedure to be called. + + client_data + + Specifies the additional client data. + + The XAddConnectionWatch function registers a procedure to be + called each time Xlib opens or closes an internal connection + for the specified display. The procedure is passed the display, + the specified client_data, the file descriptor for the + connection, a Boolean indicating whether the connection is + being opened or closed, and a pointer to a location for private + watch data. If opening is True, the procedure can store a + pointer to private data in the location pointed to by + watch_data; when the procedure is later called for this same + connection and opening is False, the location pointed to by + watch_data will hold this same private data pointer. + + This function can be called at any time after a display is + opened. If internal connections already exist, the registered + procedure will immediately be called for each of them, before + XAddConnectionWatch returns. XAddConnectionWatch returns a + nonzero status if the procedure is successfully registered; + otherwise, it returns zero. + + The registered procedure should not call any Xlib functions. If + the procedure directly or indirectly causes the state of + internal connections or watch procedures to change, the result + is not defined. If Xlib has been initialized for threads, the + procedure is called with the display locked and the result of a + call by the procedure to any Xlib function that locks the + display is not defined unless the executing thread has + externally locked the display using XLockDisplay. + + To stop tracking internal connections for a display, use + XRemoveConnectionWatch. + + Status XRemoveConnectionWatch(Display *display, + XConnectionWatchProc procedure, XPointer client_data); + + display + + Specifies the connection to the X server. + + procedure + + Specifies the procedure to be called. + + client_data + + Specifies the additional client data. + + The XRemoveConnectionWatch function removes a previously + registered connection watch procedure. The client_data must + match the client_data used when the procedure was initially + registered. + + To process input on an internal connection, use + XProcessInternalConnection. + + void XProcessInternalConnection(Display *display, int fd); + + display + + Specifies the connection to the X server. + + fd + + Specifies the file descriptor. + + The XProcessInternalConnection function processes input + available on an internal connection. This function should be + called for an internal connection only after an operating + system facility (for example, select or poll) has indicated + that input is available; otherwise, the effect is not defined. + + To obtain all of the current internal connections for a + display, use XInternalConnectionNumbers. + + Status XInternalConnectionNumbers(Display *display, int ** fd, + int * count_return); + + display + + Specifies the connection to the X server. + + fd_return + + Returns the file descriptors. + + count_return + + Returns the number of file descriptors. + + The XInternalConnectionNumbers function returns a list of the + file descriptors for all internal connections currently open + for the specified display. When the allocated list is no longer + needed, free it by using XFree. This functions returns a + nonzero status if the list is successfully allocated; + otherwise, it returns zero. + +Chapter 3. Window Functions + + Table of Contents + + Visual Types + Window Attributes + + Background Attribute + Border Attribute + Gravity Attributes + Backing Store Attribute + Save Under Flag + Backing Planes and Backing Pixel Attributes + Event Mask and Do Not Propagate Mask Attributes + Override Redirect Flag + Colormap Attribute + Cursor Attribute + + Creating Windows + Destroying Windows + Mapping Windows + Unmapping Windows + Configuring Windows + Changing Window Stacking Order + Changing Window Attributes + +Visual Types + + On some display hardware, it may be possible to deal with color + resources in more than one way. For example, you may be able to + deal with a screen of either 12-bit depth with arbitrary + mapping of pixel to color (pseudo-color) or 24-bit depth with 8 + bits of the pixel dedicated to each of red, green, and blue. + These different ways of dealing with the visual aspects of the + screen are called visuals. For each screen of the display, + there may be a list of valid visual types supported at + different depths of the screen. Because default windows and + visual types are defined for each screen, most simple + applications need not deal with this complexity. Xlib provides + macros and functions that return the default root window, the + default depth of the default root window, and the default + visual type (see sections 2.2.1 and 16.7). + + Xlib uses an opaque Visual structure that contains information + about the possible color mapping. The visual utility functions + (see section 16.7) use an XVisualInfo structure to return this + information to an application. The members of this structure + pertinent to this discussion are class, red_mask, green_mask, + blue_mask, bits_per_rgb, and colormap_size. The class member + specifies one of the possible visual classes of the screen and + can be StaticGray, StaticColor, TrueColor, GrayScale, + PseudoColor, or DirectColor. + + The following concepts may serve to make the explanation of + visual types clearer. The screen can be color or grayscale, can + have a colormap that is writable or read-only, and can also + have a colormap whose indices are decomposed into separate RGB + pieces, provided one is not on a grayscale screen. This leads + to the following diagram: + Color Gray-Scale + R/O R/W R/O R/W +---------------------------------------------- + Undecomposed Static Pseudo Static Gray + Colormap Color Color Gray Scale + + Decomposed True Direct + Colormap Color Color +---------------------------------------------- + + Conceptually, as each pixel is read out of video memory for + display on the screen, it goes through a look-up stage by + indexing into a colormap. Colormaps can be manipulated + arbitrarily on some hardware, in limited ways on other + hardware, and not at all on other hardware. The visual types + affect the colormap and the RGB values in the following ways: + + * For PseudoColor, a pixel value indexes a colormap to + produce independent RGB values, and the RGB values can be + changed dynamically. + * GrayScale is treated the same way as PseudoColor except + that the primary that drives the screen is undefined. Thus, + the client should always store the same value for red, + green, and blue in the colormaps. + * For DirectColor, a pixel value is decomposed into separate + RGB subfields, and each subfield separately indexes the + colormap for the corresponding value. The RGB values can be + changed dynamically. + * TrueColor is treated the same way as DirectColor except + that the colormap has predefined, read-only RGB values. + These RGB values are server dependent but provide linear or + near-linear ramps in each primary. + * StaticColor is treated the same way as PseudoColor except + that the colormap has predefined, read-only, + server-dependent RGB values. + * StaticGray is treated the same way as StaticColor except + that the RGB values are equal for any single pixel value, + thus resulting in shades of gray. StaticGray with a + two-entry colormap can be thought of as monochrome. + + The red_mask, green_mask, and blue_mask members are only + defined for DirectColor and TrueColor. Each has one contiguous + set of bits with no intersections. The bits_per_rgb member + specifies the log base 2 of the number of distinct color values + (individually) of red, green, and blue. Actual RGB values are + unsigned 16-bit numbers. The colormap_size member defines the + number of available colormap entries in a newly created + colormap. For DirectColor and TrueColor, this is the size of an + individual pixel subfield. + + To obtain the visual ID from a Visual, use XVisualIDFromVisual. + + VisualID XVisualIDFromVisual(Visual *visual); + + visual + + Specifies the visual type. + + The XVisualIDFromVisual function returns the visual ID for the + specified visual type. + +Window Attributes + + All InputOutput windows have a border width of zero or more + pixels, an optional background, an event suppression mask + (which suppresses propagation of events from children), and a + property list (see section 4.3). The window border and + background can be a solid color or a pattern, called a tile. + All windows except the root have a parent and are clipped by + their parent. If a window is stacked on top of another window, + it obscures that other window for the purpose of input. If a + window has a background (almost all do), it obscures the other + window for purposes of output. Attempts to output to the + obscured area do nothing, and no input events (for example, + pointer motion) are generated for the obscured area. + + Windows also have associated property lists (see section 4.3). + + Both InputOutput and InputOnly windows have the following + common attributes, which are the only attributes of an + InputOnly window: + * win-gravity + * event-mask + * do-not-propagate-mask + * override-redirect + * cursor + + If you specify any other attributes for an InputOnly window, a + BadMatch error results. + + InputOnly windows are used for controlling input events in + situations where InputOutput windows are unnecessary. InputOnly + windows are invisible; can only be used to control such things + as cursors, input event generation, and grabbing; and cannot be + used in any graphics requests. Note that InputOnly windows + cannot have InputOutput windows as inferiors. + + Windows have borders of a programmable width and pattern as + well as a background pattern or tile. Pixel values can be used + for solid colors. The background and border pixmaps can be + destroyed immediately after creating the window if no further + explicit references to them are to be made. The pattern can + either be relative to the parent or absolute. If + ParentRelative, the parent's background is used. + + When windows are first created, they are not visible (not + mapped) on the screen. Any output to a window that is not + visible on the screen and that does not have backing store will + be discarded. An application may wish to create a window long + before it is mapped to the screen. When a window is eventually + mapped to the screen (using XMapWindow), the X server generates + an Expose event for the window if backing store has not been + maintained. + + A window manager can override your choice of size, border + width, and position for a top-level window. Your program must + be prepared to use the actual size and position of the top + window. It is not acceptable for a client application to resize + itself unless in direct response to a human command to do so. + Instead, either your program should use the space given to it, + or if the space is too small for any useful work, your program + might ask the user to resize the window. The border of your + top-level window is considered fair game for window managers. + + To set an attribute of a window, set the appropriate member of + the XSetWindowAttributes structure and OR in the corresponding + value bitmask in your subsequent calls to XCreateWindow and + XChangeWindowAttributes, or use one of the other convenience + functions that set the appropriate attribute. The symbols for + the value mask bits and the XSetWindowAttributes structure are: + + /* Window attribute value mask bits */ +/* Window attribute value mask bits */ +#define CWBackPixmap (1L<<0) +#define CWBackPixel (1L<<1) +#define CWBorderPixmap (1L<<2) +#define CWBorderPixel (1L<<3) +#define CWBitGravity (1L<<4) +#define CWWinGravity (1L<<5) +#define CWBackingStore (1L<<6) +#define CWBackingPlanes (1L<<7) +#define CWBackingPixel (1L<<8) +#define CWOverrideRedirect (1L<<9) +#define CWSaveUnder (1L<<10) +#define CWEventMask (1L<<11) +#define CWDontPropagate (1L<<12) +#define CWColormap (1L<<13) +#define CWCursor (1L<<14) + + + +/* Values */ + +typedef struct { + Pixmap background_pixmap; /* background, None, or ParentRelativ +e */ + unsigned long background_pixel; /* background pixel */ + Pixmap border_pixmap; /* border of the window or CopyFromP +arent */ + 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 poss +ible */ + unsigned long backing_pixel; /* value to use in restoring plane +s */ + 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 pr +opagate */ + 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 InputOutput + and InputOnly windows: + Attribute Default InputOutput InputOnly + background-pixmap None Yes No + background-pixel Undefined Yes No + border-pixmap CopyFromParent Yes No + border-pixel Undefined Yes No + bit-gravity ForgetGravity Yes No + win-gravity NorthWestGravity Yes Yes + backing-store NotUseful Yes No + backing-planes All ones Yes No + backing-pixel zero Yes No + save-under False Yes No + event-mask empty set Yes Yes + do-not-propagate-mask empty set Yes Yes + override-redirect False Yes Yes + colormap CopyFromParent Yes No + cursor None Yes Yes + +Background Attribute + + Only InputOutput windows can have a background. You can set the + background of an InputOutput window by using a pixel or a + pixmap. + + The background-pixmap attribute of a window specifies the + pixmap to be used for a window's background. This pixmap can be + of any size, although some sizes may be faster than others. The + background-pixel attribute of a window specifies a pixel value + used to paint a window's background in a single color. + + You can set the background-pixmap to a pixmap, None (default), + or ParentRelative. You can set the background-pixel of a window + to any pixel value (no default). If you specify a + background-pixel, it overrides either the default + background-pixmap or any value you may have set in the + background-pixmap. A pixmap of an undefined size that is filled + with the background-pixel is used for the background. Range + checking is not performed on the background pixel; it simply is + truncated to the appropriate number of bits. + + If you set the background-pixmap, it overrides the default. The + background-pixmap and the window must have the same depth, or a + BadMatch error results. If you set background-pixmap to None, + the window has no defined background. If you set the + background-pixmap to ParentRelative: + * The parent window's background-pixmap is used. The child + window, however, must have the same depth as its parent, or + a BadMatch error results. + * If the parent window has a background-pixmap of None, the + window also has a background-pixmap of None. + * 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 parent + window's background tile origin. If the background-pixmap + is not ParentRelative, 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 background. The + background-pixmap can be freed immediately if no further + explicit reference is made to it (the X server will keep a copy + to use when needed). If you later draw into the pixmap used for + the background, what happens is undefined because the X + implementation is free to make a copy of the pixmap or to use + the same pixmap. + + When no valid contents are available for regions of a window + and either the regions are visible or the server is maintaining + backing store, the server automatically tiles the regions with + the window's background unless the window has a background of + None. If the background is None, the previous screen contents + from other windows of the same depth as the window are simply + left in place as long as the contents come from the parent of + the window or an inferior of the parent. Otherwise, the initial + contents of the exposed regions are undefined. Expose events + are then generated for the regions, even if the + background-pixmap is None (see section 10.9). + +Border Attribute + + Only InputOutput windows can have a border. You can set the + border of an InputOutput window by using a pixel or a pixmap. + + The border-pixmap attribute of a window specifies the pixmap to + be used for a window's border. The border-pixel attribute of a + window specifies a pixmap of undefined size filled with that + pixel be used for a window's border. Range checking is not + performed on the background pixel; it simply is truncated to + the appropriate number of bits. The border tile origin is + always the same as the background tile origin. + + You can also set the border-pixmap to a pixmap of any size + (some may be faster than others) or to CopyFromParent + (default). You can set the border-pixel to any pixel value (no + default). + + If you set a border-pixmap, it overrides the default. The + border-pixmap and the window must have the same depth, or a + BadMatch error results. If you set the border-pixmap to + CopyFromParent, the parent window's border-pixmap is copied. + Subsequent changes to the parent window's border attribute do + not affect the child window. However, the child window must + have the same depth as the parent window, or a BadMatch error + results. + + The border-pixmap can be freed immediately if no further + explicit reference is made to it. If you later draw into the + pixmap used for the border, what happens is undefined because + the X implementation is free either to make a copy of the + pixmap or to use the same pixmap. If you specify a + border-pixel, it overrides either the default border-pixmap or + any value you may have set in the border-pixmap. All pixels in + the window's border will be set to the border-pixel. Setting a + new border, whether by setting border-pixel or by setting + border-pixmap, overrides any previous border. + + Output to a window is always clipped to the inside of the + window. Therefore, graphics operations never affect the window + border. + +Gravity Attributes + + The bit gravity of a window defines which region of the window + should be retained when an InputOutput window is resized. The + default value for the bit-gravity attribute is ForgetGravity. + The window gravity of a window allows you to define how the + InputOutput or InputOnly window should be repositioned if its + parent is resized. The default value for the win-gravity + attribute is NorthWestGravity. + + If the inside width or height of a window is not changed and if + the window is moved or its border is changed, then the contents + of the window are not lost but move with the window. Changing + the inside width or height of the window causes its contents to + be moved or lost (depending on the bit-gravity of the window) + and causes children to be reconfigured (depending on their + win-gravity). For a change of width and height, the (x, y) + pairs are defined: + + Gravity Direction Coordinates + NorthWestGravity (0, 0) + NorthGravity (Width/2, 0) + NorthEastGravity (Width, 0) + WestGravity (0, Height/2) + CenterGravity (Width/2, Height/2) + EastGravity (Width, Height/2) + SouthWestGravity (0, Height) + SouthGravity (Width/2, Height) + SouthEastGravity (Width, Height) + + When a window with one of these bit-gravity values is resized, + the corresponding pair defines the change in position of each + pixel in the window. When a window with one of these + win-gravities has its parent window resized, the corresponding + pair defines the change in position of the window within the + parent. When a window is so repositioned, a GravityNotify event + is generated (see section 10.10.5). + + A bit-gravity of StaticGravity indicates that the contents or + origin should not move relative to the origin of the root + window. If the change in size of the window is coupled with a + change in position (x, y), then for bit-gravity the change in + position of each pixel is (-x, -y), and for win-gravity the + change in position of a child when its parent is so resized is + (-x, -y). Note that StaticGravity still only takes effect when + the width or height of the window is changed, not when the + window is moved. + + A bit-gravity of ForgetGravity indicates that the window's + contents are always discarded after a size change, even if a + backing store or save under has been requested. The window is + tiled with its background and zero or more Expose events are + generated. If no background is defined, the existing screen + contents are not altered. Some X servers may also ignore the + specified bit-gravity and always generate Expose events. + + The contents and borders of inferiors are not affected by their + parent's bit-gravity. A server is permitted to ignore the + specified bit-gravity and use Forget instead. + + A win-gravity of UnmapGravity is like NorthWestGravity (the + window is not moved), except the child is also unmapped when + the parent is resized, and an UnmapNotify event is generated. + +Backing Store Attribute + + Some implementations of the X server may choose to maintain the + contents of InputOutput windows. If the X server maintains the + contents of a window, the off-screen saved pixels are known as + backing store. The backing store advises the X server on what + to do with the contents of a window. The backing-store + attribute can be set to NotUseful (default), WhenMapped, or + Always. + + A backing-store attribute of NotUseful advises the X server + that maintaining contents is unnecessary, although some X + implementations may still choose to maintain contents and, + therefore, not generate Expose events. A backing-store + attribute of WhenMapped advises the X server that maintaining + contents of obscured regions when the window is mapped would be + beneficial. In this case, the server may generate an Expose + event when the window is created. A backing-store attribute of + Always advises the X server that maintaining contents even when + the window is unmapped would be beneficial. Even if the window + is larger than its parent, this is a request to the X server to + maintain complete contents, not just the region within the + parent window boundaries. While the X server maintains the + window's contents, Expose events normally are not generated, + but the X server may stop maintaining contents at any time. + + When the contents of obscured regions of a window are being + maintained, regions obscured by noninferior windows are + included in the destination of graphics requests (and source, + when the window is the source). However, regions obscured by + inferior windows are not included. + +Save Under Flag + + Some server implementations may preserve contents of + InputOutput windows under other InputOutput windows. This is + not the same as preserving the contents of a window for you. + You may get better visual appeal if transient windows (for + example, pop-up menus) request that the system preserve the + screen contents under them, so the temporarily obscured + applications do not have to repaint. + + You can set the save-under flag to True or False (default). If + save-under is True, the X server is advised that, when this + window is mapped, saving the contents of windows it obscures + would be beneficial. + +Backing Planes and Backing Pixel Attributes + + You can set backing planes to indicate (with bits set to 1) + which bit planes of an InputOutput window hold dynamic data + that must be preserved in backing store and during save unders. + The default value for the backing-planes attribute is all bits + set to 1. You can set backing pixel to specify what bits to use + in planes not covered by backing planes. The default value for + the backing-pixel attribute is all bits set to 0. The X server + is free to save only the specified bit planes in the backing + store or the save under and is free to regenerate the remaining + planes with the specified pixel value. Any extraneous bits in + these values (that is, those bits beyond the specified depth of + the window) may be simply ignored. If you request backing store + or save unders, you should use these members to minimize the + amount of off-screen memory required to store your window. + +Event Mask and Do Not Propagate Mask Attributes + + The event mask defines which events the client is interested in + for this InputOutput or InputOnly window (or, for some event + types, inferiors of this window). The event mask is the bitwise + inclusive OR of zero or more of the valid event mask bits. You + can specify that no maskable events are reported by setting + NoEventMask (default). + + The do-not-propagate-mask attribute defines which events should + not be propagated to ancestor windows when no client has the + event type selected in this InputOutput or InputOnly window. + The do-not-propagate-mask is the bitwise inclusive OR of zero + or more of the following masks: KeyPress, KeyRelease, + ButtonPress, ButtonRelease, PointerMotion, Button1Motion, + Button2Motion, Button3Motion, Button4Motion, Button5Motion, and + ButtonMotion. You can specify that all events are propagated by + setting NoEventMask (default). + +Override Redirect Flag + + To control window placement or to add decoration, a window + manager often needs to intercept (redirect) any map or + configure request. Pop-up windows, however, often need to be + mapped without a window manager getting in the way. To control + whether an InputOutput or InputOnly window is to ignore these + structure control facilities, use the override-redirect flag. + + The override-redirect flag specifies whether map and configure + requests on this window should override a + SubstructureRedirectMask on the parent. You can set the + override-redirect flag to True or False (default). Window + managers use this information to avoid tampering with pop-up + windows (see also chapter 14). + +Colormap Attribute + + The colormap attribute specifies which colormap best reflects + the true colors of the InputOutput window. The colormap must + have the same visual type as the window, or a BadMatch error + results. X servers capable of supporting multiple hardware + colormaps can use this information, and window managers can use + it for calls to XInstallColormap. You can set the colormap + attribute to a colormap or to CopyFromParent (default). + + If you set the colormap to CopyFromParent, the parent window's + colormap is copied and used by its child. However, the child + window must have the same visual type as the parent, or a + BadMatch error results. The parent window must not have a + colormap of None, or a BadMatch error results. The colormap is + copied by sharing the colormap object between the child and + parent, not by making a complete copy of the colormap contents. + Subsequent changes to the parent window's colormap attribute do + not affect the child window. + +Cursor Attribute + + The cursor attribute specifies which cursor is to be used when + the pointer is in the InputOutput or InputOnly window. You can + set the cursor to a cursor or None (default). + + If you set the cursor to None, the parent's cursor is used when + the pointer is in the InputOutput or InputOnly window, and any + change in the parent's cursor will cause an immediate change in + the displayed cursor. By calling XFreeCursor, the cursor can be + freed immediately as long as no further explicit reference to + it is made. + +Creating Windows + + Xlib provides basic ways for creating windows, and toolkits + often supply higher-level functions specifically for creating + and placing top-level windows, which are discussed in the + appropriate toolkit documentation. If you do not use a toolkit, + however, you must provide some standard information or hints + for the window manager by using the Xlib inter-client + communication functions (see chapter 14). + + If you use Xlib to create your own top-level windows (direct + children of the root window), you must observe the following + rules so that all applications interact reasonably across the + different styles of window management: + * 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 properties + for top-level windows before mapping them. + + For further information, see chapter 14 and the Inter-Client + Communication Conventions Manual. + + XCreateWindow is the more general function that allows you to + set specific window attributes when you create a window. + XCreateSimpleWindow creates a window that inherits its + attributes from its parent window. + + The X server acts as if InputOnly windows do not exist for the + purposes of graphics requests, exposure processing, and + VisibilityNotify events. An InputOnly window cannot be used as + a drawable (that is, as a source or destination for graphics + requests). InputOnly and InputOutput windows act identically in + other respects (properties, grabs, input control, and so on). + Extension packages can define other classes of windows. + + To create an unmapped window and set its window attributes, use + XCreateWindow. + + Window XCreateWindow(Display *display, Window parent, int x, + int y, unsigned int width, unsigned int height, unsigned int + border_width, int depth, unsigned int class, Visual *visual, + unsigned long valuemask, XSetWindowAttributes *attributes); + + display + + Specifies the connection to the X server. + + parent + + Specifies the parent window. + + x + + y + + 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 parent window's borders. + + width + + height + + Specify the width and height, which are the created window's + inside dimensions and do not include the created window's + borders. The dimensions must be nonzero, or a BadValue error + results. + + border_width + + Specifies the width of the created window's border in pixels. + + depth + + Specifies the window's depth. A depth of CopyFromParent means + the depth is taken from the parent. + + class + + Specifies the created window's class. You can pass InputOutput, + InputOnly, or CopyFromParent. A class of CopyFromParent means + the class is taken from the parent. + + visual + + Specifies the visual type. A visual of CopyFromParent means the + visual type is taken from the parent. + + valuemask + + 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. + + attributes + + 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 XCreateWindow function creates an unmapped subwindow for a + specified parent window, returns the window ID of the created + window, and causes the X server to generate a CreateNotify + event. The created window is placed on top in the stacking + order with respect to siblings. + + The coordinate system has the X axis horizontal and the Y axis + vertical with the origin [0, 0] at the upper-left corner. + Coordinates are integral, in terms of pixels, and coincide with + pixel centers. Each window and pixmap has its own coordinate + system. For a window, the origin is inside the border at the + inside, upper-left corner. + + The border_width for an InputOnly window must be zero, or a + BadMatch error results. For class InputOutput, the visual type + and depth must be a combination supported for the screen, or a + BadMatch error results. The depth need not be the same as the + parent, but the parent must not be a window of class InputOnly, + or a BadMatch error results. For an InputOnly window, the depth + must be zero, and the visual must be one supported by the + screen. If either condition is not met, a BadMatch error + results. The parent window, however, may have any depth and + class. If you specify any invalid window attribute for a + window, a BadMatch error results. + + The created window is not yet displayed (mapped) on the user's + display. To display the window, call XMapWindow. The new window + initially uses the same cursor as its parent. A new cursor can + be defined for the new window by calling XDefineCursor. The + window will not be visible on the screen unless it and all of + its ancestors are mapped and it is not obscured by any of its + ancestors. + + XCreateWindow can generate BadAlloc, BadColor, BadCursor, + BadMatch, BadPixmap, BadValue, and BadWindow errors. + + To create an unmapped InputOutput subwindow of a given parent + window, use XCreateSimpleWindow. + + Window XCreateSimpleWindow(Display *display, Window parent, int + x, int y, unsigned int width, unsigned int height, unsigned int + border_width, unsigned long border, unsigned long background); + + display + + Specifies the connection to the X server. + + parent + + Specifies the parent window. + + x + + y + + Specify the x and y coordinates, which are the top-left outside + corner of the new window's borders and are relative to the + inside of the parent window's borders. + + width + + height + + Specify the width and height, which are the created window's + inside dimensions and do not include the created window's + borders. The dimensions must be nonzero, or a BadValue error + results. + + border_width + + Specifies the width of the created window's border in pixels. + + border + + Specifies the border pixel value of the window. + + background + + Specifies the background pixel value of the window. + + The XCreateSimpleWindow function creates an unmapped + InputOutput subwindow for a specified parent window, returns + the window ID of the created window, and causes the X server to + generate a CreateNotify event. The created window is placed on + top in the stacking order with respect to siblings. Any part of + the window that extends outside its parent window is clipped. + The border_width for an InputOnly window must be zero, or a + BadMatch error results. XCreateSimpleWindow inherits its depth, + class, and visual from its parent. All other window attributes, + except background and border, have their default values. + + XCreateSimpleWindow can generate BadAlloc, BadMatch, BadValue, + and BadWindow errors. + +Destroying Windows + + Xlib provides functions that you can use to destroy a window or + destroy all subwindows of a window. + + To destroy a window and all of its subwindows, use + XDestroyWindow. + + XDestroyWindow(Display *display, Window w); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + The XDestroyWindow function destroys the specified window as + well as all of its subwindows and causes the X server to + generate a DestroyNotify event for each window. The window + should never be referenced again. If the window specified by + the w argument is mapped, it is unmapped automatically. The + ordering of the DestroyNotify events is such that for any given + window being destroyed, DestroyNotify is generated on any + inferiors of the window before being generated on the window + itself. The ordering among siblings and across subhierarchies + is not otherwise constrained. If the window you specified is a + root window, no windows are destroyed. Destroying a mapped + window will generate Expose events on other windows that were + obscured by the window being destroyed. + + XDestroyWindow can generate a BadWindow error. + + To destroy all subwindows of a specified window, use + XDestroySubwindows. + + XDestroySubwindows(Display *display, Window w); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + The XDestroySubwindows function destroys all inferior windows + of the specified window, in bottom-to-top stacking order. It + causes the X server to generate a DestroyNotify event for each + window. If any mapped subwindows were actually destroyed, + XDestroySubwindows causes the X server to generate Expose + events on the specified window. This is much more efficient + than deleting many windows one at a time because much of the + work need be performed only once for all of the windows, rather + than for each window. The subwindows should never be referenced + again. + + XDestroySubwindows can generate a BadWindow error. + +Mapping Windows + + A window is considered mapped if an XMapWindow call has been + made on it. It may not be visible on the screen for one of the + following reasons: + * It is obscured by another opaque window. + * One of its ancestors is not mapped. + * It is entirely clipped by an ancestor. + + Expose events are generated for the window when part or all of + it becomes visible on the screen. A client receives the Expose + events only if it has asked for them. Windows retain their + position in the stacking order when they are unmapped. + + A window manager may want to control the placement of + subwindows. If SubstructureRedirectMask has been selected by a + window manager on a parent window (usually a root window), a + map request initiated by other clients on a child window is not + performed, and the window manager is sent a MapRequest event. + However, if the override-redirect flag on the child had been + set to True (usually only on pop-up menus), the map request is + performed. + + A tiling window manager might decide to reposition and resize + other clients' windows and then decide to map the window to its + final location. A window manager that wants to provide + decoration might reparent the child into a frame first. For + further information, see sections 3.2.8 and 10.10. Only a + single client at a time can select for + SubstructureRedirectMask. + + Similarly, a single client can select for ResizeRedirectMask on + a parent window. Then, any attempt to resize the window by + another client is suppressed, and the client receives a + ResizeRequest event. + + To map a given window, use XMapWindow. + + XMapWindow(Display *display, Window w); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + The XMapWindow function maps the window and all of its + subwindows that have had map requests. Mapping a window that + has an unmapped ancestor does not display the window but marks + it as eligible for display when the ancestor becomes mapped. + Such a window is called unviewable. When all its ancestors are + mapped, the window becomes viewable and will be visible on the + screen if it is not obscured by another window. This function + has no effect if the window is already mapped. + + If the override-redirect of the window is False and if some + other client has selected SubstructureRedirectMask on the + parent window, then the X server generates a MapRequest event, + and the XMapWindow function does not map the window. Otherwise, + the window is mapped, and the X server generates a MapNotify + event. + + If the window becomes viewable and no earlier contents for it + are remembered, the X server tiles the window with its + background. If the window's background is undefined, the + existing screen contents are not altered, and the X server + generates zero or more Expose events. If backing-store was + maintained while the window was unmapped, no Expose events are + generated. If backing-store will now be maintained, a + full-window exposure is always generated. Otherwise, only + visible regions may be reported. Similar tiling and exposure + take place for any newly viewable inferiors. + + If the window is an InputOutput window, XMapWindow generates + Expose events on each InputOutput window that it causes to be + displayed. If the client maps and paints the window and if the + client begins processing events, the window is painted twice. + To avoid this, first ask for Expose events and then map the + window, so the client processes input events as usual. The + event list will include Expose for each window that has + appeared on the screen. The client's normal response to an + Expose event should be to repaint the window. This method + usually leads to simpler programs and to proper interaction + with window managers. + + XMapWindow can generate a BadWindow error. + + To map and raise a window, use XMapRaised. + + XMapRaised(Display *display, Window w); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + The XMapRaised function essentially is similar to XMapWindow in + that it maps the window and all of its subwindows that have had + map requests. However, it also raises the specified window to + the top of the stack. For additional information, see + XMapWindow. + + XMapRaised can generate multiple BadWindow errors. + + To map all subwindows for a specified window, use + XMapSubwindows. + + XMapSubwindows(Display *display, Window w); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + The XMapSubwindows function maps all subwindows for a specified + window in top-to-bottom stacking order. The X server generates + Expose events on each newly displayed window. This may be much + more efficient than mapping many windows one at a time because + the server needs to perform much of the work only once, for all + of the windows, rather than for each window. + + XMapSubwindows can generate a BadWindow error. + +Unmapping Windows + + Xlib provides functions that you can use to unmap a window or + all subwindows. + + To unmap a window, use XUnmapWindow. + + XUnmapWindow(Display *display, Window w); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + The XUnmapWindow function unmaps the specified window and + causes the X server to generate an UnmapNotify event. If the + specified window is already unmapped, XUnmapWindow has no + effect. Normal exposure processing on formerly obscured windows + is performed. Any child window will no longer be visible until + another map call is made on the parent. In other words, the + subwindows are still mapped but are not visible until the + parent is mapped. Unmapping a window will generate Expose + events on windows that were formerly obscured by it. + + XUnmapWindow can generate a BadWindow error. + + To unmap all subwindows for a specified window, use + XUnmapSubwindows. + + XUnmapSubwindows(Display *display, Window w); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + The XUnmapSubwindows function unmaps all subwindows for the + specified window in bottom-to-top stacking order. It causes the + X server to generate an UnmapNotify event on each subwindow and + Expose events on formerly obscured windows. Using this function + is much more efficient than unmapping multiple windows one at a + time because the server needs to perform much of the work only + once, for all of the windows, rather than for each window. + + XUnmapSubwindows can generate a BadWindow error. + +Configuring Windows + + Xlib provides functions that you can use to move a window, + resize a window, move and resize a window, or change a window's + border width. To change one of these parameters, set the + appropriate member of the XWindowChanges structure and OR in + the corresponding value mask in subsequent calls to + XConfigureWindow. The symbols for the value mask bits and the + XWindowChanges structure are: + +/* Configure window value mask bits */ +#define CWX (1<<0) +#define CWY (1<<1) +#define CWWidth (1<<2) +#define CWHeight (1<<3) +#define CWBorderWidth (1<<4) +#define CWSibling (1<<5) +#define CWStackMode (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 BadValue error results. Attempts to configure a + root window have no effect. + + The border_width member is used to set the width of the border + in pixels. Note that setting just the border width leaves the + outer-left corner of the window in a fixed position but moves + the absolute position of the window's origin. If you attempt to + set the border-width attribute of an InputOnly window nonzero, + a BadMatch error results. + + The sibling member is used to set the sibling window for + stacking operations. The stack_mode member is used to set how + the window is to be restacked and can be set to Above, Below, + TopIf, BottomIf, or Opposite. + + If the override-redirect flag of the window is False and if + some other client has selected SubstructureRedirectMask on the + parent, the X server generates a ConfigureRequest event, and no + further processing is performed. Otherwise, if some other + client has selected ResizeRedirectMask on the window and the + inside width or height of the window is being changed, a + ResizeRequest event is generated, and the current inside width + and height are used instead. Note that the override-redirect + flag of the window has no effect on ResizeRedirectMask and that + SubstructureRedirectMask on the parent has precedence over + ResizeRedirectMask on the window. + + When the geometry of the window is changed as specified, the + window is restacked among siblings, and a ConfigureNotify event + is generated if the state of the window actually changes. + GravityNotify events are generated after ConfigureNotify + events. If the inside width or height of the window has + actually changed, children of the window are affected as + specified. + + If a window's size actually changes, the window's subwindows + move according to their window gravity. Depending on the + window's bit gravity, the contents of the window also may be + moved (see section 3.2.3). + + If regions of the window were obscured but now are not, + exposure processing is performed on these formerly obscured + windows, including the window itself and its inferiors. As a + result of increasing the width or height, exposure processing + is also performed on any new regions of the window and any + regions where window contents are lost. + + The restack check (specifically, the computation for BottomIf, + TopIf, and Opposite) is performed with respect to the window's + final size and position (as controlled by the other arguments + of the request), not its initial position. If a sibling is + specified without a stack_mode, a BadMatch error results. + + If a sibling and a stack_mode are specified, the window is + restacked as follows: + Above The window is placed just above the sibling. + Below The window is placed just below the sibling. + TopIf If the sibling occludes the window, the window is placed + at the top of the stack. + BottomIf If the window occludes the sibling, the window is + placed at the bottom of the stack. + Opposite If the sibling occludes the window, the window is + placed at the top of the stack. If the window occludes the + sibling, the window is placed at the bottom of the stack. + + If a stack_mode is specified but no sibling is specified, the + window is restacked as follows: + Above The window is placed at the top of the stack. + Below The window is placed at the bottom of the stack. + TopIf If any sibling occludes the window, the window is placed + at the top of the stack. + BottomIf If the window occludes any sibling, the window is + placed at the bottom of the stack. + Opposite If any sibling occludes the window, the window is + placed at the top of the stack. If the window occludes any + sibling, the window is placed at the bottom of the stack. + + Attempts to configure a root window have no effect. + + To configure a window's size, location, stacking, or border, + use XConfigureWindow. + + XConfigureWindow(Display *display, Window w, unsigned int + value_mask, XWindowChanges *values); + + display + + Specifies the connection to the X server. + + w + + Specifies the window to be reconfigured. + + value_mask + + Specifies which values are to be set using information in the + values structure. This mask is the bitwise inclusive OR of the + valid configure window values bits. + + values + + Specifies the XWindowChanges structure. + + The XConfigureWindow function uses the values specified in the + XWindowChanges structure to reconfigure a window's size, + position, border, and stacking order. Values not specified are + taken from the existing geometry of the window. + + If a sibling is specified without a stack_mode or if the window + is not actually a sibling, a BadMatch error results. Note that + the computations for BottomIf, TopIf, and Opposite are + performed with respect to the window's final geometry (as + controlled by the other arguments passed to XConfigureWindow), + not its initial geometry. Any backing store contents of the + window, its inferiors, and other newly visible windows are + either discarded or changed to reflect the current screen + contents (depending on the implementation). + + XConfigureWindow can generate BadMatch, BadValue, and BadWindow + errors. + + To move a window without changing its size, use XMoveWindow. + + XMoveWindow(Display *display, Window w, int x, int y); + + display + + Specifies the connection to the X server. + + w + + Specifies the window to be moved. + + x + + y + + Specify the x and y coordinates, which define the new location + of the top-left pixel of the window's border or the window + itself if it has no border. + + The XMoveWindow function moves the specified window to the + specified x and y coordinates, but it does not change the + window's size, raise the window, or change the mapping state of + the window. Moving a mapped window may or may not lose the + window's contents depending on if the window is obscured by + nonchildren and if no backing store exists. If the contents of + the window are lost, the X server generates Expose events. + Moving a mapped window generates Expose events on any formerly + obscured windows. + + If the override-redirect flag of the window is False and some + other client has selected SubstructureRedirectMask on the + parent, the X server generates a ConfigureRequest event, and no + further processing is performed. Otherwise, the window is + moved. + + XMoveWindow can generate a BadWindow error. + + To change a window's size without changing the upper-left + coordinate, use XResizeWindow. + + XResizeWindow(Display *display, Window w, unsigned int width, + unsigned int height); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + width + + height + + Specify the width and height, which are the interior dimensions + of the window after the call completes. + + The XResizeWindow function changes the inside dimensions of the + specified window, not including its borders. This function does + not change the window's upper-left coordinate or the origin and + does not restack the window. Changing the size of a mapped + window may lose its contents and generate Expose events. If a + mapped window is made smaller, changing its size generates + Expose events on windows that the mapped window formerly + obscured. + + If the override-redirect flag of the window is False and some + other client has selected SubstructureRedirectMask on the + parent, the X server generates a ConfigureRequest event, and no + further processing is performed. If either width or height is + zero, a BadValue error results. + + XResizeWindow can generate BadValue and BadWindow errors. + + To change the size and location of a window, use + XMoveResizeWindow. + + XMoveResizeWindow(Display *display, Window w, int x, int y, + unsigned int width, unsigned int height); + + display + + Specifies the connection to the X server. + + w + + Specifies the window to be reconfigured. + + x + + y + + Specify the x and y coordinates, which define the new position + of the window relative to its parent. + + width + + height + + Specify the width and height, which define the interior size of + the window. + + The XMoveResizeWindow function changes the size and location of + the specified window without raising it. Moving and resizing a + mapped window may generate an Expose event on the window. + Depending on the new size and location parameters, moving and + resizing a window may generate Expose events on windows that + the window formerly obscured. + + If the override-redirect flag of the window is False and some + other client has selected SubstructureRedirectMask on the + parent, the X server generates a ConfigureRequest event, and no + further processing is performed. Otherwise, the window size and + location are changed. + + XMoveResizeWindow can generate BadValue and BadWindow errors. + + To change the border width of a given window, use + XSetWindowBorderWidth. + + XSetWindowBorderWidth(Display *display, Window w, unsigned int + width); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + width + + Specifies the width of the window border. + + The XSetWindowBorderWidth function sets the specified window's + border width to the specified width. + + XSetWindowBorderWidth can generate a BadWindow error. + +Changing Window Stacking Order + + Xlib provides functions that you can use to raise, lower, + circulate, or restack windows. + + To raise a window so that no sibling window obscures it, use + XRaiseWindow. + + XRaiseWindow(Display *display, Window w); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + The XRaiseWindow function raises the specified window to the + top of the stack so that no sibling window obscures it. If the + windows are regarded as overlapping sheets of paper stacked on + a desk, then raising a window is analogous to moving the sheet + to the top of the stack but leaving its x and y location on the + desk constant. Raising a mapped window may generate Expose + events for the window and any mapped subwindows that were + formerly obscured. + + If the override-redirect attribute of the window is False and + some other client has selected SubstructureRedirectMask on the + parent, the X server generates a ConfigureRequest event, and no + processing is performed. Otherwise, the window is raised. + + XRaiseWindow can generate a BadWindow error. + + To lower a window so that it does not obscure any sibling + windows, use XLowerWindow. + + XLowerWindow(Display *display, Window w); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + The XLowerWindow function lowers the specified window to the + bottom of the stack so that it does not obscure any sibling + windows. If the windows are regarded as overlapping sheets of + paper stacked on a desk, then lowering a window is analogous to + moving the sheet to the bottom of the stack but leaving its x + and y location on the desk constant. Lowering a mapped window + will generate Expose events on any windows it formerly + obscured. + + If the override-redirect attribute of the window is False and + some other client has selected SubstructureRedirectMask on the + parent, the X server generates a ConfigureRequest event, and no + processing is performed. Otherwise, the window is lowered to + the bottom of the stack. + + XLowerWindow can generate a BadWindow error. + + To circulate a subwindow up or down, use XCirculateSubwindows. + + XCirculateSubwindows(Display *display, Window w, int + direction); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + direction + + Specifies the direction (up or down) that you want to circulate + the window. You can pass RaiseLowest or LowerHighest. + + The XCirculateSubwindows function circulates children of the + specified window in the specified direction. If you specify + RaiseLowest, XCirculateSubwindows raises the lowest mapped + child (if any) that is occluded by another child to the top of + the stack. If you specify LowerHighest, XCirculateSubwindows + lowers the highest mapped child (if any) that occludes another + child to the bottom of the stack. Exposure processing is then + performed on formerly obscured windows. If some other client + has selected SubstructureRedirectMask on the window, the X + server generates a CirculateRequest event, and no further + processing is performed. If a child is actually restacked, the + X server generates a CirculateNotify event. + + XCirculateSubwindows can generate BadValue and BadWindow + errors. + + To raise the lowest mapped child of a window that is partially + or completely occluded by another child, use + XCirculateSubwindowsUp. + + XCirculateSubwindowsUp(Display *display, Window w); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + The XCirculateSubwindowsUp function raises the lowest mapped + child of the specified window that is partially or completely + occluded by another child. Completely unobscured children are + not affected. This is a convenience function equivalent to + XCirculateSubwindows with RaiseLowest specified. + + XCirculateSubwindowsUp can generate a BadWindow error. + + To lower the highest mapped child of a window that partially or + completely occludes another child, use + XCirculateSubwindowsDown. + + XCirculateSubwindowsDown(Display *display, Window w); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + The XCirculateSubwindowsDown function lowers the highest mapped + child of the specified window that partially or completely + occludes another child. Completely unobscured children are not + affected. This is a convenience function equivalent to + XCirculateSubwindows with LowerHighest specified. + + XCirculateSubwindowsDown can generate a BadWindow error. + + To restack a set of windows from top to bottom, use + XRestackWindows. + + XRestackWindows(Display *display, Window windows[], int + nwindows); + + display + + Specifies the connection to the X server. + + windows + + Specifies an array containing the windows to be restacked. + + nwindows + + Specifies the number of windows to be restacked. + + The XRestackWindows function restacks the windows in the order + specified, from top to bottom. The stacking order of the first + window in the windows array is unaffected, but the other + windows in the array are stacked underneath the first window, + in the order of the array. The stacking order of the other + windows is not affected. For each window in the window array + that is not a child of the specified window, a BadMatch error + results. + + If the override-redirect attribute of a window is False and + some other client has selected SubstructureRedirectMask on the + parent, the X server generates ConfigureRequest events for each + window whose override-redirect flag is not set, and no further + processing is performed. Otherwise, the windows will be + restacked in top-to-bottom order. + + XRestackWindows can generate a BadWindow error. + +Changing Window Attributes + + Xlib provides functions that you can use to set window + attributes. XChangeWindowAttributes is the more general + function that allows you to set one or more window attributes + provided by the XSetWindowAttributes structure. The other + functions described in this section allow you to set one + specific window attribute, such as a window's background. + + To change one or more attributes for a given window, use + XChangeWindowAttributes. + + XChangeWindowAttributes(Display *display, Window w, unsigned + long valuemask, XSetWindowAttributes *attributes); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + valuemask + + Specifies which window attributes are defined in the attributes + argument. This mask is the bitwise inclusive OR of the valid + attribute mask bits. If valuemask is zero, the attributes are + ignored and are not referenced. The values and restrictions are + the same as for XCreateWindow. + + attributes + + Specifies the structure from which the values (as specified by + the value mask) are to be taken. The value mask should have the + appropriate bits set to indicate which attributes have been set + in the structure (see section 3.2). + + Depending on the valuemask, the XChangeWindowAttributes + function uses the window attributes in the XSetWindowAttributes + structure to change the specified window attributes. Changing + the background does not cause the window contents to be + changed. To repaint the window and its background, use + XClearWindow. Setting the border or changing the background + such that the border tile origin changes causes the border to + be repainted. Changing the background of a root window to None + or ParentRelative restores the default background pixmap. + Changing the border of a root window to CopyFromParent restores + the default border pixmap. Changing the win-gravity does not + affect the current position of the window. Changing the + backing-store of an obscured window to WhenMapped or Always, or + changing the backing-planes, backing-pixel, or save-under of a + mapped window may have no immediate effect. Changing the + colormap of a window (that is, defining a new map, not changing + the contents of the existing map) generates a ColormapNotify + event. Changing the colormap of a visible window may have no + immediate effect on the screen because the map may not be + installed (see XInstallColormap). Changing the cursor of a root + window to None restores the default cursor. Whenever possible, + you are encouraged to share colormaps. + + Multiple clients can select input on the same window. Their + event masks are maintained separately. When an event is + generated, it is reported to all interested clients. However, + only one client at a time can select for + SubstructureRedirectMask, ResizeRedirectMask, and + ButtonPressMask. If a client attempts to select any of these + event masks and some other client has already selected one, a + BadAccess error results. There is only one + do-not-propagate-mask for a window, not one per client. + + XChangeWindowAttributes can generate BadAccess, BadColor, + BadCursor, BadMatch, BadPixmap, BadValue, and BadWindow errors. + + To set the background of a window to a given pixel, use + XSetWindowBackground. + + XSetWindowBackground(Display *display, Window w, unsigned long + background_pixel); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + background_pixel + + Specifies the pixel that is to be used for the background. + + The XSetWindowBackground function sets the background of the + window to the specified pixel value. Changing the background + does not cause the window contents to be changed. + XSetWindowBackground uses a pixmap of undefined size filled + with the pixel value you passed. If you try to change the + background of an InputOnly window, a BadMatch error results. + + XSetWindowBackground can generate BadMatch and BadWindow + errors. + + To set the background of a window to a given pixmap, use + XSetWindowBackgroundPixmap. + + XSetWindowBackgroundPixmap(Display *display, Window w, Pixmap + background_pixmap); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + background_pixmap + + Specifies the background pixmap, ParentRelative, or None. + + The XSetWindowBackgroundPixmap function sets the background + pixmap of the window to the specified pixmap. The background + pixmap can immediately be freed if no further explicit + references to it are to be made. If ParentRelative is + specified, the background pixmap of the window's parent is + used, or on the root window, the default background is + restored. If you try to change the background of an InputOnly + window, a BadMatch error results. If the background is set to + None, the window has no defined background. + + XSetWindowBackgroundPixmap can generate BadMatch, BadPixmap, + and BadWindow errors. XSetWindowBackground and + XSetWindowBackgroundPixmap do not change the current contents + of the window. + + To change and repaint a window's border to a given pixel, use + XSetWindowBorder. + + XSetWindowBorder(Display *display, Window w, unsigned long + border_pixel); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + border_pixel + + Specifies the entry in the colormap. + + The XSetWindowBorder function sets the border of the window to + the pixel value you specify. If you attempt to perform this on + an InputOnly window, a BadMatch error results. + + XSetWindowBorder can generate BadMatch and BadWindow errors. + + To change and repaint the border tile of a given window, use + XSetWindowBorderPixmap. + + XSetWindowBorderPixmap(Display *display, Window w, Pixmap + border_pixmap); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + border_pixmap + + Specifies the border pixmap or CopyFromParent. + + The XSetWindowBorderPixmap function sets the border pixmap of + the window to the pixmap you specify. The border pixmap can be + freed immediately if no further explicit references to it are + to be made. If you specify CopyFromParent, a copy of the parent + window's border pixmap is used. If you attempt to perform this + on an InputOnly window, a BadMatch error results. + + XSetWindowBorderPixmap can generate BadMatch, BadPixmap, and + BadWindow errors. + + To set the colormap of a given window, use XSetWindowColormap. + + XSetWindowColormap(Display *display, Window w, Colormap + colormap); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + colormap + + Specifies the colormap. + + The XSetWindowColormap function sets the specified colormap of + the specified window. The colormap must have the same visual + type as the window, or a BadMatch error results. + + XSetWindowColormap can generate BadColor, BadMatch, and + BadWindow errors. + + To define which cursor will be used in a window, use + XDefineCursor. + + XDefineCursor(Display *display, Window w, Cursor cursor); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + cursor + + Specifies the cursor that is to be displayed or None. + + If a cursor is set, it will be used when the pointer is in the + window. If the cursor is None, it is equivalent to + XUndefineCursor. + + XDefineCursor can generate BadCursor and BadWindow errors. + + To undefine the cursor in a given window, use XUndefineCursor. + + XUndefineCursor(Display *display, Window w); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + The XUndefineCursor function undoes the effect of a previous + XDefineCursor for this window. When the pointer is in the + window, the parent's cursor will now be used. On the root + window, the default cursor is restored. + + XUndefineCursor can generate a BadWindow error. + +Chapter 4. Window Information Functions + + Table of Contents + + Obtaining Window Information + Translating Screen Coordinates + Properties and Atoms + Obtaining and Changing Window Properties + Selections + + After you connect the display to the X server and create a + window, you can use the Xlib window information functions to: + * Obtain information about a window + * Translate screen coordinates + * Manipulate property lists + * Obtain and change window properties + * Manipulate selections + +Obtaining Window Information + + Xlib provides functions that you can use to obtain information + about the window tree, the window's current attributes, the + window's current geometry, or the current pointer coordinates. + Because they are most frequently used by window managers, these + functions all return a status to indicate whether the window + still exists. + + To obtain the parent, a list of children, and number of + children for a given window, use XQueryTree. + + Status XQueryTree(Display *display, Window w, Window + *root_return, Window *parent_return, Window **children_return, + unsigned int *nchildren_return); + + display + + Specifies the connection to the X server. + + w + + Specifies the window whose list of children, root, parent, and + number of children you want to obtain. + + root_return + + Returns the root window. + + parent_return + + Returns the parent window. + + children_return + + Returns the list of children. + + nchildren_return + + Returns the number of children. + + The XQueryTree function returns the root ID, the parent window + ID, a pointer to the list of children windows (NULL when there + are no children), and the number of children in the list for + the specified window. The children are listed in current + stacking order, from bottom-most (first) to top-most (last). + XQueryTree returns zero if it fails and nonzero if it succeeds. + To free a non-NULL children list when it is no longer needed, + use XFree. + + XQueryTree can generate a BadWindow error. + + To obtain the current attributes of a given window, use + XGetWindowAttributes. + + Status XGetWindowAttributes(Display *display, Window w, + XWindowAttributes *window_attributes_return); + + display + + Specifies the connection to the X server. + + w + + Specifies the window whose current attributes you want to + obtain. + + window_attributes_return + + Returns the specified window's attributes in the + XWindowAttributes structure. + + The XGetWindowAttributes function returns the current + attributes for the specified window to an XWindowAttributes + structure. + + + +typedef struct { + int x, y; /* location of window */ + int width, height; /* width and height of window */ + int border_width; /* border width of window */ + int depth; /* depth of window */ + Visual *visual; /* the associated visual structure */ + Window root; /* root of screen containing window * +/ + int class; /* InputOutput, InputOnly*/ + int bit_gravity; /* one of the bit gravity values */ + int win_gravity; /* one of the window gravity values * +/ + int backing_store; /* NotUseful, WhenMapped, Always */ + unsigned long backing_planes; /* planes to be preserved if possible + */ + unsigned long backing_pixel; /* value to be used when restoring pl +anes */ + Bool save_under; /* boolean, should bits under be save +d? */ + Colormap colormap; /* color map to be associated with wi +ndow */ + Bool map_installed; /* boolean, is color map currently in +stalled*/ + int map_state; /* IsUnmapped, IsUnviewable, IsViewab +le */ + long all_event_masks; /* set of events all people have inte +rest in*/ + long your_event_mask; /* my event mask */ + long do_not_propagate_mask; /* set of events that should not prop +agate */ + Bool override_redirect; /* boolean value for override-redirec +t */ + Screen *screen; /* back pointer to correct screen */ +} XWindowAttributes; + + The x and y members are set to the upper-left outer corner + relative to the parent window's origin. The width and height + members are set to the inside size of the window, not including + the border. The border_width member is set to the window's + border width in pixels. The depth member is set to the depth of + the window (that is, bits per pixel for the object). The visual + member is a pointer to the screen's associated Visual + structure. The root member is set to the root window of the + screen containing the window. The class member is set to the + window's class and can be either InputOutput or InputOnly. + + The bit_gravity member is set to the window's bit gravity and + can be one of the following: + ForgetGravity EastGravity + NorthWestGravity SouthWestGravity + NorthGravity SouthGravity + NorthEastGravity SouthEastGravity + WestGravity StaticGravity + + The win_gravity member is set to the window's window gravity + and can be one of the following: + UnmapGravity SouthWestGravity + NorthWestGravity SouthGravity + NorthGravity SouthEastGravity + NorthEastGravity StaticGravity + WestGravity CenterGravity + EastGravity + + For additional information on gravity, see section 3.2.3. + + The backing_store member is set to indicate how the X server + should maintain the contents of a window and can be WhenMapped, + Always, or NotUseful. The backing_planes member is set to + indicate (with bits set to 1) which bit planes of the window + hold dynamic data that must be preserved in backing_stores and + during save_unders. The backing_pixel member is set to indicate + what values to use for planes not set in backing_planes. + + The save_under member is set to True or False. The colormap + member is set to the colormap for the specified window and can + be a colormap ID or None. The map_installed member is set to + indicate whether the colormap is currently installed and can be + True or False. The map_state member is set to indicate the + state of the window and can be IsUnmapped, IsUnviewable, or + IsViewable. IsUnviewable is used if the window is mapped but + some ancestor is unmapped. + + The all_event_masks member is set to the bitwise inclusive OR + of all event masks selected on the window by all clients. The + your_event_mask member is set to the bitwise inclusive OR of + all event masks selected by the querying client. The + do_not_propagate_mask member is set to the bitwise inclusive OR + of the set of events that should not propagate. + + The override_redirect member is set to indicate whether this + window overrides structure control facilities and can be True + or False. Window manager clients should ignore the window if + this member is True. + + The screen member is set to a screen pointer that gives you a + back pointer to the correct screen. This makes it easier to + obtain the screen information without having to loop over the + root window fields to see which field matches. + + XGetWindowAttributes can generate BadDrawable and BadWindow + errors. + + To obtain the current geometry of a given drawable, use + XGetGeometry. + + Status XGetGeometry(Display *display, Drawable d, Window + *root_return, int *x_return, int *y_return, unsigned int + *width_return, unsigned int *height_return, unsigned int + *border_width_return, unsigned int *depth_return); + + display + + Specifies the connection to the X server. + + d + + Specifies the drawable, which can be a window or a pixmap. + + root_return + + Returns the root window. + + x_return + + y_return + + Return the x and y coordinates that define the location of the + drawable. For a window, these coordinates specify the + upper-left outer corner relative to its parent's origin. For + pixmaps, these coordinates are always zero. + + width_return + + height_return + + Return the drawable's dimensions (width and height). For a + window, these dimensions specify the inside size, not including + the border. + + border_width_return + + Returns the border width in pixels. If the drawable is a + pixmap, it returns zero. + + depth_return + + Returns the depth of the drawable (bits per pixel for the + object). + + The XGetGeometry function returns the root window and the + current geometry of the drawable. The geometry of the drawable + includes the x and y coordinates, width and height, border + width, and depth. These are described in the argument list. It + is legal to pass to this function a window whose class is + InputOnly. + + XGetGeometry can generate a BadDrawable error. + +Translating Screen Coordinates + + Applications sometimes need to perform a coordinate + transformation from the coordinate space of one window to + another window or need to determine which window the pointing + device is in. XTranslateCoordinates and XQueryPointer fulfill + these needs (and avoid any race conditions) by asking the X + server to perform these operations. + + To translate a coordinate in one window to the coordinate space + of another window, use XTranslateCoordinates. + + Bool XTranslateCoordinates(Display *display, Window src_w, + Window dest_w, int src_x, int src_y, int *dest_x_return, int + *dest_y_return, Window *child_return); + + display + + Specifies the connection to the X server. + + src_w + + Specifies the source window. + + dest_w + + Specifies the destination window. + + src_x + + src_y + + Specify the x and y coordinates within the source window. + + dest_x_return + + dest_y_return + + Return the x and y coordinates within the destination window. + + child_return + + Returns the child if the coordinates are contained in a mapped + child of the destination window. + + If XTranslateCoordinates returns True, it takes the src_x and + src_y coordinates relative to the source window's origin and + returns these coordinates to dest_x_return and dest_y_return + relative to the destination window's origin. If + XTranslateCoordinates returns False, src_w and dest_w are on + different screens, and dest_x_return and dest_y_return are + zero. If the coordinates are contained in a mapped child of + dest_w, that child is returned to child_return. Otherwise, + child_return is set to None. + + XTranslateCoordinates can generate a BadWindow error. + + To obtain the screen coordinates of the pointer or to determine + the pointer coordinates relative to a specified window, use + XQueryPointer. + + Bool XQueryPointer(Display *display, Window w, Window + *root_return, Window *child_return, int *root_x_return, int + *root_y_return, int *win_x_return, int *win_y_return, unsigned + int *mask_return); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + root_return + + Returns the root window that the pointer is in. + + child_return + + Returns the child window that the pointer is located in, if + any. + + root_x_return + + root_y_return + + Return the pointer coordinates relative to the root window's + origin. + + win_x_return + + win_y_return + + Return the pointer coordinates relative to the specified + window. + + mask_return + + Returns the current state of the modifier keys and pointer + buttons. + + The XQueryPointer function returns the root window the pointer + is logically on and the pointer coordinates relative to the + root window's origin. If XQueryPointer returns False, the + pointer is not on the same screen as the specified window, and + XQueryPointer returns None to child_return and zero to + win_x_return and win_y_return. If XQueryPointer returns True, + the pointer coordinates returned to win_x_return and + win_y_return are relative to the origin of the specified + window. In this case, XQueryPointer returns the child that + contains the pointer, if any, or else None to child_return. + + XQueryPointer returns the current logical state of the keyboard + buttons and the modifier keys in mask_return. It sets + mask_return to the bitwise inclusive OR of one or more of the + button or modifier key bitmasks to match the current state of + the mouse buttons and the modifier keys. + + Note that the logical state of a device (as seen through Xlib) + may lag the physical state if device event processing is frozen + (see section 12.1). + + XQueryPointer can generate a BadWindow error. + +Properties and Atoms + + A property is a collection of named, typed data. The window + system has a set of predefined properties (for example, the + name of a window, size hints, and so on), and users can define + any other arbitrary information and associate it with windows. + Each property has a name, which is an ISO Latin-1 string. For + each named property, a unique identifier (atom) is associated + with it. A property also has a type, for example, string or + integer. These types are also indicated using atoms, so + arbitrary new types can be defined. Data of only one type may + be associated with a single property name. Clients can store + and retrieve properties associated with windows. For efficiency + reasons, an atom is used rather than a character string. + XInternAtom can be used to obtain the atom for property names. + + A property is also stored in one of several possible formats. + The X server can store the information as 8-bit quantities, + 16-bit quantities, or 32-bit quantities. This permits the X + server to present the data in the byte order that the client + expects. If you define further properties of complex type, you + must encode and decode them yourself. These functions must be + carefully written if they are to be portable. For further + information about how to write a library extension, see + appendix C. The type of a property is defined by an atom, which + allows for arbitrary extension in this type scheme. + + Certain property names are predefined in the server for + commonly used functions. The atoms for these properties are + defined in . To avoid name clashes with user + symbols, the #define name for each atom has the XA_ prefix. For + an explanation of the functions that let you get and set much + of the information stored in these predefined properties, see + chapter 14. + + The core protocol imposes no semantics on these property names, + but semantics are specified in other X Consortium standards, + such as the Inter-Client Communication Conventions Manual and + the X Logical Font Description Conventions. + + You can use properties to communicate other information between + applications. The functions described in this section let you + define new properties and get the unique atom IDs in your + applications. + + Although any particular atom can have some client + interpretation within each of the name spaces, atoms occur in + five distinct name spaces within the protocol: + * Selections + * Property names + * Property types + * Font properties + * Type of a ClientMessage event (none are built into the X + server) + + The built-in selection property names are: + PRIMARY SECONDARY + + The built-in property names are: + CUT_BUFFER0 RESOURCE_MANAGER + CUT_BUFFER1 WM_CLASS + CUT_BUFFER2 WM_CLIENT_MACHINE + CUT_BUFFER3 WM_COLORMAP_WINDOWS + CUT_BUFFER4 WM_COMMAND + CUT_BUFFER5 WM_HINTS + CUT_BUFFER6 WM_ICON_NAME + CUT_BUFFER7 WM_ICON_SIZE + RGB_BEST_MAP WM_NAME + RGB_BLUE_MAP WM_NORMAL_HINTS + RGB_DEFAULT_MAP WM_PROTOCOLS + RGB_GRAY_MAP WM_STATE + RGB_GREEN_MAP WM_TRANSIENT_FOR + RGB_RED_MAP WM_ZOOM_HINTS + + The built-in property types are: + ARC PIXMAP + ATOM POINT + BITMAP RGB_COLOR_MAP + CARDINAL RECTANGLE + COLORMAP STRING + CURSOR VISUALID + DRAWABLE WINDOW + FONT WM_HINTS + INTEGER WM_SIZE_HINTS + + The built-in font property names are: + MIN_SPACE STRIKEOUT_DESCENT + NORM_SPACE STRIKEOUT_ASCENT + MAX_SPACE ITALIC_ANGLE + END_SPACE X_HEIGHT + SUPERSCRIPT_X QUAD_WIDTH + SUPERSCRIPT_Y WEIGHT + SUBSCRIPT_X POINT_SIZE + SUBSCRIPT_Y RESOLUTION + UNDERLINE_POSITION COPYRIGHT + UNDERLINE_THICKNESS NOTICE + FONT_NAME FAMILY_NAME + FULL_NAME CAP_HEIGHT + + For further information about font properties, see section 8.5. + + To return an atom for a given name, use XInternAtom. + + Atom XInternAtom(Display *display, char *atom_name, Bool + only_if_exists); + + display + + Specifies the connection to the X server. + + atom_name + + Specifies the name associated with the atom you want returned. + + only_if_exists + + Specifies a Boolean value that indicates whether the atom must + be created. + + The XInternAtom function returns the atom identifier associated + with the specified atom_name string. If only_if_exists is + False, the atom is created if it does not exist. Therefore, + XInternAtom can return None. If the atom name is not in the + Host Portable Character Encoding, the result is + implementation-dependent. Uppercase and lowercase matter; the + strings ``thing'', ``Thing'', and ``thinG'' all designate + different atoms. The atom will remain defined even after the + client's connection closes. It will become undefined only when + the last connection to the X server closes. + + XInternAtom can generate BadAlloc and BadValue errors. + + To return atoms for an array of names, use XInternAtoms. + + Status XInternAtoms(Display *display, char **names, int count, + Bool only_if_exists, Atom *atoms_return); + + display + + Specifies the connection to the X server. + + names + + Specifies the array of atom names. + + count + + Specifies the number of atom names in the array. + + only_if_exists + + Specifies a Boolean value that indicates whether the atom must + be created. + + atoms_return + + Returns the atoms. + + The XInternAtoms function returns the atom identifiers + associated with the specified names. The atoms are stored in + the atoms_return array supplied by the caller. Calling this + function is equivalent to calling XInternAtom for each of the + names in turn with the specified value of only_if_exists, but + this function minimizes the number of round-trip protocol + exchanges between the client and the X server. + + This function returns a nonzero status if atoms are returned + for all of the names; otherwise, it returns zero. + + XInternAtoms can generate BadAlloc and BadValue errors. + + To return a name for a given atom identifier, use XGetAtomName. + + char *XGetAtomName(Display *display, Atom atom); + + display + + Specifies the connection to the X server. + + atom + + Specifies the atom for the property name you want returned. + + The XGetAtomName function returns the name associated with the + specified atom. If the data returned by the server is in the + Latin Portable Character Encoding, then the returned string is + in the Host Portable Character Encoding. Otherwise, the result + is implementation-dependent. To free the resulting string, call + XFree. + + XGetAtomName can generate a BadAtom error. + + To return the names for an array of atom identifiers, use + XGetAtomNames. + + Status XGetAtomNames(Display *display, Atom *atoms, int count, + char **names_return); + + display + + Specifies the connection to the X server. + + atoms + + Specifies the array of atoms. + + count + + Specifies the number of atoms in the array. + + names_return + + Returns the atom names. + + The XGetAtomNames function returns the names associated with + the specified atoms. The names are stored in the names_return + array supplied by the caller. Calling this function is + equivalent to calling XGetAtomName for each of the atoms in + turn, but this function minimizes the number of round-trip + protocol exchanges between the client and the X server. + + This function returns a nonzero status if names are returned + for all of the atoms; otherwise, it returns zero. + + XGetAtomNames can generate a BadAtom error. + +Obtaining and Changing Window Properties + + You can attach a property list to every window. Each property + has a name, a type, and a value (see section 4.3). The value is + an array of 8-bit, 16-bit, or 32-bit quantities, whose + interpretation is left to the clients. The type char is used to + represent 8-bit quantities, the type short is used to represent + 16-bit quantities, and the type long is used to represent + 32-bit quantities. + + Xlib provides functions that you can use to obtain, change, + update, or interchange window properties. In addition, Xlib + provides other utility functions for inter-client communication + (see chapter 14). + + To obtain the type, format, and value of a property of a given + window, use XGetWindowProperty. + + int XGetWindowProperty(Display *display, Window w, Atom + property, long long_offset, long long_length, Bool delete, Atom + req_type, Atom *actual_type_return, int *actual_format_return, + unsigned long *nitems_return, unsigned long + *bytes_after_return, unsigned char **prop_return); + + display + + Specifies the connection to the X server. + + w + + Specifies the window whose property you want to obtain. + + property + + Specifies the property name. + + long_offset + + Specifies the offset in the specified property (in 32-bit + quantities) where the data is to be retrieved. + + long_length + + Specifies the length in 32-bit multiples of the data to be + retrieved. + + delete + + Specifies a Boolean value that determines whether the property + is deleted. + + req_type + + Specifies the atom identifier associated with the property type + or AnyPropertyType. + + actual_type_return + + Returns the atom identifier that defines the actual type of the + property. + + actual_format_return + + Returns the actual format of the property. + + nitems_return + + Returns the actual number of 8-bit, 16-bit, or 32-bit items + stored in the prop_return data. + + bytes_after_return + + Returns the number of bytes remaining to be read in the + property if a partial read was performed. + + prop_return + + Returns the data in the specified format. + + The XGetWindowProperty function returns the actual type of the + property; the actual format of the property; the number of + 8-bit, 16-bit, or 32-bit items transferred; the number of bytes + remaining to be read in the property; and a pointer to the data + actually returned. XGetWindowProperty sets the return arguments + as follows: + * If the specified property does not exist for the specified + window, XGetWindowProperty returns None to + actual_type_return and the value zero to + actual_format_return and bytes_after_return. The + nitems_return argument is empty. In this case, the delete + argument is ignored. + * If the specified property exists but its type does not + match the specified type, XGetWindowProperty returns the + actual property type to actual_type_return, the actual + property format (never zero) to actual_format_return, and + the property length in bytes (even if the + actual_format_return is 16 or 32) to bytes_after_return. It + also ignores the delete argument. The nitems_return + argument is empty. + * If the specified property exists and either you assign + AnyPropertyType to the req_type argument or the specified + type matches the actual property type, XGetWindowProperty + returns the actual property type to actual_type_return and + the actual property format (never zero) to + actual_format_return. It also returns a value to + bytes_after_return and nitems_return, by defining the + following values: + * N = actual length of the stored property in bytes (even if + the format is 16 or 32) I = 4 * long_offset T = N - I L = + MINIMUM(T, 4 * long_length) A = N - (I + L) + * The returned value starts at byte index I in the property + (indexing from zero), and its length in bytes is L. If the + value for long_offset causes L to be negative, a BadValue + error results. The value of bytes_after_return is A, giving + the number of trailing unread bytes in the stored property. + + If the returned format is 8, the returned data is represented + as a char array. If the returned format is 16, the returned + data is represented as a short array and should be cast to that + type to obtain the elements. If the returned format is 32, the + returned data is represented as a long array and should be cast + to that type to obtain the elements. + + XGetWindowProperty always allocates one extra byte in + prop_return (even if the property is zero length) and sets it + to zero so that simple properties consisting of characters do + not have to be copied into yet another string before use. + + If delete is True and bytes_after_return is zero, + XGetWindowProperty deletes the property from the window and + generates a PropertyNotify event on the window. + + The function returns Success if it executes successfully. To + free the resulting data, use XFree. + + XGetWindowProperty can generate BadAtom, BadValue, and + BadWindow errors. + + To obtain a given window's property list, use XListProperties. + + Atom *XListProperties(Display *display, Window w, int + *num_prop_return); + + display + + Specifies the connection to the X server. + + w + + Specifies the window whose property list you want to obtain. + + num_prop_return + + Returns the length of the properties array. + + The XListProperties function returns a pointer to an array of + atom properties that are defined for the specified window or + returns NULL if no properties were found. To free the memory + allocated by this function, use XFree. + + XListProperties can generate a BadWindow error. + + To change a property of a given window, use XChangeProperty. + + XChangeProperty(Display *display, Window w, Atom property, Atom + type, int format, int mode, unsignedchar *data, int nelements); + + display + + Specifies the connection to the X server. + + w + + Specifies the window whose property you want to change. + + property + + Specifies the property name. + + type + + Specifies the type of the property. The X server does not + interpret the type but simply passes it back to an application + that later calls XGetWindowProperty. + + format + + Specifies whether the data should be viewed as a list of 8-bit, + 16-bit, or 32-bit quantities. Possible values are 8, 16, and + 32. This information allows the X server to correctly perform + byte-swap operations as necessary. If the format is 16-bit or + 32-bit, you must explicitly cast your data pointer to an + (unsigned char *) in the call to XChangeProperty. + + mode + + Specifies the mode of the operation. You can pass + PropModeReplace, PropModePrepend, or PropModeAppend. + + data + + Specifies the property data. + + nelements + + Specifies the number of elements of the specified data format. + + The XChangeProperty function alters the property for the + specified window and causes the X server to generate a + PropertyNotify event on that window. XChangeProperty performs + the following: + * If mode is PropModeReplace, XChangeProperty discards the + previous property value and stores the new data. + * If mode is PropModePrepend or PropModeAppend, + XChangeProperty inserts the specified data before the + beginning of the existing data or onto the end of the + existing data, respectively. The type and format must match + the existing property value, or a BadMatch error results. + If the property is undefined, it is treated as defined with + the correct type and format with zero-length data. + + If the specified format is 8, the property data must be a char + array. If the specified format is 16, the property data must be + a short array. If the specified format is 32, the property data + must be a long array. + + The lifetime of a property is not tied to the storing client. + Properties remain until explicitly deleted, until the window is + destroyed, or until the server resets. For a discussion of what + happens when the connection to the X server is closed, see + section 2.6. The maximum size of a property is server dependent + and can vary dynamically depending on the amount of memory the + server has available. (If there is insufficient space, a + BadAlloc error results.) + + XChangeProperty can generate BadAlloc, BadAtom, BadMatch, + BadValue, and BadWindow errors. + + To rotate a window's property list, use + XRotateWindowProperties. + + XRotateWindowProperties(Display *display, Window w, Atom + properties[], int num_prop, int npositions); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + properties + + Specifies the array of properties that are to be rotated. + + num_prop + + Specifies the length of the properties array. + + npositions + + Specifies the rotation amount. + + The XRotateWindowProperties function allows you to rotate + properties on a window and causes the X server to generate + PropertyNotify events. If the property names in the properties + array are viewed as being numbered starting from zero and if + there are num_prop property names in the list, then the value + associated with property name I becomes the value associated + with property name (I + npositions) mod N for all I from zero + to N - 1. The effect is to rotate the states by npositions + places around the virtual ring of property names (right for + positive npositions, left for negative npositions). If + npositions mod N is nonzero, the X server generates a + PropertyNotify event for each property in the order that they + are listed in the array. If an atom occurs more than once in + the list or no property with that name is defined for the + window, a BadMatch error results. If a BadAtom or BadMatch + error results, no properties are changed. + + XRotateWindowProperties can generate BadAtom, BadMatch, and + BadWindow errors. + + To delete a property on a given window, use XDeleteProperty. + + XDeleteProperty(Display *display, Window w, Atom property); + + display + + Specifies the connection to the X server. + + w + + Specifies the window whose property you want to delete. + + property + + Specifies the property name. + + The XDeleteProperty function deletes the specified property + only if the property was defined on the specified window and + causes the X server to generate a PropertyNotify event on the + window unless the property does not exist. + + XDeleteProperty can generate BadAtom and BadWindow errors. + +Selections + + Selections are one method used by applications to exchange + data. By using the property mechanism, applications can + exchange data of arbitrary types and can negotiate the type of + the data. A selection can be thought of as an indirect property + with a dynamic type. That is, rather than having the property + stored in the X server, the property is maintained by some + client (the owner). A selection is global in nature (considered + to belong to the user but be maintained by clients) rather than + being private to a particular window subhierarchy or a + particular set of clients. + + Xlib provides functions that you can use to set, get, or + request conversion of selections. This allows applications to + implement the notion of current selection, which requires that + notification be sent to applications when they no longer own + the selection. Applications that support selection often + highlight the current selection and so must be informed when + another application has acquired the selection so that they can + unhighlight the selection. + + When a client asks for the contents of a selection, it + specifies a selection target type. This target type can be used + to control the transmitted representation of the contents. For + example, if the selection is ``the last thing the user clicked + on'' and that is currently an image, then the target type might + specify whether the contents of the image should be sent in XY + format or Z format. + + The target type can also be used to control the class of + contents transmitted, for example, asking for the ``looks'' + (fonts, line spacing, indentation, and so forth) of a paragraph + selection, not the text of the paragraph. The target type can + also be used for other purposes. The protocol does not + constrain the semantics. + + To set the selection owner, use XSetSelectionOwner. + + XSetSelectionOwner(Display *display, Atom selection, Window + owner, Time time); + + display + + Specifies the connection to the X server. + + selection + + Specifies the selection atom. + + owner + + Specifies the owner of the specified selection atom. You can + pass a window or None. + + time + + Specifies the time. You can pass either a timestamp or + CurrentTime. + + The XSetSelectionOwner function changes the owner and + last-change time for the specified selection and has no effect + if the specified time is earlier than the current last-change + time of the specified selection or is later than the current X + server time. Otherwise, the last-change time is set to the + specified time, with CurrentTime replaced by the current server + time. If the owner window is specified as None, then the owner + of the selection becomes None (that is, no owner). Otherwise, + the owner of the selection becomes the client executing the + request. + + If the new owner (whether a client or None) is not the same as + the current owner of the selection and the current owner is not + None, the current owner is sent a SelectionClear event. If the + client that is the owner of a selection is later terminated + (that is, its connection is closed) or if the owner window it + has specified in the request is later destroyed, the owner of + the selection automatically reverts to None, but the + last-change time is not affected. The selection atom is + uninterpreted by the X server. XGetSelectionOwner returns the + owner window, which is reported in SelectionRequest and + SelectionClear events. Selections are global to the X server. + + XSetSelectionOwner can generate BadAtom and BadWindow errors. + + To return the selection owner, use XGetSelectionOwner. + + Window XGetSelectionOwner(Display *display, Atom selection); + + display + + Specifies the connection to the X server. + + selection + + Specifies the selection atom whose owner you want returned. + + The XGetSelectionOwner function returns the window ID + associated with the window that currently owns the specified + selection. If no selection was specified, the function returns + the constant None. If None is returned, there is no owner for + the selection. + + XGetSelectionOwner can generate a BadAtom error. + + To request conversion of a selection, use XConvertSelection. + + XConvertSelection(Display *display, Atom selection, Atom + target, Atom property, Window requestor, Time time); + + display + + Specifies the connection to the X server. + + selection + + Specifies the selection atom. + + target + + Specifies the target atom. + + property + + Specifies the property name. You also can pass None. + + requestor + + Specifies the requestor. + + time + + Specifies the time. You can pass either a timestamp or + CurrentTime. + + XConvertSelection requests that the specified selection be + converted to the specified target type: + * If the specified selection has an owner, the X server sends + a SelectionRequest event to that owner. + * If no owner for the specified selection exists, the X + server generates a SelectionNotify event to the requestor + with property None. + + The arguments are passed on unchanged in either of the events. + There are two predefined selection atoms: PRIMARY and + SECONDARY. + + XConvertSelection can generate BadAtom and BadWindow errors. + +Chapter 5. Pixmap and Cursor Functions + + Table of Contents + + Creating and Freeing Pixmaps + Creating, Recoloring, and Freeing Cursors + +Creating and Freeing Pixmaps + + Pixmaps can only be used on the screen on which they were + created. Pixmaps are off-screen resources that are used for + various operations, such as defining cursors as tiling patterns + or as the source for certain raster operations. Most graphics + requests can operate either on a window or on a pixmap. A + bitmap is a single bit-plane pixmap. + + To create a pixmap of a given size, use XCreatePixmap. + + Pixmap XCreatePixmap(Display *display, Drawable d, unsigned int + width, unsigned int height, unsigned int depth); + + display + + Specifies the connection to the X server. + + d + + Specifies which screen the pixmap is created on. + + width + + height + + Specify the width and height, which define the dimensions of + the pixmap. + + depth + + Specifies the depth of the pixmap. + + The XCreatePixmap function creates a pixmap of the width, + height, and depth you specified and returns a pixmap ID that + identifies it. It is valid to pass an InputOnly window to the + drawable argument. The width and height arguments must be + nonzero, or a BadValue error results. The depth argument must + be one of the depths supported by the screen of the specified + drawable, or a BadValue error results. + + The server uses the specified drawable to determine on which + screen to create the pixmap. The pixmap can be used only on + this screen and only with other drawables of the same depth + (see XCopyPlane for an exception to this rule). The initial + contents of the pixmap are undefined. + + XCreatePixmap can generate BadAlloc, BadDrawable, and BadValue + errors. + + To free all storage associated with a specified pixmap, use + XFreePixmap. + + XFreePixmap(Display *display, Pixmap pixmap); + + display + + Specifies the connection to the X server. + + pixmap + + Specifies the pixmap. + + The XFreePixmap function first deletes the association between + the pixmap ID and the pixmap. Then, the X server frees the + pixmap storage when there are no references to it. The pixmap + should never be referenced again. + + XFreePixmap can generate a BadPixmap error. + +Creating, Recoloring, and Freeing Cursors + + Each window can have a different cursor defined for it. + Whenever the pointer is in a visible window, it is set to the + cursor defined for that window. If no cursor was defined for + that window, the cursor is the one defined for the parent + window. + + From X's perspective, a cursor consists of a cursor source, + mask, colors, and a hotspot. The mask pixmap determines the + shape of the cursor and must be a depth of one. The source + pixmap must have a depth of one, and the colors determine the + colors of the source. The hotspot defines the point on the + cursor that is reported when a pointer event occurs. There may + be limitations imposed by the hardware on cursors as to size + and whether a mask is implemented. XQueryBestCursor can be used + to find out what sizes are possible. There is a standard font + for creating cursors, but Xlib provides functions that you can + use to create cursors from an arbitrary font or from bitmaps. + + To create a cursor from the standard cursor font, use + XCreateFontCursor. + + #include + + Cursor XCreateFontCursor(Display *display, unsigned int shape); + + display + + Specifies the connection to the X server. + + shape + + Specifies the shape of the cursor. + + X provides a set of standard cursor shapes in a special font + named cursor. Applications are encouraged to use this interface + for their cursors because the font can be customized for the + individual display type. The shape argument specifies which + glyph of the standard fonts to use. + + The hotspot comes from the information stored in the cursor + font. The initial colors of a cursor are a black foreground and + a white background (see XRecolorCursor). For further + information about cursor shapes, see appendix B. + + XCreateFontCursor can generate BadAlloc and BadValue errors. + + To create a cursor from font glyphs, use XCreateGlyphCursor. + + Cursor XCreateGlyphCursor(Display *display, Font source_font, + Font mask_font, unsigned int source_char, unsigned int + mask_char, XColor *foreground_color, XColor *background_color); + + display + + Specifies the connection to the X server. + + source_font + + Specifies the font for the source glyph. + + mask_font + + Specifies the font for the mask glyph or None. + + source_char + + Specifies the character glyph for the source. + + mask_char + + Specifies the glyph character for the mask. + + foreground_color + + Specifies the RGB values for the foreground of the source. + + background_color + + Specifies the RGB values for the background of the source. + + The XCreateGlyphCursor function is similar to + XCreatePixmapCursor except that the source and mask bitmaps are + obtained from the specified font glyphs. The source_char must + be a defined glyph in source_font, or a BadValue error results. + If mask_font is given, mask_char must be a defined glyph in + mask_font, or a BadValue error results. The mask_font and + character are optional. The origins of the source_char and + mask_char (if defined) glyphs are positioned coincidently and + define the hotspot. The source_char and mask_char need not have + the same bounding box metrics, and there is no restriction on + the placement of the hotspot relative to the bounding boxes. If + no mask_char is given, all pixels of the source are displayed. + You can free the fonts immediately by calling XFreeFont if no + further explicit references to them are to be made. + + For 2-byte matrix fonts, the 16-bit value should be formed with + the byte1 member in the most significant byte and the byte2 + member in the least significant byte. + + XCreateGlyphCursor can generate BadAlloc, BadFont, and BadValue + errors. + + To create a cursor from two bitmaps, use XCreatePixmapCursor. + + Cursor XCreatePixmapCursor(Display *display, Pixmap source, + Pixmap mask, XColor *foreground_color, XColor + *background_color, unsigned int x, unsigned int y); + + display + + Specifies the connection to the X server. + + source + + Specifies the shape of the source cursor. + + mask + + Specifies the cursor's source bits to be displayed or None. + + foreground_color + + Specifies the RGB values for the foreground of the source. + + background_color + + Specifies the RGB values for the background of the source. + + x + + y + + Specify the x and y coordinates, which indicate the hotspot + relative to the source's origin. + + The XCreatePixmapCursor function creates a cursor and returns + the cursor ID associated with it. The foreground and background + RGB values must be specified using foreground_color and + background_color, even if the X server only has a StaticGray or + GrayScale screen. The foreground color is used for the pixels + set to 1 in the source, and the background color is used for + the pixels set to 0. Both source and mask, if specified, must + have depth one (or a BadMatch error results) but can have any + root. The mask argument defines the shape of the cursor. The + pixels set to 1 in the mask define which source pixels are + displayed, and the pixels set to 0 define which pixels are + ignored. If no mask is given, all pixels of the source are + displayed. The mask, if present, must be the same size as the + pixmap defined by the source argument, or a BadMatch error + results. The hotspot must be a point within the source, or a + BadMatch error results. + + The components of the cursor can be transformed arbitrarily to + meet display limitations. The pixmaps can be freed immediately + if no further explicit references to them are to be made. + Subsequent drawing in the source or mask pixmap has an + undefined effect on the cursor. The X server might or might not + make a copy of the pixmap. + + XCreatePixmapCursor can generate BadAlloc and BadPixmap errors. + + To determine useful cursor sizes, use XQueryBestCursor. + + Status XQueryBestCursor(Display *display, Drawable d, unsigned + int width, unsigned int height, unsigned int *width_return, + unsigned int *height_return); + + display + + Specifies the connection to the X server. + + d + + Specifies the drawable, which indicates the screen. + + width + + height + + Specify the width and height of the cursor that you want the + size information for. + + width_return + + height_return + + Return the best width and height that is closest to the + specified width and height. + + Some displays allow larger cursors than other displays. The + XQueryBestCursor function provides a way to find out what size + cursors are actually possible on the display. It returns the + largest size that can be displayed. Applications should be + prepared to use smaller cursors on displays that cannot support + large ones. + + XQueryBestCursor can generate a BadDrawable error. + + To change the color of a given cursor, use XRecolorCursor. + + XRecolorCursor(Display *display, Cursor cursor, XColor + *foreground_color, XColor *background_color); + + display + + Specifies the connection to the X server. + + cursor + + Specifies the cursor. + + foreground_color + + Specifies the RGB values for the foreground of the source. + + background_color + + Specifies the RGB values for the background of the source. + + The XRecolorCursor function changes the color of the specified + cursor, and if the cursor is being displayed on a screen, the + change is visible immediately. The pixel members of the XColor + structures are ignored; only the RGB values are used. + + XRecolorCursor can generate a BadCursor error. + + To free (destroy) a given cursor, use XFreeCursor. + + XFreeCursor(Display *display, Cursor cursor); + + display + + Specifies the connection to the X server. + + cursor + + Specifies the cursor. + + The XFreeCursor function deletes the association between the + cursor resource ID and the specified cursor. The cursor storage + is freed when no other resource references it. The specified + cursor ID should not be referred to again. + + XFreeCursor can generate a BadCursor error. + +Chapter 6. Color Management Functions + + Table of Contents + + Color Structures + Color Strings + + RGB Device String Specification + RGB Intensity String Specification + Device-Independent String Specifications + + Color Conversion Contexts and Gamut Mapping + Creating, Copying, and Destroying Colormaps + Mapping Color Names to Values + Allocating and Freeing Color Cells + Modifying and Querying Colormap Cells + Color Conversion Context Functions + + Getting and Setting the Color Conversion Context of a + Colormap + + Obtaining the Default Color Conversion Context + Color Conversion Context Macros + Modifying Attributes of a Color Conversion Context + Creating and Freeing a Color Conversion Context + + Converting between Color Spaces + Callback Functions + + Prototype Gamut Compression Procedure + Supplied Gamut Compression Procedures + Prototype White Point Adjustment Procedure + Supplied White Point Adjustment Procedures + + Gamut Querying Functions + + Red, Green, and Blue Queries + CIELab Queries + CIELuv Queries + TekHVC Queries + + Color Management Extensions + + Color Spaces + Adding Device-Independent Color Spaces + Querying Color Space Format and Prefix + Creating Additional Color Spaces + Parse String Callback + Color Specification Conversion Callback + Function Sets + Adding Function Sets + Creating Additional Function Sets + + Each X window always has an associated colormap that provides a + level of indirection between pixel values and colors displayed + on the screen. Xlib provides functions that you can use to + manipulate a colormap. The X protocol defines colors using + values in the RGB color space. The RGB color space is device + dependent; rendering an RGB value on differing output devices + typically results in different colors. Xlib also provides a + means for clients to specify color using device-independent + color spaces for consistent results across devices. Xlib + supports device-independent color spaces derivable from the CIE + XYZ color space. This includes the CIE XYZ, xyY, L*u*v*, and + L*a*b* color spaces as well as the TekHVC color space. + + This chapter discusses how to: + * Create, copy, and destroy a colormap + * Specify colors by name or value + * Allocate, modify, and free color cells + * Read entries in a colormap + * Convert between color spaces + * Control aspects of color conversion + * Query the color gamut of a screen + * Add new color spaces + + All functions, types, and symbols in this chapter with the + prefix ``Xcms'' are defined in . The remaining + functions and types are defined in . + + Functions in this chapter manipulate the representation of + color on the screen. For each possible value that a pixel can + take in a window, there is a color cell in the colormap. For + example, if a window is 4 bits deep, pixel values 0 through 15 + are defined. A colormap is a collection of color cells. A color + cell consists of a triple of red, green, and blue (RGB) values. + The hardware imposes limits on the number of significant bits + in these values. As each pixel is read out of display memory, + the pixel is looked up in a colormap. The RGB value of the cell + determines what color is displayed on the screen. On a + grayscale display with a black-and-white monitor, the values + are combined to determine the brightness on the screen. + + Typically, an application allocates color cells or sets of + color cells to obtain the desired colors. The client can + allocate read-only cells. In which case, the pixel values for + these colors can be shared among multiple applications, and the + RGB value of the cell cannot be changed. If the client + allocates read/write cells, they are exclusively owned by the + client, and the color associated with the pixel value can be + changed at will. Cells must be allocated (and, if read/write, + initialized with an RGB value) by a client to obtain desired + colors. The use of pixel value for an unallocated cell results + in an undefined color. + + Because colormaps are associated with windows, X supports + displays with multiple colormaps and, indeed, different types + of colormaps. If there are insufficient colormap resources in + the display, some windows will display in their true colors, + and others will display with incorrect colors. A window manager + usually controls which windows are displayed in their true + colors if more than one colormap is required for the color + resources the applications are using. At any time, there is a + set of installed colormaps for a screen. Windows using one of + the installed colormaps display with true colors, and windows + using other colormaps generally display with incorrect colors. + You can control the set of installed colormaps by using + XInstallColormap and XUninstallColormap. + + Colormaps are local to a particular screen. Screens always have + a default colormap, and programs typically allocate cells out + of this colormap. Generally, you should not write applications + that monopolize color resources. Although some hardware + supports multiple colormaps installed at one time, many of the + hardware displays built today support only a single installed + colormap, so the primitives are written to encourage sharing of + colormap entries between applications. + + The DefaultColormap macro returns the default colormap. The + DefaultVisual macro returns the default visual type for the + specified screen. Possible visual types are StaticGray, + GrayScale, StaticColor, PseudoColor, TrueColor, or DirectColor + (see section 3.1). + +Color Structures + + Functions that operate only on RGB color space values use an + XColor structure, which contains: + + + +typedef struct { + unsigned long pixel; /* pixel value */ + unsigned short red, green, blue; /* rgb values */ + char flags; /* DoRed, DoGreen, DoBlue */ + char pad; +} XColor; + + The red, green, and blue values are always in the range 0 to + 65535 inclusive, independent of the number of bits actually + used in the display hardware. The server scales these values + down to the range used by the hardware. Black is represented by + (0,0,0), and white is represented by (65535,65535,65535). In + some functions, the flags member controls which of the red, + green, and blue members is used and can be the inclusive OR of + zero or more of DoRed, DoGreen, and DoBlue. + + Functions that operate on all color space values use an + XcmsColor structure. This structure contains a union of + substructures, each supporting color specification encoding for + a particular color space. Like the XColor structure, the + XcmsColor structure contains pixel and color specification + information (the spec member in the XcmsColor structure). + + + +typedef unsigned long XcmsColorFormat; /* Color Specifi +cation Format */ + +typedef struct { + union { + XcmsRGB RGB; + XcmsRGBi RGBi; + XcmsCIEXYZ CIEXYZ; + XcmsCIEuvY CIEuvY; + XcmsCIExyY CIExyY; + XcmsCIELab CIELab; + XcmsCIELuv CIELuv; + XcmsTekHVC TekHVC; + XcmsPad Pad; + } spec; + unsigned long pixel; + XcmsColorFormat format; +} XcmsColor; /* Xcms Color Structure */ + + Because the color specification can be encoded for the various + color spaces, encoding for the spec member is identified by the + format member, which is of type XcmsColorFormat. The following + macros define standard formats. +#define XcmsUndefinedFormat 0x00000000 +#define XcmsCIEXYZFormat 0x00000001 /* CIE XYZ */ +#define XcmsCIEuvYFormat 0x00000002 /* CIE u'v'Y */ +#define XcmsCIExyYFormat 0x00000003 /* CIE xyY */ +#define XcmsCIELabFormat 0x00000004 /* CIE L*a*b* */ +#define XcmsCIELuvFormat 0x00000005 /* CIE L*u*v* */ +#define XcmsTekHVCFormat 0x00000006 /* TekHVC */ +#define XcmsRGBFormat 0x80000000 /* RGB Device */ +#define XcmsRGBiFormat 0x80000001 /* RGB Intensity */ + + Formats for device-independent color spaces are distinguishable + from those for device-dependent spaces by the 32nd bit. If this + bit is set, it indicates that the color specification is in a + device-dependent form; otherwise, it is in a device-independent + form. If the 31st bit is set, this indicates that the color + space has been added to Xlib at run time (see section 6.12.4). + The format value for a color space added at run time may be + different each time the program is executed. If references to + such a color space must be made outside the client (for + example, storing a color specification in a file), then + reference should be made by color space string prefix (see + XcmsFormatOfPrefix and XcmsPrefixOfFormat). + + Data types that describe the color specification encoding for + the various color spaces are defined as follows: + + + +typedef double XcmsFloat; + +typedef struct { + unsigned short red; /* 0x0000 to 0xffff */ + unsigned short green; /* 0x0000 to 0xffff */ + unsigned short blue; /* 0x0000 to 0xffff */ +} XcmsRGB; /* RGB Device */ + + + +typedef struct { + XcmsFloat red; /* 0.0 to 1.0 */ + XcmsFloat green; /* 0.0 to 1.0 */ + XcmsFloat blue; /* 0.0 to 1.0 */ +} XcmsRGBi; /* RGB Intensity */ + + + +typedef struct { + XcmsFloat X; + XcmsFloat Y; /* 0.0 to 1.0 */ + XcmsFloat Z; +} XcmsCIEXYZ; /* CIE XYZ */ + + + +typedef struct { + XcmsFloat u_prime; /* 0.0 to ~0.6 */ + XcmsFloat v_prime; /* 0.0 to ~0.6 */ + XcmsFloat Y; /* 0.0 to 1.0 */ +} XcmsCIEuvY; /* CIE u'v'Y */ + + + +typedef struct { + XcmsFloat x; /* 0.0 to ~.75 */ + XcmsFloat y; /* 0.0 to ~.85 */ + XcmsFloat Y; /* 0.0 to 1.0 */ +} XcmsCIExyY; /* CIE xyY */ + + + +typedef struct { + XcmsFloat L_star; /* 0.0 to 100.0 */ + XcmsFloat a_star; + XcmsFloat b_star; +} XcmsCIELab; /* CIE L*a*b* */ + + + +typedef struct { + XcmsFloat L_star; /* 0.0 to 100.0 */ + XcmsFloat u_star; + XcmsFloat v_star; +} XcmsCIELuv; /* CIE L*u*v* */ + + + +typedef struct { + XcmsFloat H; /* 0.0 to 360.0 */ + XcmsFloat V; /* 0.0 to 100.0 */ + XcmsFloat C; /* 0.0 to 100.0 */ +} XcmsTekHVC; /* TekHVC */ + + + +typedef struct { + XcmsFloat pad0; + XcmsFloat pad1; + XcmsFloat pad2; + XcmsFloat pad3; +} XcmsPad; /* four doubles */ + + The device-dependent formats provided allow color specification + in: + * RGB Intensity (XcmsRGBi) + * Red, green, and blue linear intensity values, + floating-point values from 0.0 to 1.0, where 1.0 indicates + full intensity, 0.5 half intensity, and so on. + * RGB Device (XcmsRGB) + * Red, green, and blue values appropriate for the specified + output device. XcmsRGB values are of type unsigned short, + scaled from 0 to 65535 inclusive, and are interchangeable + with the red, green, and blue values in an XColor + structure. + + It is important to note that RGB Intensity values are not gamma + corrected values. In contrast, RGB Device values generated as a + result of converting color specifications are always gamma + corrected, and RGB Device values acquired as a result of + querying a colormap or passed in by the client are assumed by + Xlib to be gamma corrected. The term RGB value in this manual + always refers to an RGB Device value. + +Color Strings + + Xlib provides a mechanism for using string names for colors. A + color string may either contain an abstract color name or a + numerical color specification. Color strings are + case-insensitive. + + Color strings are used in the following functions: + * XAllocNamedColor + * XcmsAllocNamedColor + * XLookupColor + * XcmsLookupColor + * XParseColor + * XStoreNamedColor + + Xlib supports the use of abstract color names, for example, red + or blue. A value for this abstract name is obtained by + searching one or more color name databases. Xlib first searches + zero or more client-side databases; the number, location, and + content of these databases is implementation-dependent and + might depend on the current locale. If the name is not found, + Xlib then looks for the color in the X server's database. If + the color name is not in the Host Portable Character Encoding, + the result is implementation-dependent. + + A numerical color specification consists of a color space name + and a set of values in the following syntax: + +:/.../ + + The following are examples of valid color strings. + +"CIEXYZ:0.3227/0.28133/0.2493" +"RGBi:1.0/0.0/0.0" +"rgb:00/ff/00" +"CIELuv:50.0/0.0/0.0" + + The syntax and semantics of numerical specifications are given + for each standard color space in the following sections. + +RGB Device String Specification + + An RGB Device specification is identified by the prefix + ``rgb:'' and conforms to the following syntax: + +rgb:// + + , , := h | hh | hhh | hhhh + h := single hexadecimal digits (case insignificant) + + Note that h indicates the value scaled in 4 bits, hh the value + scaled in 8 bits, hhh the value scaled in 12 bits, and hhhh the + value scaled in 16 bits, respectively. + + Typical examples are the strings ``rgb:ea/75/52'' and + ``rgb:ccc/320/320'', but mixed numbers of hexadecimal digit + strings (``rgb:ff/a5/0'' and ``rgb:ccc/32/0'') are also + allowed. + + For backward compatibility, an older syntax for RGB Device is + supported, but its continued use is not encouraged. The syntax + is an initial sharp sign character followed by a numeric + specification, in one of the following formats: + + + +#RGB (4 bits each) +#RRGGBB (8 bits each) +#RRRGGGBBB (12 bits each) +#RRRRGGGGBBBB (16 bits each) + + The R, G, and B represent single hexadecimal digits. When fewer + than 16 bits each are specified, they represent the most + significant bits of the value (unlike the ``rgb:'' syntax, in + which values are scaled). For example, the string ``#3a7'' is + the same as ``#3000a0007000''. + +RGB Intensity String Specification + + An RGB intensity specification is identified by the prefix + ``rgbi:'' and conforms to the following syntax: + +rgbi:// + + Note that red, green, and blue are floating-point values + between 0.0 and 1.0, inclusive. The input format for these + values is an optional sign, a string of numbers possibly + containing a decimal point, and an optional exponent field + containing an E or e followed by a possibly signed integer + string. + +Device-Independent String Specifications + + The standard device-independent string specifications have the + following syntax: + +CIEXYZ:// +CIEuvY:// +CIExyY:// +CIELab:// +CIELuv:// +TekHVC:// + + All of the values (C, H, V, X, Y, Z, a, b, u, v, y, x) are + floating-point values. The syntax for these values is an + optional plus or minus sign, a string of digits possibly + containing a decimal point, and an optional exponent field + consisting of an ``E'' or ``e'' followed by an optional plus or + minus followed by a string of digits. + +Color Conversion Contexts and Gamut Mapping + + When Xlib converts device-independent color specifications into + device-dependent specifications and vice versa, it uses + knowledge about the color limitations of the screen hardware. + This information, typically called the device profile, is + available in a Color Conversion Context (CCC). + + Because a specified color may be outside the color gamut of the + target screen and the white point associated with the color + specification may differ from the white point inherent to the + screen, Xlib applies gamut mapping when it encounters certain + conditions: + * Gamut compression occurs when conversion of + device-independent color specifications to device-dependent + color specifications results in a color out of the target + screen's gamut. + * White adjustment occurs when the inherent white point of + the screen differs from the white point assumed by the + client. + + Gamut handling methods are stored as callbacks in the CCC, + which in turn are used by the color space conversion routines. + Client data is also stored in the CCC for each callback. The + CCC also contains the white point the client assumes to be + associated with color specifications (that is, the Client White + Point). The client can specify the gamut handling callbacks and + client data as well as the Client White Point. Xlib does not + preclude the X client from performing other forms of gamut + handling (for example, gamut expansion); however, Xlib does not + provide direct support for gamut handling other than white + adjustment and gamut compression. + + Associated with each colormap is an initial CCC transparently + generated by Xlib. Therefore, when you specify a colormap as an + argument to an Xlib function, you are indirectly specifying a + CCC. There is a default CCC associated with each screen. Newly + created CCCs inherit attributes from the default CCC, so the + default CCC attributes can be modified to affect new CCCs. + + Xcms functions in which gamut mapping can occur return Status + and have specific status values defined for them, as follows: + * XcmsFailure indicates that the function failed. + * XcmsSuccess indicates that the function succeeded. In + addition, if the function performed any color conversion, + the colors did not need to be compressed. + * XcmsSuccessWithCompression indicates the function performed + color conversion and at least one of the colors needed to + be compressed. The gamut compression method is determined + by the gamut compression procedure in the CCC that is + specified directly as a function argument or in the CCC + indirectly specified by means of the colormap argument. + +Creating, Copying, and Destroying Colormaps + + To create a colormap for a screen, use XCreateColormap. + + Colormap XCreateColormap(Display *display, Window w, Visual + *visual, int alloc); + + display + + Specifies the connection to the X server. + + w + + Specifies the window on whose screen you want to create a + colormap. + + visual + + Specifies a visual type supported on the screen. If the visual + type is not one supported by the screen, a BadMatch error + results. + + alloc + + Specifies the colormap entries to be allocated. You can pass + AllocNone or AllocAll. + + The XCreateColormap function creates a colormap of the + specified visual type for the screen on which the specified + window resides and returns the colormap ID associated with it. + Note that the specified window is only used to determine the + screen. + + The initial values of the colormap entries are undefined for + the visual classes GrayScale, PseudoColor, and DirectColor. For + StaticGray, StaticColor, and TrueColor, the entries have + defined values, but those values are specific to the visual and + are not defined by X. For StaticGray, StaticColor, and + TrueColor, alloc must be AllocNone, or a BadMatch error + results. For the other visual classes, if alloc is AllocNone, + the colormap initially has no allocated entries, and clients + can allocate them. For information about the visual types, see + section 3.1. + + If alloc is AllocAll, the entire colormap is allocated + writable. The initial values of all allocated entries are + undefined. For GrayScale and PseudoColor, the effect is as if + an XAllocColorCells call returned all pixel values from zero to + N - 1, where N is the colormap entries value in the specified + visual. For DirectColor, the effect is as if an + XAllocColorPlanes call returned a pixel value of zero and + red_mask, green_mask, and blue_mask values containing the same + bits as the corresponding masks in the specified visual. + However, in all cases, none of these entries can be freed by + using XFreeColors. + + XCreateColormap can generate BadAlloc, BadMatch, BadValue, and + BadWindow errors. + + To create a new colormap when the allocation out of a + previously shared colormap has failed because of resource + exhaustion, use XCopyColormapAndFree. + + Colormap XCopyColormapAndFree(Display *display, Colormap + colormap); + + display + + Specifies the connection to the X server. + + colormap + + Specifies the colormap. + + The XCopyColormapAndFree function creates a colormap of the + same visual type and for the same screen as the specified + colormap and returns the new colormap ID. It also moves all of + the client's existing allocation from the specified colormap to + the new colormap with their color values intact and their + read-only or writable characteristics intact and frees those + entries in the specified colormap. Color values in other + entries in the new colormap are undefined. If the specified + colormap was created by the client with alloc set to AllocAll, + the new colormap is also created with AllocAll, all color + values for all entries are copied from the specified colormap, + and then all entries in the specified colormap are freed. If + the specified colormap was not created by the client with + AllocAll, the allocations to be moved are all those pixels and + planes that have been allocated by the client using + XAllocColor, XAllocNamedColor, XAllocColorCells, or + XAllocColorPlanes and that have not been freed since they were + allocated. + + XCopyColormapAndFree can generate BadAlloc and BadColor errors. + + To destroy a colormap, use XFreeColormap. + + XFreeColormap(Display *display, Colormap colormap); + + display + + Specifies the connection to the X server. + + colormap + + Specifies the colormap that you want to destroy. + + The XFreeColormap function deletes the association between the + colormap resource ID and the colormap and frees the colormap + storage. However, this function has no effect on the default + colormap for a screen. If the specified colormap is an + installed map for a screen, it is uninstalled (see + XUninstallColormap). If the specified colormap is defined as + the colormap for a window (by XCreateWindow, + XSetWindowColormap, or XChangeWindowAttributes), XFreeColormap + changes the colormap associated with the window to None and + generates a ColormapNotify event. X does not define the colors + displayed for a window with a colormap of None. + + XFreeColormap can generate a BadColor error. + +Mapping Color Names to Values + + To map a color name to an RGB value, use XLookupColor. + + Status XLookupColor(Display *display, Colormap colormap, char + *color_name, XColor *exact_def_return, XColor + *screen_def_return); + + display + + Specifies the connection to the X server. + + colormap + + Specifies the colormap. + + color_name + + Specifies the color name string (for example, red) whose color + definition structure you want returned. + + exact_def_return + + Returns the exact RGB values. + + screen_def_return + + Returns the closest RGB values provided by the hardware. + + The XLookupColor function looks up the string name of a color + with respect to the screen associated with the specified + colormap. It returns both the exact color values and the + closest values provided by the screen with respect to the + visual type of the specified colormap. If the color name is not + in the Host Portable Character Encoding, the result is + implementation-dependent. Use of uppercase or lowercase does + not matter. XLookupColor returns nonzero if the name is + resolved; otherwise, it returns zero. + + XLookupColor can generate a BadColor error. + + To map a color name to the exact RGB value, use XParseColor. + + Status XParseColor(Display *display, Colormap colormap, char + *spec, XColor *exact_def_return); + + display + + Specifies the connection to the X server. + + colormap + + Specifies the colormap. + + spec + + Specifies the color name string; case is ignored. + + exact_def_return + + Returns the exact color value for later use and sets the DoRed, + DoGreen, and DoBlue flags. + + The XParseColor function looks up the string name of a color + with respect to the screen associated with the specified + colormap. It returns the exact color value. If the color name + is not in the Host Portable Character Encoding, the result is + implementation-dependent. Use of uppercase or lowercase does + not matter. XParseColor returns nonzero if the name is + resolved; otherwise, it returns zero. + + XParseColor can generate a BadColor error. + + To map a color name to a value in an arbitrary color space, use + XcmsLookupColor. + + Status XcmsLookupColor(Display *display, Colormap colormap, + char *color_string, XcmsColor *color_exact_return, XcmsColor + *color_screen_return, XcmsColorFormat result_format); + + display + + Specifies the connection to the X server. + + colormap + + Specifies the colormap. + + color_string + + Specifies the color string(St. + + color_exact_return + + Returns the color specification parsed from the color string or + parsed from the corresponding string found in a color-name + database. + + color_screen_return + + Returns the color that can be reproduced on the screen. + + result_format + + Specifies the color format for the returned color + specifications (color_screen_return and color_exact_return + arguments). If the format is XcmsUndefinedFormat and the color + string contains a numerical color specification, the + specification is returned in the format used in that numerical + color specification. If the format is XcmsUndefinedFormat and + the color string contains a color name, the specification is + returned in the format used to store the color in the database. + + The XcmsLookupColor function looks up the string name of a + color with respect to the screen associated with the specified + colormap. It returns both the exact color values and the + closest values provided by the screen with respect to the + visual type of the specified colormap. The values are returned + in the format specified by result_format. If the color name is + not in the Host Portable Character Encoding, the result is + implementation-dependent. Use of uppercase or lowercase does + not matter. XcmsLookupColor returns XcmsSuccess or + XcmsSuccessWithCompression if the name is resolved; otherwise, + it returns XcmsFailure. If XcmsSuccessWithCompression is + returned, the color specification returned in + color_screen_return is the result of gamut compression. + +Allocating and Freeing Color Cells + + There are two ways of allocating color cells: explicitly as + read-only entries, one pixel value at a time, or read/write, + where you can allocate a number of color cells and planes + simultaneously. A read-only cell has its RGB value set by the + server. Read/write cells do not have defined colors initially; + functions described in the next section must be used to store + values into them. Although it is possible for any client to + store values into a read/write cell allocated by another + client, read/write cells normally should be considered private + to the client that allocated them. + + Read-only colormap cells are shared among clients. The server + counts each allocation and freeing of the cell by clients. When + the last client frees a shared cell, the cell is finally + deallocated. If a single client allocates the same read-only + cell multiple times, the server counts each such allocation, + not just the first one. + + To allocate a read-only color cell with an RGB value, use + XAllocColor. + + Status XAllocColor(Display *display, Colormap colormap, XColor + *screen_in_out); + + display + + Specifies the connection to the X server. + + colormap + + Specifies the colormap. + + screen_in_out + + Specifies and returns the values actually used in the colormap. + + The XAllocColor function allocates a read-only colormap entry + corresponding to the closest RGB value supported by the + hardware. XAllocColor returns the pixel value of the color + closest to the specified RGB elements supported by the hardware + and returns the RGB value actually used. The corresponding + colormap cell is read-only. In addition, XAllocColor returns + nonzero if it succeeded or zero if it failed. Multiple clients + that request the same effective RGB value can be assigned the + same read-only entry, thus allowing entries to be shared. When + the last client deallocates a shared cell, it is deallocated. + XAllocColor does not use or affect the flags in the XColor + structure. + + XAllocColor can generate a BadColor error. delim %% + + To allocate a read-only color cell with a color in arbitrary + format, use XcmsAllocColor. + + Status XcmsAllocColor(Display *display, Colormap colormap, + XcmsColor *color_in_out, XcmsColorFormat result_format); + + display + + Specifies the connection to the X server. + + colormap + + Specifies the colormap. + + color_in_out + + Specifies the color to allocate and returns the pixel and color + that is actually used in the colormap. + + result_format + + Specifies the color format for the returned color + specification. + + The XcmsAllocColor function is similar to XAllocColor except + the color can be specified in any format. The XcmsAllocColor + function ultimately calls XAllocColor to allocate a read-only + color cell (colormap entry) with the specified color. + XcmsAllocColor first converts the color specified to an RGB + value and then passes this to XAllocColor. XcmsAllocColor + returns the pixel value of the color cell and the color + specification actually allocated. This returned color + specification is the result of converting the RGB value + returned by XAllocColor into the format specified with the + result_format argument. If there is no interest in a returned + color specification, unnecessary computation can be bypassed if + result_format is set to XcmsRGBFormat. The corresponding + colormap cell is read-only. If this routine returns + XcmsFailure, the color_in_out color specification is left + unchanged. + + XcmsAllocColor can generate a BadColor error. + + To allocate a read-only color cell using a color name and + return the closest color supported by the hardware in RGB + format, use XAllocNamedColor. + + Status XAllocNamedColor(Display *display, Colormap colormap, + char *color_name, XColor *screen_def_return, XColor + *exact_def_return); + + display + + Specifies the connection to the X server. + + colormap + + Specifies the colormap. + + color_name + + Specifies the color name string (for example, red) whose color + definition structure you want returned. + + screen_def_return + + Returns the closest RGB values provided by the hardware. + + exact_def_return + + Returns the exact RGB values. + + The XAllocNamedColor function looks up the named color with + respect to the screen that is associated with the specified + colormap. It returns both the exact database definition and the + closest color supported by the screen. The allocated color cell + is read-only. The pixel value is returned in screen_def_return. + If the color name is not in the Host Portable Character + Encoding, the result is implementation-dependent. Use of + uppercase or lowercase does not matter. If screen_def_return + and exact_def_return point to the same structure, the pixel + field will be set correctly, but the color values are + undefined. XAllocNamedColor returns nonzero if a cell is + allocated; otherwise, it returns zero. + + XAllocNamedColor can generate a BadColor error. + + To allocate a read-only color cell using a color name and + return the closest color supported by the hardware in an + arbitrary format, use XcmsAllocNamedColor. + + Status XcmsAllocNamedColor(Display *display, Colormap colormap, + char *color_string, XcmsColor *color_screen_return, XcmsColor + *color_exact_return, XcmsColorFormat result_format); + + display + + Specifies the connection to the X server. + + colormap + + Specifies the colormap. + + color_string + + Specifies the color string whose color definition structure is + to be returned. + + color_screen_return + + Returns the pixel value of the color cell and color + specification that actually is stored for that cell. + + color_exact_return + + Returns the color specification parsed from the color string or + parsed from the corresponding string found in a color-name + database. + + result_format + + Specifies the color format for the returned color + specifications (color_screen_return and color_exact_return + arguments). If the format is XcmsUndefinedFormat and the color + string contains a numerical color specification, the + specification is returned in the format used in that numerical + color specification. If the format is XcmsUndefinedFormat and + the color string contains a color name, the specification is + returned in the format used to store the color in the database. + + The XcmsAllocNamedColor function is similar to XAllocNamedColor + except that the color returned can be in any format specified. + This function ultimately calls XAllocColor to allocate a + read-only color cell with the color specified by a color + string. The color string is parsed into an XcmsColor structure + (see XcmsLookupColor), converted to an RGB value, and finally + passed to XAllocColor. If the color name is not in the Host + Portable Character Encoding, the result is + implementation-dependent. Use of uppercase or lowercase does + not matter. + + This function returns both the color specification as a result + of parsing (exact specification) and the actual color + specification stored (screen specification). This screen + specification is the result of converting the RGB value + returned by XAllocColor into the format specified in + result_format. If there is no interest in a returned color + specification, unnecessary computation can be bypassed if + result_format is set to XcmsRGBFormat. If color_screen_return + and color_exact_return point to the same structure, the pixel + field will be set correctly, but the color values are + undefined. + + XcmsAllocNamedColor can generate a BadColor error. + + To allocate read/write color cell and color plane combinations + for a PseudoColor model, use XAllocColorCells. + + Status XAllocColorCells(Display *display, Colormap colormap, + Bool contig, unsigned long plane_masks_return[], unsigned int + nplanes, unsigned long pixels_return[], unsigned int npixels); + + display + + Specifies the connection to the X server. + + colormap + + Specifies the colormap. + + contig + + Specifies a Boolean value that indicates whether the planes + must be contiguous. + + plane_mask_return + + Returns an array of plane masks. + + nplanes + + Specifies the number of plane masks that are to be returned in + the plane masks array. + + pixels_return + + Returns an array of pixel values. + + npixels + + Specifies the number of pixel values that are to be returned in + the pixels_return array. + + The XAllocColorCells function allocates read/write color cells. + The number of colors must be positive and the number of planes + nonnegative, or a BadValue error results. If ncolors and + nplanes are requested, then ncolors pixels and nplane plane + masks are returned. No mask will have any bits set to 1 in + common with any other mask or with any of the pixels. By ORing + together each pixel with zero or more masks, ncolors × + 2^nplanes distinct pixels can be produced. All of these are + allocated writable by the request. For GrayScale or + PseudoColor, each mask has exactly one bit set to 1. For + DirectColor, each has exactly three bits set to 1. If contig is + True and if all masks are ORed together, a single contiguous + set of bits set to 1 will be formed for GrayScale or + PseudoColor and three contiguous sets of bits set to 1 (one + within each pixel subfield) for DirectColor. The RGB values of + the allocated entries are undefined. XAllocColorCells returns + nonzero if it succeeded or zero if it failed. + + XAllocColorCells can generate BadColor and BadValue errors. + + To allocate read/write color resources for a DirectColor model, + use XAllocColorPlanes. + + Status XAllocColorPlanes(Display *display, Colormap colormap, + Bool contig, unsigned long pixels_return[], int ncolors, int + nreds, int ngreens, int nblues, unsigned long *rmask_return, + unsigned long *gmask_return, unsigned long *bmask_return); + + display + + Specifies the connection to the X server. + + colormap + + Specifies the colormap. + + contig + + Specifies a Boolean value that indicates whether the planes + must be contiguous. + + pixels_return + + Returns an array of pixel values. XAllocColorPlanes returns the + pixel values in this array. + + ncolors + + Specifies the number of pixel values that are to be returned in + the pixels_return array. + + nreds + + ngreens + + nblues + + Specify the number of red, green, and blue planes. The value + you pass must be nonnegative. + + rmask_return + + gmask_return + + bmask_return + + Return bit masks for the red, green, and blue planes. + + The specified ncolors must be positive; and nreds, ngreens, and + nblues must be nonnegative, or a BadValue error results. If + ncolors colors, nreds reds, ngreens greens, and nblues blues + are requested, ncolors pixels are returned; and the masks have + nreds, ngreens, and nblues bits set to 1, respectively. If + contig is True, each mask will have a contiguous set of bits + set to 1. No mask will have any bits set to 1 in common with + any other mask or with any of the pixels. For DirectColor, each + mask will lie within the corresponding pixel subfield. By ORing + together subsets of masks with each pixel value, ncolors × + 2^(nreds+ngreens+nblues) distinct pixel values can be produced. + All of these are allocated by the request. However, in the + colormap, there are only ncolors × 2^nreds independent red + entries, ncolors × 2^ngreens independent green entries, and + ncolors × 2^nblues independent blue entries. This is true even + for PseudoColor. When the colormap entry of a pixel value is + changed (using XStoreColors, XStoreColor, or XStoreNamedColor), + the pixel is decomposed according to the masks, and the + corresponding independent entries are updated. + XAllocColorPlanes returns nonzero if it succeeded or zero if it + failed. + + XAllocColorPlanes can generate BadColor and BadValue errors. + + To free colormap cells, use XFreeColors. + + XFreeColors(Display *display, Colormap colormap, unsigned long + pixels[], int npixels, unsigned long planes); + + display + + Specifies the connection to the X server. + + colormap + + Specifies the colormap. + + pixels + + Specifies an array of pixel values that map to the cells in the + specified colormap. + + npixels + + Specifies the number of pixels. + + planes + + Specifies the planes you want to free. + + The XFreeColors function frees the cells represented by pixels + whose values are in the pixels array. The planes argument + should not have any bits set to 1 in common with any of the + pixels. The set of all pixels is produced by ORing together + subsets of the planes argument with the pixels. The request + frees all of these pixels that were allocated by the client + (using XAllocColor, XAllocNamedColor, XAllocColorCells, and + XAllocColorPlanes). Note that freeing an individual pixel + obtained from XAllocColorPlanes may not actually allow it to be + reused until all of its related pixels are also freed. + Similarly, a read-only entry is not actually freed until it has + been freed by all clients, and if a client allocates the same + read-only entry multiple times, it must free the entry that + many times before the entry is actually freed. + + All specified pixels that are allocated by the client in the + colormap are freed, even if one or more pixels produce an + error. If a specified pixel is not a valid index into the + colormap, a BadValue error results. If a specified pixel is not + allocated by the client (that is, is unallocated or is only + allocated by another client) or if the colormap was created + with all entries writable (by passing AllocAll to + XCreateColormap), a BadAccess error results. If more than one + pixel is in error, the one that gets reported is arbitrary. + + XFreeColors can generate BadAccess, BadColor, and BadValue + errors. + +Modifying and Querying Colormap Cells + + To store an RGB value in a single colormap cell, use + XStoreColor. + + XStoreColor(Display *display, Colormap colormap, XColor + *color); + + display + + Specifies the connection to the X server. + + colormap + + Specifies the colormap. + + color + + Specifies the pixel and RGB values. + + The XStoreColor function changes the colormap entry of the + pixel value specified in the pixel member of the XColor + structure. You specified this value in the pixel member of the + XColor structure. This pixel value must be a read/write cell + and a valid index into the colormap. If a specified pixel is + not a valid index into the colormap, a BadValue error results. + XStoreColor also changes the red, green, and/or blue color + components. You specify which color components are to be + changed by setting DoRed, DoGreen, and/or DoBlue in the flags + member of the XColor structure. If the colormap is an installed + map for its screen, the changes are visible immediately. + + XStoreColor can generate BadAccess, BadColor, and BadValue + errors. + + To store multiple RGB values in multiple colormap cells, use + XStoreColors. + + XStoreColors(Display *display, Colormap colormap, XColor + color[], int ncolors); + + display + + Specifies the connection to the X server. + + colormap + + Specifies the colormap. + + color + + Specifies an array of color definition structures to be stored. + + ncolors + + Specifies the number of XColor structures in the color + definition array. + + The XStoreColors function changes the colormap entries of the + pixel values specified in the pixel members of the XColor + structures. You specify which color components are to be + changed by setting DoRed, DoGreen, and/or DoBlue in the flags + member of the XColor structures. If the colormap is an + installed map for its screen, the changes are visible + immediately. XStoreColors changes the specified pixels if they + are allocated writable in the colormap by any client, even if + one or more pixels generates an error. If a specified pixel is + not a valid index into the colormap, a BadValue error results. + If a specified pixel either is unallocated or is allocated + read-only, a BadAccess error results. If more than one pixel is + in error, the one that gets reported is arbitrary. + + XStoreColors can generate BadAccess, BadColor, and BadValue + errors. + + To store a color of arbitrary format in a single colormap cell, + use XcmsStoreColor. + + Status XcmsStoreColor(Display *display, Colormap colormap, + XcmsColor *color); + + display + + Specifies the connection to the X server. + + colormap + + Specifies the colormap. + + color + + Specifies the color cell and the color to store. Values + specified in this XcmsColor structure remain unchanged on + return. + + The XcmsStoreColor function converts the color specified in the + XcmsColor structure into RGB values. It then uses this RGB + specification in an XColor structure, whose three flags (DoRed, + DoGreen, and DoBlue) are set, in a call to XStoreColor to + change the color cell specified by the pixel member of the + XcmsColor structure. This pixel value must be a valid index for + the specified colormap, and the color cell specified by the + pixel value must be a read/write cell. If the pixel value is + not a valid index, a BadValue error results. If the color cell + is unallocated or is allocated read-only, a BadAccess error + results. If the colormap is an installed map for its screen, + the changes are visible immediately. + + Note that XStoreColor has no return value; therefore, an + XcmsSuccess return value from this function indicates that the + conversion to RGB succeeded and the call to XStoreColor was + made. To obtain the actual color stored, use XcmsQueryColor. + Because of the screen's hardware limitations or gamut + compression, the color stored in the colormap may not be + identical to the color specified. + + XcmsStoreColor can generate BadAccess, BadColor, and BadValue + errors. + + To store multiple colors of arbitrary format in multiple + colormap cells, use XcmsStoreColors. + + Status XcmsStoreColors(Display *display, Colormap colormap, + XcmsColor colors[], int ncolors, Bool + compression_flags_return[]); + + display + + Specifies the connection to the X server. + + colormap + + Specifies the colormap. + + colors + + Specifies the color specification array of XcmsColor + structures, each specifying a color cell and the color to store + in that cell. Values specified in the array remain unchanged + upon return. + + ncolors + + Specifies the number of XcmsColor structures in the + color-specification array. + + compression_flags_return + + Returns an array of Boolean values indicating compression + status. If a non-NULL pointer is supplied, each element of the + array is set to True if the corresponding color was compressed + and False otherwise. Pass NULL if the compression status is not + useful. + + The XcmsStoreColors function converts the colors specified in + the array of XcmsColor structures into RGB values and then uses + these RGB specifications in XColor structures, whose three + flags (DoRed, DoGreen, and DoBlue) are set, in a call to + XStoreColors to change the color cells specified by the pixel + member of the corresponding XcmsColor structure. Each pixel + value must be a valid index for the specified colormap, and the + color cell specified by each pixel value must be a read/write + cell. If a pixel value is not a valid index, a BadValue error + results. If a color cell is unallocated or is allocated + read-only, a BadAccess error results. If more than one pixel is + in error, the one that gets reported is arbitrary. If the + colormap is an installed map for its screen, the changes are + visible immediately. + + Note that XStoreColors has no return value; therefore, an + XcmsSuccess return value from this function indicates that + conversions to RGB succeeded and the call to XStoreColors was + made. To obtain the actual colors stored, use XcmsQueryColors. + Because of the screen's hardware limitations or gamut + compression, the colors stored in the colormap may not be + identical to the colors specified. + + XcmsStoreColors can generate BadAccess, BadColor, and BadValue + errors. + + To store a color specified by name in a single colormap cell, + use XStoreNamedColor. + + XStoreNamedColor(Display *display, Colormap colormap, char + *color, unsigned long pixel, int flags); + + display + + Specifies the connection to the X server. + + colormap + + Specifies the colormap. + + color + + Specifies the color name string (for example, red). + + pixel + + Specifies the entry in the colormap. + + flags + + Specifies which red, green, and blue components are set. + + The XStoreNamedColor function looks up the named color with + respect to the screen associated with the colormap and stores + the result in the specified colormap. The pixel argument + determines the entry in the colormap. The flags argument + determines which of the red, green, and blue components are + set. You can set this member to the bitwise inclusive OR of the + bits DoRed, DoGreen, and DoBlue. If the color name is not in + the Host Portable Character Encoding, the result is + implementation-dependent. Use of uppercase or lowercase does + not matter. If the specified pixel is not a valid index into + the colormap, a BadValue error results. If the specified pixel + either is unallocated or is allocated read-only, a BadAccess + error results. + + XStoreNamedColor can generate BadAccess, BadColor, BadName, and + BadValue errors. + + The XQueryColor and XQueryColors functions take pixel values in + the pixel member of XColor structures and store in the + structures the RGB values for those pixels from the specified + colormap. The values returned for an unallocated entry are + undefined. These functions also set the flags member in the + XColor structure to all three colors. If a pixel is not a valid + index into the specified colormap, a BadValue error results. If + more than one pixel is in error, the one that gets reported is + arbitrary. + + To query the RGB value of a single colormap cell, use + XQueryColor. + + XQueryColor(Display *display, Colormap colormap, XColor + *def_in_out); + + display + + Specifies the connection to the X server. + + colormap + + Specifies the colormap. + + def_in_out + + Specifies and returns the RGB values for the pixel specified in + the structure. + + The XQueryColor function returns the current RGB value for the + pixel in the XColor structure and sets the DoRed, DoGreen, and + DoBlue flags. + + XQueryColor can generate BadColor and BadValue errors. + + To query the RGB values of multiple colormap cells, use + XQueryColors. + + XQueryColors(Display *display, Colormap colormap, XColor + defs_in_out[], int ncolors); + + display + + Specifies the connection to the X server. + + colormap + + Specifies the colormap. + + defs_in_out + + Specifies and returns an array of color definition structures + for the pixel specified in the structure. + + ncolors + + Specifies the number of XColor structures in the color + definition array. + + The XQueryColors function returns the RGB value for each pixel + in each XColor structure and sets the DoRed, DoGreen, and + DoBlue flags in each structure. + + XQueryColors can generate BadColor and BadValue errors. + + To query the color of a single colormap cell in an arbitrary + format, use XcmsQueryColor. + + Status XcmsQueryColor(Display *display, Colormap colormap, + XcmsColor *color_in_out, XcmsColorFormat result_format); + + display + + Specifies the connection to the X server. + + colormap + + Specifies the colormap. + + color_in_out + + Specifies the pixel member that indicates the color cell to + query. The color specification stored for the color cell is + returned in this XcmsColor structure. + + result_format + + Specifies the color format for the returned color + specification. + + The XcmsQueryColor function obtains the RGB value for the pixel + value in the pixel member of the specified XcmsColor structure + and then converts the value to the target format as specified + by the result_format argument. If the pixel is not a valid + index in the specified colormap, a BadValue error results. + + XcmsQueryColor can generate BadColor and BadValue errors. + + To query the color of multiple colormap cells in an arbitrary + format, use XcmsQueryColors. + + Status XcmsQueryColors(Display *display, Colormap colormap, + XcmsColor colors_in_out[], unsigned int ncolors, + XcmsColorFormat result_format); + + display + + Specifies the connection to the X server. + + colormap + + Specifies the colormap. + + colors_in_out + + Specifies an array of XcmsColor structures, each pixel member + indicating the color cell to query. The color specifications + for the color cells are returned in these structures. + + ncolors + + Specifies the number of XcmsColor structures in the + color-specification array. + + result_format + + Specifies the color format for the returned color + specification. + + The XcmsQueryColors function obtains the RGB values for pixel + values in the pixel members of XcmsColor structures and then + converts the values to the target format as specified by the + result_format argument. If a pixel is not a valid index into + the specified colormap, a BadValue error results. If more than + one pixel is in error, the one that gets reported is arbitrary. + + XcmsQueryColors can generate BadColor and BadValue errors. + +Color Conversion Context Functions + + This section describes functions to create, modify, and query + Color Conversion Contexts (CCCs). + + Associated with each colormap is an initial CCC transparently + generated by Xlib. Therefore, when you specify a colormap as an + argument to a function, you are indirectly specifying a CCC. + The CCC attributes that can be modified by the X client are: + * Client White Point + * Gamut compression procedure and client data + * White point adjustment procedure and client data + + The initial values for these attributes are implementation + specific. The CCC attributes for subsequently created CCCs can + be defined by changing the CCC attributes of the default CCC. + There is a default CCC associated with each screen. + +Getting and Setting the Color Conversion Context of a Colormap + + To obtain the CCC associated with a colormap, use + XcmsCCCOfColormap. + + XcmsCCC XcmsCCCOfColormap(Display *display, Colormap colormap); + + display + + Specifies the connection to the X server. + + colormap + + Specifies the colormap. + + The XcmsCCCOfColormap function returns the CCC associated with + the specified colormap. Once obtained, the CCC attributes can + be queried or modified. Unless the CCC associated with the + specified colormap is changed with XcmsSetCCCOfColormap, this + CCC is used when the specified colormap is used as an argument + to color functions. + + To change the CCC associated with a colormap, use + XcmsSetCCCOfColormap. + + XcmsCCC XcmsSetCCCOfColormap(Display *display, Colormap + colormap, XcmsCCC ccc); + + display + + Specifies the connection to the X server. + + colormap + + Specifies the colormap. + + ccc + + Specifies the CCC. + + The XcmsSetCCCOfColormap function changes the CCC associated + with the specified colormap. It returns the CCC previously + associated with the colormap. If they are not used again in the + application, CCCs should be freed by calling XcmsFreeCCC. + Several colormaps may share the same CCC without restriction; + this includes the CCCs generated by Xlib with each colormap. + Xlib, however, creates a new CCC with each new colormap. + +Obtaining the Default Color Conversion Context + + You can change the default CCC attributes for subsequently + created CCCs by changing the CCC attributes of the default CCC. + A default CCC is associated with each screen. + + To obtain the default CCC for a screen, use XcmsDefaultCCC. + + XcmsCCC XcmsDefaultCCC(Display *display, int screen_number); + + display + + Specifies the connection to the X server. + + screen_number + + Specifies the appropriate screen number on the host server. + + The XcmsDefaultCCC function returns the default CCC for the + specified screen. Its visual is the default visual of the + screen. Its initial gamut compression and white point + adjustment procedures as well as the associated client data are + implementation specific. + +Color Conversion Context Macros + + Applications should not directly modify any part of the + XcmsCCC. The following lists the C language macros, their + corresponding function equivalents for other language bindings, + and what data they both can return. + + DisplayOfCCC(XcmsCCC ccc); + + Display *XcmsDisplayOfCCC(XcmsCCC ccc); + + ccc + + Specifies the CCC. + + Both return the display associated with the specified CCC. + + VisualOfCCC(XcmsCCC ccc); + + Visual *XcmsVisualOfCCC(XcmsCCC ccc); + + ccc + + Specifies the CCC. + + Both return the visual associated with the specified CCC. + + ScreenNumberOfCCC(XcmsCCC ccc); + + int XcmsScreenNumberOfCCC(XcmsCCC ccc); + + ccc + + Specifies the CCC. + + Both return the number of the screen associated with the + specified CCC. + + ScreenWhitePointOfCCC(XcmsCCC ccc); + + XcmsColor XcmsScreenWhitePointOfCCC(XcmsCCC ccc); + + ccc + + Specifies the CCC. + + Both return the white point of the screen associated with the + specified CCC. + + ClientWhitePointOfCCC(XcmsCCC ccc); + + XcmsColor *XcmsClientWhitePointOfCCC(XcmsCCC ccc); + + ccc + + Specifies the CCC. + + Both return the Client White Point of the specified CCC. + +Modifying Attributes of a Color Conversion Context + + To set the Client White Point in the CCC, use + XcmsSetWhitePoint. + + Status XcmsSetWhitePoint(XcmsCCC ccc, XcmsColor *color); + + ccc + + Specifies the CCC. + + color + + Specifies the new Client White Point. + + The XcmsSetWhitePoint function changes the Client White Point + in the specified CCC. Note that the pixel member is ignored and + that the color specification is left unchanged upon return. The + format for the new white point must be XcmsCIEXYZFormat, + XcmsCIEuvYFormat, XcmsCIExyYFormat, or XcmsUndefinedFormat. If + the color argument is NULL, this function sets the format + component of the Client White Point specification to + XcmsUndefinedFormat, indicating that the Client White Point is + assumed to be the same as the Screen White Point. + + This function returns nonzero status if the format for the new + white point is valid; otherwise, it returns zero. + + To set the gamut compression procedure and corresponding client + data in a specified CCC, use XcmsSetCompressionProc. + + XcmsCompressionProc XcmsSetCompressionProc(XcmsCCC ccc, + XcmsCompressionProc compression_proc, XPointer client_data); + + ccc + + Specifies the CCC. + + compression_proc + + Specifies the gamut compression procedure that is to be applied + when a color lies outside the screen's color gamut. If NULL is + specified and a function using this CCC must convert a color + specification to a device-dependent format and encounters a + color that lies outside the screen's color gamut, that function + will return XcmsFailure. + + client_data + + Specifies client data for gamut compression procedure or NULL. + + The XcmsSetCompressionProc function first sets the gamut + compression procedure and client data in the specified CCC with + the newly specified procedure and client data and then returns + the old procedure. + + To set the white point adjustment procedure and corresponding + client data in a specified CCC, use XcmsSetWhiteAdjustProc. + + XcmsWhiteAdjustProc XcmsSetWhiteAdjustProc(XcmsCCC ccc, + XcmsWhiteAdjustProc white_adjust_proc, XPointer client_data); + + ccc + + Specifies the CCC. + + white_adjust_proc + + Specifies the white point adjustment procedure. + + client_data + + Specifies client data for white point adjustment procedure or + NULL. + + The XcmsSetWhiteAdjustProc function first sets the white point + adjustment procedure and client data in the specified CCC with + the newly specified procedure and client data and then returns + the old procedure. + +Creating and Freeing a Color Conversion Context + + You can explicitly create a CCC within your application by + calling XcmsCreateCCC. These created CCCs can then be used by + those functions that explicitly call for a CCC argument. Old + CCCs that will not be used by the application should be freed + using XcmsFreeCCC. + + To create a CCC, use XcmsCreateCCC. + + XcmsCCC XcmsCreateCCC(Display *display, int screen_number, + Visual *visual, XcmsColor *client_white_point, + XcmsCompressionProc compression_proc, XPointer + compression_client_data, XcmsWhiteAdjustProc white_adjust_proc, + XPointer white_adjust_client_data); + + display + + Specifies the connection to the X server. + + screen_number + + Specifies the appropriate screen number on the host server. + + visual + + Specifies the visual type. + + client_white_point + + Specifies the Client White Point. If NULL is specified, the + Client White Point is to be assumed to be the same as the + Screen White Point. Note that the pixel member is ignored. + + compression_proc + + Specifies the gamut compression procedure that is to be applied + when a color lies outside the screen's color gamut. If NULL is + specified and a function using this CCC must convert a color + specification to a device-dependent format and encounters a + color that lies outside the screen's color gamut, that function + will return XcmsFailure. + + compression_client_data + + Specifies client data for use by the gamut compression + procedure or NULL. + + white_adjust_proc + + Specifies the white adjustment procedure that is to be applied + when the Client White Point differs from the Screen White + Point. NULL indicates that no white point adjustment is + desired. + + white_adjust_client_data + + Specifies client data for use with the white point adjustment + procedure or NULL. + + The XcmsCreateCCC function creates a CCC for the specified + display, screen, and visual. + + To free a CCC, use XcmsFreeCCC. + + void XcmsFreeCCC(XcmsCCC ccc); + + ccc + + Specifies the CCC. + + The XcmsFreeCCC function frees the memory used for the + specified CCC. Note that default CCCs and those currently + associated with colormaps are ignored. + +Converting between Color Spaces + + To convert an array of color specifications in arbitrary color + formats to a single destination format, use XcmsConvertColors. + + Status XcmsConvertColors(XcmsCCC ccc, XcmsColor + colors_in_out[], unsigned int ncolors, XcmsColorFormat + target_format, Bool compression_flags_return[]); + + ccc + + Specifies the CCC. If conversion is between device-independent + color spaces only (for example, TekHVC to CIELuv), the CCC is + necessary only to specify the Client White Point. + + colors_in_out + + Specifies an array of color specifications. Pixel members are + ignored and remain unchanged upon return. + + ncolors + + Specifies the number of XcmsColor structures in the + color-specification array. + + target_format + + Specifies the target color specification format. + + compression_flags_return + + Returns an array of Boolean values indicating compression + status. If a non-NULL pointer is supplied, each element of the + array is set to True if the corresponding color was compressed + and False otherwise. Pass NULL if the compression status is not + useful. + + The XcmsConvertColors function converts the color + specifications in the specified array of XcmsColor structures + from their current format to a single target format, using the + specified CCC. When the return value is XcmsFailure, the + contents of the color specification array are left unchanged. + + The array may contain a mixture of color specification formats + (for example, 3 CIE XYZ, 2 CIE Luv, and so on). When the array + contains both device-independent and device-dependent color + specifications and the target_format argument specifies a + device-dependent format (for example, XcmsRGBiFormat, + XcmsRGBFormat), all specifications are converted to CIE XYZ + format and then to the target device-dependent format. + +Callback Functions + + This section describes the gamut compression and white point + adjustment callbacks. + + The gamut compression procedure specified in the CCC is called + when an attempt to convert a color specification from + XcmsCIEXYZ to a device-dependent format (typically XcmsRGBi) + results in a color that lies outside the screen's color gamut. + If the gamut compression procedure requires client data, this + data is passed via the gamut compression client data in the + CCC. + + During color specification conversion between + device-independent and device-dependent color spaces, if a + white point adjustment procedure is specified in the CCC, it is + triggered when the Client White Point and Screen White Point + differ. If required, the client data is obtained from the CCC. + +Prototype Gamut Compression Procedure + + The gamut compression callback interface must adhere to the + following: + + typedef Status(*XcmsCompressionProc)(XcmsCCC ccc, XcmsColor + colors_in_out[], unsigned int ncolors, unsigned int index, Bool + compression_flags_return[]); + + ccc + + Specifies the CCC. + + colors_in_out + + Specifies an array of color specifications. Pixel members + should be ignored and must remain unchanged upon return. + + ncolors + + Specifies the number of XcmsColor structures in the + color-specification array. + + index + + Specifies the index into the array of XcmsColor structures for + the encountered color specification that lies outside the + screen's color gamut. Valid values are 0 (for the first + element) to ncolors - 1. + + compression_flags_return + + Returns an array of Boolean values for indicating compression + status. If a non-NULL pointer is supplied and a color at a + given index is compressed, then True should be stored at the + corresponding index in this array; otherwise, the array should + not be modified. + + When implementing a gamut compression procedure, consider the + following rules and assumptions: + * The gamut compression procedure can attempt to compress one + or multiple specifications at a time. + * When called, elements 0 to index - 1 in the color + specification array can be assumed to fall within the + screen's color gamut. In addition, these color + specifications are already in some device-dependent format + (typically XcmsRGBi). If any modifications are made to + these color specifications, they must be in their initial + device-dependent format upon return. + * When called, the element in the color specification array + specified by the index argument contains the color + specification outside the screen's color gamut encountered + by the calling routine. In addition, this color + specification can be assumed to be in XcmsCIEXYZ. Upon + return, this color specification must be in XcmsCIEXYZ. + * When called, elements from index to ncolors - 1 in the + color specification array may or may not fall within the + screen's color gamut. In addition, these color + specifications can be assumed to be in XcmsCIEXYZ. If any + modifications are made to these color specifications, they + must be in XcmsCIEXYZ upon return. + * The color specifications passed to the gamut compression + procedure have already been adjusted to the Screen White + Point. This means that at this point the color + specification's white point is the Screen White Point. + * If the gamut compression procedure uses a + device-independent color space not initially accessible for + use in the color management system, use XcmsAddColorSpace + to ensure that it is added. + +Supplied Gamut Compression Procedures + + The following equations are useful in describing gamut + compression functions: delim %% + +%CIELab~Psychometric~Chroma ~=~ sqrt(a_star sup 2 ~+~ b_star sup 2 )% + +%CIELab~Psychometric~Hue ~=~ tan sup -1 left [ b_star over a_star right +]% + +%CIELuv~Psychometric~Chroma ~=~ sqrt(u_star sup 2 ~+~ v_star sup 2 )% + +%CIELuv~Psychometric~Hue ~=~ tan sup -1 left [ v_star over u_star right +]% + + The gamut compression callback procedures provided by Xlib are + as follows: + * XcmsCIELabClipL + * This brings the encountered out-of-gamut color + specification into the screen's color gamut by reducing or + increasing CIE metric lightness (L*) in the CIE L*a*b* + color space until the color is within the gamut. If the + Psychometric Chroma of the color specification is beyond + maximum for the Psychometric Hue Angle, then while + maintaining the same Psychometric Hue Angle, the color will + be clipped to the CIE L*a*b* coordinates of maximum + Psychometric Chroma. See XcmsCIELabQueryMaxC. No client + data is necessary. + * XcmsCIELabClipab + * This brings the encountered out-of-gamut color + specification into the screen's color gamut by reducing + Psychometric Chroma, while maintaining Psychometric Hue + Angle, until the color is within the gamut. No client data + is necessary. + * XcmsCIELabClipLab + * This brings the encountered out-of-gamut color + specification into the screen's color gamut by replacing it + with CIE L*a*b* coordinates that fall within the color + gamut while maintaining the original Psychometric Hue Angle + and whose vector to the original coordinates is the + shortest attainable. No client data is necessary. + * XcmsCIELuvClipL + * This brings the encountered out-of-gamut color + specification into the screen's color gamut by reducing or + increasing CIE metric lightness (L*) in the CIE L*u*v* + color space until the color is within the gamut. If the + Psychometric Chroma of the color specification is beyond + maximum for the Psychometric Hue Angle, then, while + maintaining the same Psychometric Hue Angle, the color will + be clipped to the CIE L*u*v* coordinates of maximum + Psychometric Chroma. See XcmsCIELuvQueryMaxC. No client + data is necessary. + * XcmsCIELuvClipuv + * This brings the encountered out-of-gamut color + specification into the screen's color gamut by reducing + Psychometric Chroma, while maintaining Psychometric Hue + Angle, until the color is within the gamut. No client data + is necessary. + * XcmsCIELuvClipLuv + * This brings the encountered out-of-gamut color + specification into the screen's color gamut by replacing it + with CIE L*u*v* coordinates that fall within the color + gamut while maintaining the original Psychometric Hue Angle + and whose vector to the original coordinates is the + shortest attainable. No client data is necessary. + * XcmsTekHVCClipV + * This brings the encountered out-of-gamut color + specification into the screen's color gamut by reducing or + increasing the Value dimension in the TekHVC color space + until the color is within the gamut. If Chroma of the color + specification is beyond maximum for the particular Hue, + then, while maintaining the same Hue, the color will be + clipped to the Value and Chroma coordinates that represent + maximum Chroma for that particular Hue. No client data is + necessary. + * XcmsTekHVCClipC + * This brings the encountered out-of-gamut color + specification into the screen's color gamut by reducing the + Chroma dimension in the TekHVC color space until the color + is within the gamut. No client data is necessary. + * XcmsTekHVCClipVC + * This brings the encountered out-of-gamut color + specification into the screen's color gamut by replacing it + with TekHVC coordinates that fall within the color gamut + while maintaining the original Hue and whose vector to the + original coordinates is the shortest attainable. No client + data is necessary. + +Prototype White Point Adjustment Procedure + + The white point adjustment procedure interface must adhere to + the following: + + typedef Status (*XcmsWhiteAdjustProc)(XcmsCCC ccc, XcmsColor + *initial_white_point, XcmsColor *target_white_point, + XcmsColorFormat target_format, XcmsColor colors_in_out[], + unsigned int ncolors, Bool compression_flags_return[]); + + ccc + + Specifies the CCC. + + initial_white_point + + Specifies the initial white point. + + target_white_point + + Specifies the target white point. + + target_format + + Specifies the target color specification format. + + colors_in_out + + Specifies an array of color specifications. Pixel members + should be ignored and must remain unchanged upon return. + + ncolors + + Specifies the number of XcmsColor structures in the + color-specification array. + + compression_flags_return + + Returns an array of Boolean values for indicating compression + status. If a non-NULL pointer is supplied and a color at a + given index is compressed, then True should be stored at the + corresponding index in this array; otherwise, the array should + not be modified. + +Supplied White Point Adjustment Procedures + + White point adjustment procedures provided by Xlib are as + follows: + * XcmsCIELabWhiteShiftColors + * This uses the CIE L*a*b* color space for adjusting the + chromatic character of colors to compensate for the + chromatic differences between the source and destination + white points. This procedure simply converts the color + specifications to XcmsCIELab using the source white point + and then converts to the target specification format using + the destination's white point. No client data is necessary. + * XcmsCIELuvWhiteShiftColors + * This uses the CIE L*u*v* color space for adjusting the + chromatic character of colors to compensate for the + chromatic differences between the source and destination + white points. This procedure simply converts the color + specifications to XcmsCIELuv using the source white point + and then converts to the target specification format using + the destination's white point. No client data is necessary. + * XcmsTekHVCWhiteShiftColors + * This uses the TekHVC color space for adjusting the + chromatic character of colors to compensate for the + chromatic differences between the source and destination + white points. This procedure simply converts the color + specifications to XcmsTekHVC using the source white point + and then converts to the target specification format using + the destination's white point. An advantage of this + procedure over those previously described is an attempt to + minimize hue shift. No client data is necessary. + + From an implementation point of view, these white point + adjustment procedures convert the color specifications to a + device-independent but white-point-dependent color space (for + example, CIE L*u*v*, CIE L*a*b*, TekHVC) using one white point + and then converting those specifications to the target color + space using another white point. In other words, the + specification goes in the color space with one white point but + comes out with another white point, resulting in a chromatic + shift based on the chromatic displacement between the initial + white point and target white point. The CIE color spaces that + are assumed to be white-point-independent are CIE u'v'Y, CIE + XYZ, and CIE xyY. When developing a custom white point + adjustment procedure that uses a device-independent color space + not initially accessible for use in the color management + system, use XcmsAddColorSpace to ensure that it is added. + + As an example, if the CCC specifies a white point adjustment + procedure and if the Client White Point and Screen White Point + differ, the XcmsAllocColor function will use the white point + adjustment procedure twice: + * Once to convert to XcmsRGB + * A second time to convert from XcmsRGB + + For example, assume the specification is in XcmsCIEuvY and the + adjustment procedure is XcmsCIELuvWhiteShiftColors. During + conversion to XcmsRGB, the call to XcmsAllocColor results in + the following series of color specification conversions: + * From XcmsCIEuvY to XcmsCIELuv using the Client White Point + * From XcmsCIELuv to XcmsCIEuvY using the Screen White Point + * From XcmsCIEuvY to XcmsCIEXYZ (CIE u'v'Y and XYZ are + white-point-independent color spaces) + * From XcmsCIEXYZ to XcmsRGBi + * From XcmsRGBi to XcmsRGB + + The resulting RGB specification is passed to XAllocColor, and + the RGB specification returned by XAllocColor is converted back + to XcmsCIEuvY by reversing the color conversion sequence. + +Gamut Querying Functions + + This section describes the gamut querying functions that Xlib + provides. These functions allow the client to query the + boundary of the screen's color gamut in terms of the CIE + L*a*b*, CIE L*u*v*, and TekHVC color spaces. Functions are also + provided that allow you to query the color specification of: + * White (full-intensity red, green, and blue) + * Red (full-intensity red while green and blue are zero) + * Green (full-intensity green while red and blue are zero) + * Blue (full-intensity blue while red and green are zero) + * Black (zero-intensity red, green, and blue) + + The white point associated with color specifications passed to + and returned from these gamut querying functions is assumed to + be the Screen White Point. This is a reasonable assumption, + because the client is trying to query the screen's color gamut. + + The following naming convention is used for the Max and Min + functions: + +XcmsQueryMax + +XcmsQueryMin + + The consists of a letter or letters that identify + the dimensions of the color space that are not fixed. For + example, XcmsTekHVCQueryMaxC is given a fixed Hue and Value for + which maximum Chroma is found. + +Red, Green, and Blue Queries + + To obtain the color specification for black (zero-intensity + red, green, and blue), use XcmsQueryBlack. + + Status XcmsQueryBlack(XcmsCCC ccc, XcmsColorFormat + target_format, XcmsColor *color_return); + + ccc + + Specifies the CCC. The CCC's Client White Point and white point + adjustment procedures are ignored. + + target_format + + Specifies the target color specification format. + + color_return + + Returns the color specification in the specified target format + for zero-intensity red, green, and blue. The white point + associated with the returned color specification is the Screen + White Point. The value returned in the pixel member is + undefined. + + The XcmsQueryBlack function returns the color specification in + the specified target format for zero-intensity red, green, and + blue. + + To obtain the color specification for blue (full-intensity blue + while red and green are zero), use XcmsQueryBlue. + + Status XcmsQueryBlue(XcmsCCC ccc, XcmsColorFormat + target_format, XcmsColor *color_return); + + ccc + + Specifies the CCC. The CCC's Client White Point and white point + adjustment procedures are ignored. + + target_format + + Specifies the target color specification format. + + color_return + + Returns the color specification in the specified target format + for full-intensity blue while red and green are zero. The white + point associated with the returned color specification is the + Screen White Point. The value returned in the pixel member is + undefined. + + The XcmsQueryBlue function returns the color specification in + the specified target format for full-intensity blue while red + and green are zero. + + To obtain the color specification for green (full-intensity + green while red and blue are zero), use XcmsQueryGreen. + + Status XcmsQueryGreen(XcmsCCC ccc, XcmsColorFormat + target_format, XcmsColor *color_return); + + ccc + + Specifies the CCC. The CCC's Client White Point and white point + adjustment procedures are ignored. + + target_format + + Specifies the target color specification format. + + color_return + + Returns the color specification in the specified target format + for full-intensity green while red and blue are zero. The white + point associated with the returned color specification is the + Screen White Point. The value returned in the pixel member is + undefined. + + The XcmsQueryGreen function returns the color specification in + the specified target format for full-intensity green while red + and blue are zero. + + To obtain the color specification for red (full-intensity red + while green and blue are zero), use XcmsQueryRed. + + Status XcmsQueryRed(XcmsCCC ccc, XcmsColorFormat target_format, + XcmsColor *color_return); + + ccc + + Specifies the CCC. The CCC's Client White Point and white point + adjustment procedures are ignored. + + target_format + + Specifies the target color specification format. + + color_return + + Returns the color specification in the specified target format + for full-intensity red while green and blue are zero. The white + point associated with the returned color specification is the + Screen White Point. The value returned in the pixel member is + undefined. + + The XcmsQueryRed function returns the color specification in + the specified target format for full-intensity red while green + and blue are zero. + + To obtain the color specification for white (full-intensity + red, green, and blue), use XcmsQueryWhite. + + Status XcmsQueryWhite(XcmsCCC ccc, XcmsColorFormat + target_format, XcmsColor *color_return); + + ccc + + Specifies the CCC. The CCC's Client White Point and white point + adjustment procedures are ignored. + + target_format + + Specifies the target color specification format. + + color_return + + Returns the color specification in the specified target format + for full-intensity red, green, and blue. The white point + associated with the returned color specification is the Screen + White Point. The value returned in the pixel member is + undefined. + + The XcmsQueryWhite function returns the color specification in + the specified target format for full-intensity red, green, and + blue. + +CIELab Queries + + The following equations are useful in describing the CIELab + query functions: delim %% + +%CIELab~Psychometric~Chroma ~=~ sqrt(a_star sup 2 ~+~ b_star sup 2 )% + +%CIELab~Psychometric~Hue ~=~ tan sup -1 left [ b_star over a_star right +]% + + To obtain the CIE L*a*b* coordinates of maximum Psychometric + Chroma for a given Psychometric Hue Angle and CIE metric + lightness (L*), use XcmsCIELabQueryMaxC. + + Status XcmsCIELabQueryMaxC(XcmsCCC ccc, XcmsFloat hue_angle, + XcmsFloat L_star, XcmsColor *color_return); + + ccc + + Specifies the CCC. The CCC's Client White Point and white point + adjustment procedures are ignored. + + hue_angle + + Specifies the hue angle (in degrees) at which to find maximum + chroma. + + L_star + + Specifies the lightness (L*) at which to find maximum chroma. + + color_return + + Returns the CIE L*a*b* coordinates of maximum chroma + displayable by the screen for the given hue angle and + lightness. The white point associated with the returned color + specification is the Screen White Point. The value returned in + the pixel member is undefined. + + The XcmsCIELabQueryMaxC function, given a hue angle and + lightness, finds the point of maximum chroma displayable by the + screen. It returns this point in CIE L*a*b* coordinates. + + To obtain the CIE L*a*b* coordinates of maximum CIE metric + lightness (L*) for a given Psychometric Hue Angle and + Psychometric Chroma, use XcmsCIELabQueryMaxL. + + Status XcmsCIELabQueryMaxL(XcmsCCC ccc, XcmsFloat hue_angle, + XcmsFloat chroma, XcmsColor *color_return); + + ccc + + Specifies the CCC. The CCC's Client White Point and white point + adjustment procedures are ignored. + + hue_angle + + Specifies the hue angle (in degrees) at which to find maximum + lightness. + + chroma + + Specifies the chroma at which to find maximum lightness. + + color_return + + Returns the CIE L*a*b* coordinates of maximum lightness + displayable by the screen for the given hue angle and chroma. + The white point associated with the returned color + specification is the Screen White Point. The value returned in + the pixel member is undefined. + + The XcmsCIELabQueryMaxL function, given a hue angle and chroma, + finds the point in CIE L*a*b* color space of maximum lightness + (L*) displayable by the screen. It returns this point in CIE + L*a*b* coordinates. An XcmsFailure return value usually + indicates that the given chroma is beyond maximum for the given + hue angle. + + To obtain the CIE L*a*b* coordinates of maximum Psychometric + Chroma for a given Psychometric Hue Angle, use + XcmsCIELabQueryMaxLC. + + Status XcmsCIELabQueryMaxLC(XcmsCCC ccc, XcmsFloat hue_angle, + XcmsColor *color_return); + + ccc + + Specifies the CCC. The CCC's Client White Point and white point + adjustment procedures are ignored. + + hue_angle + + Specifies the hue angle (in degrees) at which to find maximum + chroma. + + color_return + + Returns the CIE L*a*b* coordinates of maximum chroma + displayable by the screen for the given hue angle. The white + point associated with the returned color specification is the + Screen White Point. The value returned in the pixel member is + undefined. + + The XcmsCIELabQueryMaxLC function, given a hue angle, finds the + point of maximum chroma displayable by the screen. It returns + this point in CIE L*a*b* coordinates. + + To obtain the CIE L*a*b* coordinates of minimum CIE metric + lightness (L*) for a given Psychometric Hue Angle and + Psychometric Chroma, use XcmsCIELabQueryMinL. + + Status XcmsCIELabQueryMinL(XcmsCCC ccc, XcmsFloat hue_angle, + XcmsFloat chroma, XcmsColor *color_return); + + ccc + + Specifies the CCC. The CCC's Client White Point and white point + adjustment procedures are ignored. + + hue_angle + + Specifies the hue angle (in degrees) at which to find minimum + lightness. + + chroma + + Specifies the chroma at which to find minimum lightness. + + color_return + + Returns the CIE L*a*b* coordinates of minimum lightness + displayable by the screen for the given hue angle and chroma. + The white point associated with the returned color + specification is the Screen White Point. The value returned in + the pixel member is undefined. + + The XcmsCIELabQueryMinL function, given a hue angle and chroma, + finds the point of minimum lightness (L*) displayable by the + screen. It returns this point in CIE L*a*b* coordinates. An + XcmsFailure return value usually indicates that the given + chroma is beyond maximum for the given hue angle. + +CIELuv Queries + + The following equations are useful in describing the CIELuv + query functions: delim %% + +%CIELuv~Psychometric~Chroma ~=~ sqrt(u_star sup 2 ~+~ v_star sup 2 )% + +%CIELuv~Psychometric~Hue ~=~ tan sup -1 left [ v_star over u_star right +]% + + To obtain the CIE L*u*v* coordinates of maximum Psychometric + Chroma for a given Psychometric Hue Angle and CIE metric + lightness (L*), use XcmsCIELuvQueryMaxC. + + Status XcmsCIELuvQueryMaxC(XcmsCCC ccc, XcmsFloat hue_angle, + XcmsFloat L_star, XcmsColor *color_return); + + ccc + + Specifies the CCC. The CCC's Client White Point and white point + adjustment procedures are ignored. + + hue_angle + + Specifies the hue angle (in degrees) at which to find maximum + chroma. + + L_star + + Specifies the lightness (L*) at which to find maximum chroma. + + color_return + + Returns the CIE L*u*v* coordinates of maximum chroma + displayable by the screen for the given hue angle and + lightness. The white point associated with the returned color + specification is the Screen White Point. The value returned in + the pixel member is undefined. + + The XcmsCIELuvQueryMaxC function, given a hue angle and + lightness, finds the point of maximum chroma displayable by the + screen. It returns this point in CIE L*u*v* coordinates. + + To obtain the CIE L*u*v* coordinates of maximum CIE metric + lightness (L*) for a given Psychometric Hue Angle and + Psychometric Chroma, use XcmsCIELuvQueryMaxL. + + Status XcmsCIELuvQueryMaxL(XcmsCCC ccc, XcmsFloat hue_angle, + XcmsFloat chroma, XcmsColor *color_return); + + ccc + + Specifies the CCC. The CCC's Client White Point and white point + adjustment procedures are ignored. + + hue_angle + + Specifies the hue angle (in degrees) at which to find maximum + lightness. + + L_star + + Specifies the lightness (L*) at which to find maximum + lightness. + + color_return + + Returns the CIE L*u*v* coordinates of maximum lightness + displayable by the screen for the given hue angle and chroma. + The white point associated with the returned color + specification is the Screen White Point. The value returned in + the pixel member is undefined. + + The XcmsCIELuvQueryMaxL function, given a hue angle and chroma, + finds the point in CIE L*u*v* color space of maximum lightness + (L*) displayable by the screen. It returns this point in CIE + L*u*v* coordinates. An XcmsFailure return value usually + indicates that the given chroma is beyond maximum for the given + hue angle. + + To obtain the CIE L*u*v* coordinates of maximum Psychometric + Chroma for a given Psychometric Hue Angle, use + XcmsCIELuvQueryMaxLC. + + Status XcmsCIELuvQueryMaxLC(XcmsCCC ccc, XcmsFloat hue_angle, + XcmsColor *color_return); + + ccc + + Specifies the CCC. The CCC's Client White Point and white point + adjustment procedures are ignored. + + hue_angle + + Specifies the hue angle (in degrees) at which to find maximum + chroma. + + color_return + + Returns the CIE L*u*v* coordinates of maximum chroma + displayable by the screen for the given hue angle. The white + point associated with the returned color specification is the + Screen White Point. The value returned in the pixel member is + undefined. + + The XcmsCIELuvQueryMaxLC function, given a hue angle, finds the + point of maximum chroma displayable by the screen. It returns + this point in CIE L*u*v* coordinates. + + To obtain the CIE L*u*v* coordinates of minimum CIE metric + lightness (L*) for a given Psychometric Hue Angle and + Psychometric Chroma, use XcmsCIELuvQueryMinL. + + Status XcmsCIELuvQueryMinL(XcmsCCC ccc, XcmsFloat hue_angle, + XcmsFloat chroma, XcmsColor *color_return); + + ccc + + Specifies the CCC. The CCC's Client White Point and white point + adjustment procedures are ignored. + + hue_angle + + Specifies the hue angle (in degrees) at which to find minimum + lightness. + + chroma + + Specifies the chroma at which to find minimum lightness. + + color_return + + Returns the CIE L*u*v* coordinates of minimum lightness + displayable by the screen for the given hue angle and chroma. + The white point associated with the returned color + specification is the Screen White Point. The value returned in + the pixel member is undefined. + + The XcmsCIELuvQueryMinL function, given a hue angle and chroma, + finds the point of minimum lightness (L*) displayable by the + screen. It returns this point in CIE L*u*v* coordinates. An + XcmsFailure return value usually indicates that the given + chroma is beyond maximum for the given hue angle. + +TekHVC Queries + + To obtain the maximum Chroma for a given Hue and Value, use + XcmsTekHVCQueryMaxC. + + Status XcmsTekHVCQueryMaxC(XcmsCCC ccc, XcmsFloat hue, + XcmsFloat value, XcmsColor *color_return); + + ccc + + Specifies the CCC. The CCC's Client White Point and white point + adjustment procedures are ignored. + + hue + + Specifies the Hue in which to find the maximum Chroma. + + value + + Specifies the Value in which to find the maximum Chroma. + + color_return + + Returns the maximum Chroma along with the actual Hue and Value + at which the maximum Chroma was found. The white point + associated with the returned color specification is the Screen + White Point. The value returned in the pixel member is + undefined. + + The XcmsTekHVCQueryMaxC function, given a Hue and Value, + determines the maximum Chroma in TekHVC color space displayable + by the screen. It returns the maximum Chroma along with the + actual Hue and Value at which the maximum Chroma was found. + + To obtain the maximum Value for a given Hue and Chroma, use + XcmsTekHVCQueryMaxV. + + Status XcmsTekHVCQueryMaxV(XcmsCCC ccc, XcmsFloat hue, + XcmsFloat chroma, XcmsColor *color_return); + + ccc + + Specifies the CCC. The CCC's Client White Point and white point + adjustment procedures are ignored. + + hue + + Specifies the Hue in which to find the maximum Value. + + chroma + + Specifies the chroma at which to find maximum Value. + + color_return + + Returns the maximum Value along with the Hue and Chroma at + which the maximum Value was found. The white point associated + with the returned color specification is the Screen White + Point. The value returned in the pixel member is undefined. + + The XcmsTekHVCQueryMaxV function, given a Hue and Chroma, + determines the maximum Value in TekHVC color space displayable + by the screen. It returns the maximum Value and the actual Hue + and Chroma at which the maximum Value was found. + + To obtain the maximum Chroma and Value at which it is reached + for a specified Hue, use XcmsTekHVCQueryMaxVC. + + Status XcmsTekHVCQueryMaxVC(XcmsCCC ccc, XcmsFloat hue, + XcmsColor *color_return); + + ccc + + Specifies the CCC. The CCC's Client White Point and white point + adjustment procedures are ignored. + + hue + + Specifies the Hue in which to find the maximum Chroma. + + color_return + + Returns the color specification in XcmsTekHVC for the maximum + Chroma, the Value at which that maximum Chroma is reached, and + the actual Hue at which the maximum Chroma was found. The white + point associated with the returned color specification is the + Screen White Point. The value returned in the pixel member is + undefined. + + The XcmsTekHVCQueryMaxVC function, given a Hue, determines the + maximum Chroma in TekHVC color space displayable by the screen + and the Value at which that maximum Chroma is reached. It + returns the maximum Chroma, the Value at which that maximum + Chroma is reached, and the actual Hue for which the maximum + Chroma was found. + + To obtain a specified number of TekHVC specifications such that + they contain maximum Values for a specified Hue and the Chroma + at which the maximum Values are reached, use + XcmsTekHVCQueryMaxVSamples. + + Status XcmsTekHVCQueryMaxVSamples(XcmsCCC ccc, XcmsFloat hue, + XcmsColor colors_return[], unsigned int nsamples); + + ccc + + Specifies the CCC. The CCC's Client White Point and white point + adjustment procedures are ignored. + + hue + + Specifies the Hue for maximum Chroma/Value samples. + + nsamples + + Specifies the number of samples. + + colors_return + + Returns nsamples of color specifications in XcmsTekHVC such + that the Chroma is the maximum attainable for the Value and + Hue. The white point associated with the returned color + specification is the Screen White Point. The value returned in + the pixel member is undefined. + + The XcmsTekHVCQueryMaxVSamples returns nsamples of maximum + Value, the Chroma at which that maximum Value is reached, and + the actual Hue for which the maximum Chroma was found. These + sample points may then be used to plot the maximum Value/Chroma + boundary of the screen's color gamut for the specified Hue in + TekHVC color space. + + To obtain the minimum Value for a given Hue and Chroma, use + XcmsTekHVCQueryMinV. + + Status XcmsTekHVCQueryMinV(XcmsCCC ccc, XcmsFloat hue, + XcmsFloat chroma, XcmsColor *color_return); + + ccc + + Specifies the CCC. The CCC's Client White Point and white point + adjustment procedures are ignored. + + hue + + Specifies the Hue in which to find the minimum Value. + + value + + Specifies the Value in which to find the minimum Value. + + color_return + + Returns the minimum Value and the actual Hue and Chroma at + which the minimum Value was found. The white point associated + with the returned color specification is the Screen White + Point. The value returned in the pixel member is undefined. + + The XcmsTekHVCQueryMinV function, given a Hue and Chroma, + determines the minimum Value in TekHVC color space displayable + by the screen. It returns the minimum Value and the actual Hue + and Chroma at which the minimum Value was found. + +Color Management Extensions + + The Xlib color management facilities can be extended in two + ways: + * Device-Independent Color Spaces + * Device-independent color spaces that are derivable to CIE + XYZ space can be added using the XcmsAddColorSpace + function. + * Color Characterization Function Set + * A Color Characterization Function Set consists of + device-dependent color spaces and their functions that + convert between these color spaces and the CIE XYZ color + space, bundled together for a specific class of output + devices. A function set can be added using the + XcmsAddFunctionSet function. + +Color Spaces + + The CIE XYZ color space serves as the hub for all conversions + between device-independent and device-dependent color spaces. + Therefore, the knowledge to convert an XcmsColor structure to + and from CIE XYZ format is associated with each color space. + For example, conversion from CIE L*u*v* to RGB requires the + knowledge to convert from CIE L*u*v* to CIE XYZ and from CIE + XYZ to RGB. This knowledge is stored as an array of functions + that, when applied in series, will convert the XcmsColor + structure to or from CIE XYZ format. This color specification + conversion mechanism facilitates the addition of color spaces. + + Of course, when converting between only device-independent + color spaces or only device-dependent color spaces, shortcuts + are taken whenever possible. For example, conversion from + TekHVC to CIE L*u*v* is performed by intermediate conversion to + CIE u*v*Y and then to CIE L*u*v*, thus bypassing conversion + between CIE u*v*Y and CIE XYZ. + +Adding Device-Independent Color Spaces + + To add a device-independent color space, use XcmsAddColorSpace. + + Status XcmsAddColorSpace(XcmsColorSpace *color_space); + + color_space + + Specifies the device-independent color space to add. + + The XcmsAddColorSpace function makes a device-independent color + space (actually an XcmsColorSpace structure) accessible by the + color management system. Because format values for unregistered + color spaces are assigned at run time, they should be treated + as private to the client. If references to an unregistered + color space must be made outside the client (for example, + storing color specifications in a file using the unregistered + color space), then reference should be made by color space + prefix (see XcmsFormatOfPrefix and XcmsPrefixOfFormat). + + If the XcmsColorSpace structure is already accessible in the + color management system, XcmsAddColorSpace returns XcmsSuccess. + + Note that added XcmsColorSpaces must be retained for reference + by Xlib. + +Querying Color Space Format and Prefix + + To obtain the format associated with the color space associated + with a specified color string prefix, use XcmsFormatOfPrefix. + + XcmsColorFormat XcmsFormatOfPrefix(char *prefix); + + prefix + + Specifies the string that contains the color space prefix. + + The XcmsFormatOfPrefix function returns the format for the + specified color space prefix (for example, the string + ``CIEXYZ''). The prefix is case-insensitive. If the color space + is not accessible in the color management system, + XcmsFormatOfPrefix returns XcmsUndefinedFormat. + + To obtain the color string prefix associated with the color + space specified by a color format, use XcmsPrefixOfFormat. + + char *XcmsPrefixOfFormat(XcmsColorFormat format); + + format + + Specifies the color specification format. + + The XcmsPrefixOfFormat function returns the string prefix + associated with the color specification encoding specified by + the format argument. Otherwise, if no encoding is found, it + returns NULL. The returned string must be treated as read-only. + +Creating Additional Color Spaces + + Color space specific information necessary for color space + conversion and color string parsing is stored in an + XcmsColorSpace structure. Therefore, a new structure containing + this information is required for each additional color space. + In the case of device-independent color spaces, a handle to + this new structure (that is, by means of a global variable) is + usually made accessible to the client program for use with the + XcmsAddColorSpace function. + + If a new XcmsColorSpace structure specifies a color space not + registered with the X Consortium, they should be treated as + private to the client because format values for unregistered + color spaces are assigned at run time. If references to an + unregistered color space must be made outside the client (for + example, storing color specifications in a file using the + unregistered color space), then reference should be made by + color space prefix (see XcmsFormatOfPrefix and + XcmsPrefixOfFormat). + + + +typedef (*XcmsConversionProc)(); +typedef XcmsConversionProc *XcmsFuncListPtr; + /* A NULL terminated list of function pointers*/ + +typedef struct _XcmsColorSpace { + char *prefix; + XcmsColorFormat format; + XcmsParseStringProc parseString; + XcmsFuncListPtr to_CIEXYZ; + XcmsFuncListPtr from_CIEXYZ; + int inverse_flag; +} XcmsColorSpace; + + The prefix member specifies the prefix that indicates a color + string is in this color space's string format. For example, the + strings ``ciexyz'' or ``CIEXYZ'' for CIE XYZ, and ``rgb'' or + ``RGB'' for RGB. The prefix is case insensitive. The format + member specifies the color specification format. Formats for + unregistered color spaces are assigned at run time. The + parseString member contains a pointer to the function that can + parse a color string into an XcmsColor structure. This function + returns an integer (int): nonzero if it succeeded and zero + otherwise. The to_CIEXYZ and from_CIEXYZ members contain + pointers, each to a NULL terminated list of function pointers. + When the list of functions is executed in series, it will + convert the color specified in an XcmsColor structure from/to + the current color space format to/from the CIE XYZ format. Each + function returns an integer (int): nonzero if it succeeded and + zero otherwise. The white point to be associated with the + colors is specified explicitly, even though white points can be + found in the CCC. The inverse_flag member, if nonzero, + specifies that for each function listed in to_CIEXYZ, its + inverse function can be found in from_CIEXYZ such that: + +Given: n = number of functions in each list + +for each i, such that 0 <= i < n + from_CIEXYZ[n - i - 1] is the inverse of to_CIEXYZ[i]. + + This allows Xlib to use the shortest conversion path, thus + bypassing CIE XYZ if possible (for example, TekHVC to CIE + L*u*v*). + +Parse String Callback + + The callback in the XcmsColorSpace structure for parsing a + color string for the particular color space must adhere to the + following software interface specification: + + Status XcmsParseStringProc(char *color_string, XcmsColor + *color_return); + + color_string + + Specifies the color string to parse. + + color_return + + Returns the color specification in the color space's format. + +Color Specification Conversion Callback + + Callback functions in the XcmsColorSpace structure for + converting a color specification between device-independent + spaces must adhere to the following software interface + specification: + + Status ConversionProc(XcmsCCC ccc, XcmsColor *white_point, + XcmsColor *colors_in_out, unsigned int ncolors); + + ccc + + Specifies the CCC. + + white_point + + Specifies the white point associated with color specifications. + The pixel member should be ignored, and the entire structure + remain unchanged upon return. + + colors_in_out + + Specifies an array of color specifications. Pixel members + should be ignored and must remain unchanged upon return. + + ncolors + + Specifies the number of XcmsColor structures in the + color-specification array. + + Callback functions in the XcmsColorSpace structure for + converting a color specification to or from a device-dependent + space must adhere to the following software interface + specification: + + Status ConversionProc(XcmsCCC ccc, XcmsColor *colors_in_out, + unsigned int ncolors, Bool compression_flags_return[]); + + ccc + + Specifies the CCC. + + colors_in_out + + Specifies an array of color specifications. Pixel members + should be ignored and must remain unchanged upon return. + + ncolors + + Specifies the number of XcmsColor structures in the + color-specification array. + + compression_flags_return + + Returns an array of Boolean values for indicating compression + status. If a non-NULL pointer is supplied and a color at a + given index is compressed, then True should be stored at the + corresponding index in this array; otherwise, the array should + not be modified. + + Conversion functions are available globally for use by other + color spaces. The conversion functions provided by Xlib are: + Function Converts from Converts to + XcmsCIELabToCIEXYZ XcmsCIELabFormat XcmsCIEXYZFormat + XcmsCIELuvToCIEuvY XcmsCIELuvFormat XcmsCIEuvYFormat + XcmsCIEXYZToCIELab XcmsCIEXYZFormat XcmsCIELabFormat + XcmsCIEXYZToCIEuvY XcmsCIEXYZFormat XcmsCIEuvYFormat + XcmsCIEXYZToCIExyY XcmsCIEXYZFormat XcmsCIExyYFormat + XcmsCIEXYZToRGBi XcmsCIEXYZFormat XcmsRGBiFormat + XcmsCIEuvYToCIELuv XcmsCIEuvYFormat XcmsCIELabFormat + XcmsCIEuvYToCIEXYZ XcmsCIEuvYFormat XcmsCIEXYZFormat + XcmsCIEuvYToTekHVC XcmsCIEuvYFormat XcmsTekHVCFormat + XcmsCIExyYToCIEXYZ XcmsCIExyYFormat XcmsCIEXYZFormat + XcmsRGBToRGBi XcmsRGBFormat XcmsRGBiFormat + XcmsRGBiToCIEXYZ XcmsRGBiFormat XcmsCIEXYZFormat + XcmsRGBiToRGB XcmsRGBiFormat XcmsRGBFormat + XcmsTekHVCToCIEuvY XcmsTekHVCFormat XcmsCIEuvYFormat + +Function Sets + + Functions to convert between device-dependent color spaces and + CIE XYZ may differ for different classes of output devices (for + example, color versus gray monitors). Therefore, the notion of + a Color Characterization Function Set has been developed. A + function set consists of device-dependent color spaces and the + functions that convert color specifications between these + device-dependent color spaces and the CIE XYZ color space + appropriate for a particular class of output devices. The + function set also contains a function that reads color + characterization data off root window properties. It is this + characterization data that will differ between devices within a + class of output devices. For details about how color + characterization data is stored in root window properties, see + the section on Device Color Characterization in the + Inter-Client Communication Conventions Manual. The LINEAR_RGB + function set is provided by Xlib and will support most color + monitors. Function sets may require data that differs from + those needed for the LINEAR_RGB function set. In that case, its + corresponding data may be stored on different root window + properties. + +Adding Function Sets + + To add a function set, use XcmsAddFunctionSet. + + Status XcmsAddFunctionSet(XcmsFunctionSet *function_set); + + function_set + + Specifies the function set to add. + + The XcmsAddFunctionSet function adds a function set to the + color management system. If the function set uses + device-dependent XcmsColorSpace structures not accessible in + the color management system, XcmsAddFunctionSet adds them. If + an added XcmsColorSpace structure is for a device-dependent + color space not registered with the X Consortium, they should + be treated as private to the client because format values for + unregistered color spaces are assigned at run time. If + references to an unregistered color space must be made outside + the client (for example, storing color specifications in a file + using the unregistered color space), then reference should be + made by color space prefix (see XcmsFormatOfPrefix and + XcmsPrefixOfFormat). + + Additional function sets should be added before any calls to + other Xlib routines are made. If not, the XcmsPerScrnInfo + member of a previously created XcmsCCC does not have the + opportunity to initialize with the added function set. + +Creating Additional Function Sets + + The creation of additional function sets should be required + only when an output device does not conform to existing + function sets or when additional device-dependent color spaces + are necessary. A function set consists primarily of a + collection of device-dependent XcmsColorSpace structures and a + means to read and store a screen's color characterization data. + This data is stored in an XcmsFunctionSet structure. A handle + to this structure (that is, by means of global variable) is + usually made accessible to the client program for use with + XcmsAddFunctionSet. + + If a function set uses new device-dependent XcmsColorSpace + structures, they will be transparently processed into the color + management system. Function sets can share an XcmsColorSpace + structure for a device-dependent color space. In addition, + multiple XcmsColorSpace structures are allowed for a + device-dependent color space; however, a function set can + reference only one of them. These XcmsColorSpace structures + will differ in the functions to convert to and from CIE XYZ, + thus tailored for the specific function set. + + + +typedef struct _XcmsFunctionSet { + XcmsColorSpace **DDColorSpaces; + XcmsScreenInitProc screenInitProc; + XcmsScreenFreeProc screenFreeProc; +} XcmsFunctionSet; + + The DDColorSpaces member is a pointer to a NULL terminated list + of pointers to XcmsColorSpace structures for the + device-dependent color spaces that are supported by the + function set. The screenInitProc member is set to the callback + procedure (see the following interface specification) that + initializes the XcmsPerScrnInfo structure for a particular + screen. + + The screen initialization callback must adhere to the following + software interface specification: + + typedef Status (*XcmsScreenInitProc)(Display *display, int + screen_number, ScmsPerScrnInfo *screen_info); + + display + + Specifies the connection to the X server. + + screen_number + + Specifies the appropriate screen number on the host server. + + screen_info + + Specifies the XcmsPerScrnInfo structure, which contains the per + screen information. + + The screen initialization callback in the XcmsFunctionSet + structure fetches the color characterization data (device + profile) for the specified screen, typically off properties on + the screen's root window. It then initializes the specified + XcmsPerScrnInfo structure. If successful, the procedure fills + in the XcmsPerScrnInfo structure as follows: + * It sets the screenData member to the address of the created + device profile data structure (contents known only by the + function set). + * It next sets the screenWhitePoint member. + * It next sets the functionSet member to the address of the + XcmsFunctionSet structure. + * It then sets the state member to XcmsInitSuccess and + finally returns XcmsSuccess. + + If unsuccessful, the procedure sets the state member to + XcmsInitFailure and returns XcmsFailure. + + The XcmsPerScrnInfo structure contains: + + + +typedef struct _XcmsPerScrnInfo { + XcmsColor screenWhitePoint; + XPointer functionSet; + XPointer screenData; + unsigned char state; + char pad[3]; +} XcmsPerScrnInfo; + + The screenWhitePoint member specifies the white point inherent + to the screen. The functionSet member specifies the appropriate + function set. The screenData member specifies the device + profile. The state member is set to one of the following: + * XcmsInitNone indicates initialization has not been + previously attempted. + * XcmsInitFailure indicates initialization has been + previously attempted but failed. + * XcmsInitSuccess indicates initialization has been + previously attempted and succeeded. + + The screen free callback must adhere to the following software + interface specification: + + typedef void (*XcmsScreenFreeProc)(XPointer screenData); + + screenData + + Specifies the data to be freed. + + This function is called to free the screenData stored in an + XcmsPerScrnInfo structure. + +Chapter 7. Graphics Context Functions + + Table of Contents + + Manipulating Graphics Context/State + Using Graphics Context Convenience Routines + + Setting the Foreground, Background, Function, or Plane + Mask + + Setting the Line Attributes and Dashes + Setting the Fill Style and Fill Rule + Setting the Fill Tile and Stipple + Setting the Current Font + Setting the Clip Region + Setting the Arc Mode, Subwindow Mode, and Graphics + Exposure + + A number of resources are used when performing graphics + operations in X. Most information about performing graphics + (for example, foreground color, background color, line style, + and so on) is stored in resources called graphics contexts + (GCs). Most graphics operations (see chapter 8) take a GC as an + argument. Although in theory the X protocol permits sharing of + GCs between applications, it is expected that applications will + use their own GCs when performing operations. Sharing of GCs is + highly discouraged because the library may cache GC state. + + Graphics operations can be performed to either windows or + pixmaps, which collectively are called drawables. Each drawable + exists on a single screen. A GC is created for a specific + screen and drawable depth and can only be used with drawables + of matching screen and depth. + + This chapter discusses how to: + * Manipulate graphics context/state + * Use graphics context convenience functions + +Manipulating Graphics Context/State + + Most attributes of graphics operations are stored in GCs. These + include line width, line style, plane mask, foreground, + background, tile, stipple, clipping region, end style, join + style, and so on. Graphics operations (for example, drawing + lines) use these values to determine the actual drawing + operation. Extensions to X may add additional components to + GCs. The contents of a GC are private to Xlib. + + Xlib implements a write-back cache for all elements of a GC + that are not resource IDs to allow Xlib to implement the + transparent coalescing of changes to GCs. For example, a call + to XSetForeground of a GC followed by a call to + XSetLineAttributes results in only a single-change GC protocol + request to the server. GCs are neither expected nor encouraged + to be shared between client applications, so this write-back + caching should present no problems. Applications cannot share + GCs without external synchronization. Therefore, sharing GCs + between applications is highly discouraged. + + To set an attribute of a GC, set the appropriate member of the + XGCValues structure and OR in the corresponding value bitmask + in your subsequent calls to XCreateGC. The symbols for the + value mask bits and the XGCValues structure are: +/* GC attribute value mask bits */ + +#define GCFunction (1L<<0) +#define GCPlaneMask (1L<<1) +#define GCForeground (1L<<2) +#define GCBackground (1L<<3) +#define GCLineWidth (1L<<4) +#define GCLineStyle (1L<<5) +#define GCCapStyle (1L<<6) +#define GCJoinStyle (1L<<7) +#define GCFillStyle (1L<<8) +#define GCFillRule (1L<<9) +#define GCTile (1L<<10) +#define GCStipple (1L<<11) +#define GCTileStipXOrigin (1L<<12) +#define GCTileStipYOrigin (1L<<13) +#define GCFont (1L<<14) +#define GCSubwindowMode (1L<<15) +#define GCGraphicsExposures (1L<<16) +#define GCClipXOrigin (1L<<17) +#define GCClipYOrigin (1L<<18) +#define GCClipMask (1L<<19) +#define GCDashOffset (1L<<20) +#define GCDashList (1L<<21) +#define GCArcMode (1L<<22) + + + +/* Values */ + +typedef struct { + int function; /* logical operation */ + unsigned long plane_mask; /* plane mask */ + unsigned long foreground; /* foreground pixel */ + unsigned long background; /* background pixel */ + int line_width; /* line width (in pixels) */ + int line_style; /* LineSolid, LineOnOffDash, LineDoub +leDash */ + int cap_style; /* CapNotLast, CapButt, CapRound, Cap +Projecting */ + int join_style; /* JoinMiter, JoinRound, JoinBevel */ + int fill_style; /* FillSolid, FillTiled, FillStippled + FillOpaqueStippled*/ + int fill_rule; /* EvenOddRule, WindingRule */ + int arc_mode; /* ArcChord, ArcPieSlice */ + Pixmap tile; /* tile pixmap for tiling operations +*/ + Pixmap stipple; /* stipple 1 plane pixmap for stippli +ng */ + int ts_x_origin; /* offset for tile or stipple operati +ons */ + int ts_y_origin + Font font; /* default text font for text operati +ons */ + int subwindow_mode; /* ClipByChildren, IncludeInferiors * +/ + Bool graphics_exposures; /* boolean, should exposures be gener +ated */ + int clip_x_origin; /* origin for clipping */ + int clip_y_origin; + Pixmap clip_mask; /* bitmap clipping; other calls for r +ects */ + int dash_offset; /* patterned/dashed line information +*/ + char dashes; +} XGCValues; + + The default GC values are: + Component Default + function GXcopy + plane_mask All ones + foreground 0 + background 1 + line_width 0 + line_style LineSolid + cap_style CapButt + join_style JoinMiter + fill_style FillSolid + fill_rule EvenOddRule + arc_mode ArcPieSlice + tile + + Pixmap of unspecified size filled with foreground pixel + + (that is, client specified pixel if any, else 0) + + (subsequent changes to foreground do not affect this pixmap) + stipple Pixmap of unspecified size filled with ones + ts_x_origin 0 + ts_y_origin 0 + font + subwindow_mode ClipByChildren + graphics_exposures True + clip_x_origin 0 + clip_y_origin 0 + clip_mask None + dash_offset 0 + dashes 4 (that is, the list [4, 4]) + + Note that foreground and background are not set to any values + likely to be useful in a window. + + The function attributes of a GC are used when you update a + section of a drawable (the destination) with bits from + somewhere else (the source). The function in a GC defines how + the new destination bits are to be computed from the source + bits and the old destination bits. GXcopy is typically the most + useful because it will work on a color display, but special + applications may use other functions, particularly in concert + with particular planes of a color display. The 16 GC functions, + defined in , are: + Function Name Value Operation + GXclear 0x0 0 + GXand 0x1 src AND dst + GXandReverse 0x2 src AND NOT dst + GXcopy 0x3 src + GXandInverted 0x4 (NOT src) AND dst + GXnoop 0x5 dst + GXxor 0x6 src XOR dst + GXor 0x7 src OR dst + GXnor 0x8 (NOT src) AND (NOT dst) + GXequiv 0x9 (NOT src) XOR dst + GXinvert 0xa NOT dst + GXorReverse 0xb src OR (NOT dst) + GXcopyInverted 0xc NOT src + GXorInverted 0xd (NOT src) OR dst + GXnand 0xe (NOT src) OR (NOT dst) + GXset 0xf 1 + + Many graphics operations depend on either pixel values or + planes in a GC. The planes attribute is of type long, and it + specifies which planes of the destination are to be modified, + one bit per plane. A monochrome display has only one plane and + will be the least significant bit of the word. As planes are + added to the display hardware, they will occupy more + significant bits in the plane mask. + + In graphics operations, given a source and destination pixel, + the result is computed bitwise on corresponding bits of the + pixels. That is, a Boolean operation is performed in each bit + plane. The plane_mask restricts the operation to a subset of + planes. A macro constant AllPlanes can be used to refer to all + planes of the screen simultaneously. The result is computed by + the following: + +((src FUNC dst) AND plane-mask) OR (dst AND (NOT plane-mask)) + + Range checking is not performed on the values for foreground, + background, or plane_mask. They are simply truncated to the + appropriate number of bits. The line-width is measured in + pixels and either can be greater than or equal to one (wide + line) or can be the special value zero (thin line). + + Wide lines are drawn centered on the path described by the + graphics request. Unless otherwise specified by the join-style + or cap-style, the bounding box of a wide line with endpoints + [x1, y1], [x2, y2] and width w is a rectangle with vertices at + the following real coordinates: + + + +[x1-(w*sn/2), y1+(w*cs/2)], [x1+(w*sn/2), y1-(w*cs/2)], +[x2-(w*sn/2), y2+(w*cs/2)], [x2+(w*sn/2), y2-(w*cs/2)] + + Here sn is the sine of the angle of the line, and cs is the + cosine of the angle of the line. A pixel is part of the line + and so is drawn if the center of the pixel is fully inside the + bounding box (which is viewed as having infinitely thin edges). + If the center of the pixel is exactly on the bounding box, it + is part of the line if and only if the interior is immediately + to its right (x increasing direction). Pixels with centers on a + horizontal edge are a special case and are part of the line if + and only if the interior or the boundary is immediately below + (y increasing direction) and the interior or the boundary is + immediately to the right (x increasing direction). + + Thin lines (zero line-width) are one-pixel-wide lines drawn + using an unspecified, device-dependent algorithm. There are + only two constraints on this algorithm. + * If a line is drawn unclipped from [x1,y1] to [x2,y2] and if + another line is drawn unclipped from [x1+dx,y1+dy] to + [x2+dx,y2+dy], a point [x,y] is touched by drawing the + first line if and only if the point [x+dx,y+dy] is touched + by drawing the second line. + * The effective set of points comprising a line cannot be + affected by clipping. That is, a point is touched in a + clipped line if and only if the point lies inside the + clipping region and the point would be touched by the line + when drawn unclipped. + + A wide line drawn from [x1,y1] to [x2,y2] always draws the same + pixels as a wide line drawn from [x2,y2] to [x1,y1], not + counting cap-style and join-style. It is recommended that this + property be true for thin lines, but this is not required. A + line-width of zero may differ from a line-width of one in which + pixels are drawn. This permits the use of many manufacturers' + line drawing hardware, which may run many times faster than the + more precisely specified wide lines. + + In general, drawing a thin line will be faster than drawing a + wide line of width one. However, because of their different + drawing algorithms, thin lines may not mix well aesthetically + with wide lines. If it is desirable to obtain precise and + uniform results across all displays, a client should always use + a line-width of one rather than a line-width of zero. + + The line-style defines which sections of a line are drawn: + + LineSolid + + The full path of the line is drawn. + + LineDoubleDash + + The full path of the line is drawn, but the even dashes are + filled differently from the odd dashes (see fill-style) with + CapButt style used where even and odd dashes meet. + + LineOnOffDash + + Only the even dashes are drawn, and cap-style applies to all + internal ends of the individual dashes, except CapNotLast is + treated as CapButt. + + The cap-style defines how the endpoints of a path are drawn: + + CapNotLast + + This is equivalent to CapButt except that for a line-width of + zero the final endpoint is not drawn. + + CapButt + + The line is square at the endpoint (perpendicular to the slope + of the line) with no projection beyond. + + CapRound + + The line has a circular arc with the diameter equal to the + line-width, centered on the endpoint. (This is equivalent to + CapButt for line-width of zero). + + CapProjecting + + The line is square at the end, but the path continues beyond + the endpoint for a distance equal to half the line-width. (This + is equivalent to CapButt for line-width of zero). + + The join-style defines how corners are drawn for wide lines: + + JoinMiter + + The outer edges of two lines extend to meet at an angle. + However, if the angle is less than 11 degrees, then a JoinBevel + join-style is used instead. + + JoinRound + + The corner is a circular arc with the diameter equal to the + line-width, centered on the joinpoint. + + JoinBevel + + The corner has CapButt endpoint styles with the triangular + notch filled. + + For a line with coincident endpoints (x1=x2, y1=y2), when the + cap-style is applied to both endpoints, the semantics depends + on the line-width and the cap-style: + CapNotLast thin The results are device dependent, but the + desired effect is that nothing is drawn. + CapButt thin The results are device dependent, but the desired + effect is that a single pixel is drawn. + CapRound thin The results are the same as for CapButt /thin. + CapProjecting thin The results are the same as for CapButt + /thin. + CapButt wide Nothing is drawn. + CapRound wide The closed path is a circle, centered at the + endpoint, and with the diameter equal to the line-width. + CapProjecting wide The closed path is a square, aligned with + the coordinate axes, centered at the endpoint, and with the + sides equal to the line-width. + + For a line with coincident endpoints (x1=x2, y1=y2), when the + join-style is applied at one or both endpoints, the effect is + as if the line was removed from the overall path. However, if + the total path consists of or is reduced to a single point + joined with itself, the effect is the same as when the + cap-style is applied at both endpoints. + + The tile/stipple represents an infinite two-dimensional plane, + with the tile/stipple replicated in all dimensions. When that + plane is superimposed on the drawable for use in a graphics + operation, the upper-left corner of some instance of the + tile/stipple is at the coordinates within the drawable + specified by the tile/stipple origin. The tile/stipple and clip + origins are interpreted relative to the origin of whatever + destination drawable is specified in a graphics request. The + tile pixmap must have the same root and depth as the GC, or a + BadMatch error results. The stipple pixmap must have depth one + and must have the same root as the GC, or a BadMatch error + results. For stipple operations where the fill-style is + FillStippled but not FillOpaqueStippled, the stipple pattern is + tiled in a single plane and acts as an additional clip mask to + be ANDed with the clip-mask. Although some sizes may be faster + to use than others, any size pixmap can be used for tiling or + stippling. + + The fill-style defines the contents of the source for line, + text, and fill requests. For all text and fill requests (for + example, XDrawText, XDrawText16, XFillRectangle, XFillPolygon, + and XFillArc); for line requests with line-style LineSolid (for + example, XDrawLine, XDrawSegments, XDrawRectangle, XDrawArc); + and for the even dashes for line requests with line-style + LineOnOffDash or LineDoubleDash, the following apply: + FillSolid Foreground + FillTiled Tile + FillOpaqueStippled A tile with the same width and height as + stipple, but with background everywhere stipple has a zero and + with foreground everywhere stipple has a one + FillStippled Foreground masked by stipple + + When drawing lines with line-style LineDoubleDash, the odd + dashes are controlled by the fill-style in the following + manner: + FillSolid Background + FillTiled Same as for even dashes + FillOpaqueStippled Same as for even dashes + FillStippled Background masked by stipple + + Storing a pixmap in a GC might or might not result in a copy + being made. If the pixmap is later used as the destination for + a graphics request, the change might or might not be reflected + in the GC. If the pixmap is used simultaneously in a graphics + request both as a destination and as a tile or stipple, the + results are undefined. + + For optimum performance, you should draw as much as possible + with the same GC (without changing its components). The costs + of changing GC components relative to using different GCs + depend on the display hardware and the server implementation. + It is quite likely that some amount of GC information will be + cached in display hardware and that such hardware can only + cache a small number of GCs. + + The dashes value is actually a simplified form of the more + general patterns that can be set with XSetDashes. Specifying a + value of N is equivalent to specifying the two-element list [N, + N] in XSetDashes. The value must be nonzero, or a BadValue + error results. + + The clip-mask restricts writes to the destination drawable. If + the clip-mask is set to a pixmap, it must have depth one and + have the same root as the GC, or a BadMatch error results. If + clip-mask is set to None, the pixels are always drawn + regardless of the clip origin. The clip-mask also can be set by + calling the XSetClipRectangles or XSetRegion functions. Only + pixels where the clip-mask has a bit set to 1 are drawn. Pixels + are not drawn outside the area covered by the clip-mask or + where the clip-mask has a bit set to 0. The clip-mask affects + all graphics requests. The clip-mask does not clip sources. The + clip-mask origin is interpreted relative to the origin of + whatever destination drawable is specified in a graphics + request. + + You can set the subwindow-mode to ClipByChildren or + IncludeInferiors. For ClipByChildren, both source and + destination windows are additionally clipped by all viewable + InputOutput children. For IncludeInferiors, neither source nor + destination window is clipped by inferiors. This will result in + including subwindow contents in the source and drawing through + subwindow boundaries of the destination. The use of + IncludeInferiors on a window of one depth with mapped inferiors + of differing depth is not illegal, but the semantics are + undefined by the core protocol. + + The fill-rule defines what pixels are inside (drawn) for paths + given in XFillPolygon requests and can be set to EvenOddRule or + WindingRule. For EvenOddRule, a point is inside if an infinite + ray with the point as origin crosses the path an odd number of + times. For WindingRule, a point is inside if an infinite ray + with the point as origin crosses an unequal number of clockwise + and counterclockwise directed path segments. A clockwise + directed path segment is one that crosses the ray from left to + right as observed from the point. A counterclockwise segment is + one that crosses the ray from right to left as observed from + the point. The case where a directed line segment is coincident + with the ray is uninteresting because you can simply choose a + different ray that is not coincident with a segment. + + For both EvenOddRule and WindingRule, a point is infinitely + small, and the path is an infinitely thin line. A pixel is + inside if the center point of the pixel is inside and the + center point is not on the boundary. If the center point is on + the boundary, the pixel is inside if and only if the polygon + interior is immediately to its right (x increasing direction). + Pixels with centers on a horizontal edge are a special case and + are inside if and only if the polygon interior is immediately + below (y increasing direction). + + The arc-mode controls filling in the XFillArcs function and can + be set to ArcPieSlice or ArcChord. For ArcPieSlice, the arcs + are pie-slice filled. For ArcChord, the arcs are chord filled. + + The graphics-exposure flag controls GraphicsExpose event + generation for XCopyArea and XCopyPlane requests (and any + similar requests defined by extensions). + + To create a new GC that is usable on a given screen with a + depth of drawable, use XCreateGC. + + GC XCreateGC(Display *display, Drawable d, unsigned long + valuemask, XGCValues *values); + + display + + Specifies the connection to the X server. + + d + + Specifies the drawable. + + valuemask + + Specifies which components in the GC are to be set using the + information in the specified values structure. This argument is + the bitwise inclusive OR of zero or more of the valid GC + component mask bits. + + values + + Specifies any values as specified by the valuemask. + + The XCreateGC function creates a graphics context and returns a + GC. The GC can be used with any destination drawable having the + same root and depth as the specified drawable. Use with other + drawables results in a BadMatch error. + + XCreateGC can generate BadAlloc, BadDrawable, BadFont, + BadMatch, BadPixmap, and BadValue errors. + + To copy components from a source GC to a destination GC, use + XCopyGC. + + XCopyGC(Display *display, GC src, GC dest, unsigned long + valuemask); + + display + + Specifies the connection to the X server. + + src + + Specifies the components of the source GC. + + valuemask + + Specifies which components in the GC are to be copied to the + destination GC. This argument is the bitwise inclusive OR of + zero or more of the valid GC component mask bits. + + dest + + Specifies the destination GC. + + The XCopyGC function copies the specified components from the + source GC to the destination GC. The source and destination GCs + must have the same root and depth, or a BadMatch error results. + The valuemask specifies which component to copy, as for + XCreateGC. + + XCopyGC can generate BadAlloc, BadGC, and BadMatch errors. + + To change the components in a given GC, use XChangeGC. + + XChangeGC(Display *display, GC gc, unsigned long valuemask, + XGCValues *values); + + display + + Specifies the connection to the X server. + + gc + + Specifies the GC. + + valuemask + + Specifies which components in the GC are to be changed using + information in the specified values structure. This argument is + the bitwise inclusive OR of zero or more of the valid GC + component mask bits. + + values + + Specifies any values as specified by the valuemask. + + The XChangeGC function changes the components specified by + valuemask for the specified GC. The values argument contains + the values to be set. The values and restrictions are the same + as for XCreateGC. Changing the clip-mask overrides any previous + XSetClipRectangles request on the context. Changing the + dash-offset or dash-list overrides any previous XSetDashes + request on the context. The order in which components are + verified and altered is server dependent. If an error is + generated, a subset of the components may have been altered. + + XChangeGC can generate BadAlloc, BadFont, BadGC, BadMatch, + BadPixmap, and BadValue errors. + + To obtain components of a given GC, use XGetGCValues. + + Status XGetGCValues(Display *display, GC gc, unsigned long + valuemask, XGCValues *values_return); + + display + + Specifies the connection to the X server. + + gc + + Specifies the GC. + + valuemask + + Specifies which components in the GC are to be returned in the + values_return argument. This argument is the bitwise inclusive + OR of zero or more of the valid GC component mask bits. + + values_return + + Returns the GC values in the specified XGCValues structure. + + The XGetGCValues function returns the components specified by + valuemask for the specified GC. If the valuemask contains a + valid set of GC mask bits (GCFunction, GCPlaneMask, + GCForeground, GCBackground, GCLineWidth, GCLineStyle, + GCCapStyle, GCJoinStyle, GCFillStyle, GCFillRule, GCTile, + GCStipple, GCTileStipXOrigin, GCTileStipYOrigin, GCFont, + GCSubwindowMode, GCGraphicsExposures, GCClipXOrigin, + GCClipYOrigin, GCDashOffset, or GCArcMode) and no error occurs, + XGetGCValues sets the requested components in values_return and + returns a nonzero status. Otherwise, it returns a zero status. + Note that the clip-mask and dash-list (represented by the + GCClipMask and GCDashList bits, respectively, in the valuemask) + cannot be requested. Also note that an invalid resource ID + (with one or more of the three most significant bits set to 1) + will be returned for GCFont, GCTile, and GCStipple if the + component has never been explicitly set by the client. + + To free a given GC, use XFreeGC. + + XFreeGC(Display *display, GC gc); + + display + + Specifies the connection to the X server. + + gc + + Specifies the GC. + + The XFreeGC function destroys the specified GC as well as all + the associated storage. + + XFreeGC can generate a BadGC error. + + To obtain the GContext resource ID for a given GC, use + XGContextFromGC. + + GContext XGContextFromGC(GC gc); + + gc + + Specifies the GC for which you want the resource ID. + + Xlib usually defers sending changes to the components of a GC + to the server until a graphics function is actually called with + that GC. This permits batching of component changes into a + single server request. In some circumstances, however, it may + be necessary for the client to explicitly force sending the + changes to the server. An example might be when a protocol + extension uses the GC indirectly, in such a way that the + extension interface cannot know what GC will be used. To force + sending GC component changes, use XFlushGC. + + void XFlushGC(Display *display, GC gc); + + display + + Specifies the connection to the X server. + + gc + + Specifies the GC. + +Using Graphics Context Convenience Routines + + This section discusses how to set the: + * Foreground, background, plane mask, or function components + * Line attributes and dashes components + * Fill style and fill rule components + * Fill tile and stipple components + * Font component + * Clip region component + * Arc mode, subwindow mode, and graphics exposure components + +Setting the Foreground, Background, Function, or Plane Mask + + To set the foreground, background, plane mask, and function + components for a given GC, use XSetState. + + XSetState(Display *display, GC gc, unsigned long foreground, + unsigned long background, int function, unsigned long + plane_mask); + + display + + Specifies the connection to the X server. + + gc + + Specifies the GC. + + foreground + + Specifies the foreground you want to set for the specified GC. + + background + + Specifies the background you want to set for the specified GC. + + function + + Specifies the function you want to set for the specified GC. + + plane_mask + + Specifies the plane mask. + + XSetState can generate BadAlloc, BadGC, and BadValue errors. + + To set the foreground of a given GC, use XSetForeground. + + XSetForeground(Display *display, GC gc, unsigned long + foreground); + + display + + Specifies the connection to the X server. + + gc + + Specifies the GC. + + foreground + + Specifies the foreground you want to set for the specified GC. + + XSetForeground can generate BadAlloc and BadGC errors. + + To set the background of a given GC, use XSetBackground. + + XSetBackground(Display *display, GC gc, unsigned long + background); + + display + + Specifies the connection to the X server. + + gc + + Specifies the GC. + + background + + Specifies the background you want to set for the specified GC. + + XSetBackground can generate BadAlloc and BadGC errors. + + To set the display function in a given GC, use XSetFunction. + + XSetFunction(Display *display, GC gc, int function); + + display + + Specifies the connection to the X server. + + gc + + Specifies the GC. + + function + + Specifies the function you want to set for the specified GC. + + XSetFunction can generate BadAlloc, BadGC, and BadValue errors. + + To set the plane mask of a given GC, use XSetPlaneMask. + + XSetPlaneMask(Display *display, GC gc, unsigned long + plane_mask); + + display + + Specifies the connection to the X server. + + gc + + Specifies the GC. + + plane_mask + + Specifies the plane mask. + + XSetPlaneMask can generate BadAlloc and BadGC errors. + +Setting the Line Attributes and Dashes + + To set the line drawing components of a given GC, use + XSetLineAttributes. + + XSetLineAttributes(Display *display, GC gc, unsigned int + line_width, int line_style, int cap_style, int join_style); + + display + + Specifies the connection to the X server. + + gc + + Specifies the GC. + + line_width + + Specifies the line-width you want to set for the specified GC. + + line_style + + Specifies the line-style you want to set for the specified GC. + You can pass LineSolid, LineOnOffDash, or LineDoubleDash. + + cap_style + + Specifies the line-style and cap-style you want to set for the + specified GC. You can pass CapNotLast, CapButt, CapRound, or + CapProjecting. + + join_style + + Specifies the line join-style you want to set for the specified + GC. You can pass JoinMiter, JoinRound, or JoinBevel. + + XSetLineAttributes can generate BadAlloc, BadGC, and BadValue + errors. + + To set the dash-offset and dash-list for dashed line styles of + a given GC, use XSetDashes. + + XSetDashes(Display *display, GC gc, int dash_offset, char + dash_list[], int n); + + display + + Specifies the connection to the X server. + + gc + + Specifies the GC. + + dash_offset + + Specifies the phase of the pattern for the dashed line-style + you want to set for the specified GC. + + dash_list + + Specifies the dash-list for the dashed line-style you want to + set for the specified GC. + + n + + Specifies the number of elements in dash_list. + + The XSetDashes function sets the dash-offset and dash-list + attributes for dashed line styles in the specified GC. There + must be at least one element in the specified dash_list, or a + BadValue error results. The initial and alternating elements + (second, fourth, and so on) of the dash_list are the even + dashes, and the others are the odd dashes. Each element + specifies a dash length in pixels. All of the elements must be + nonzero, or a BadValue error results. Specifying an odd-length + list is equivalent to specifying the same list concatenated + with itself to produce an even-length list. + + The dash-offset defines the phase of the pattern, specifying + how many pixels into the dash-list the pattern should actually + begin in any single graphics request. Dashing is continuous + through path elements combined with a join-style but is reset + to the dash-offset between each sequence of joined lines. + + The unit of measure for dashes is the same for the ordinary + coordinate system. Ideally, a dash length is measured along the + slope of the line, but implementations are only required to + match this ideal for horizontal and vertical lines. Failing the + ideal semantics, it is suggested that the length be measured + along the major axis of the line. The major axis is defined as + the x axis for lines drawn at an angle of between -45 and +45 + degrees or between 135 and 225 degrees from the x axis. For all + other lines, the major axis is the y axis. + + XSetDashes can generate BadAlloc, BadGC, and BadValue errors. + +Setting the Fill Style and Fill Rule + + To set the fill-style of a given GC, use XSetFillStyle. + + XSetFillStyle(Display *display, GC gc, int fill_style); + + display + + Specifies the connection to the X server. + + gc + + Specifies the GC. + + fill_style + + Specifies the fill-style you want to set for the specified GC. + You can pass FillSolid, FillTiled, FillStippled, or + FillOpaqueStippled. + + XSetFillStyle can generate BadAlloc, BadGC, and BadValue + errors. + + To set the fill-rule of a given GC, use XSetFillRule. + + XSetFillRule(Display *display, GC gc, int fill_rule); + + display + + Specifies the connection to the X server. + + gc + + Specifies the GC. + + fill_rule + + Specifies the fill-rule you want to set for the specified GC. + You can pass EvenOddRule or WindingRule. + + XSetFillRule can generate BadAlloc, BadGC, and BadValue errors. + +Setting the Fill Tile and Stipple + + Some displays have hardware support for tiling or stippling + with patterns of specific sizes. Tiling and stippling + operations that restrict themselves to those specific sizes run + much faster than such operations with arbitrary size patterns. + Xlib provides functions that you can use to determine the best + size, tile, or stipple for the display as well as to set the + tile or stipple shape and the tile or stipple origin. + + To obtain the best size of a tile, stipple, or cursor, use + XQueryBestSize. + + Status XQueryBestSize(Display *display, int class, Drawable + which_screen, unsigned int width, unsigned int height, unsigned + int *width_return, unsigned int *height_return); + + display + + Specifies the connection to the X server. + + class + + Specifies the class that you are interested in. You can pass + TileShape, CursorShape, or StippleShape. + + which_screen + + Specifies any drawable on the screen. + + width + + height + + Specify the width and height. + + width_return + + height_return + + Return the width and height of the object best supported by the + display hardware. + + The XQueryBestSize function returns the best or closest size to + the specified size. For CursorShape, this is the largest size + that can be fully displayed on the screen specified by + which_screen. For TileShape, this is the size that can be tiled + fastest. For StippleShape, this is the size that can be + stippled fastest. For CursorShape, the drawable indicates the + desired screen. For TileShape and StippleShape, the drawable + indicates the screen and possibly the window class and depth. + An InputOnly window cannot be used as the drawable for + TileShape or StippleShape, or a BadMatch error results. + + XQueryBestSize can generate BadDrawable, BadMatch, and BadValue + errors. + + To obtain the best fill tile shape, use XQueryBestTile. + + Status XQueryBestTile(Display *display, Drawable which_screen, + unsigned int width, unsigned int height, unsigned int + *width_return, unsigned int *height_return); + + display + + Specifies the connection to the X server. + + which_screen + + Specifies any drawable on the screen. + + width + + height + + Specify the width and height. + + width_return + + height_return + + Return the width and height of the object best supported by the + display hardware. + + The XQueryBestTile function returns the best or closest size, + that is, the size that can be tiled fastest on the screen + specified by which_screen. The drawable indicates the screen + and possibly the window class and depth. If an InputOnly window + is used as the drawable, a BadMatch error results. + + XQueryBestTile can generate BadDrawable and BadMatch errors. + + To obtain the best stipple shape, use XQueryBestStipple. + + Status XQueryBestStipple(Display *display, Drawable + which_screen, unsigned int width, unsigned int height, unsigned + int *width_return, unsigned int *height_return); + + display + + Specifies the connection to the X server. + + which_screen + + Specifies any drawable on the screen. + + width + + height + + Specify the width and height. + + width_return + + height_return + + Return the width and height of the object best supported by the + display hardware. + + The XQueryBestStipple function returns the best or closest + size, that is, the size that can be stippled fastest on the + screen specified by which_screen. The drawable indicates the + screen and possibly the window class and depth. If an InputOnly + window is used as the drawable, a BadMatch error results. + + XQueryBestStipple can generate BadDrawable and BadMatch errors. + + To set the fill tile of a given GC, use XSetTile. + + XSetTile(Display *display, GC gc, Pixmap tile); + + display + + Specifies the connection to the X server. + + gc + + Specifies the GC. + + tile + + Specifies the fill tile you want to set for the specified GC. + + The tile and GC must have the same depth, or a BadMatch error + results. + + XSetTile can generate BadAlloc, BadGC, BadMatch, and BadPixmap + errors. + + To set the stipple of a given GC, use XSetStipple. + + XSetStipple(Display *display, GC gc, Pixmap stipple); + + display + + Specifies the connection to the X server. + + gc + + Specifies the GC. + + stipple + + Specifies the stipple you want to set for the specified GC. + + The stipple must have a depth of one, or a BadMatch error + results. + + XSetStipple can generate BadAlloc, BadGC, BadMatch, and + BadPixmap errors. + + To set the tile or stipple origin of a given GC, use + XSetTSOrigin. + + XSetTSOrigin(Display *display, GC gc, int ts_x_origin, int + ts_y_origin); + + display + + Specifies the connection to the X server. + + gc + + Specifies the GC. + + ts_x_origin + + ts_y_origin + + Specify the x and y coordinates of the tile and stipple origin. + + When graphics requests call for tiling or stippling, the + parent's origin will be interpreted relative to whatever + destination drawable is specified in the graphics request. + + XSetTSOrigin can generate BadAlloc and BadGC errors. + +Setting the Current Font + + To set the current font of a given GC, use XSetFont. + + XSetFont(Display *display, GC gc, Font font); + + display + + Specifies the connection to the X server. + + gc + + Specifies the GC. + + font + + Specifies the font. + + XSetFont can generate BadAlloc, BadFont, and BadGC errors. + +Setting the Clip Region + + Xlib provides functions that you can use to set the clip-origin + and the clip-mask or set the clip-mask to a list of rectangles. + + To set the clip-origin of a given GC, use XSetClipOrigin. + + XSetClipOrigin(Display *display, GC gc, int clip_x_origin, int + clip_y_origin); + + display + + Specifies the connection to the X server. + + gc + + Specifies the GC. + + clip_x_origin + + clip_y_origin + + Specify the x and y coordinates of the clip-mask origin. + + The clip-mask origin is interpreted relative to the origin of + whatever destination drawable is specified in the graphics + request. + + XSetClipOrigin can generate BadAlloc and BadGC errors. + + To set the clip-mask of a given GC to the specified pixmap, use + XSetClipMask. + + XSetClipMask(Display *display, GC gc, Pixmap pixmap); + + display + + Specifies the connection to the X server. + + gc + + Specifies the GC. + + pixmap + + Specifies the pixmap or None. + + If the clip-mask is set to None, the pixels are always drawn + (regardless of the clip-origin). + + XSetClipMask can generate BadAlloc, BadGC, BadMatch, and + BadPixmap errors. + + To set the clip-mask of a given GC to the specified list of + rectangles, use XSetClipRectangles. + + XSetClipRectangles(Display *display, GC gc, int clip_x_origin, + int clip_y_origin, XRectangle rectangles[], int n, int + ordering); + + display + + Specifies the connection to the X server. + + gc + + Specifies the GC. + + clip_x_origin + + clip_y_origin + + Specify the x and y coordinates of the clip-mask origin. + + rectangles + + Specifies an array of rectangles that define the clip-mask. + + n + + Specifies the number of rectangles. + + ordering + + Specifies the ordering relations on the rectangles. You can + pass Unsorted, YSorted, YXSorted, or YXBanded. + + The XSetClipRectangles function changes the clip-mask in the + specified GC to the specified list of rectangles and sets the + clip origin. The output is clipped to remain contained within + the rectangles. The clip-origin is interpreted relative to the + origin of whatever destination drawable is specified in a + graphics request. The rectangle coordinates are interpreted + relative to the clip-origin. The rectangles should be + nonintersecting, or the graphics results will be undefined. + Note that the list of rectangles can be empty, which + effectively disables output. This is the opposite of passing + None as the clip-mask in XCreateGC, XChangeGC, and + XSetClipMask. + + If known by the client, ordering relations on the rectangles + can be specified with the ordering argument. This may provide + faster operation by the server. If an incorrect ordering is + specified, the X server may generate a BadMatch error, but it + is not required to do so. If no error is generated, the + graphics results are undefined. Unsorted means the rectangles + are in arbitrary order. YSorted means that the rectangles are + nondecreasing in their Y origin. YXSorted additionally + constrains YSorted order in that all rectangles with an equal Y + origin are nondecreasing in their X origin. YXBanded + additionally constrains YXSorted by requiring that, for every + possible Y scanline, all rectangles that include that scanline + have an identical Y origins and Y extents. + + XSetClipRectangles can generate BadAlloc, BadGC, BadMatch, and + BadValue errors. + + Xlib provides a set of basic functions for performing region + arithmetic. For information about these functions, see section + 16.5. + +Setting the Arc Mode, Subwindow Mode, and Graphics Exposure + + To set the arc mode of a given GC, use XSetArcMode. + + XSetArcMode(Display *display, GC gc, int arc_mode); + + display + + Specifies the connection to the X server. + + gc + + Specifies the GC. + + arc_mode + + Specifies the arc mode. You can pass ArcChord or ArcPieSlice. + + XSetArcMode can generate BadAlloc, BadGC, and BadValue errors. + + To set the subwindow mode of a given GC, use XSetSubwindowMode. + + XSetSubwindowMode(Display *display, GC gc, int subwindow_mode); + + display + + Specifies the connection to the X server. + + gc + + Specifies the GC. + + subwindow_mode + + Specifies the subwindow mode. You can pass ClipByChildren or + IncludeInferiors. + + XSetSubwindowMode can generate BadAlloc, BadGC, and BadValue + errors. + + To set the graphics-exposures flag of a given GC, use + XSetGraphicsExposures. + + XSetGraphicsExposures(Display *display, GC gc, Bool + graphics_exposures); + + display + + Specifies the connection to the X server. + + gc + + Specifies the GC. + + graphics_exposures + + Specifies a Boolean value that indicates whether you want + GraphicsExpose and NoExpose events to be reported when calling + XCopyArea and XCopyPlane with this GC. + + XSetGraphicsExposures can generate BadAlloc, BadGC, and + BadValue errors. + +Chapter 8. Graphics Functions + + Table of Contents + + Clearing Areas + Copying Areas + Drawing Points, Lines, Rectangles, and Arcs + + Drawing Single and Multiple Points + Drawing Single and Multiple Lines + Drawing Single and Multiple Rectangles + Drawing Single and Multiple Arcs + + Filling Areas + + Filling Single and Multiple Rectangles + Filling a Single Polygon + Filling Single and Multiple Arcs + + Font Metrics + + Loading and Freeing Fonts + Obtaining and Freeing Font Names and Information + Computing Character String Sizes + Computing Logical Extents + Querying Character String Sizes + + Drawing Text + + Drawing Complex Text + Drawing Text Characters + Drawing Image Text Characters + + Transferring Images between Client and Server + + Once you have established a connection to a display, you can + use the Xlib graphics functions to: + * Clear and copy areas + * Draw points, lines, rectangles, and arcs + * Fill areas + * Manipulate fonts + * Draw text + * Transfer images between clients and the server + + If the same drawable and GC is used for each call, Xlib batches + back-to-back calls to XDrawPoint, XDrawLine, XDrawRectangle, + XFillArc, and XFillRectangle. Note that this reduces the total + number of requests sent to the server. + +Clearing Areas + + Xlib provides functions that you can use to clear an area or + the entire window. Because pixmaps do not have defined + backgrounds, they cannot be filled by using the functions + described in this section. Instead, to accomplish an analogous + operation on a pixmap, you should use XFillRectangle, which + sets the pixmap to a known value. + + To clear a rectangular area of a given window, use XClearArea. + + XClearArea(Display *display, Window w, int x, int y, unsigned + int width, unsigned int height, Bool exposures); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + x + + y + + Specify the x and y coordinates, which are relative to the + origin of the window and specify the upper-left corner of the + rectangle. + + width + + height + + Specify the width and height, which are the dimensions of the + rectangle. + + exposures + + Specifies a Boolean value that indicates if Expose events are + to be generated. + + The XClearArea function paints a rectangular area in the + specified window according to the specified dimensions with the + window's background pixel or pixmap. The subwindow-mode + effectively is ClipByChildren. If width is zero, it is replaced + with the current width of the window minus x. If height is + zero, it is replaced with the current height of the window + minus y. If the window has a defined background tile, the + rectangle clipped by any children is filled with this tile. If + the window has background None, the contents of the window are + not changed. In either case, if exposures is True, one or more + Expose events are generated for regions of the rectangle that + are either visible or are being retained in a backing store. If + you specify a window whose class is InputOnly, a BadMatch error + results. + + XClearArea can generate BadMatch, BadValue, and BadWindow + errors. + + To clear the entire area in a given window, use XClearWindow. + + XClearWindow(Display *display, Window w); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + The XClearWindow function clears the entire area in the + specified window and is equivalent to XClearArea (display, w, + 0, 0, 0, 0, False). If the window has a defined background + tile, the rectangle is tiled with a plane-mask of all ones and + GXcopy function. If the window has background None, the + contents of the window are not changed. If you specify a window + whose class is InputOnly, a BadMatch error results. + + XClearWindow can generate BadMatch and BadWindow errors. + +Copying Areas + + Xlib provides functions that you can use to copy an area or a + bit plane. + + To copy an area between drawables of the same root and depth, + use XCopyArea. + + XCopyArea(Display *display, Drawable src, Drawable dest, GC gc, + int src_x, int src_y, unsigned int width, unsigned int height, + int dest_x, int dest_y); + + display + + Specifies the connection to the X server. + + src + + dest + + Specify the source and destination rectangles to be combined. + + gc + + Specifies the GC. + + src_x + + src_y + + Specify the x and y coordinates, which are relative to the + origin of the source rectangle and specify its upper-left + corner. + + width + + height + + Specify the width and height, which are the dimensions of both + the source and destination rectangles. + + dest_x + + dest_y + + Specify the x and y coordinates, which are relative to the + origin of the destination rectangle and specify its upper-left + corner. + + The XCopyArea function combines the specified rectangle of src + with the specified rectangle of dest. The drawables must have + the same root and depth, or a BadMatch error results. + + If regions of the source rectangle are obscured and have not + been retained in backing store or if regions outside the + boundaries of the source drawable are specified, those regions + are not copied. Instead, the following occurs on all + corresponding destination regions that are either visible or + are retained in backing store. If the destination is a window + with a background other than None, corresponding regions of the + destination are tiled with that background (with plane-mask of + all ones and GXcopy function). Regardless of tiling or whether + the destination is a window or a pixmap, if graphics-exposures + is True, then GraphicsExpose events for all corresponding + destination regions are generated. If graphics-exposures is + True but no GraphicsExpose events are generated, a NoExpose + event is generated. Note that by default graphics-exposures is + True in new GCs. + + This function uses these GC components: function, plane-mask, + subwindow-mode, graphics-exposures, clip-x-origin, + clip-y-origin, and clip-mask. + + XCopyArea can generate BadDrawable, BadGC, and BadMatch errors. + + To copy a single bit plane of a given drawable, use XCopyPlane. + + XCopyPlane(Display *display, Drawable src, Drawable dest, GC + gc, int src_x, int src_y, unsigned int width, unsigned int + height, int dest_x, int dest_y, unsigned long plane); + + display + + Specifies the connection to the X server. + + src + + dest + + Specify the source and destination rectangles to be combined. + + gc + + Specifies the GC. + + src_x + + src_y + + Specify the x and y coordinates, which are relative to the + origin of the source rectangle and specify its upper-left + corner. + + width + + height + + Specify the width and height, which are the dimensions of both + the source and destination rectangles. + + dest_x + + dest_y + + Specify the x and y coordinates, which are relative to the + origin of the destination rectangle and specify its upper-left + corner. + + plane + + Specifies the bit plane. You must set exactly one bit to 1. + + The XCopyPlane function uses a single bit plane of the + specified source rectangle combined with the specified GC to + modify the specified rectangle of dest. The drawables must have + the same root but need not have the same depth. If the + drawables do not have the same root, a BadMatch error results. + If plane does not have exactly one bit set to 1 and the value + of plane is not less than %2 sup n%, where n is the depth of + src, a BadValue error results. + + Effectively, XCopyPlane forms a pixmap of the same depth as the + rectangle of dest and with a size specified by the source + region. It uses the foreground/background pixels in the GC + (foreground everywhere the bit plane in src contains a bit set + to 1, background everywhere the bit plane in src contains a bit + set to 0) and the equivalent of a CopyArea protocol request is + performed with all the same exposure semantics. This can also + be thought of as using the specified region of the source bit + plane as a stipple with a fill-style of FillOpaqueStippled for + filling a rectangular area of the destination. + + This function uses these GC components: function, plane-mask, + foreground, background, subwindow-mode, graphics-exposures, + clip-x-origin, clip-y-origin, and clip-mask. + + XCopyPlane can generate BadDrawable, BadGC, BadMatch, and + BadValue errors. + +Drawing Points, Lines, Rectangles, and Arcs + + Xlib provides functions that you can use to draw: + * A single point or multiple points + * A single line or multiple lines + * A single rectangle or multiple rectangles + * A single arc or multiple arcs + + Some of the functions described in the following sections use + these structures: + + + +typedef struct { + short x1, y1, x2, y2; +} XSegment; + + + +typedef struct { + short x, y; +} XPoint; + + + +typedef struct { + short x, y; + unsigned short width, height; +} XRectangle; + + + +typedef struct { + short x, y; + unsigned short width, height; + short angle1, angle2; /* Degrees * 64 */ +} XArc; + + All x and y members are signed integers. The width and height + members are 16-bit unsigned integers. You should be careful not + to generate coordinates and sizes out of the 16-bit ranges, + because the protocol only has 16-bit fields for these values. + +Drawing Single and Multiple Points + + To draw a single point in a given drawable, use XDrawPoint. + + XDrawPoint(Display *display, Drawable d, GC gc, int x, int y); + + display + + Specifies the connection to the X server. + + d + + Specifies the drawable. + + gc + + Specifies the GC. + + x + + y + + Specify the x and y coordinates where you want the point drawn. + + To draw multiple points in a given drawable, use XDrawPoints. + + XDrawPoints(Display *display, Drawable d, GC gc, XPoint + *points, int npoints, int mode); + + display + + Specifies the connection to the X server. + + d + + Specifies the drawable. + + gc + + Specifies the GC. + + points + + Specifies an array of points. + + npoints + + Specifies the number of points in the array. + + mode + + Specifies the coordinate mode. You can pass CoordModeOrigin or + CoordModePrevious. + + The XDrawPoint function uses the foreground pixel and function + components of the GC to draw a single point into the specified + drawable; XDrawPoints draws multiple points this way. + CoordModeOrigin treats all coordinates as relative to the + origin, and CoordModePrevious treats all coordinates after the + first as relative to the previous point. XDrawPoints draws the + points in the order listed in the array. + + Both functions use these GC components: function, plane-mask, + foreground, subwindow-mode, clip-x-origin, clip-y-origin, and + clip-mask. + + XDrawPoint can generate BadDrawable, BadGC, and BadMatch + errors. XDrawPoints can generate BadDrawable, BadGC, BadMatch, + and BadValue errors. + +Drawing Single and Multiple Lines + + To draw a single line between two points in a given drawable, + use XDrawLine. + + XDrawLine(Display *display, Drawable d, GC gc, int x1, int y1, + int x2, int y2); + + display + + Specifies the connection to the X server. + + d + + Specifies the drawable. + + gc + + Specifies the GC. + + x1 + + y1 + + x2 + + y2 + + Specify the points (x1, y1) and (x2, y2) to be connected. + + To draw multiple lines in a given drawable, use XDrawLines. + + XDrawLines(Display *display, Drawable d, GC gc, XPoint *points, + int npoints, int mode); + + display + + Specifies the connection to the X server. + + d + + Specifies the drawable. + + gc + + Specifies the GC. + + points + + Specifies an array of points. + + npoints + + Specifies the number of points in the array. + + mode + + Specifies the coordinate mode. You can pass CoordModeOrigin or + CoordModePrevious. + + To draw multiple, unconnected lines in a given drawable, use + XDrawSegments. + + XDrawSegments(Display *display, Drawable d, GC gc, XSegment + *segments, int nsegments); + + display + + Specifies the connection to the X server. + + d + + Specifies the drawable. + + gc + + Specifies the GC. + + segments + + Specifies an array of segments. + + nsegments + + Specifies the number of segments in the array. + + The XDrawLine function uses the components of the specified GC + to draw a line between the specified set of points (x1, y1) and + (x2, y2). It does not perform joining at coincident endpoints. + For any given line, XDrawLine does not draw a pixel more than + once. If lines intersect, the intersecting pixels are drawn + multiple times. + + The XDrawLines function uses the components of the specified GC + to draw npoints-1 lines between each pair of points (point[i], + point[i+1]) in the array of XPoint structures. It draws the + lines in the order listed in the array. The lines join + correctly at all intermediate points, and if the first and last + points coincide, the first and last lines also join correctly. + For any given line, XDrawLines does not draw a pixel more than + once. If thin (zero line-width) lines intersect, the + intersecting pixels are drawn multiple times. If wide lines + intersect, the intersecting pixels are drawn only once, as + though the entire PolyLine protocol request were a single, + filled shape. CoordModeOrigin treats all coordinates as + relative to the origin, and CoordModePrevious treats all + coordinates after the first as relative to the previous point. + + The XDrawSegments function draws multiple, unconnected lines. + For each segment, XDrawSegments draws a line between (x1, y1) + and (x2, y2). It draws the lines in the order listed in the + array of XSegment structures and does not perform joining at + coincident endpoints. For any given line, XDrawSegments does + not draw a pixel more than once. If lines intersect, the + intersecting pixels are drawn multiple times. + + All three functions use these GC components: function, + plane-mask, line-width, line-style, cap-style, fill-style, + subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. + The XDrawLines function also uses the join-style GC component. + All three functions also use these GC mode-dependent + components: foreground, background, tile, stipple, + tile-stipple-x-origin, tile-stipple-y-origin, dash-offset, and + dash-list. + + XDrawLine, XDrawLines, and XDrawSegments can generate + BadDrawable, BadGC, and BadMatch errors. XDrawLines also can + generate BadValue errors. + +Drawing Single and Multiple Rectangles + + To draw the outline of a single rectangle in a given drawable, + use XDrawRectangle. + + XDrawRectangle(Display *display, Drawable d, GC gc, int x, int + y, unsigned int width, unsigned int height); + + display + + Specifies the connection to the X server. + + d + + Specifies the drawable. + + gc + + Specifies the GC. + + x + + y + + Specify the x and y coordinates, which specify the upper-left + corner of the rectangle. + + width + + height + + Specify the width and height, which specify the dimensions of + the rectangle. + + To draw the outline of multiple rectangles in a given drawable, + use XDrawRectangles. + + XDrawRectangles(Display *display, Drawable d, GC gc, XRectangle + rectangles[], int nrectangles); + + display + + Specifies the connection to the X server. + + d + + Specifies the drawable. + + gc + + Specifies the GC. + + rectangles + + Specifies an array of rectangles. + + nrectangles + + Specifies the number of rectangles in the array. + + The XDrawRectangle and XDrawRectangles functions draw the + outlines of the specified rectangle or rectangles as if a + five-point PolyLine protocol request were specified for each + rectangle: + * [x,y] [x+width,y] [x+width,y+height] [x,y+height] [x,y] + + For the specified rectangle or rectangles, these functions do + not draw a pixel more than once. XDrawRectangles draws the + rectangles in the order listed in the array. If rectangles + intersect, the intersecting pixels are drawn multiple times. + + Both functions use these GC components: function, plane-mask, + line-width, line-style, cap-style, join-style, fill-style, + subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. + They also use these GC mode-dependent components: foreground, + background, tile, stipple, tile-stipple-x-origin, + tile-stipple-y-origin, dash-offset, and dash-list. + + XDrawRectangle and XDrawRectangles can generate BadDrawable, + BadGC, and BadMatch errors. + +Drawing Single and Multiple Arcs + + To draw a single arc in a given drawable, use XDrawArc. + + XDrawArc(Display *display, Drawable d, GC gc, int x, int y, + unsigned int width, unsigned int height, int angle1, int + angle2); + + display + + Specifies the connection to the X server. + + d + + Specifies the drawable. + + gc + + Specifies the GC. + + x + + y + + Specify the x and y coordinates, which are relative to the + origin of the drawable and specify the upper-left corner of the + bounding rectangle. + + width + + height + + Specify the width and height, which are the major and minor + axes of the arc. + + angle1 + + Specifies the start of the arc relative to the three-o'clock + position from the center, in units of degrees * 64. + + angle2 + + Specifies the path and extent of the arc relative to the start + of the arc, in units of degrees * 64. + + To draw multiple arcs in a given drawable, use XDrawArcs. + + XDrawArcs(Display *display, Drawable d, GC gc, XArc *arcs, int + narcs); + + display + + Specifies the connection to the X server. + + d + + Specifies the drawable. + + gc + + Specifies the GC. + + arcs + + Specifies an array of arcs. + + narcs + + Specifies the number of arcs in the array. + + delim %% XDrawArc draws a single circular or elliptical arc, + and XDrawArcs draws multiple circular or elliptical arcs. Each + arc is specified by a rectangle and two angles. The center of + the circle or ellipse is the center of the rectangle, and the + major and minor axes are specified by the width and height. + Positive angles indicate counterclockwise motion, and negative + angles indicate clockwise motion. If the magnitude of angle2 is + greater than 360 degrees, XDrawArc or XDrawArcs truncates it to + 360 degrees. + + For an arc specified as %[ ~x, ~y, ~width , ~height, ~angle1, + ~angle2 ]%, the origin of the major and minor axes is at % [ x + +^ {width over 2} , ~y +^ {height over 2} ]%, and the + infinitely thin path describing the entire circle or ellipse + intersects the horizontal axis at % [ x, ~y +^ {height over 2} + ]% and % [ x +^ width , ~y +^ { height over 2 }] % and + intersects the vertical axis at % [ x +^ { width over 2 } , ~y + ]% and % [ x +^ { width over 2 }, ~y +^ height ]%. These + coordinates can be fractional and so are not truncated to + discrete coordinates. The path should be defined by the ideal + mathematical path. For a wide line with line-width lw, the + bounding outlines for filling are given by the two infinitely + thin paths consisting of all points whose perpendicular + distance from the path of the circle/ellipse is equal to lw/2 + (which may be a fractional value). The cap-style and join-style + are applied the same as for a line corresponding to the tangent + of the circle/ellipse at the endpoint. + + For an arc specified as % [ ~x, ~y, ~width, ~height, ~angle1, + ~angle2 ]%, the angles must be specified in the effectively + skewed coordinate system of the ellipse (for a circle, the + angles and coordinate systems are identical). The relationship + between these angles and angles expressed in the normal + coordinate system of the screen (as measured with a protractor) + is as follows: + +% roman "skewed-angle" ~ = ~ atan left ( tan ( roman "normal-angle" ) + * width over height right ) +^ adjust% + + The skewed-angle and normal-angle are expressed in radians + (rather than in degrees scaled by 64) in the range % [ 0 , ~2 + pi ]% and where atan returns a value in the range % [ - pi over + 2 , ~pi over 2 ] % and adjust is: + + + +%0% for normal-angle in the range % [ 0 , ~pi over 2 ]% +%pi% for normal-angle in the range % [ pi over 2 , ~{3 pi} over 2 ] +% +%2 pi% for normal-angle in the range % [ {3 pi} over 2 , ~2 pi ]% + + For any given arc, XDrawArc and XDrawArcs do not draw a pixel + more than once. If two arcs join correctly and if the + line-width is greater than zero and the arcs intersect, + XDrawArc and XDrawArcs do not draw a pixel more than once. + Otherwise, the intersecting pixels of intersecting arcs are + drawn multiple times. Specifying an arc with one endpoint and a + clockwise extent draws the same pixels as specifying the other + endpoint and an equivalent counterclockwise extent, except as + it affects joins. + + If the last point in one arc coincides with the first point in + the following arc, the two arcs will join correctly. If the + first point in the first arc coincides with the last point in + the last arc, the two arcs will join correctly. By specifying + one axis to be zero, a horizontal or vertical line can be + drawn. Angles are computed based solely on the coordinate + system and ignore the aspect ratio. + + Both functions use these GC components: function, plane-mask, + line-width, line-style, cap-style, join-style, fill-style, + subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. + They also use these GC mode-dependent components: foreground, + background, tile, stipple, tile-stipple-x-origin, + tile-stipple-y-origin, dash-offset, and dash-list. + + XDrawArc and XDrawArcs can generate BadDrawable, BadGC, and + BadMatch errors. + +Filling Areas + + Xlib provides functions that you can use to fill: + * A single rectangle or multiple rectangles + * A single polygon + * A single arc or multiple arcs + +Filling Single and Multiple Rectangles + + To fill a single rectangular area in a given drawable, use + XFillRectangle. + + XFillRectangle(Display *display, Drawable d, GC gc, int x, int + y, unsigned int width, unsigned int height); + + display + + Specifies the connection to the X server. + + d + + Specifies the drawable. + + gc + + Specifies the GC. + + x + + y + + Specify the x and y coordinates, which are relative to the + origin of the drawable and specify the upper-left corner of the + rectangle. + + width + + height + + Specify the width and height, which are the dimensions of the + rectangle to be filled. + + To fill multiple rectangular areas in a given drawable, use + XFillRectangles. + + XFillRectangles(Display *display, Drawable d, GC gc, XRectangle + *rectangles, int nrectangles); + + display + + Specifies the connection to the X server. + + d + + Specifies the drawable. + + gc + + Specifies the GC. + + rectangles + + Specifies an array of rectangles. + + nrectangles + + Specifies the number of rectangles in the array. + + The XFillRectangle and XFillRectangles functions fill the + specified rectangle or rectangles as if a four-point + FillPolygon protocol request were specified for each rectangle: + +[x,y] [x+width,y] [x+width,y+height] [x,y+height] + + Each function uses the x and y coordinates, width and height + dimensions, and GC you specify. + + XFillRectangles fills the rectangles in the order listed in the + array. For any given rectangle, XFillRectangle and + XFillRectangles do not draw a pixel more than once. If + rectangles intersect, the intersecting pixels are drawn + multiple times. + + Both functions use these GC components: function, plane-mask, + fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and + clip-mask. They also use these GC mode-dependent components: + foreground, background, tile, stipple, tile-stipple-x-origin, + and tile-stipple-y-origin. + + XFillRectangle and XFillRectangles can generate BadDrawable, + BadGC, and BadMatch errors. + +Filling a Single Polygon + + To fill a polygon area in a given drawable, use XFillPolygon. + + XFillPolygon(Display *display, Drawable d, GC gc, XPoint + *points, int npoints, int shape, int mode); + + display + + Specifies the connection to the X server. + + d + + Specifies the drawable. + + gc + + Specifies the GC. + + points + + Specifies an array of points. + + npoints + + Specifies the number of points in the array. + + shape + + Specifies a shape that helps the server to improve performance. + You can pass Complex, Convex, or Nonconvex. + + mode + + Specifies the coordinate mode. You can pass CoordModeOrigin or + CoordModePrevious. + + XFillPolygon fills the region closed by the specified path. The + path is closed automatically if the last point in the list does + not coincide with the first point. XFillPolygon does not draw a + pixel of the region more than once. CoordModeOrigin treats all + coordinates as relative to the origin, and CoordModePrevious + treats all coordinates after the first as relative to the + previous point. + + Depending on the specified shape, the following occurs: + * If shape is Complex, the path may self-intersect. Note that + contiguous coincident points in the path are not treated as + self-intersection. + * If shape is Convex, for every pair of points inside the + polygon, the line segment connecting them does not + intersect the path. If known by the client, specifying + Convex can improve performance. If you specify Convex for a + path that is not convex, the graphics results are + undefined. + * If shape is Nonconvex, the path does not self-intersect, + but the shape is not wholly convex. If known by the client, + specifying Nonconvex instead of Complex may improve + performance. If you specify Nonconvex for a + self-intersecting path, the graphics results are undefined. + + The fill-rule of the GC controls the filling behavior of + self-intersecting polygons. + + This function uses these GC components: function, plane-mask, + fill-style, fill-rule, subwindow-mode, clip-x-origin, + clip-y-origin, and clip-mask. It also uses these GC + mode-dependent components: foreground, background, tile, + stipple, tile-stipple-x-origin, and tile-stipple-y-origin. + + XFillPolygon can generate BadDrawable, BadGC, BadMatch, and + BadValue errors. + +Filling Single and Multiple Arcs + + To fill a single arc in a given drawable, use XFillArc. + + XFillArc(Display *display, Drawable d, GC gc, int x, int y, + unsigned int width, unsigned int height, int angle1, int + angle2); + + display + + Specifies the connection to the X server. + + d + + Specifies the drawable. + + gc + + Specifies the GC. + + x + + y + + Specify the x and y coordinates, which are relative to the + origin of the drawable and specify the upper-left corner of the + bounding rectangle. + + width + + height + + Specify the width and height, which are the major and minor + axes of the arc. + + angle1 + + Specifies the start of the arc relative to the three-o'clock + position from the center, in units of degrees * 64. + + angle2 + + Specifies the path and extent of the arc relative to the start + of the arc, in units of degrees * 64. + + To fill multiple arcs in a given drawable, use XFillArcs. + + XFillArcs(Display *display, Drawable d, GC gc, XArc *arcs, int + narcs); + + display + + Specifies the connection to the X server. + + d + + Specifies the drawable. + + gc + + Specifies the GC. + + arcs + + Specifies an array of arcs. + + narcs + + Specifies the number of arcs in the array. + + For each arc, XFillArc or XFillArcs fills the region closed by + the infinitely thin path described by the specified arc and, + depending on the arc-mode specified in the GC, one or two line + segments. For ArcChord, the single line segment joining the + endpoints of the arc is used. For ArcPieSlice, the two line + segments joining the endpoints of the arc with the center point + are used. XFillArcs fills the arcs in the order listed in the + array. For any given arc, XFillArc and XFillArcs do not draw a + pixel more than once. If regions intersect, the intersecting + pixels are drawn multiple times. + + Both functions use these GC components: function, plane-mask, + fill-style, arc-mode, subwindow-mode, clip-x-origin, + clip-y-origin, and clip-mask. They also use these GC + mode-dependent components: foreground, background, tile, + stipple, tile-stipple-x-origin, and tile-stipple-y-origin. + + XFillArc and XFillArcs can generate BadDrawable, BadGC, and + BadMatch errors. + +Font Metrics + + A font is a graphical description of a set of characters that + are used to increase efficiency whenever a set of small, + similar sized patterns are repeatedly used. + + This section discusses how to: + * Load and free fonts + * Obtain and free font names + * Compute character string sizes + * Compute logical extents + * Query character string sizes + + The X server loads fonts whenever a program requests a new + font. The server can cache fonts for quick lookup. Fonts are + global across all screens in a server. Several levels are + possible when dealing with fonts. Most applications simply use + XLoadQueryFont to load a font and query the font metrics. + + Characters in fonts are regarded as masks. Except for image + text requests, the only pixels modified are those in which bits + are set to 1 in the character. This means that it makes sense + to draw text using stipples or tiles (for example, many menus + gray-out unusable entries). + + The XFontStruct structure contains all of the information for + the font and consists of the font-specific information as well + as a pointer to an array of XCharStruct structures for the + characters contained in the font. The XFontStruct, XFontProp, + and XCharStruct structures contain: + + + +typedef struct { + short lbearing; /* origin to left edge of raster */ + short rbearing; /* origin to right edge of raster */ + short width; /* advance to next char's origin */ + short ascent; /* baseline to top edge of raster */ + short descent; /* baseline to bottom edge of raster +*/ + unsigned short attributes; /* per char flags (not predefined) */ +} XCharStruct; + + + +typedef struct { + Atom name; + unsigned long card32; +} XFontProp; + + + +typedef struct { /* normal 16 bit characters are two bytes */ + unsigned char byte1; + unsigned char byte2; +} XChar2b; + + + +typedef struct { + XExtData *ext_data; /* hook for extension to hang dat +a */ + Font fid; /* Font id for this font */ + unsigned direction; /* hint about the direction font +is painted */ + unsigned min_char_or_byte2; /* first character */ + unsigned max_char_or_byte2; /* last character */ + unsigned min_byte1; /* first row that exists */ + unsigned max_byte1; /* last row that exists */ + Bool all_chars_exist; /* flag if all characters have no +nzero size */ + unsigned default_char; /* char to print for undefined ch +aracter */ + int n_properties; /* how many properties there are +*/ + XFontProp *properties; /* pointer to array of additional + properties */ + XCharStruct min_bounds; /* minimum bounds over all existi +ng char */ + XCharStruct max_bounds; /* maximum bounds over all existi +ng char */ + XCharStruct *per_char; /* first_char to last_char inform +ation */ + int ascent; /* logical extent above baseline +for spacing */ + int descent; /* logical descent below baseline + for spacing */ +} XFontStruct; + + X supports single byte/character, two bytes/character matrix, + and 16-bit character text operations. Note that any of these + forms can be used with a font, but a single byte/character text + request can only specify a single byte (that is, the first row + of a 2-byte font). You should view 2-byte fonts as a + two-dimensional matrix of defined characters: byte1 specifies + the range of defined rows and byte2 defines the range of + defined columns of the font. Single byte/character fonts have + one row defined, and the byte2 range specified in the structure + defines a range of characters. + + The bounding box of a character is defined by the XCharStruct + of that character. When characters are absent from a font, the + default_char is used. When fonts have all characters of the + same size, only the information in the XFontStruct min and max + bounds are used. + + The members of the XFontStruct have the following semantics: + * The direction member can be either FontLeftToRight or + FontRightToLeft. It is just a hint as to whether most + XCharStruct elements have a positive (FontLeftToRight) or a + negative (FontRightToLeft) character width metric. The core + protocol defines no support for vertical text. + * If the min_byte1 and max_byte1 members are both zero, + min_char_or_byte2 specifies the linear character index + corresponding to the first element of the per_char array, + and max_char_or_byte2 specifies the linear character index + of the last element. + * If either min_byte1 or max_byte1 are nonzero, both + min_char_or_byte2 and max_char_or_byte2 are less than 256, + and the 2-byte character index values corresponding to the + per_char array element N (counting from 0) are: + * byte1 = N/D + min_byte1 byte2 = N\\D + min_char_or_byte2 + * where: + * D = max_char_or_byte2 - min_char_or_byte2 + 1 / = integer + division \\ = integer modulus + * If the per_char pointer is NULL, all glyphs between the + first and last character indexes inclusive have the same + information, as given by both min_bounds and max_bounds. + * If all_chars_exist is True, all characters in the per_char + array have nonzero bounding boxes. + * The default_char member specifies the character that will + be used when an undefined or nonexistent character is + printed. The default_char is a 16-bit character (not a + 2-byte character). For a font using 2-byte matrix format, + the default_char has byte1 in the most-significant byte and + byte2 in the least significant byte. If the default_char + itself specifies an undefined or nonexistent character, no + printing is performed for an undefined or nonexistent + character. + * The min_bounds and max_bounds members contain the most + extreme values of each individual XCharStruct component + over all elements of this array (and ignore nonexistent + characters). The bounding box of the font (the smallest + rectangle enclosing the shape obtained by superimposing all + of the characters at the same origin [x,y]) has its + upper-left coordinate at: + [x + min_bounds.lbearing, y - max_bounds.ascent] + + * Its width is: + max_bounds.rbearing - min_bounds.lbearing + + * Its height is: + max_bounds.ascent + max_bounds.descent + + * The ascent member is the logical extent of the font above + the baseline that is used for determining line spacing. + Specific characters may extend beyond this. + * The descent member is the logical extent of the font at or + below the baseline that is used for determining line + spacing. Specific characters may extend beyond this. + * If the baseline is at Y-coordinate y, the logical extent of + the font is inclusive between the Y-coordinate values (y - + font.ascent) and (y + font.descent - 1). Typically, the + minimum interline spacing between rows of text is given by + ascent + descent. + + For a character origin at [x,y], the bounding box of a + character (that is, the smallest rectangle that encloses the + character's shape) described in terms of XCharStruct components + is a rectangle with its upper-left corner at: + +[x + lbearing, y - ascent] + + Its width is: + +rbearing - lbearing + + Its height is: + +ascent + descent + + The origin for the next character is defined to be: + +[x + width, y] + + The lbearing member defines the extent of the left edge of the + character ink from the origin. The rbearing member defines the + extent of the right edge of the character ink from the origin. + The ascent member defines the extent of the top edge of the + character ink from the origin. The descent member defines the + extent of the bottom edge of the character ink from the origin. + The width member defines the logical width of the character. + + Note that the baseline (the y position of the character origin) + is logically viewed as being the scanline just below + nondescending characters. When descent is zero, only pixels + with Y-coordinates less than y are drawn, and the origin is + logically viewed as being coincident with the left edge of a + nonkerned character. When lbearing is zero, no pixels with + X-coordinate less than x are drawn. Any of the XCharStruct + metric members could be negative. If the width is negative, the + next character will be placed to the left of the current + origin. + + The X protocol does not define the interpretation of the + attributes member in the XCharStruct structure. A nonexistent + character is represented with all members of its XCharStruct + set to zero. + + A font is not guaranteed to have any properties. The + interpretation of the property value (for example, long or + unsigned long) must be derived from a priori knowledge of the + property. A basic set of font properties is specified in the X + Consortium standard X Logical Font Description Conventions. + +Loading and Freeing Fonts + + Xlib provides functions that you can use to load fonts, get + font information, unload fonts, and free font information. A + few font functions use a GContext resource ID or a font ID + interchangeably. + + To load a given font, use XLoadFont. + + Font XLoadFont(Display *display, char *name); + + display + + Specifies the connection to the X server. + + name + + Specifies the name of the font, which is a null-terminated + string. + + The XLoadFont function loads the specified font and returns its + associated font ID. If the font name is not in the Host + Portable Character Encoding, the result is + implementation-dependent. Use of uppercase or lowercase does + not matter. When the characters ``?'' and ``*'' are used in a + font name, a pattern match is performed and any matching font + is used. In the pattern, the ``?'' character will match any + single character, and the ``*'' character will match any number + of characters. A structured format for font names is specified + in the X Consortium standard X Logical Font Description + Conventions. If XLoadFont was unsuccessful at loading the + specified font, a BadName error results. Fonts are not + associated with a particular screen and can be stored as a + component of any GC. When the font is no longer needed, call + XUnloadFont. + + XLoadFont can generate BadAlloc and BadName errors. + + To return information about an available font, use XQueryFont. + + XFontStruct *XQueryFont(Display *display, XID font_ID); + + display + + Specifies the connection to the X server. + + font_ID + + Specifies the font ID or the GContext ID. + + The XQueryFont function returns a pointer to the XFontStruct + structure, which contains information associated with the font. + You can query a font or the font stored in a GC. The font ID + stored in the XFontStruct structure will be the GContext ID, + and you need to be careful when using this ID in other + functions (see XGContextFromGC). If the font does not exist, + XQueryFont returns NULL. To free this data, use XFreeFontInfo. + + To perform a XLoadFont and XQueryFont in a single operation, + use XLoadQueryFont. + + XFontStruct *XLoadQueryFont(Display *display, char *name); + + display + + Specifies the connection to the X server. + + name + + Specifies the name of the font, which is a null-terminated + string. + + The XLoadQueryFont function provides the most common way for + accessing a font. XLoadQueryFont both opens (loads) the + specified font and returns a pointer to the appropriate + XFontStruct structure. If the font name is not in the Host + Portable Character Encoding, the result is + implementation-dependent. If the font does not exist, + XLoadQueryFont returns NULL. + + XLoadQueryFont can generate a BadAlloc error. + + To unload the font and free the storage used by the font + structure that was allocated by XQueryFont or XLoadQueryFont, + use XFreeFont. + + XFreeFont(Display *display, XFontStruct *font_struct); + + display + + Specifies the connection to the X server. + + font_struct + + Specifies the storage associated with the font. + + The XFreeFont function deletes the association between the font + resource ID and the specified font and frees the XFontStruct + structure. The font itself will be freed when no other resource + references it. The data and the font should not be referenced + again. + + XFreeFont can generate a BadFont error. + + To return a given font property, use XGetFontProperty. + + Bool XGetFontProperty(XFontStruct *font_struct, Atom atom, + unsigned long *value_return); + + font_struct + + Specifies the storage associated with the font. + + atom + + Specifies the atom for the property name you want returned. + + value_return + + Returns the value of the font property. + + Given the atom for that property, the XGetFontProperty function + returns the value of the specified font property. + XGetFontProperty also returns False if the property was not + defined or True if it was defined. A set of predefined atoms + exists for font properties, which can be found in + . This set contains the standard properties + associated with a font. Although it is not guaranteed, it is + likely that the predefined font properties will be present. + + To unload a font that was loaded by XLoadFont, use XUnloadFont. + + XUnloadFont(Display *display, Font font); + + display + + Specifies the connection to the X server. + + font + + Specifies the font. + + The XUnloadFont function deletes the association between the + font resource ID and the specified font. The font itself will + be freed when no other resource references it. The font should + not be referenced again. + + XUnloadFont can generate a BadFont error. + +Obtaining and Freeing Font Names and Information + + You obtain font names and information by matching a wildcard + specification when querying a font type for a list of available + sizes and so on. + + To return a list of the available font names, use XListFonts. + + char **XListFonts(Display *display, char *pattern, int + maxnames, int *actual_count_return); + + display + + Specifies the connection to the X server. + + pattern + + Specifies the null-terminated pattern string that can contain + wildcard characters. + + maxnames + + Specifies the maximum number of names to be returned. + + actual_count_return + + Returns the actual number of font names. + + The XListFonts function returns an array of available font + names (as controlled by the font search path; see XSetFontPath) + that match the string you passed to the pattern argument. The + pattern string can contain any characters, but each asterisk + (*) is a wildcard for any number of characters, and each + question mark (?) is a wildcard for a single character. If the + pattern string is not in the Host Portable Character Encoding, + the result is implementation-dependent. Use of uppercase or + lowercase does not matter. Each returned string is + null-terminated. If the data returned by the server is in the + Latin Portable Character Encoding, then the returned strings + are in the Host Portable Character Encoding. Otherwise, the + result is implementation-dependent. If there are no matching + font names, XListFonts returns NULL. The client should call + XFreeFontNames when finished with the result to free the + memory. + + To free a font name array, use XFreeFontNames. + + XFreeFontNames(char *list[]); + + list + + Specifies the array of strings you want to free. + + The XFreeFontNames function frees the array and strings + returned by XListFonts or XListFontsWithInfo. + + To obtain the names and information about available fonts, use + XListFontsWithInfo. + + char **XListFontsWithInfo(Display *display, char *pattern, int + maxnames, int *count_return, XFontStruct **info_return); + + display + + Specifies the connection to the X server. + + pattern + + Specifies the null-terminated pattern string that can contain + wildcard characters. + + maxnames + + Specifies the maximum number of names to be returned. + + count_return + + Returns the actual number of matched font names. + + info_return + + Returns the font information. + + The XListFontsWithInfo function returns a list of font names + that match the specified pattern and their associated font + information. The list of names is limited to size specified by + maxnames. The information returned for each font is identical + to what XLoadQueryFont would return except that the + per-character metrics are not returned. The pattern string can + contain any characters, but each asterisk (*) is a wildcard for + any number of characters, and each question mark (?) is a + wildcard for a single character. If the pattern string is not + in the Host Portable Character Encoding, the result is + implementation-dependent. Use of uppercase or lowercase does + not matter. Each returned string is null-terminated. If the + data returned by the server is in the Latin Portable Character + Encoding, then the returned strings are in the Host Portable + Character Encoding. Otherwise, the result is + implementation-dependent. If there are no matching font names, + XListFontsWithInfo returns NULL. + + To free only the allocated name array, the client should call + XFreeFontNames. To free both the name array and the font + information array or to free just the font information array, + the client should call XFreeFontInfo. + + To free font structures and font names, use XFreeFontInfo. + + XFreeFontInfo(char **names, XFontStruct *free_info, int + actual_count); + + names + + Specifies the list of font names. + + free_info + + Specifies the font information. + + actual_count + + Specifies the actual number of font names. + + The XFreeFontInfo function frees a font structure or an array + of font structures and optionally an array of font names. If + NULL is passed for names, no font names are freed. If a font + structure for an open font (returned by XLoadQueryFont) is + passed, the structure is freed, but the font is not closed; use + XUnloadFont to close the font. + +Computing Character String Sizes + + Xlib provides functions that you can use to compute the width, + the logical extents, and the server information about 8-bit and + 2-byte text strings. The width is computed by adding the + character widths of all the characters. It does not matter if + the font is an 8-bit or 2-byte font. These functions return the + sum of the character metrics in pixels. + + To determine the width of an 8-bit character string, use + XTextWidth. + + int XTextWidth(XFontStruct *font_struct, char *string, int + count); + + font_struct + + Specifies the font used for the width computation. + + string + + Specifies the character string. + + count + + Specifies the character count in the specified string. + + To determine the width of a 2-byte character string, use + XTextWidth16. + + int XTextWidth16(XFontStruct *font_struct, XChar2b *string, int + count); + + font_struct + + Specifies the font used for the width computation. + + string + + Specifies the character string. + + count + + Specifies the character count in the specified string. + +Computing Logical Extents + + To compute the bounding box of an 8-bit character string in a + given font, use XTextExtents. + + XTextExtents(XFontStruct *font_struct, char *string, int + nchars, int *direction_return, int *font_ascent_return, int + *font_descent_return, XCharStruct *overall_return); + + font_struct + + Specifies the XFontStruct structure. + + string + + Specifies the character string. + + nchars + + Specifies the number of characters in the character string. + + direction_return + + Returns the value of the direction hint (FontLeftToRight or + FontRightToLeft). + + font_ascent_return + + Returns the font ascent. + + font_descent_return + + Returns the font descent. + + overall_return + + Returns the overall size in the specified XCharStruct + structure. + + To compute the bounding box of a 2-byte character string in a + given font, use XTextExtents16. + + XTextExtents16(XFontStruct *font_struct, XChar2b *string, int + nchars, int *direction_return, int *font_ascent_return, int + *font_descent_return, XCharStruct *overall_return); + + font_struct + + Specifies the XFontStruct structure. + + string + + Specifies the character string. + + nchars + + Specifies the number of characters in the character string. + + direction_return + + Returns the value of the direction hint (FontLeftToRight or + FontRightToLeft). + + font_ascent_return + + Returns the font ascent. + + font_descent_return + + Returns the font descent. + + overall_return + + Returns the overall size in the specified XCharStruct + structure. + + The XTextExtents and XTextExtents16 functions perform the size + computation locally and, thereby, avoid the round-trip overhead + of XQueryTextExtents and XQueryTextExtents16. Both functions + return an XCharStruct structure, whose members are set to the + values as follows. + + The ascent member is set to the maximum of the ascent metrics + of all characters in the string. The descent member is set to + the maximum of the descent metrics. The width member is set to + the sum of the character-width metrics of all characters in the + string. For each character in the string, let W be the sum of + the character-width metrics of all characters preceding it in + the string. Let L be the left-side-bearing metric of the + character plus W. Let R be the right-side-bearing metric of the + character plus W. The lbearing member is set to the minimum L + of all characters in the string. The rbearing member is set to + the maximum R. + + For fonts defined with linear indexing rather than 2-byte + matrix indexing, each XChar2b structure is interpreted as a + 16-bit number with byte1 as the most significant byte. If the + font has no defined default character, undefined characters in + the string are taken to have all zero metrics. + +Querying Character String Sizes + + To query the server for the bounding box of an 8-bit character + string in a given font, use XQueryTextExtents. + + XQueryTextExtents(Display *display, XID font_ID, char *string, + int nchars, int *direction_return, int *font_ascent_return, int + *font_descent_return, XCharStruct *overall_return); + + display + + Specifies the connection to the X server. + + font_ID + + Specifies either the font ID or the GContext ID that contains + the font. + + string + + Specifies the character string. + + nchars + + Specifies the number of characters in the character string. + + direction_return + + Returns the value of the direction hint (FontLeftToRight or + FontRightToLeft). + + font_ascent_return + + Returns the font ascent. + + font_descent_return + + Returns the font descent. + + overall_return + + Returns the overall size in the specified XCharStruct + structure. + + To query the server for the bounding box of a 2-byte character + string in a given font, use XQueryTextExtents16. + + XQueryTextExtents16(Display *display, XID font_ID, XChar2b + *string, int nchars, int *direction_return, int + *font_ascent_return, int *font_descent_return, XCharStruct + *overall_return); + + display + + Specifies the connection to the X server. + + font_ID + + Specifies either the font ID or the GContext ID that contains + the font. + + string + + Specifies the character string. + + nchars + + Specifies the number of characters in the character string. + + direction_return + + Returns the value of the direction hint (FontLeftToRight or + FontRightToLeft). + + font_ascent_return + + Returns the font ascent. + + font_descent_return + + Returns the font descent. + + overall_return + + Returns the overall size in the specified XCharStruct + structure. + + The XQueryTextExtents and XQueryTextExtents16 functions return + the bounding box of the specified 8-bit and 16-bit character + string in the specified font or the font contained in the + specified GC. These functions query the X server and, + therefore, suffer the round-trip overhead that is avoided by + XTextExtents and XTextExtents16. Both functions return a + XCharStruct structure, whose members are set to the values as + follows. + + The ascent member is set to the maximum of the ascent metrics + of all characters in the string. The descent member is set to + the maximum of the descent metrics. The width member is set to + the sum of the character-width metrics of all characters in the + string. For each character in the string, let W be the sum of + the character-width metrics of all characters preceding it in + the string. Let L be the left-side-bearing metric of the + character plus W. Let R be the right-side-bearing metric of the + character plus W. The lbearing member is set to the minimum L + of all characters in the string. The rbearing member is set to + the maximum R. + + For fonts defined with linear indexing rather than 2-byte + matrix indexing, each XChar2b structure is interpreted as a + 16-bit number with byte1 as the most significant byte. If the + font has no defined default character, undefined characters in + the string are taken to have all zero metrics. + + Characters with all zero metrics are ignored. If the font has + no defined default_char, the undefined characters in the string + are also ignored. + + XQueryTextExtents and XQueryTextExtents16 can generate BadFont + and BadGC errors. + +Drawing Text + + This section discusses how to draw: + * Complex text + * Text characters + * Image text characters + + The fundamental text functions XDrawText and XDrawText16 use + the following structures: + + + +typedef struct { + char *chars; /* pointer to string */ + int nchars; /* number of characters */ + int delta; /* delta between strings */ + Font font; /* Font to print it in, None don't change */ +} XTextItem; + + + +typedef struct { + XChar2b *chars; /* pointer to two-byte characters */ + int nchars; /* number of characters */ + int delta; /* delta between strings */ + Font font; /* font to print it in, None don't change */ +} XTextItem16; + + If the font member is not None, the font is changed before + printing and also is stored in the GC. If an error was + generated during text drawing, the previous items may have been + drawn. The baseline of the characters are drawn starting at the + x and y coordinates that you pass in the text drawing + functions. + + For example, consider the background rectangle drawn by + XDrawImageString. If you want the upper-left corner of the + background rectangle to be at pixel coordinate (x,y), pass the + (x,y + ascent) as the baseline origin coordinates to the text + functions. The ascent is the font ascent, as given in the + XFontStruct structure. If you want the lower-left corner of the + background rectangle to be at pixel coordinate (x,y), pass the + (x,y - descent + 1) as the baseline origin coordinates to the + text functions. The descent is the font descent, as given in + the XFontStruct structure. + +Drawing Complex Text + + To draw 8-bit characters in a given drawable, use XDrawText. + + XDrawText(Display *display, Drawable d, GC gc, int x, int y, + XTextItem *items, int nitems); + + display + + Specifies the connection to the X server. + + d + + Specifies the drawable. + + gc + + Specifies the GC. + + x + + y + + Specify the x and y coordinates, which are relative to the + origin of the specified drawable and define the origin of the + first character. + + items + + Specifies an array of text items. + + nitems + + Specifies the number of text items in the array. + + To draw 2-byte characters in a given drawable, use XDrawText16. + + XDrawText16(Display *display, Drawable d, GC gc, int x, int y, + XTextItem16 *items, int nitems); + + display + + Specifies the connection to the X server. + + d + + Specifies the drawable. + + gc + + Specifies the GC. + + x + + y + + Specify the x and y coordinates, which are relative to the + origin of the specified drawable and define the origin of the + first character. + + items + + Specifies an array of text items. + + nitems + + Specifies the number of text items in the array. + + The XDrawText16 function is similar to XDrawText except that it + uses 2-byte or 16-bit characters. Both functions allow complex + spacing and font shifts between counted strings. + + Each text item is processed in turn. A font member other than + None in an item causes the font to be stored in the GC and used + for subsequent text. A text element delta specifies an + additional change in the position along the x axis before the + string is drawn. The delta is always added to the character + origin and is not dependent on any characteristics of the font. + Each character image, as defined by the font in the GC, is + treated as an additional mask for a fill operation on the + drawable. The drawable is modified only where the font + character has a bit set to 1. If a text item generates a + BadFont error, the previous text items may have been drawn. + + For fonts defined with linear indexing rather than 2-byte + matrix indexing, each XChar2b structure is interpreted as a + 16-bit number with byte1 as the most significant byte. + + Both functions use these GC components: function, plane-mask, + fill-style, font, subwindow-mode, clip-x-origin, clip-y-origin, + and clip-mask. They also use these GC mode-dependent + components: foreground, background, tile, stipple, + tile-stipple-x-origin, and tile-stipple-y-origin. + + XDrawText and XDrawText16 can generate BadDrawable, BadFont, + BadGC, and BadMatch errors. + +Drawing Text Characters + + To draw 8-bit characters in a given drawable, use XDrawString. + + XDrawString(Display *display, Drawable d, GC gc, int x, int y, + char *string, int length); + + display + + Specifies the connection to the X server. + + d + + Specifies the drawable. + + gc + + Specifies the GC. + + x + + y + + Specify the x and y coordinates, which are relative to the + origin of the specified drawable and define the origin of the + first character. + + string + + Specifies the character string. + + length + + Specifies the number of characters in the string argument. + + To draw 2-byte characters in a given drawable, use + XDrawString16. + + XDrawString16(Display *display, Drawable d, GC gc, int x, int + y, XChar2b *string, int length); + + display + + Specifies the connection to the X server. + + d + + Specifies the drawable. + + gc + + Specifies the GC. + + x + + y + + Specify the x and y coordinates, which are relative to the + origin of the specified drawable and define the origin of the + first character. + + string + + Specifies the character string. + + length + + Specifies the number of characters in the string argument. + + Each character image, as defined by the font in the GC, is + treated as an additional mask for a fill operation on the + drawable. The drawable is modified only where the font + character has a bit set to 1. For fonts defined with 2-byte + matrix indexing and used with XDrawString16, each byte is used + as a byte2 with a byte1 of zero. + + Both functions use these GC components: function, plane-mask, + fill-style, font, subwindow-mode, clip-x-origin, clip-y-origin, + and clip-mask. They also use these GC mode-dependent + components: foreground, background, tile, stipple, + tile-stipple-x-origin, and tile-stipple-y-origin. + + XDrawString and XDrawString16 can generate BadDrawable, BadGC, + and BadMatch errors. + +Drawing Image Text Characters + + Some applications, in particular terminal emulators, need to + print image text in which both the foreground and background + bits of each character are painted. This prevents annoying + flicker on many displays. + + To draw 8-bit image text characters in a given drawable, use + XDrawImageString. + + XDrawImageString(Display *display, Drawable d, GC gc, int x, + int y, char *string, int length); + + display + + Specifies the connection to the X server. + + d + + Specifies the drawable. + + gc + + Specifies the GC. + + x + + y + + Specify the x and y coordinates, which are relative to the + origin of the specified drawable and define the origin of the + first character. + + string + + Specifies the character string. + + length + + Specifies the number of characters in the string argument. + + To draw 2-byte image text characters in a given drawable, use + XDrawImageString16. + + XDrawImageString16(Display *display, Drawable d, GC gc, int x, + int y, XChar2b *string, int length); + + display + + Specifies the connection to the X server. + + d + + Specifies the drawable. + + gc + + Specifies the GC. + + x + + y + + Specify the x and y coordinates, which are relative to the + origin of the specified drawable and define the origin of the + first character. + + string + + Specifies the character string. + + length + + Specifies the number of characters in the string argument. + + The XDrawImageString16 function is similar to XDrawImageString + except that it uses 2-byte or 16-bit characters. Both functions + also use both the foreground and background pixels of the GC in + the destination. + + The effect is first to fill a destination rectangle with the + background pixel defined in the GC and then to paint the text + with the foreground pixel. The upper-left corner of the filled + rectangle is at: + +[x, y - font-ascent] + + The width is: + +overall-width + + The height is: + +font-ascent + font-descent + + The overall-width, font-ascent, and font-descent are as would + be returned by XQueryTextExtents using gc and string. The + function and fill-style defined in the GC are ignored for these + functions. The effective function is GXcopy, and the effective + fill-style is FillSolid. + + For fonts defined with 2-byte matrix indexing and used with + XDrawImageString, each byte is used as a byte2 with a byte1 of + zero. + + Both functions use these GC components: plane-mask, foreground, + background, font, subwindow-mode, clip-x-origin, clip-y-origin, + and clip-mask. + + XDrawImageString and XDrawImageString16 can generate + BadDrawable, BadGC, and BadMatch errors. + +Transferring Images between Client and Server + + Xlib provides functions that you can use to transfer images + between a client and the server. Because the server may require + diverse data formats, Xlib provides an image object that fully + describes the data in memory and that provides for basic + operations on that data. You should reference the data through + the image object rather than referencing the data directly. + However, some implementations of the Xlib library may + efficiently deal with frequently used data formats by replacing + functions in the procedure vector with special case functions. + Supported operations include destroying the image, getting a + pixel, storing a pixel, extracting a subimage of an image, and + adding a constant to an image (see section 16.8). + + All the image manipulation functions discussed in this section + make use of the XImage structure, which describes an image as + it exists in the client's memory. + + + +typedef struct _XImage { + int width, height; /* size of image */ + int xoffset; /* number of pixels offset in X directio +n */ + int format; /* XYBitmap, XYPixmap, ZPixmap */ + char *data; /* pointer to image data */ + int byte_order; /* data byte order, LSBFirst, MSBFirst * +/ + int bitmap_unit; /* quant. of scanline 8, 16, 32 */ + int bitmap_bit_order; /* LSBFirst, MSBFirst */ + int bitmap_pad; /* 8, 16, 32 either XY or ZPixmap */ + int depth; /* depth of image */ + int bytes_per_line; /* accelerator to next scanline */ + int bits_per_pixel; /* bits per pixel (ZPixmap) */ + unsigned long red_mask; /* bits in z arrangement */ + unsigned long green_mask; + unsigned long blue_mask; + XPointer obdata; /* hook for the object routines to hang +on */ + struct funcs { /* image manipulation routines */ + struct _XImage *(*create_image)(); + int (*destroy_image)(); + unsigned long (*get_pixel)(); + int (*put_pixel)(); + struct _XImage *(*sub_image)(); + int (*add_pixel)(); + } f; +} XImage; + + To initialize the image manipulation routines of an image + structure, use XInitImage. + + Status XInitImage(XImage *image); + + ximage + + Specifies the image. + + The XInitImage function initializes the internal image + manipulation routines of an image structure, based on the + values of the various structure members. All fields other than + the manipulation routines must already be initialized. If the + bytes_per_line member is zero, XInitImage will assume the image + data is contiguous in memory and set the bytes_per_line member + to an appropriate value based on the other members; otherwise, + the value of bytes_per_line is not changed. All of the + manipulation routines are initialized to functions that other + Xlib image manipulation functions need to operate on the type + of image specified by the rest of the structure. + + This function must be called for any image constructed by the + client before passing it to any other Xlib function. Image + structures created or returned by Xlib do not need to be + initialized in this fashion. + + This function returns a nonzero status if initialization of the + structure is successful. It returns zero if it detected some + error or inconsistency in the structure, in which case the + image is not changed. + + To combine an image with a rectangle of a drawable on the + display, use XPutImage. + + XPutImage(Display *display, Drawable d, GC gc, XImage *image, + int src_x, int src_y, int dest_x, int dest_y, unsigned int + width, unsigned int height); + + display + + Specifies the connection to the X server. + + d + + Specifies the drawable. + + gc + + Specifies the GC. + + image + + Specifies the image you want combined with the rectangle. + + src_x + + Specifies the offset in X from the left edge of the image + defined by the XImage structure. + + src_y + + Specifies the offset in Y from the top edge of the image + defined by the XImage structure. + + dest_x + + dest_y + + Specify the x and y coordinates, which are relative to the + origin of the drawable and are the coordinates of the subimage. + + width + + height + + Specify the width and height of the subimage, which define the + dimensions of the rectangle. + + The XPutImage function combines an image with a rectangle of + the specified drawable. The section of the image defined by the + src_x, src_y, width, and height arguments is drawn on the + specified part of the drawable. If XYBitmap format is used, the + depth of the image must be one, or a BadMatch error results. + The foreground pixel in the GC defines the source for the one + bits in the image, and the background pixel defines the source + for the zero bits. For XYPixmap and ZPixmap, the depth of the + image must match the depth of the drawable, or a BadMatch error + results. + + If the characteristics of the image (for example, byte_order + and bitmap_unit) differ from what the server requires, + XPutImage automatically makes the appropriate conversions. + + This function uses these GC components: function, plane-mask, + subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. It + also uses these GC mode-dependent components: foreground and + background. + + XPutImage can generate BadDrawable, BadGC, BadMatch, and + BadValue errors. + + To return the contents of a rectangle in a given drawable on + the display, use XGetImage. This function specifically supports + rudimentary screen dumps. + + XImage *XGetImage(Display *display, Drawable d, int x, int y, + unsigned int width, unsigned int height, unsigned long + plane_mask, int format); + + display + + Specifies the connection to the X server. + + d + + Specifies the drawable. + + x + + y + + Specify the x and y coordinates, which are relative to the + origin of the drawable and define the upper-left corner of the + rectangle. + + width + + height + + Specify the width and height of the subimage, which define the + dimensions of the rectangle. + + plane_mask + + Specifies the plane mask. + + format + + Specifies the format for the image. You can pass XYPixmap or + ZPixmap. + + The XGetImage function returns a pointer to an XImage + structure. This structure provides you with the contents of the + specified rectangle of the drawable in the format you specify. + If the format argument is XYPixmap, the image contains only the + bit planes you passed to the plane_mask argument. If the + plane_mask argument only requests a subset of the planes of the + display, the depth of the returned image will be the number of + planes requested. If the format argument is ZPixmap, XGetImage + returns as zero the bits in all planes not specified in the + plane_mask argument. The function performs no range checking on + the values in plane_mask and ignores extraneous bits. + + XGetImage returns the depth of the image to the depth member of + the XImage structure. The depth of the image is as specified + when the drawable was created, except when getting a subset of + the planes in XYPixmap format, when the depth is given by the + number of bits set to 1 in plane_mask. + + If the drawable is a pixmap, the given rectangle must be wholly + contained within the pixmap, or a BadMatch error results. If + the drawable is a window, the window must be viewable, and it + must be the case that if there were no inferiors or overlapping + windows, the specified rectangle of the window would be fully + visible on the screen and wholly contained within the outside + edges of the window, or a BadMatch error results. Note that the + borders of the window can be included and read with this + request. If the window has backing-store, the backing-store + contents are returned for regions of the window that are + obscured by noninferior windows. If the window does not have + backing-store, the returned contents of such obscured regions + are undefined. The returned contents of visible regions of + inferiors of a different depth than the specified window's + depth are also undefined. The pointer cursor image is not + included in the returned contents. If a problem occurs, + XGetImage returns NULL. + + XGetImage can generate BadDrawable, BadMatch, and BadValue + errors. + + To copy the contents of a rectangle on the display to a + location within a preexisting image structure, use + XGetSubImage. + + XImage *XGetSubImage(Display *display, Drawable d, int x, int + y, unsigned int width, unsigned int height, unsigned long + plane_mask, int format, XImage *dest_image, int dest_x, int + dest_y); + + display + + Specifies the connection to the X server. + + d + + Specifies the drawable. + + x + + y + + Specify the x and y coordinates, which are relative to the + origin of the drawable and define the upper-left corner of the + rectangle. + + width + + height + + Specify the width and height of the subimage, which define the + dimensions of the rectangle. + + plane_mask + + Specifies the plane mask. + + format + + Specifies the format for the image. You can pass XYPixmap or + ZPixmap. + + dest_image + + Specifies the destination image. + + dest_x + + dest_y + + Specify the x and y coordinates, which are relative to the + origin of the destination rectangle, specify its upper-left + corner, and determine where the subimage is placed in the + destination image. + + The XGetSubImage function updates dest_image with the specified + subimage in the same manner as XGetImage. If the format + argument is XYPixmap, the image contains only the bit planes + you passed to the plane_mask argument. If the format argument + is ZPixmap, XGetSubImage returns as zero the bits in all planes + not specified in the plane_mask argument. The function performs + no range checking on the values in plane_mask and ignores + extraneous bits. As a convenience, XGetSubImage returns a + pointer to the same XImage structure specified by dest_image. + + The depth of the destination XImage structure must be the same + as that of the drawable. If the specified subimage does not fit + at the specified location on the destination image, the right + and bottom edges are clipped. If the drawable is a pixmap, the + given rectangle must be wholly contained within the pixmap, or + a BadMatch error results. If the drawable is a window, the + window must be viewable, and it must be the case that if there + were no inferiors or overlapping windows, the specified + rectangle of the window would be fully visible on the screen + and wholly contained within the outside edges of the window, or + a BadMatch error results. If the window has backing-store, then + the backing-store contents are returned for regions of the + window that are obscured by noninferior windows. If the window + does not have backing-store, the returned contents of such + obscured regions are undefined. The returned contents of + visible regions of inferiors of a different depth than the + specified window's depth are also undefined. If a problem + occurs, XGetSubImage returns NULL. + + XGetSubImage can generate BadDrawable, BadGC, BadMatch, and + BadValue errors. + +Chapter 9. Window and Session Manager Functions + + Table of Contents + + Changing the Parent of a Window + Controlling the Lifetime of a Window + Managing Installed Colormaps + Setting and Retrieving the Font Search Path + Grabbing the Server + Killing Clients + Controlling the Screen Saver + Controlling Host Access + + Adding, Getting, or Removing Hosts + Changing, Enabling, or Disabling Access Control + + Although it is difficult to categorize functions as exclusively + for an application, a window manager, or a session manager, the + functions in this chapter are most often used by window + managers and session managers. It is not expected that these + functions will be used by most application programs. Xlib + provides management functions to: + * Change the parent of a window + * Control the lifetime of a window + * Manage installed colormaps + * Set and retrieve the font search path + * Grab the server + * Kill a client + * Control the screen saver + * Control host access + +Changing the Parent of a Window + + To change a window's parent to another window on the same + screen, use XReparentWindow. There is no way to move a window + between screens. + + XReparentWindow(Display *display, Window w, Window parent, int + x, int y); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + parent + + Specifies the parent window. + + x + + y + + Specify the x and y coordinates of the position in the new + parent window. + + If the specified window is mapped, XReparentWindow + automatically performs an UnmapWindow request on it, removes it + from its current position in the hierarchy, and inserts it as + the child of the specified parent. The window is placed in the + stacking order on top with respect to sibling windows. + + After reparenting the specified window, XReparentWindow causes + the X server to generate a ReparentNotify event. The + override_redirect member returned in this event is set to the + window's corresponding attribute. Window manager clients + usually should ignore this window if this member is set to + True. Finally, if the specified window was originally mapped, + the X server automatically performs a MapWindow request on it. + + The X server performs normal exposure processing on formerly + obscured windows. The X server might not generate Expose events + for regions from the initial UnmapWindow request that are + immediately obscured by the final MapWindow request. A BadMatch + error results if: + * The new parent window is not on the same screen as the old + parent window. + * The new parent window is the specified window or an + inferior of the specified window. + * The new parent is InputOnly, and the window is not. + * The specified window has a ParentRelative background, and + the new parent window is not the same depth as the + specified window. + + XReparentWindow can generate BadMatch and BadWindow errors. + +Controlling the Lifetime of a Window + + The save-set of a client is a list of other clients' windows + that, if they are inferiors of one of the client's windows at + connection close, should not be destroyed and should be + remapped if they are unmapped. For further information about + close-connection processing, see section 2.6. To allow an + application's window to survive when a window manager that has + reparented a window fails, Xlib provides the save-set functions + that you can use to control the longevity of subwindows that + are normally destroyed when the parent is destroyed. For + example, a window manager that wants to add decoration to a + window by adding a frame might reparent an application's + window. When the frame is destroyed, the application's window + should not be destroyed but be returned to its previous place + in the window hierarchy. + + The X server automatically removes windows from the save-set + when they are destroyed. + + To add or remove a window from the client's save-set, use + XChangeSaveSet. + + XChangeSaveSet(Display *display, Window w, int change_mode); + + display + + Specifies the connection to the X server. + + w + + Specifies the window that you want to add to or delete from the + client's save-set. + + change_mode + + Specifies the mode. You can pass SetModeInsert or + SetModeDelete. + + Depending on the specified mode, XChangeSaveSet either inserts + or deletes the specified window from the client's save-set. The + specified window must have been created by some other client, + or a BadMatch error results. + + XChangeSaveSet can generate BadMatch, BadValue, and BadWindow + errors. + + To add a window to the client's save-set, use XAddToSaveSet. + + XAddToSaveSet(Display *display, Window w); + + display + + Specifies the connection to the X server. + + w + + Specifies the window that you want to add to the client's + save-set. + + The XAddToSaveSet function adds the specified window to the + client's save-set. The specified window must have been created + by some other client, or a BadMatch error results. + + XAddToSaveSet can generate BadMatch and BadWindow errors. + + To remove a window from the client's save-set, use + XRemoveFromSaveSet. + + XRemoveFromSaveSet(Display *display, Window w); + + display + + Specifies the connection to the X server. + + w + + Specifies the window that you want to delete from the client's + save-set. + + The XRemoveFromSaveSet function removes the specified window + from the client's save-set. The specified window must have been + created by some other client, or a BadMatch error results. + + XRemoveFromSaveSet can generate BadMatch and BadWindow errors. + +Managing Installed Colormaps + + The X server maintains a list of installed colormaps. Windows + using these colormaps are guaranteed to display with correct + colors; windows using other colormaps may or may not display + with correct colors. Xlib provides functions that you can use + to install a colormap, uninstall a colormap, and obtain a list + of installed colormaps. + + At any time, there is a subset of the installed maps that is + viewed as an ordered list and is called the required list. The + length of the required list is at most M, where M is the + minimum number of installed colormaps specified for the screen + in the connection setup. The required list is maintained as + follows. When a colormap is specified to XInstallColormap, it + is added to the head of the list; the list is truncated at the + tail, if necessary, to keep its length to at most M. When a + colormap is specified to XUninstallColormap and it is in the + required list, it is removed from the list. A colormap is not + added to the required list when it is implicitly installed by + the X server, and the X server cannot implicitly uninstall a + colormap that is in the required list. + + To install a colormap, use XInstallColormap. + + XInstallColormap(Display *display, Colormap colormap); + + display + + Specifies the connection to the X server. + + colormap + + Specifies the colormap. + + The XInstallColormap function installs the specified colormap + for its associated screen. All windows associated with this + colormap immediately display with true colors. You associated + the windows with this colormap when you created them by calling + XCreateWindow, XCreateSimpleWindow, XChangeWindowAttributes, or + XSetWindowColormap. + + If the specified colormap is not already an installed colormap, + the X server generates a ColormapNotify event on each window + that has that colormap. In addition, for every other colormap + that is installed as a result of a call to XInstallColormap, + the X server generates a ColormapNotify event on each window + that has that colormap. + + XInstallColormap can generate a BadColor error. + + To uninstall a colormap, use XUninstallColormap. + + XUninstallColormap(Display *display, Colormap colormap); + + display + + Specifies the connection to the X server. + + colormap + + Specifies the colormap. + + The XUninstallColormap function removes the specified colormap + from the required list for its screen. As a result, the + specified colormap might be uninstalled, and the X server might + implicitly install or uninstall additional colormaps. Which + colormaps get installed or uninstalled is server dependent + except that the required list must remain installed. + + If the specified colormap becomes uninstalled, the X server + generates a ColormapNotify event on each window that has that + colormap. In addition, for every other colormap that is + installed or uninstalled as a result of a call to + XUninstallColormap, the X server generates a ColormapNotify + event on each window that has that colormap. + + XUninstallColormap can generate a BadColor error. + + To obtain a list of the currently installed colormaps for a + given screen, use XListInstalledColormaps. + + Colormap *XListInstalledColormaps(Display *display, Window w, + int *num_return); + + display + + Specifies the connection to the X server. + + w + + Specifies the window that determines the screen. + + num_return + + Returns the number of currently installed colormaps. + + The XListInstalledColormaps function returns a list of the + currently installed colormaps for the screen of the specified + window. The order of the colormaps in the list is not + significant and is no explicit indication of the required list. + When the allocated list is no longer needed, free it by using + XFree. + + XListInstalledColormaps can generate a BadWindow error. + +Setting and Retrieving the Font Search Path + + The set of fonts available from a server depends on a font + search path. Xlib provides functions to set and retrieve the + search path for a server. + + To set the font search path, use XSetFontPath. + + XSetFontPath(Display *display, char **directories, int ndirs); + + display + + Specifies the connection to the X server. + + directories + + Specifies the directory path used to look for a font. Setting + the path to the empty list restores the default path defined + for the X server. + + ndirs + + Specifies the number of directories in the path. + + The XSetFontPath function defines the directory search path for + font lookup. There is only one search path per X server, not + one per client. The encoding and interpretation of the strings + are implementation-dependent, but typically they specify + directories or font servers to be searched in the order listed. + An X server is permitted to cache font information internally; + for example, it might cache an entire font from a file and not + check on subsequent opens of that font to see if the underlying + font file has changed. However, when the font path is changed, + the X server is guaranteed to flush all cached information + about fonts for which there currently are no explicit resource + IDs allocated. The meaning of an error from this request is + implementation-dependent. + + XSetFontPath can generate a BadValue error. + + To get the current font search path, use XGetFontPath. + + char **XGetFontPath(Display *display, int *npaths_return); + + display + + Specifies the connection to the X server. + + npaths_return + + Returns the number of strings in the font path array. + + The XGetFontPath function allocates and returns an array of + strings containing the search path. The contents of these + strings are implementation-dependent and are not intended to be + interpreted by client applications. When it is no longer + needed, the data in the font path should be freed by using + XFreeFontPath. + + To free data returned by XGetFontPath, use XFreeFontPath. + + XFreeFontPath(char **list); + + list + + Specifies the array of strings you want to free. + + The XFreeFontPath function frees the data allocated by + XGetFontPath. + +Grabbing the Server + + Xlib provides functions that you can use to grab and ungrab the + server. These functions can be used to control processing of + output on other connections by the window system server. While + the server is grabbed, no processing of requests or close downs + on any other connection will occur. A client closing its + connection automatically ungrabs the server. Although grabbing + the server is highly discouraged, it is sometimes necessary. + + To grab the server, use XGrabServer. + + XGrabServer(Display *display); + + display + + Specifies the connection to the X server. + + The XGrabServer function disables processing of requests and + close downs on all other connections than the one this request + arrived on. You should not grab the X server any more than is + absolutely necessary. + + To ungrab the server, use XUngrabServer. + + XUngrabServer(Display *display); + + display + + Specifies the connection to the X server. + + The XUngrabServer function restarts processing of requests and + close downs on other connections. You should avoid grabbing the + X server as much as possible. + +Killing Clients + + Xlib provides a function to cause the connection to a client to + be closed and its resources to be destroyed. To destroy a + client, use XKillClient. + + XKillClient(Display *display, XID resource); + + display + + Specifies the connection to the X server. + + resource + + Specifies any resource associated with the client that you want + to destroy or AllTemporary. + + The XKillClient function forces a close down of the client that + created the resource if a valid resource is specified. If the + client has already terminated in either RetainPermanent or + RetainTemporary mode, all of the client's resources are + destroyed. If AllTemporary is specified, the resources of all + clients that have terminated in RetainTemporary are destroyed + (see section 2.5). This permits implementation of window + manager facilities that aid debugging. A client can set its + close-down mode to RetainTemporary. If the client then crashes, + its windows would not be destroyed. The programmer can then + inspect the application's window tree and use the window + manager to destroy the zombie windows. + + XKillClient can generate a BadValue error. + +Controlling the Screen Saver + + Xlib provides functions that you can use to set or reset the + mode of the screen saver, to force or activate the screen + saver, or to obtain the current screen saver values. + + To set the screen saver mode, use XSetScreenSaver. + + XSetScreenSaver(Display *display, int timeout, int interval, + int prefer_blanking, int allow_exposures); + + display + + Specifies the connection to the X server. + + timeout + + Specifies the timeout, in seconds, until the screen saver turns + on. + + interval + + Specifies the interval, in seconds, between screen saver + alterations. + + prefer_blanking + + Specifies how to enable screen blanking. You can pass + DontPreferBlanking, PreferBlanking, or DefaultBlanking. + + allow_exposures + + Specifies the screen save control values. You can pass + DontAllowExposures, AllowExposures, or DefaultExposures. + + Timeout and interval are specified in seconds. A timeout of 0 + disables the screen saver (but an activated screen saver is not + deactivated), and a timeout of -1 restores the default. Other + negative values generate a BadValue error. If the timeout value + is nonzero, XSetScreenSaver enables the screen saver. An + interval of 0 disables the random-pattern motion. If no input + from devices (keyboard, mouse, and so on) is generated for the + specified number of timeout seconds once the screen saver is + enabled, the screen saver is activated. + + For each screen, if blanking is preferred and the hardware + supports video blanking, the screen simply goes blank. + Otherwise, if either exposures are allowed or the screen can be + regenerated without sending Expose events to clients, the + screen is tiled with the root window background tile randomly + re-origined each interval seconds. Otherwise, the screens' + state do not change, and the screen saver is not activated. The + screen saver is deactivated, and all screen states are restored + at the next keyboard or pointer input or at the next call to + XForceScreenSaver with mode ScreenSaverReset. + + If the server-dependent screen saver method supports periodic + change, the interval argument serves as a hint about how long + the change period should be, and zero hints that no periodic + change should be made. Examples of ways to change the screen + include scrambling the colormap periodically, moving an icon + image around the screen periodically, or tiling the screen with + the root window background tile, randomly re-origined + periodically. + + XSetScreenSaver can generate a BadValue error. + + To force the screen saver on or off, use XForceScreenSaver. + + XForceScreenSaver(Display *display, int mode); + + display + + Specifies the connection to the X server. + + mode + + Specifies the mode that is to be applied. You can pass + ScreenSaverActive or ScreenSaverReset. + + If the specified mode is ScreenSaverActive and the screen saver + currently is deactivated, XForceScreenSaver activates the + screen saver even if the screen saver had been disabled with a + timeout of zero. If the specified mode is ScreenSaverReset and + the screen saver currently is enabled, XForceScreenSaver + deactivates the screen saver if it was activated, and the + activation timer is reset to its initial state (as if device + input had been received). + + XForceScreenSaver can generate a BadValue error. + + To activate the screen saver, use XActivateScreenSaver. + + XActivateScreenSaver(Display *display); + + display + + Specifies the connection to the X server. + + To reset the screen saver, use XResetScreenSaver. + + XResetScreenSaver(Display *display); + + display + + Specifies the connection to the X server. + + To get the current screen saver values, use XGetScreenSaver. + + XGetScreenSaver(Display *display, int *timeout_return, int + *interval_return, int *prefer_blanking_return, int + *allow_exposures_return); + + display + + Specifies the connection to the X server. + + timeout_return + + Returns the timeout, in seconds, until the screen saver turns + on. + + interval_return + + Returns the interval between screen saver invocations. + + prefer_blanking_return + + Returns the current screen blanking preference + (DontPreferBlanking, PreferBlanking, or DefaultBlanking). + + allow_exposures_return + + Returns the current screen save control value + (DontAllowExposures, AllowExposures, or DefaultExposures). + +Controlling Host Access + + This section discusses how to: + * Add, get, or remove hosts from the access control list + * Change, enable, or disable access + + X does not provide any protection on a per-window basis. If you + find out the resource ID of a resource, you can manipulate it. + To provide some minimal level of protection, however, + connections are permitted only from machines you trust. This is + adequate on single-user workstations but obviously breaks down + on timesharing machines. Although provisions exist in the X + protocol for proper connection authentication, the lack of a + standard authentication server leaves host-level access control + as the only common mechanism. + + The initial set of hosts allowed to open connections typically + consists of: + * The host the window system is running on. + * On POSIX-conformant systems, each host listed in the + /etc/X?.hosts file. The ? indicates the number of the + display. This file should consist of host names separated + by newlines. DECnet nodes must terminate in :: to + distinguish them from Internet hosts. + + If a host is not in the access control list when the access + control mechanism is enabled and if the host attempts to + establish a connection, the server refuses the connection. To + change the access list, the client must reside on the same host + as the server and/or must have been granted permission in the + initial authorization at connection setup. + + Servers also can implement other access control policies in + addition to or in place of this host access facility. For + further information about other access control implementations, + see X Window System Protocol. + +Adding, Getting, or Removing Hosts + + Xlib provides functions that you can use to add, get, or remove + hosts from the access control list. All the host access control + functions use the XHostAddress structure, which contains: + + + +typedef struct { + int family; /* for example FamilyInternet */ + int length; /* length of address, in bytes */ + char *address; /* pointer to where to find the address */ +} XHostAddress; + + The family member specifies which protocol address family to + use (for example, TCP/IP or DECnet) and can be FamilyInternet, + FamilyInternet6, FamilyServerInterpreted, FamilyDECnet, or + FamilyChaos. The length member specifies the length of the + address in bytes. The address member specifies a pointer to the + address. + + For TCP/IP, the address should be in network byte order. For IP + version 4 addresses, the family should be FamilyInternet and + the length should be 4 bytes. For IP version 6 addresses, the + family should be FamilyInternet6 and the length should be 16 + bytes. + + For the DECnet family, the server performs no automatic + swapping on the address bytes. A Phase IV address is 2 bytes + long. The first byte contains the least significant 8 bits of + the node number. The second byte contains the most significant + 2 bits of the node number in the least significant 2 bits of + the byte and the area in the most significant 6 bits of the + byte. + + For the ServerInterpreted family, the length is ignored and the + address member is a pointer to a XServerInterpretedAddress + structure, which contains: + + + +typedef struct { + int typelength; /* length of type string, in bytes */ + int valuelength; /* length of value string, in bytes */ + char *type; /* pointer to where to find the type string */ + char *value; /* pointer to where to find the address */ +} XServerInterpretedAddress; + + The type and value members point to strings representing the + type and value of the server interpreted entry. These strings + may not be NULL-terminated so care should be used when + accessing them. The typelength and valuelength members specify + the length in byte of the type and value strings. + + To add a single host, use XAddHost. + + XAddHost(Display *display, XHostAddress *host); + + display + + Specifies the connection to the X server. + + host + + Specifies the host that is to be added. + + The XAddHost function adds the specified host to the access + control list for that display. The server must be on the same + host as the client issuing the command, or a BadAccess error + results. + + XAddHost can generate BadAccess and BadValue errors. + + To add multiple hosts at one time, use XAddHosts. + + XAddHosts(Display *display, XHostAddress *hosts, int + num_hosts); + + display + + Specifies the connection to the X server. + + hosts + + Specifies each host that is to be added. + + num_hosts + + Specifies the number of hosts. + + The XAddHosts function adds each specified host to the access + control list for that display. The server must be on the same + host as the client issuing the command, or a BadAccess error + results. + + XAddHosts can generate BadAccess and BadValue errors. + + To obtain a host list, use XListHosts. + + XHostAddress *XListHosts(Display *display, int *nhosts_return, + Bool *state_return); + + display + + Specifies the connection to the X server. + + nhosts_return + + Returns the number of hosts currently in the access control + list. + + state_return + + Returns the state of the access control. + + The XListHosts function returns the current access control list + as well as whether the use of the list at connection setup was + enabled or disabled. XListHosts allows a program to find out + what machines can make connections. It also returns a pointer + to a list of host structures that were allocated by the + function. When no longer needed, this memory should be freed by + calling XFree. + + To remove a single host, use XRemoveHost. + + XRemoveHost(Display *display, XHostAddress *host); + + display + + Specifies the connection to the X server. + + host + + Specifies the host that is to be removed. + + The XRemoveHost function removes the specified host from the + access control list for that display. The server must be on the + same host as the client process, or a BadAccess error results. + If you remove your machine from the access list, you can no + longer connect to that server, and this operation cannot be + reversed unless you reset the server. + + XRemoveHost can generate BadAccess and BadValue errors. + + To remove multiple hosts at one time, use XRemoveHosts. + + XRemoveHosts(Display *display, XHostAddress *hosts, int + num_hosts); + + display + + Specifies the connection to the X server. + + hosts + + Specifies each host that is to be removed. + + num_hosts + + Specifies the number of hosts. + + The XRemoveHosts function removes each specified host from the + access control list for that display. The X server must be on + the same host as the client process, or a BadAccess error + results. If you remove your machine from the access list, you + can no longer connect to that server, and this operation cannot + be reversed unless you reset the server. + + XRemoveHosts can generate BadAccess and BadValue errors. + +Changing, Enabling, or Disabling Access Control + + Xlib provides functions that you can use to enable, disable, or + change access control. + + For these functions to execute successfully, the client + application must reside on the same host as the X server and/or + have been given permission in the initial authorization at + connection setup. + + To change access control, use XSetAccessControl. + + XSetAccessControl(Display *display, int mode); + + display + + Specifies the connection to the X server. + + mode + + Specifies the mode. You can pass EnableAccess or DisableAccess. + + The XSetAccessControl function either enables or disables the + use of the access control list at each connection setup. + + XSetAccessControl can generate BadAccess and BadValue errors. + + To enable access control, use XEnableAccessControl. + + XEnableAccessControl(Display *display); + + display + + Specifies the connection to the X server. + + The XEnableAccessControl function enables the use of the access + control list at each connection setup. + + XEnableAccessControl can generate a BadAccess error. + + To disable access control, use XDisableAccessControl. + + XDisableAccessControl(Display *display); + + display + + Specifies the connection to the X server. + + The XDisableAccessControl function disables the use of the + access control list at each connection setup. + + XDisableAccessControl can generate a BadAccess error. + +Chapter 10. Events + + Table of Contents + + Event Types + Event Structures + Event Masks + Event Processing Overview + Keyboard and Pointer Events + + Pointer Button Events + Keyboard and Pointer Events + + Window Entry/Exit Events + + Normal Entry/Exit Events + Grab and Ungrab Entry/Exit Events + + Input Focus Events + + Normal Focus Events and Focus Events While Grabbed + Focus Events Generated by Grabs + + Key Map State Notification Events + Exposure Events + + Expose Events + GraphicsExpose and NoExpose Events + + Window State Change Events + + CirculateNotify Events + ConfigureNotify Events + CreateNotify Events + DestroyNotify Events + GravityNotify Events + MapNotify Events + MappingNotify Events + ReparentNotify Events + UnmapNotify Events + VisibilityNotify Events + + Structure Control Events + + CirculateRequest Events + ConfigureRequest Events + MapRequest Events + ResizeRequest Events + + Colormap State Change Events + Client Communication Events + + ClientMessage Events + PropertyNotify Events + SelectionClear Events + SelectionRequest Events + SelectionNotify Events + + A client application communicates with the X server through the + connection you establish with the XOpenDisplay function. A + client application sends requests to the X server over this + connection. These requests are made by the Xlib functions that + are called in the client application. Many Xlib functions cause + the X server to generate events, and the user's typing or + moving the pointer can generate events asynchronously. The X + server returns events to the client on the same connection. + + This chapter discusses the following topics associated with + events: + * Event types + * Event structures + * Event masks + * Event processing + + Functions for handling events are dealt with in the next + chapter. + +Event Types + + An event is data generated asynchronously by the X server as a + result of some device activity or as side effects of a request + sent by an Xlib function. Device-related events propagate from + the source window to ancestor windows until some client + application has selected that event type or until the event is + explicitly discarded. The X server generally sends an event to + a client application only if the client has specifically asked + to be informed of that event type, typically by setting the + event-mask attribute of the window. The mask can also be set + when you create a window or by changing the window's + event-mask. You can also mask out events that would propagate + to ancestor windows by manipulating the do-not-propagate mask + of the window's attributes. However, MappingNotify events are + always sent to all clients. + + An event type describes a specific event generated by the X + server. For each event type, a corresponding constant name is + defined in , which is used when referring to an event + type. The following table lists the event category and its + associated event type or types. The processing associated with + these events is discussed in section 10.5. + + Event Category Event Type + Keyboard events KeyPress, KeyRelease + Pointer events ButtonPress, ButtonRelease, MotionNotify + Window crossing events EnterNotify, LeaveNotify + Input focus events FocusIn, FocusOut + Keymap state notification event KeymapNotify + Exposure events Expose, GraphicsExpose, NoExpose + Structure control events CirculateRequest, ConfigureRequest, + MapRequest, ResizeRequest + Window state notification events CirculateNotify, + ConfigureNotify, CreateNotify, DestroyNotify, GravityNotify, + MapNotify, MappingNotify, ReparentNotify, UnmapNotify, + VisibilityNotify + Colormap state notification event ColormapNotify + Client communication events ClientMessage, PropertyNotify, + SelectionClear, SelectionNotify, SelectionRequest + +Event Structures + + For each event type, a corresponding structure is declared in + . All the event structures have the following + common members: + + + +typedef struct { + int type; + unsigned long serial; /* # of last request processed by server +*/ + Bool send_event; /* true if this came from a SendEvent req +uest */ + Display *display; /* Display the event was read from */ + Window window; +} XAnyEvent; + + The type member is set to the event type constant name that + uniquely identifies it. For example, when the X server reports + a GraphicsExpose event to a client application, it sends an + XGraphicsExposeEvent structure with the type member set to + GraphicsExpose. The display member is set to a pointer to the + display the event was read on. The send_event member is set to + True if the event came from a SendEvent protocol request. The + serial member is set from the serial number reported in the + protocol but expanded from the 16-bit least-significant bits to + a full 32-bit value. The window member is set to the window + that is most useful to toolkit dispatchers. + + The X server can send events at any time in the input stream. + Xlib stores any events received while waiting for a reply in an + event queue for later use. Xlib also provides functions that + allow you to check events in the event queue (see section + 11.3). + + In addition to the individual structures declared for each + event type, the XEvent structure is a union of the individual + structures declared for each event type. Depending on the type, + you should access members of each event by using the XEvent + union. + + + +typedef union _XEvent { + int type; /* must not be change +d */ + XAnyEvent xany; + XKeyEvent xkey; + XButtonEvent xbutton; + XMotionEvent xmotion; + XCrossingEvent xcrossing; + XFocusChangeEvent xfocus; + XExposeEvent xexpose; + XGraphicsExposeEvent xgraphicsexpose; + XNoExposeEvent xnoexpose; + XVisibilityEvent xvisibility; + XCreateWindowEvent xcreatewindow; + XDestroyWindowEvent xdestroywindow; + XUnmapEvent xunmap; + XMapEvent xmap; + XMapRequestEvent xmaprequest; + XReparentEvent xreparent; + XConfigureEvent xconfigure; + XGravityEvent xgravity; + XResizeRequestEvent xresizerequest; + XConfigureRequestEvent xconfigurerequest; + XCirculateEvent xcirculate; + XCirculateRequestEvent xcirculaterequest; + XPropertyEvent xproperty; + XSelectionClearEvent xselectionclear; + XSelectionRequestEvent xselectionrequest; + XSelectionEvent xselection; + XColormapEvent xcolormap; + XClientMessageEvent xclient; + XMappingEvent xmapping; + XErrorEvent xerror; + XKeymapEvent xkeymap; + long pad[24]; +} XEvent; + + An XEvent structure's first entry always is the type member, + which is set to the event type. The second member always is the + serial number of the protocol request that generated the event. + The third member always is send_event, which is a Bool that + indicates if the event was sent by a different client. The + fourth member always is a display, which is the display that + the event was read from. Except for keymap events, the fifth + member always is a window, which has been carefully selected to + be useful to toolkit dispatchers. To avoid breaking toolkits, + the order of these first five entries is not to change. Most + events also contain a time member, which is the time at which + an event occurred. In addition, a pointer to the generic event + must be cast before it is used to access any other information + in the structure. + +Event Masks + + Clients select event reporting of most events relative to a + window. To do this, pass an event mask to an Xlib + event-handling function that takes an event_mask argument. The + bits of the event mask are defined in . Each bit in + the event mask maps to an event mask name, which describes the + event or events you want the X server to return to a client + application. + + Unless the client has specifically asked for them, most events + are not reported to clients when they are generated. Unless the + client suppresses them by setting graphics-exposures in the GC + to False, GraphicsExpose and NoExpose are reported by default + as a result of XCopyPlane and XCopyArea. SelectionClear, + SelectionRequest, SelectionNotify, or ClientMessage cannot be + masked. Selection-related events are only sent to clients + cooperating with selections (see section 4.5). When the + keyboard or pointer mapping is changed, MappingNotify is always + sent to clients. + + The following table lists the event mask constants you can pass + to the event_mask argument and the circumstances in which you + would want to specify the event mask: + Event Mask Circumstances + NoEventMask No events wanted + KeyPressMask Keyboard down events wanted + KeyReleaseMask Keyboard up events wanted + ButtonPressMask Pointer button down events wanted + ButtonReleaseMask Pointer button up events wanted + EnterWindowMask Pointer window entry events wanted + LeaveWindowMask Pointer window leave events wanted + PointerMotionMask Pointer motion events wanted + PointerMotionHintMask Pointer motion hints wanted + Button1MotionMask Pointer motion while button 1 down + Button2MotionMask Pointer motion while button 2 down + Button3MotionMask Pointer motion while button 3 down + Button4MotionMask Pointer motion while button 4 down + Button5MotionMask Pointer motion while button 5 down + ButtonMotionMask Pointer motion while any button down + KeymapStateMask Keyboard state wanted at window entry and focus + in + ExposureMask Any exposure wanted + VisibilityChangeMask Any change in visibility wanted + StructureNotifyMask Any change in window structure wanted + ResizeRedirectMask Redirect resize of this window + SubstructureNotifyMask Substructure notification wanted + SubstructureRedirectMask Redirect structure requests on + children + FocusChangeMask Any change in input focus wanted + PropertyChangeMask Any change in property wanted + ColormapChangeMask Any change in colormap wanted + OwnerGrabButtonMask Automatic grabs should activate with + owner_events set to True + +Event Processing Overview + + The event reported to a client application during event + processing depends on which event masks you provide as the + event-mask attribute for a window. For some event masks, there + is a one-to-one correspondence between the event mask constant + and the event type constant. For example, if you pass the event + mask ButtonPressMask, the X server sends back only ButtonPress + events. Most events contain a time member, which is the time at + which an event occurred. + + In other cases, one event mask constant can map to several + event type constants. For example, if you pass the event mask + SubstructureNotifyMask, the X server can send back + CirculateNotify, ConfigureNotify, CreateNotify, DestroyNotify, + GravityNotify, MapNotify, ReparentNotify, or UnmapNotify + events. + + In another case, two event masks can map to one event type. For + example, if you pass either PointerMotionMask or + ButtonMotionMask, the X server sends back a MotionNotify event. + + The following table lists the event mask, its associated event + type or types, and the structure name associated with the event + type. Some of these structures actually are typedefs to a + generic structure that is shared between two event types. Note + that N.A. appears in columns for which the information is not + applicable. + Event Mask Event Type Structure Generic Structure + + ButtonMotionMask + + Button1MotionMask + + Button2MotionMask + + Button3MotionMask + + Button4MotionMask + + Button5MotionMask + MotionNotify XPointerMovedEvent XMotionEvent + ButtonPressMask ButtonPress XButtonPressedEvent XButtonEvent + ButtonReleaseMask ButtonRelease XButtonReleasedEvent + XButtonEvent + ColormapChangeMask ColormapNotify XColormapEvent + EnterWindowMask EnterNotify XEnterWindowEvent XCrossingEvent + LeaveWindowMask LeaveNotify XLeaveWindowEvent XCrossingEvent + ExposureMask Expose XExposeEvent + GCGraphicsExposures in GC GraphicsExpose XGraphicsExposeEvent + NoExpose XNoExposeEvent + FocusChangeMask FocusIn XFocusInEvent XFocusChangeEvent + FocusOut XFocusOutEvent XFocusChangeEvent + KeymapStateMask KeymapNotify XKeymapEvent + KeyPressMask KeyPress XKeyPressedEvent XKeyEvent + KeyReleaseMask KeyRelease XKeyReleasedEvent XKeyEvent + OwnerGrabButtonMask N.A. N.A. + PointerMotionMask MotionNotify XPointerMovedEvent XMotionEvent + PointerMotionHintMask N.A. N.A. + PropertyChangeMask PropertyNotify XPropertyEvent + ResizeRedirectMask ResizeRequest XResizeRequestEvent + StructureNotifyMask CirculateNotify XCirculateEvent + ConfigureNotify XConfigureEvent + DestroyNotify XDestroyWindowEvent + GravityNotify XGravityEvent + MapNotify XMapEvent + ReparentNotify XReparentEvent + UnmapNotify XUnmapEvent + SubstructureNotifyMask CirculateNotify XCirculateEvent + ConfigureNotify XConfigureEvent + CreateNotify XCreateWindowEvent + DestroyNotify XDestroyWindowEvent + GravityNotify XGravityEvent + MapNotify XMapEvent + ReparentNotify XReparentEvent + UnmapNotify XUnmapEvent + SubstructureRedirectMask CirculateRequest + XCirculateRequestEvent + ConfigureRequest XConfigureRequestEvent + MapRequest XMapRequestEvent + N.A. ClientMessage XClientMessageEvent + N.A. MappingNotify XMappingEvent + N.A. SelectionClear XSelectionClearEvent + N.A. SelectionNotify XSelectionEvent + N.A. SelectionRequest XSelectionRequestEvent + VisibilityChangeMask VisibilityNotify XVisibilityEvent + + The sections that follow describe the processing that occurs + when you select the different event masks. The sections are + organized according to these processing categories: + * Keyboard and pointer events + * Window crossing events + * Input focus events + * Keymap state notification events + * Exposure events + * Window state notification events + * Structure control events + * Colormap state notification events + * Client communication events + +Keyboard and Pointer Events + + This section discusses: + * Pointer button events + * Keyboard and pointer events + +Pointer Button Events + + The following describes the event processing that occurs when a + pointer button press is processed with the pointer in some + window w and when no active pointer grab is in progress. + + The X server searches the ancestors of w from the root down, + looking for a passive grab to activate. If no matching passive + grab on the button exists, the X server automatically starts an + active grab for the client receiving the event and sets the + last-pointer-grab time to the current server time. The effect + is essentially equivalent to an XGrabButton with these client + passed arguments: + Argument Value + w The event window + event_mask The client's selected pointer events on the event + window + pointer_mode GrabModeAsync + keyboard_mode GrabModeAsync + owner_events True, if the client has selected + OwnerGrabButtonMask on the event window, otherwise False + confine_to None + cursor None + + The active grab is automatically terminated when the logical + state of the pointer has all buttons released. Clients can + modify the active grab by calling XUngrabPointer and + XChangeActivePointerGrab. + +Keyboard and Pointer Events + + This section discusses the processing that occurs for the + keyboard events KeyPress and KeyRelease and the pointer events + ButtonPress, ButtonRelease, and MotionNotify. For information + about the keyboard event-handling utilities, see chapter 11. + + The X server reports KeyPress or KeyRelease events to clients + wanting information about keys that logically change state. + Note that these events are generated for all keys, even those + mapped to modifier bits. The X server reports ButtonPress or + ButtonRelease events to clients wanting information about + buttons that logically change state. + + The X server reports MotionNotify events to clients wanting + information about when the pointer logically moves. The X + server generates this event whenever the pointer is moved and + the pointer motion begins and ends in the window. The + granularity of MotionNotify events is not guaranteed, but a + client that selects this event type is guaranteed to receive at + least one event when the pointer moves and then rests. + + The generation of the logical changes lags the physical changes + if device event processing is frozen. + + To receive KeyPress, KeyRelease, ButtonPress, and ButtonRelease + events, set KeyPressMask, KeyReleaseMask, ButtonPressMask, and + ButtonReleaseMask bits in the event-mask attribute of the + window. + + To receive MotionNotify events, set one or more of the + following event masks bits in the event-mask attribute of the + window. + * Button1MotionMask - Button5MotionMask + * The client application receives MotionNotify events only + when one or more of the specified buttons is pressed. + * ButtonMotionMask + * The client application receives MotionNotify events only + when at least one button is pressed. + * PointerMotionMask + * The client application receives MotionNotify events + independent of the state of the pointer buttons. + * PointerMotionHintMask + * If PointerMotionHintMask is selected in combination with + one or more of the above masks, the X server is free to + send only one MotionNotify event (with the is_hint member + of the XPointerMovedEvent structure set to NotifyHint) to + the client for the event window, until either the key or + button state changes, the pointer leaves the event window, + or the client calls XQueryPointer or . The server still may + send MotionNotify events without is_hint set to NotifyHint. + + The source of the event is the viewable window that the pointer + is in. The window used by the X server to report these events + depends on the window's position in the window hierarchy and + whether any intervening window prohibits the generation of + these events. Starting with the source window, the X server + searches up the window hierarchy until it locates the first + window specified by a client as having an interest in these + events. If one of the intervening windows has its + do-not-propagate-mask set to prohibit generation of the event + type, the events of those types will be suppressed. Clients can + modify the actual window used for reporting by performing + active grabs and, in the case of keyboard events, by using the + focus window. + + The structures for these event types contain: +typedef struct { + int type; /* ButtonPress or ButtonRelease */ + unsigned long serial; /* # of last request processed by s +erver */ + Bool send_event; /* true if this came from a SendEve +nt request */ + Display *display; /* Display the event was read from +*/ + Window window; /* ``event'' window it is reported +relative to */ + Window root; /* root window that the event occur +red on */ + Window subwindow; /* child window */ + Time time; /* milliseconds */ + int x, y; /* pointer x, y coordinates in even +t window */ + int x_root, y_root; /* coordinates relative to root */ + unsigned int state; /* key or button mask */ + unsigned int button; /* detail */ + Bool same_screen; /* same screen flag */ +} XButtonEvent; +typedef XButtonEvent XButtonPressedEvent; +typedef XButtonEvent XButtonReleasedEvent; + +typedef struct { + int type; /* KeyPress or KeyRelease */ + unsigned long serial; /* # of last request processed by s +erver */ + Bool send_event; /* true if this came from a SendEve +nt request */ + Display *display; /* Display the event was read from +*/ + Window window; /* ``event'' window it is reported +relative to */ + Window root; /* root window that the event occur +red on */ + Window subwindow; /* child window */ + Time time; /* milliseconds */ + int x, y; /* pointer x, y coordinates in even +t window */ + int x_root, y_root; /* coordinates relative to root */ + unsigned int state; /* key or button mask */ + unsigned int keycode; /* detail */ + Bool same_screen; /* same screen flag */ +} XKeyEvent; +typedef XKeyEvent XKeyPressedEvent; +typedef XKeyEvent XKeyReleasedEvent; + +typedef struct { + int type; /* MotionNotify */ + unsigned long serial; /* # of last request processed by + server */ + Bool send_event; /* true if this came from a SendE +vent request */ + Display *display; /* Display the event was read fro +m */ + Window window; /* ``event'' window reported rela +tive to */ + Window root; /* root window that the event occ +urred on */ + Window subwindow; /* child window */ + Time time; /* milliseconds */ + int x, y; /* pointer x, y coordinates in ev +ent window */ + int x_root, y_root; /* coordinates relative to root * +/ + unsigned int state; /* key or button mask */ + char is_hint; /* detail */ + Bool same_screen; /* same screen flag */ +} XMotionEvent; +typedef XMotionEvent XPointerMovedEvent; + + These structures have the following common members: window, + root, subwindow, time, x, y, x_root, y_root, state, and + same_screen. The window member is set to the window on which + the event was generated and is referred to as the event window. + As long as the conditions previously discussed are met, this is + the window used by the X server to report the event. The root + member is set to the source window's root window. The x_root + and y_root members are set to the pointer's coordinates + relative to the root window's origin at the time of the event. + + The same_screen member is set to indicate whether the event + window is on the same screen as the root window and can be + either True or False. If True, the event and root windows are + on the same screen. If False, the event and root windows are + not on the same screen. + + If the source window is an inferior of the event window, the + subwindow member of the structure is set to the child of the + event window that is the source window or the child of the + event window that is an ancestor of the source window. + Otherwise, the X server sets the subwindow member to None. The + time member is set to the time when the event was generated and + is expressed in milliseconds. + + If the event window is on the same screen as the root window, + the x and y members are set to the coordinates relative to the + event window's origin. Otherwise, these members are set to + zero. + + The state member is set to indicate the logical state of the + pointer buttons and modifier keys just prior to the event, + which is the bitwise inclusive OR of one or more of the button + or modifier key masks: Button1Mask, Button2Mask, Button3Mask, + Button4Mask, Button5Mask, ShiftMask, LockMask, ControlMask, + Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, and Mod5Mask. + + Each of these structures also has a member that indicates the + detail. For the XKeyPressedEvent and XKeyReleasedEvent + structures, this member is called a keycode. It is set to a + number that represents a physical key on the keyboard. The + keycode is an arbitrary representation for any key on the + keyboard (see sections 12.7 and 16.1). + + For the XButtonPressedEvent and XButtonReleasedEvent + structures, this member is called button. It represents the + pointer button that changed state and can be the Button1, + Button2, Button3, Button4, or Button5 value. For the + XPointerMovedEvent structure, this member is called is_hint. It + can be set to NotifyNormal or NotifyHint. + + Some of the symbols mentioned in this section have fixed + values, as follows: + Symbol Value + Button1MotionMask (1L<<8) + Button2MotionMask (1L<<9) + Button3MotionMask (1L<<10) + Button4MotionMask (1L<<11) + Button5MotionMask (1L<<12) + Button1Mask (1<<8) + Button2Mask (1<<9) + Button3Mask (1<<10) + Button4Mask (1<<11) + Button5Mask (1<<12) + ShiftMask (1<<0) + LockMask (1<<1) + ControlMask (1<<2) + Mod1Mask (1<<3) + Mod2Mask (1<<4) + Mod3Mask (1<<5) + Mod4Mask (1<<6) + Mod5Mask (1<<7) + Button1 1 + Button2 2 + Button3 3 + Button4 4 + Button5 5 + +Window Entry/Exit Events + + This section describes the processing that occurs for the + window crossing events EnterNotify and LeaveNotify. If a + pointer motion or a window hierarchy change causes the pointer + to be in a different window than before, the X server reports + EnterNotify or LeaveNotify events to clients who have selected + for these events. All EnterNotify and LeaveNotify events caused + by a hierarchy change are generated after any hierarchy event + (UnmapNotify, MapNotify, ConfigureNotify, GravityNotify, + CirculateNotify) caused by that change; however, the X protocol + does not constrain the ordering of EnterNotify and LeaveNotify + events with respect to FocusOut, VisibilityNotify, and Expose + events. + + This contrasts with MotionNotify events, which are also + generated when the pointer moves but only when the pointer + motion begins and ends in a single window. An EnterNotify or + LeaveNotify event also can be generated when some client + application calls XGrabPointer and XUngrabPointer. + + To receive EnterNotify or LeaveNotify events, set the + EnterWindowMask or LeaveWindowMask bits of the event-mask + attribute of the window. + + The structure for these event types contains: + + +typedef struct { + int type; /* EnterNotify or LeaveNotify */ + unsigned long serial; /* # of last request processed by ser +ver */ + Bool send_event; /* true if this came from a SendEvent + request */ + Display *display; /* Display the event was read from */ + Window window; /* ``event'' window reported relative + to */ + Window root; /* root window that the event occurre +d on */ + Window subwindow; /* child window */ + Time time; /* milliseconds */ + int x, y; /* pointer x, y coordinates in event +window */ + int x_root, y_root; /* coordinates relative to root */ + int mode; /* NotifyNormal, NotifyGrab, NotifyUn +grab */ + int detail; + /* + * NotifyAncestor, NotifyVirtual, NotifyInferior, + * NotifyNonlinear,NotifyNonlinearVirtual + */ + Bool same_screen; /* same screen flag */ + Bool focus; /* boolean focus */ + unsigned int state; /* key or button mask */ +} XCrossingEvent; +typedef XCrossingEvent XEnterWindowEvent; +typedef XCrossingEvent XLeaveWindowEvent; + + The window member is set to the window on which the EnterNotify + or LeaveNotify event was generated and is referred to as the + event window. This is the window used by the X server to report + the event, and is relative to the root window on which the + event occurred. The root member is set to the root window of + the screen on which the event occurred. + + For a LeaveNotify event, if a child of the event window + contains the initial position of the pointer, the subwindow + component is set to that child. Otherwise, the X server sets + the subwindow member to None. For an EnterNotify event, if a + child of the event window contains the final pointer position, + the subwindow component is set to that child or None. + + The time member is set to the time when the event was generated + and is expressed in milliseconds. The x and y members are set + to the coordinates of the pointer position in the event window. + This position is always the pointer's final position, not its + initial position. If the event window is on the same screen as + the root window, x and y are the pointer coordinates relative + to the event window's origin. Otherwise, x and y are set to + zero. The x_root and y_root members are set to the pointer's + coordinates relative to the root window's origin at the time of + the event. + + The same_screen member is set to indicate whether the event + window is on the same screen as the root window and can be + either True or False. If True, the event and root windows are + on the same screen. If False, the event and root windows are + not on the same screen. + + The focus member is set to indicate whether the event window is + the focus window or an inferior of the focus window. The X + server can set this member to either True or False. If True, + the event window is the focus window or an inferior of the + focus window. If False, the event window is not the focus + window or an inferior of the focus window. + + The state member is set to indicate the state of the pointer + buttons and modifier keys just prior to the event. The X server + can set this member to the bitwise inclusive OR of one or more + of the button or modifier key masks: Button1Mask, Button2Mask, + Button3Mask, Button4Mask, Button5Mask, ShiftMask, LockMask, + ControlMask, Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, Mod5Mask. + + The mode member is set to indicate whether the events are + normal events, pseudo-motion events when a grab activates, or + pseudo-motion events when a grab deactivates. The X server can + set this member to NotifyNormal, NotifyGrab, or NotifyUngrab. + + The detail member is set to indicate the notify detail and can + be NotifyAncestor, NotifyVirtual, NotifyInferior, + NotifyNonlinear, or NotifyNonlinearVirtual. + +Normal Entry/Exit Events + + EnterNotify and LeaveNotify events are generated when the + pointer moves from one window to another window. Normal events + are identified by XEnterWindowEvent or XLeaveWindowEvent + structures whose mode member is set to NotifyNormal. + * When the pointer moves from window A to window B and A is + an inferior of B, the X server does the following: + * It generates a LeaveNotify event on window A, with the + detail member of the XLeaveWindowEvent structure set to + NotifyAncestor. + * It generates a LeaveNotify event on each window between + window A and window B, exclusive, with the detail member of + each XLeaveWindowEvent structure set to NotifyVirtual. + * It generates an EnterNotify event on window B, with the + detail member of the XEnterWindowEvent structure set to + NotifyInferior. + * When the pointer moves from window A to window B and B is + an inferior of A, the X server does the following: + * It generates a LeaveNotify event on window A, with the + detail member of the XLeaveWindowEvent structure set to + NotifyInferior. + * It generates an EnterNotify event on each window between + window A and window B, exclusive, with the detail member of + each XEnterWindowEvent structure set to NotifyVirtual. + * It generates an EnterNotify event on window B, with the + detail member of the XEnterWindowEvent structure set to + NotifyAncestor. + * When the pointer moves from window A to window B and window + C is their least common ancestor, the X server does the + following: + * It generates a LeaveNotify event on window A, with the + detail member of the XLeaveWindowEvent structure set to + NotifyNonlinear. + * It generates a LeaveNotify event on each window between + window A and window C, exclusive, with the detail member of + each XLeaveWindowEvent structure set to + NotifyNonlinearVirtual. + * It generates an EnterNotify event on each window between + window C and window B, exclusive, with the detail member of + each XEnterWindowEvent structure set to + NotifyNonlinearVirtual. + * It generates an EnterNotify event on window B, with the + detail member of the XEnterWindowEvent structure set to + NotifyNonlinear. + * When the pointer moves from window A to window B on + different screens, the X server does the following: + * It generates a LeaveNotify event on window A, with the + detail member of the XLeaveWindowEvent structure set to + NotifyNonlinear. + * If window A is not a root window, it generates a + LeaveNotify event on each window above window A up to and + including its root, with the detail member of each + XLeaveWindowEvent structure set to NotifyNonlinearVirtual. + * If window B is not a root window, it generates an + EnterNotify event on each window from window B's root down + to but not including window B, with the detail member of + each XEnterWindowEvent structure set to + NotifyNonlinearVirtual. + * It generates an EnterNotify event on window B, with the + detail member of the XEnterWindowEvent structure set to + NotifyNonlinear. + +Grab and Ungrab Entry/Exit Events + + Pseudo-motion mode EnterNotify and LeaveNotify events are + generated when a pointer grab activates or deactivates. Events + in which the pointer grab activates are identified by + XEnterWindowEvent or XLeaveWindowEvent structures whose mode + member is set to NotifyGrab. Events in which the pointer grab + deactivates are identified by XEnterWindowEvent or + XLeaveWindowEvent structures whose mode member is set to + NotifyUngrab (see XGrabPointer). + * When a pointer grab activates after any initial warp into a + confine_to window and before generating any actual + ButtonPress event that activates the grab, G is the + grab_window for the grab, and P is the window the pointer + is in, the X server does the following: + * It generates EnterNotify and LeaveNotify events (see + section 10.6.1) with the mode members of the + XEnterWindowEvent and XLeaveWindowEvent structures set to + NotifyGrab. These events are generated as if the pointer + were to suddenly warp from its current position in P to + some position in G. However, the pointer does not warp, and + the X server uses the pointer position as both the initial + and final positions for the events. + * When a pointer grab deactivates after generating any actual + ButtonRelease event that deactivates the grab, G is the + grab_window for the grab, and P is the window the pointer + is in, the X server does the following: + * It generates EnterNotify and LeaveNotify events (see + section 10.6.1) with the mode members of the + XEnterWindowEvent and XLeaveWindowEvent structures set to + NotifyUngrab. These events are generated as if the pointer + were to suddenly warp from some position in G to its + current position in P. However, the pointer does not warp, + and the X server uses the current pointer position as both + the initial and final positions for the events. + +Input Focus Events + + This section describes the processing that occurs for the input + focus events FocusIn and FocusOut. The X server can report + FocusIn or FocusOut events to clients wanting information about + when the input focus changes. The keyboard is always attached + to some window (typically, the root window or a top-level + window), which is called the focus window. The focus window and + the position of the pointer determine the window that receives + keyboard input. Clients may need to know when the input focus + changes to control highlighting of areas on the screen. + + To receive FocusIn or FocusOut events, set the FocusChangeMask + bit in the event-mask attribute of the window. + + The structure for these event types contains: + + +typedef struct { + int type; /* FocusIn or FocusOut */ + unsigned long serial; /* # of last request processed by server +*/ + Bool send_event; /* true if this came from a SendEvent req +uest */ + Display *display; /* Display the event was read from */ + Window window; /* window of event */ + int mode; /* NotifyNormal, NotifyGrab, NotifyUngrab + */ + int detail; + /* + * NotifyAncestor, NotifyVirtual, NotifyInferior, + * NotifyNonlinear,NotifyNonlinearVirtual, NotifyPoin +ter, + * NotifyPointerRoot, NotifyDetailNone + */ +} XFocusChangeEvent; +typedef XFocusChangeEvent XFocusInEvent; +typedef XFocusChangeEvent XFocusOutEvent; + + The window member is set to the window on which the FocusIn or + FocusOut event was generated. This is the window used by the X + server to report the event. The mode member is set to indicate + whether the focus events are normal focus events, focus events + while grabbed, focus events when a grab activates, or focus + events when a grab deactivates. The X server can set the mode + member to NotifyNormal, NotifyWhileGrabbed, NotifyGrab, or + NotifyUngrab. + + All FocusOut events caused by a window unmap are generated + after any UnmapNotify event; however, the X protocol does not + constrain the ordering of FocusOut events with respect to + generated EnterNotify, LeaveNotify, VisibilityNotify, and + Expose events. + + Depending on the event mode, the detail member is set to + indicate the notify detail and can be NotifyAncestor, + NotifyVirtual, NotifyInferior, NotifyNonlinear, + NotifyNonlinearVirtual, NotifyPointer, NotifyPointerRoot, or + NotifyDetailNone. + +Normal Focus Events and Focus Events While Grabbed + + Normal focus events are identified by XFocusInEvent or + XFocusOutEvent structures whose mode member is set to + NotifyNormal. Focus events while grabbed are identified by + XFocusInEvent or XFocusOutEvent structures whose mode member is + set to NotifyWhileGrabbed. The X server processes normal focus + and focus events while grabbed according to the following: + * When the focus moves from window A to window B, A is an + inferior of B, and the pointer is in window P, the X server + does the following: + * It generates a FocusOut event on window A, with the detail + member of the XFocusOutEvent structure set to + NotifyAncestor. + * It generates a FocusOut event on each window between window + A and window B, exclusive, with the detail member of each + XFocusOutEvent structure set to NotifyVirtual. + * It generates a FocusIn event on window B, with the detail + member of the XFocusOutEvent structure set to + NotifyInferior. + * If window P is an inferior of window B but window P is not + window A or an inferior or ancestor of window A, it + generates a FocusIn event on each window below window B, + down to and including window P, with the detail member of + each XFocusInEvent structure set to NotifyPointer. + * When the focus moves from window A to window B, B is an + inferior of A, and the pointer is in window P, the X server + does the following: + * If window P is an inferior of window A but P is not an + inferior of window B or an ancestor of B, it generates a + FocusOut event on each window from window P up to but not + including window A, with the detail member of each + XFocusOutEvent structure set to NotifyPointer. + * It generates a FocusOut event on window A, with the detail + member of the XFocusOutEvent structure set to + NotifyInferior. + * It generates a FocusIn event on each window between window + A and window B, exclusive, with the detail member of each + XFocusInEvent structure set to NotifyVirtual. + * It generates a FocusIn event on window B, with the detail + member of the XFocusInEvent structure set to + NotifyAncestor. + * When the focus moves from window A to window B, window C is + their least common ancestor, and the pointer is in window + P, the X server does the following: + * If window P is an inferior of window A, it generates a + FocusOut event on each window from window P up to but not + including window A, with the detail member of the + XFocusOutEvent structure set to NotifyPointer. + * It generates a FocusOut event on window A, with the detail + member of the XFocusOutEvent structure set to + NotifyNonlinear. + * It generates a FocusOut event on each window between window + A and window C, exclusive, with the detail member of each + XFocusOutEvent structure set to NotifyNonlinearVirtual. + * It generates a FocusIn event on each window between C and + B, exclusive, with the detail member of each XFocusInEvent + structure set to NotifyNonlinearVirtual. + * It generates a FocusIn event on window B, with the detail + member of the XFocusInEvent structure set to + NotifyNonlinear. + * If window P is an inferior of window B, it generates a + FocusIn event on each window below window B down to and + including window P, with the detail member of the + XFocusInEvent structure set to NotifyPointer. + * When the focus moves from window A to window B on different + screens and the pointer is in window P, the X server does + the following: + * If window P is an inferior of window A, it generates a + FocusOut event on each window from window P up to but not + including window A, with the detail member of each + XFocusOutEvent structure set to NotifyPointer. + * It generates a FocusOut event on window A, with the detail + member of the XFocusOutEvent structure set to + NotifyNonlinear. + * If window A is not a root window, it generates a FocusOut + event on each window above window A up to and including its + root, with the detail member of each XFocusOutEvent + structure set to NotifyNonlinearVirtual. + * If window B is not a root window, it generates a FocusIn + event on each window from window B's root down to but not + including window B, with the detail member of each + XFocusInEvent structure set to NotifyNonlinearVirtual. + * It generates a FocusIn event on window B, with the detail + member of each XFocusInEvent structure set to + NotifyNonlinear. + * If window P is an inferior of window B, it generates a + FocusIn event on each window below window B down to and + including window P, with the detail member of each + XFocusInEvent structure set to NotifyPointer. + * When the focus moves from window A to PointerRoot (events + sent to the window under the pointer) or None (discard), + and the pointer is in window P, the X server does the + following: + * If window P is an inferior of window A, it generates a + FocusOut event on each window from window P up to but not + including window A, with the detail member of each + XFocusOutEvent structure set to NotifyPointer. + * It generates a FocusOut event on window A, with the detail + member of the XFocusOutEvent structure set to + NotifyNonlinear. + * If window A is not a root window, it generates a FocusOut + event on each window above window A up to and including its + root, with the detail member of each XFocusOutEvent + structure set to NotifyNonlinearVirtual. + * It generates a FocusIn event on the root window of all + screens, with the detail member of each XFocusInEvent + structure set to NotifyPointerRoot (or NotifyDetailNone). + * If the new focus is PointerRoot, it generates a FocusIn + event on each window from window P's root down to and + including window P, with the detail member of each + XFocusInEvent structure set to NotifyPointer. + * When the focus moves from PointerRoot (events sent to the + window under the pointer) or None to window A, and the + pointer is in window P, the X server does the following: + * If the old focus is PointerRoot, it generates a FocusOut + event on each window from window P up to and including + window P's root, with the detail member of each + XFocusOutEvent structure set to NotifyPointer. + * It generates a FocusOut event on all root windows, with the + detail member of each XFocusOutEvent structure set to + NotifyPointerRoot (or NotifyDetailNone). + * If window A is not a root window, it generates a FocusIn + event on each window from window A's root down to but not + including window A, with the detail member of each + XFocusInEvent structure set to NotifyNonlinearVirtual. + * It generates a FocusIn event on window A, with the detail + member of the XFocusInEvent structure set to + NotifyNonlinear. + * If window P is an inferior of window A, it generates a + FocusIn event on each window below window A down to and + including window P, with the detail member of each + XFocusInEvent structure set to NotifyPointer. + * When the focus moves from PointerRoot (events sent to the + window under the pointer) to None (or vice versa), and the + pointer is in window P, the X server does the following: + * If the old focus is PointerRoot, it generates a FocusOut + event on each window from window P up to and including + window P's root, with the detail member of each + XFocusOutEvent structure set to NotifyPointer. + * It generates a FocusOut event on all root windows, with the + detail member of each XFocusOutEvent structure set to + either NotifyPointerRoot or NotifyDetailNone. + * It generates a FocusIn event on all root windows, with the + detail member of each XFocusInEvent structure set to + NotifyDetailNone or NotifyPointerRoot. + * If the new focus is PointerRoot, it generates a FocusIn + event on each window from window P's root down to and + including window P, with the detail member of each + XFocusInEvent structure set to NotifyPointer. + +Focus Events Generated by Grabs + + Focus events in which the keyboard grab activates are + identified by XFocusInEvent or XFocusOutEvent structures whose + mode member is set to NotifyGrab. Focus events in which the + keyboard grab deactivates are identified by XFocusInEvent or + XFocusOutEvent structures whose mode member is set to + NotifyUngrab (see XGrabKeyboard). + * When a keyboard grab activates before generating any actual + KeyPress event that activates the grab, G is the + grab_window, and F is the current focus, the X server does + the following: + * It generates FocusIn and FocusOut events, with the mode + members of the XFocusInEvent and XFocusOutEvent structures + set to NotifyGrab. These events are generated as if the + focus were to change from F to G. + * When a keyboard grab deactivates after generating any + actual KeyRelease event that deactivates the grab, G is the + grab_window, and F is the current focus, the X server does + the following: + * It generates FocusIn and FocusOut events, with the mode + members of the XFocusInEvent and XFocusOutEvent structures + set to NotifyUngrab. These events are generated as if the + focus were to change from G to F. + +Key Map State Notification Events + + The X server can report KeymapNotify events to clients that + want information about changes in their keyboard state. + + To receive KeymapNotify events, set the KeymapStateMask bit in + the event-mask attribute of the window. The X server generates + this event immediately after every EnterNotify and FocusIn + event. + + The structure for this event type contains: + + + +/* generated on EnterWindow and FocusIn when KeymapState selected */ +typedef struct { + int type; /* KeymapNotify */ + unsigned long serial; /* # of last request processed by se +rver */ + Bool send_event; /* true if this came from a SendEven +t request */ + Display *display; /* Display the event was read from * +/ + Window window; + char key_vector[32]; +} XKeymapEvent; + + The window member is not used but is present to aid some + toolkits. The key_vector member is set to the bit vector of the + keyboard. Each bit set to 1 indicates that the corresponding + key is currently pressed. The vector is represented as 32 + bytes. Byte N (from 0) contains the bits for keys 8N to 8N + 7 + with the least significant bit in the byte representing key 8N. + +Exposure Events + + The X protocol does not guarantee to preserve the contents of + window regions when the windows are obscured or reconfigured. + Some implementations may preserve the contents of windows. + Other implementations are free to destroy the contents of + windows when exposed. X expects client applications to assume + the responsibility for restoring the contents of an exposed + window region. (An exposed window region describes a formerly + obscured window whose region becomes visible.) Therefore, the X + server sends Expose events describing the window and the region + of the window that has been exposed. A naive client application + usually redraws the entire window. A more sophisticated client + application redraws only the exposed region. + +Expose Events + + The X server can report Expose events to clients wanting + information about when the contents of window regions have been + lost. The circumstances in which the X server generates Expose + events are not as definite as those for other events. However, + the X server never generates Expose events on windows whose + class you specified as InputOnly. The X server can generate + Expose events when no valid contents are available for regions + of a window and either the regions are visible, the regions are + viewable and the server is (perhaps newly) maintaining backing + store on the window, or the window is not viewable but the + server is (perhaps newly) honoring the window's backing-store + attribute of Always or WhenMapped. The regions decompose into + an (arbitrary) set of rectangles, and an Expose event is + generated for each rectangle. For any given window, the X + server guarantees to report contiguously all of the regions + exposed by some action that causes Expose events, such as + raising a window. + + To receive Expose events, set the ExposureMask bit in the + event-mask attribute of the window. + + The structure for this event type contains: + + + +typedef struct { + int type; /* Expose */ + unsigned long serial; /* # of last request processed by ser +ver */ + Bool send_event; /* true if this came from a SendEvent + request */ + Display *display; /* Display the event was read from */ + Window window; + int x, y; + int width, height; + int count; /* if nonzero, at least this many mor +e */ +} XExposeEvent; + + The window member is set to the exposed (damaged) window. The x + and y members are set to the coordinates relative to the + window's origin and indicate the upper-left corner of the + rectangle. The width and height members are set to the size + (extent) of the rectangle. The count member is set to the + number of Expose events that are to follow. If count is zero, + no more Expose events follow for this window. However, if count + is nonzero, at least that number of Expose events (and possibly + more) follow for this window. Simple applications that do not + want to optimize redisplay by distinguishing between subareas + of its window can just ignore all Expose events with nonzero + counts and perform full redisplays on events with zero counts. + +GraphicsExpose and NoExpose Events + + The X server can report GraphicsExpose events to clients + wanting information about when a destination region could not + be computed during certain graphics requests: XCopyArea or + XCopyPlane. The X server generates this event whenever a + destination region could not be computed because of an obscured + or out-of-bounds source region. In addition, the X server + guarantees to report contiguously all of the regions exposed by + some graphics request (for example, copying an area of a + drawable to a destination drawable). + + The X server generates a NoExpose event whenever a graphics + request that might produce a GraphicsExpose event does not + produce any. In other words, the client is really asking for a + GraphicsExpose event but instead receives a NoExpose event. + + To receive GraphicsExpose or NoExpose events, you must first + set the graphics-exposure attribute of the graphics context to + True. You also can set the graphics-expose attribute when + creating a graphics context using XCreateGC or by calling + XSetGraphicsExposures. + + The structures for these event types contain: + + + +typedef struct { + int type; /* GraphicsExpose */ + unsigned long serial; /* # of last request processed by se +rver */ + Bool send_event; /* true if this came from a SendEven +t request */ + Display *display; /* Display the event was read from * +/ + Drawable drawable; + int x, y; + int width, height; + int count; /* if nonzero, at least this many mo +re */ + int major_code; /* core is CopyArea or CopyPlane */ + int minor_code; /* not defined in the core */ +} XGraphicsExposeEvent; + + + +typedef struct { + int type; /* NoExpose */ + unsigned long serial; /* # of last request processed by serve +r */ + Bool send_event; /* true if this came from a SendEvent r +equest */ + Display *display; /* Display the event was read from */ + Drawable drawable; + int major_code; /* core is CopyArea or CopyPlane */ + int minor_code; /* not defined in the core */ +} XNoExposeEvent; + + Both structures have these common members: drawable, + major_code, and minor_code. The drawable member is set to the + drawable of the destination region on which the graphics + request was to be performed. The major_code member is set to + the graphics request initiated by the client and can be either + X_CopyArea or X_CopyPlane. If it is X_CopyArea, a call to + XCopyArea initiated the request. If it is X_CopyPlane, a call + to XCopyPlane initiated the request. These constants are + defined in . The minor_code member, like the + major_code member, indicates which graphics request was + initiated by the client. However, the minor_code member is not + defined by the core X protocol and will be zero in these cases, + although it may be used by an extension. + + The XGraphicsExposeEvent structure has these additional + members: x, y, width, height, and count. The x and y members + are set to the coordinates relative to the drawable's origin + and indicate the upper-left corner of the rectangle. The width + and height members are set to the size (extent) of the + rectangle. The count member is set to the number of + GraphicsExpose events to follow. If count is zero, no more + GraphicsExpose events follow for this window. However, if count + is nonzero, at least that number of GraphicsExpose events (and + possibly more) are to follow for this window. + +Window State Change Events + + The following sections discuss: + * CirculateNotify events + * ConfigureNotify events + * CreateNotify events + * DestroyNotify events + * GravityNotify events + * MapNotify events + * MappingNotify events + * ReparentNotify events + * UnmapNotify events + * VisibilityNotify events + +CirculateNotify Events + + The X server can report CirculateNotify events to clients + wanting information about when a window changes its position in + the stack. The X server generates this event type whenever a + window is actually restacked as a result of a client + application calling XCirculateSubwindows, + XCirculateSubwindowsUp, or XCirculateSubwindowsDown. + + To receive CirculateNotify events, set the StructureNotifyMask + bit in the event-mask attribute of the window or the + SubstructureNotifyMask bit in the event-mask attribute of the + parent window (in which case, circulating any child generates + an event). + + The structure for this event type contains: + + + +typedef struct { + int type; /* CirculateNotify */ + unsigned long serial; /* # of last request processed by server +*/ + Bool send_event; /* true if this came from a SendEvent request +*/ + Display *display; /* Display the event was read from */ + Window event; + Window window; + int place; /* PlaceOnTop, PlaceOnBottom */ +} XCirculateEvent; + + The event member is set either to the restacked window or to + its parent, depending on whether StructureNotify or + SubstructureNotify was selected. The window member is set to + the window that was restacked. The place member is set to the + window's position after the restack occurs and is either + PlaceOnTop or PlaceOnBottom. If it is PlaceOnTop, the window is + now on top of all siblings. If it is PlaceOnBottom, the window + is now below all siblings. + +ConfigureNotify Events + + The X server can report ConfigureNotify events to clients + wanting information about actual changes to a window's state, + such as size, position, border, and stacking order. The X + server generates this event type whenever one of the following + configure window requests made by a client application actually + completes: + * A window's size, position, border, and/or stacking order is + reconfigured by calling XConfigureWindow. + * The window's position in the stacking order is changed by + calling XLowerWindow, XRaiseWindow, or XRestackWindows. + * A window is moved by calling XMoveWindow. + * A window's size is changed by calling XResizeWindow. + * A window's size and location is changed by calling + XMoveResizeWindow. + * A window is mapped and its position in the stacking order + is changed by calling XMapRaised. + * A window's border width is changed by calling + XSetWindowBorderWidth. + + To receive ConfigureNotify events, set the StructureNotifyMask + bit in the event-mask attribute of the window or the + SubstructureNotifyMask bit in the event-mask attribute of the + parent window (in which case, configuring any child generates + an event). + + The structure for this event type contains: + + +typedef struct { + int type; /* ConfigureNotify */ + unsigned long serial; /* # of last request processed by server +*/ + Bool send_event; /* true if this came from a SendEvent req +uest */ + Display *display; /* Display the event was read from */ + Window event; + Window window; + int x, y; + int width, height; + int border_width; + Window above; + Bool override_redirect; +} XConfigureEvent; + + The event member is set either to the reconfigured window or to + its parent, depending on whether StructureNotify or + SubstructureNotify was selected. The window member is set to + the window whose size, position, border, and/or stacking order + was changed. + + The x and y members are set to the coordinates relative to the + parent window's origin and indicate the position of the + upper-left outside corner of the window. The width and height + members are set to the inside size of the window, not including + the border. The border_width member is set to the width of the + window's border, in pixels. + + The above member is set to the sibling window and is used for + stacking operations. If the X server sets this member to None, + the window whose state was changed is on the bottom of the + stack with respect to sibling windows. However, if this member + is set to a sibling window, the window whose state was changed + is placed on top of this sibling window. + + The override_redirect member is set to the override-redirect + attribute of the window. Window manager clients normally should + ignore this window if the override_redirect member is True. + +CreateNotify Events + + The X server can report CreateNotify events to clients wanting + information about creation of windows. The X server generates + this event whenever a client application creates a window by + calling XCreateWindow or XCreateSimpleWindow. + + To receive CreateNotify events, set the SubstructureNotifyMask + bit in the event-mask attribute of the window. Creating any + children then generates an event. + + The structure for the event type contains: + + + +typedef struct { + int type; /* CreateNotify */ + unsigned long serial; /* # of last request processed by + server */ + Bool send_event; /* true if this came from a SendE +vent request */ + Display *display; /* Display the event was read fro +m */ + Window parent; /* parent of the window */ + Window window; /* window id of window created */ + int x, y; /* window location */ + int width, height; /* size of window */ + int border_width; /* border width */ + Bool override_redirect; /* creation should be overridden +*/ +} XCreateWindowEvent; + + The parent member is set to the created window's parent. The + window member specifies the created window. The x and y members + are set to the created window's coordinates relative to the + parent window's origin and indicate the position of the + upper-left outside corner of the created window. The width and + height members are set to the inside size of the created window + (not including the border) and are always nonzero. The + border_width member is set to the width of the created window's + border, in pixels. The override_redirect member is set to the + override-redirect attribute of the window. Window manager + clients normally should ignore this window if the + override_redirect member is True. + +DestroyNotify Events + + The X server can report DestroyNotify events to clients wanting + information about which windows are destroyed. The X server + generates this event whenever a client application destroys a + window by calling XDestroyWindow or XDestroySubwindows. + + The ordering of the DestroyNotify events is such that for any + given window, DestroyNotify is generated on all inferiors of + the window before being generated on the window itself. The X + protocol does not constrain the ordering among siblings and + across subhierarchies. + + To receive DestroyNotify events, set the StructureNotifyMask + bit in the event-mask attribute of the window or the + SubstructureNotifyMask bit in the event-mask attribute of the + parent window (in which case, destroying any child generates an + event). + + The structure for this event type contains: + + + +typedef struct { + int type; /* DestroyNotify */ + unsigned long serial; /* # of last request processed by server +*/ + Bool send_event; /* true if this came from a SendEvent req +uest */ + Display *display; /* Display the event was read from */ + Window event; + Window window; +} XDestroyWindowEvent; + + The event member is set either to the destroyed window or to + its parent, depending on whether StructureNotify or + SubstructureNotify was selected. The window member is set to + the window that is destroyed. + +GravityNotify Events + + The X server can report GravityNotify events to clients wanting + information about when a window is moved because of a change in + the size of its parent. The X server generates this event + whenever a client application actually moves a child window as + a result of resizing its parent by calling XConfigureWindow, + XMoveResizeWindow, or XResizeWindow. + + To receive GravityNotify events, set the StructureNotifyMask + bit in the event-mask attribute of the window or the + SubstructureNotifyMask bit in the event-mask attribute of the + parent window (in which case, any child that is moved because + its parent has been resized generates an event). + + The structure for this event type contains: + + + +typedef struct { + int type; /* GravityNotify */ + unsigned long serial; /* # of last request processed by server +*/ + Bool send_event; /* true if this came from a SendEvent req +uest */ + Display *display; /* Display the event was read from */ + Window event; + Window window; + int x, y; +} XGravityEvent; + + The event member is set either to the window that was moved or + to its parent, depending on whether StructureNotify or + SubstructureNotify was selected. The window member is set to + the child window that was moved. The x and y members are set to + the coordinates relative to the new parent window's origin and + indicate the position of the upper-left outside corner of the + window. + +MapNotify Events + + The X server can report MapNotify events to clients wanting + information about which windows are mapped. The X server + generates this event type whenever a client application changes + the window's state from unmapped to mapped by calling + XMapWindow, XMapRaised, XMapSubwindows, XReparentWindow, or as + a result of save-set processing. + + To receive MapNotify events, set the StructureNotifyMask bit in + the event-mask attribute of the window or the + SubstructureNotifyMask bit in the event-mask attribute of the + parent window (in which case, mapping any child generates an + event). + + The structure for this event type contains: + + + +typedef struct { + int type; /* MapNotify */ + unsigned long serial; /* # of last request processed + by server */ + Bool send_event; /* true if this came from a Se +ndEvent request */ + Display *display; /* Display the event was read +from */ + Window event; + Window window; + Bool override_redirect; /* boolean, is override set... + */ +} XMapEvent; + + The event member is set either to the window that was mapped or + to its parent, depending on whether StructureNotify or + SubstructureNotify was selected. The window member is set to + the window that was mapped. The override_redirect member is set + to the override-redirect attribute of the window. Window + manager clients normally should ignore this window if the + override-redirect attribute is True, because these events + usually are generated from pop-ups, which override structure + control. + +MappingNotify Events + + The X server reports MappingNotify events to all clients. There + is no mechanism to express disinterest in this event. The X + server generates this event type whenever a client application + successfully calls: + * XSetModifierMapping to indicate which KeyCodes are to be + used as modifiers + * XChangeKeyboardMapping to change the keyboard mapping + * XSetPointerMapping to set the pointer mapping + + The structure for this event type contains: + + + +typedef struct { + int type; /* MappingNotify */ + unsigned long serial; /* # of last request processed by ser +ver */ + Bool send_event; /* true if this came from a SendEvent + request */ + Display *display; /* Display the event was read from */ + Window window; /* unused */ + int request; /* one of MappingModifier, MappingKey +board, + MappingPointer */ + int first_keycode; /* first keycode */ + int count; /* defines range of change w. first_k +eycode*/ +} XMappingEvent; + + The request member is set to indicate the kind of mapping + change that occurred and can be MappingModifier, + MappingKeyboard, or MappingPointer. If it is MappingModifier, + the modifier mapping was changed. If it is MappingKeyboard, the + keyboard mapping was changed. If it is MappingPointer, the + pointer button mapping was changed. The first_keycode and count + members are set only if the request member was set to + MappingKeyboard. The number in first_keycode represents the + first number in the range of the altered mapping, and count + represents the number of keycodes altered. + + To update the client application's knowledge of the keyboard, + you should call XRefreshKeyboardMapping. + +ReparentNotify Events + + The X server can report ReparentNotify events to clients + wanting information about changing a window's parent. The X + server generates this event whenever a client application calls + XReparentWindow and the window is actually reparented. + + To receive ReparentNotify events, set the StructureNotifyMask + bit in the event-mask attribute of the window or the + SubstructureNotifyMask bit in the event-mask attribute of + either the old or the new parent window (in which case, + reparenting any child generates an event). + + The structure for this event type contains: + + + +typedef struct { + int type; /* ReparentNotify */ + unsigned long serial; /* # of last request processed by server +*/ + Bool send_event; /* true if this came from a SendEvent req +uest */ + Display *display; /* Display the event was read from */ + Window event; + Window window; + Window parent; + int x, y; + Bool override_redirect; +} XReparentEvent; + + The event member is set either to the reparented window or to + the old or the new parent, depending on whether StructureNotify + or SubstructureNotify was selected. The window member is set to + the window that was reparented. The parent member is set to the + new parent window. The x and y members are set to the + reparented window's coordinates relative to the new parent + window's origin and define the upper-left outer corner of the + reparented window. The override_redirect member is set to the + override-redirect attribute of the window specified by the + window member. Window manager clients normally should ignore + this window if the override_redirect member is True. + +UnmapNotify Events + + The X server can report UnmapNotify events to clients wanting + information about which windows are unmapped. The X server + generates this event type whenever a client application changes + the window's state from mapped to unmapped. + + To receive UnmapNotify events, set the StructureNotifyMask bit + in the event-mask attribute of the window or the + SubstructureNotifyMask bit in the event-mask attribute of the + parent window (in which case, unmapping any child window + generates an event). + + The structure for this event type contains: + + + +typedef struct { + int type; /* UnmapNotify */ + unsigned long serial; /* # of last request processed by server +*/ + Bool send_event; /* true if this came from a SendEvent req +uest */ + Display *display; /* Display the event was read from */ + Window event; + Window window; + Bool from_configure; +} XUnmapEvent; + + The event member is set either to the unmapped window or to its + parent, depending on whether StructureNotify or + SubstructureNotify was selected. This is the window used by the + X server to report the event. The window member is set to the + window that was unmapped. The from_configure member is set to + True if the event was generated as a result of a resizing of + the window's parent when the window itself had a win_gravity of + UnmapGravity. + +VisibilityNotify Events + + The X server can report VisibilityNotify events to clients + wanting any change in the visibility of the specified window. A + region of a window is visible if someone looking at the screen + can actually see it. The X server generates this event whenever + the visibility changes state. However, this event is never + generated for windows whose class is InputOnly. + + All VisibilityNotify events caused by a hierarchy change are + generated after any hierarchy event (UnmapNotify, MapNotify, + ConfigureNotify, GravityNotify, CirculateNotify) caused by that + change. Any VisibilityNotify event on a given window is + generated before any Expose events on that window, but it is + not required that all VisibilityNotify events on all windows be + generated before all Expose events on all windows. The X + protocol does not constrain the ordering of VisibilityNotify + events with respect to FocusOut, EnterNotify, and LeaveNotify + events. + + To receive VisibilityNotify events, set the + VisibilityChangeMask bit in the event-mask attribute of the + window. + + The structure for this event type contains: + + + +typedef struct { + int type; /* VisibilityNotify */ + unsigned long serial; /* # of last request processed by server +*/ + Bool send_event; /* true if this came from a SendEvent req +uest */ + Display *display; /* Display the event was read from */ + Window window; + int state; +} XVisibilityEvent; + + The window member is set to the window whose visibility state + changes. The state member is set to the state of the window's + visibility and can be VisibilityUnobscured, + VisibilityPartiallyObscured, or VisibilityFullyObscured. The X + server ignores all of a window's subwindows when determining + the visibility state of the window and processes + VisibilityNotify events according to the following: + * When the window changes state from partially obscured, + fully obscured, or not viewable to viewable and completely + unobscured, the X server generates the event with the state + member of the XVisibilityEvent structure set to + VisibilityUnobscured. + * When the window changes state from viewable and completely + unobscured or not viewable to viewable and partially + obscured, the X server generates the event with the state + member of the XVisibilityEvent structure set to + VisibilityPartiallyObscured. + * When the window changes state from viewable and completely + unobscured, viewable and partially obscured, or not + viewable to viewable and fully obscured, the X server + generates the event with the state member of the + XVisibilityEvent structure set to VisibilityFullyObscured. + +Structure Control Events + + This section discusses: + * CirculateRequest events + * ConfigureRequest events + * MapRequest events + * ResizeRequest events + +CirculateRequest Events + + The X server can report CirculateRequest events to clients + wanting information about when another client initiates a + circulate window request on a specified window. The X server + generates this event type whenever a client initiates a + circulate window request on a window and a subwindow actually + needs to be restacked. The client initiates a circulate window + request on the window by calling XCirculateSubwindows, + XCirculateSubwindowsUp, or XCirculateSubwindowsDown. + + To receive CirculateRequest events, set the + SubstructureRedirectMask in the event-mask attribute of the + window. Then, in the future, the circulate window request for + the specified window is not executed, and thus, any subwindow's + position in the stack is not changed. For example, suppose a + client application calls XCirculateSubwindowsUp to raise a + subwindow to the top of the stack. If you had selected + SubstructureRedirectMask on the window, the X server reports to + you a CirculateRequest event and does not raise the subwindow + to the top of the stack. + + The structure for this event type contains: + + + +typedef struct { + int type; /* CirculateRequest */ + unsigned long serial; /* # of last request processed by server +*/ + Bool send_event; /* true if this came from a SendEvent req +uest */ + Display *display; /* Display the event was read from */ + Window parent; + Window window; + int place; /* PlaceOnTop, PlaceOnBottom */ +} XCirculateRequestEvent; + + The parent member is set to the parent window. The window + member is set to the subwindow to be restacked. The place + member is set to what the new position in the stacking order + should be and is either PlaceOnTop or PlaceOnBottom. If it is + PlaceOnTop, the subwindow should be on top of all siblings. If + it is PlaceOnBottom, the subwindow should be below all + siblings. + +ConfigureRequest Events + + The X server can report ConfigureRequest events to clients + wanting information about when a different client initiates a + configure window request on any child of a specified window. + The configure window request attempts to reconfigure a window's + size, position, border, and stacking order. The X server + generates this event whenever a different client initiates a + configure window request on a window by calling + XConfigureWindow, XLowerWindow, XRaiseWindow, XMapRaised, + XMoveResizeWindow, XMoveWindow, XResizeWindow, XRestackWindows, + or XSetWindowBorderWidth. + + To receive ConfigureRequest events, set the + SubstructureRedirectMask bit in the event-mask attribute of the + window. ConfigureRequest events are generated when a + ConfigureWindow protocol request is issued on a child window by + another client. For example, suppose a client application calls + XLowerWindow to lower a window. If you had selected + SubstructureRedirectMask on the parent window and if the + override-redirect attribute of the window is set to False, the + X server reports a ConfigureRequest event to you and does not + lower the specified window. + + The structure for this event type contains: + + + +typedef struct { + int type; /* ConfigureRequest */ + unsigned long serial; /* # of last request processed by serve +r */ + Bool send_event; /* true if this came from a SendEvent r +equest */ + Display *display; /* Display the event was read from */ + Window parent; + Window window; + int x, y; + int width, height; + int border_width; + Window above; + int detail; /* Above, Below, TopIf, BottomIf, Oppos +ite */ + unsigned long value_mask; +} XConfigureRequestEvent; + + The parent member is set to the parent window. The window + member is set to the window whose size, position, border width, + and/or stacking order is to be reconfigured. The value_mask + member indicates which components were specified in the + ConfigureWindow protocol request. The corresponding values are + reported as given in the request. The remaining values are + filled in from the current geometry of the window, except in + the case of above (sibling) and detail (stack-mode), which are + reported as None and Above, respectively, if they are not given + in the request. + +MapRequest Events + + The X server can report MapRequest events to clients wanting + information about a different client's desire to map windows. A + window is considered mapped when a map window request + completes. The X server generates this event whenever a + different client initiates a map window request on an unmapped + window whose override_redirect member is set to False. Clients + initiate map window requests by calling XMapWindow, XMapRaised, + or XMapSubwindows. + + To receive MapRequest events, set the SubstructureRedirectMask + bit in the event-mask attribute of the window. This means + another client's attempts to map a child window by calling one + of the map window request functions is intercepted, and you are + sent a MapRequest instead. For example, suppose a client + application calls XMapWindow to map a window. If you (usually a + window manager) had selected SubstructureRedirectMask on the + parent window and if the override-redirect attribute of the + window is set to False, the X server reports a MapRequest event + to you and does not map the specified window. Thus, this event + gives your window manager client the ability to control the + placement of subwindows. + + The structure for this event type contains: + + + +typedef struct { + int type; /* MapRequest */ + unsigned long serial; /* # of last request processed by server +*/ + Bool send_event; /* true if this came from a SendEvent req +uest */ + Display *display; /* Display the event was read from */ + Window parent; + Window window; +} XMapRequestEvent; + + The parent member is set to the parent window. The window + member is set to the window to be mapped. + +ResizeRequest Events + + The X server can report ResizeRequest events to clients wanting + information about another client's attempts to change the size + of a window. The X server generates this event whenever some + other client attempts to change the size of the specified + window by calling XConfigureWindow, XResizeWindow, or + XMoveResizeWindow. + + To receive ResizeRequest events, set the ResizeRedirect bit in + the event-mask attribute of the window. Any attempts to change + the size by other clients are then redirected. + + The structure for this event type contains: + + + +typedef struct { + int type; /* ResizeRequest */ + unsigned long serial; /* # of last request processed by server + */ + Bool send_event; /* true if this came from a SendEvent re +quest */ + Display *display; /* Display the event was read from */ + Window window; + int width, height; +} XResizeRequestEvent; + + The window member is set to the window whose size another + client attempted to change. The width and height members are + set to the inside size of the window, excluding the border. + +Colormap State Change Events + + The X server can report ColormapNotify events to clients + wanting information about when the colormap changes and when a + colormap is installed or uninstalled. The X server generates + this event type whenever a client application: + * Changes the colormap member of the XSetWindowAttributes + structure by calling XChangeWindowAttributes, + XFreeColormap, or XSetWindowColormap + * Installs or uninstalls the colormap by calling + XInstallColormap or XUninstallColormap + + To receive ColormapNotify events, set the ColormapChangeMask + bit in the event-mask attribute of the window. + + The structure for this event type contains: + + + +typedef struct { + int type; /* ColormapNotify */ + unsigned long serial; /* # of last request processed by server +*/ + Bool send_event; /* true if this came from a SendEvent req +uest */ + Display *display; /* Display the event was read from */ + Window window; + Colormap colormap; /* colormap or None */ + Bool new; + int state; /* ColormapInstalled, ColormapUninstalled + */ +} XColormapEvent; + + The window member is set to the window whose associated + colormap is changed, installed, or uninstalled. For a colormap + that is changed, installed, or uninstalled, the colormap member + is set to the colormap associated with the window. For a + colormap that is changed by a call to XFreeColormap, the + colormap member is set to None. The new member is set to + indicate whether the colormap for the specified window was + changed or installed or uninstalled and can be True or False. + If it is True, the colormap was changed. If it is False, the + colormap was installed or uninstalled. The state member is + always set to indicate whether the colormap is installed or + uninstalled and can be ColormapInstalled or + ColormapUninstalled. + +Client Communication Events + + This section discusses: + * ClientMessage events + * PropertyNotify events + * SelectionClear events + * SelectionNotify events + * SelectionRequest events + +ClientMessage Events + + The X server generates ClientMessage events only when a client + calls the function XSendEvent. + + The structure for this event type contains: + + + +typedef struct { + int type; /* ClientMessage */ + unsigned long serial; /* # of last request processed by ser +ver */ + Bool send_event; /* true if this came from a SendEvent + request */ + Display *display; /* Display the event was read from */ + Window window; + Atom message_type; + int format; + union { + char b[20]; + short s[10]; + long l[5]; + } data; +} XClientMessageEvent; + + The message_type member is set to an atom that indicates how + the data should be interpreted by the receiving client. The + format member is set to 8, 16, or 32 and specifies whether the + data should be viewed as a list of bytes, shorts, or longs. The + data member is a union that contains the members b, s, and l. + The b, s, and l members represent data of twenty 8-bit values, + ten 16-bit values, and five 32-bit values. Particular message + types might not make use of all these values. The X server + places no interpretation on the values in the window, + message_type, or data members. + +PropertyNotify Events + + The X server can report PropertyNotify events to clients + wanting information about property changes for a specified + window. + + To receive PropertyNotify events, set the PropertyChangeMask + bit in the event-mask attribute of the window. + + The structure for this event type contains: + + + +typedef struct { + int type; /* PropertyNotify */ + unsigned long serial; /* # of last request processed by server +*/ + Bool send_event; /* true if this came from a SendEvent req +uest */ + Display *display; /* Display the event was read from */ + Window window; + Atom atom; + Time time; + int state; /* PropertyNewValue or PropertyDelete */ +} XPropertyEvent; + + The window member is set to the window whose associated + property was changed. The atom member is set to the property's + atom and indicates which property was changed or desired. The + time member is set to the server time when the property was + changed. The state member is set to indicate whether the + property was changed to a new value or deleted and can be + PropertyNewValue or PropertyDelete. The state member is set to + PropertyNewValue when a property of the window is changed using + XChangeProperty or XRotateWindowProperties (even when adding + zero-length data using XChangeProperty) and when replacing all + or part of a property with identical data using XChangeProperty + or XRotateWindowProperties. The state member is set to + PropertyDelete when a property of the window is deleted using + XDeleteProperty or, if the delete argument is True, + XGetWindowProperty. + +SelectionClear Events + + The X server reports SelectionClear events to the client losing + ownership of a selection. The X server generates this event + type when another client asserts ownership of the selection by + calling XSetSelectionOwner. + + The structure for this event type contains: + + + +typedef struct { + int type; /* SelectionClear */ + unsigned long serial; /* # of last request processed by server +*/ + Bool send_event; /* true if this came from a SendEvent req +uest */ + Display *display; /* Display the event was read from */ + Window window; + Atom selection; + Time time; +} XSelectionClearEvent; + + The selection member is set to the selection atom. The time + member is set to the last change time recorded for the + selection. The window member is the window that was specified + by the current owner (the owner losing the selection) in its + XSetSelectionOwner call. + +SelectionRequest Events + + The X server reports SelectionRequest events to the owner of a + selection. The X server generates this event whenever a client + requests a selection conversion by calling XConvertSelection + for the owned selection. + + The structure for this event type contains: + + + +typedef struct { + int type; /* SelectionRequest */ + unsigned long serial; /* # of last request processed by server +*/ + Bool send_event; /* true if this came from a SendEvent req +uest */ + Display *display; /* Display the event was read from */ + Window owner; + Window requestor; + Atom selection; + Atom target; + Atom property; + Time time; +} XSelectionRequestEvent; + + The owner member is set to the window that was specified by the + current owner in its XSetSelectionOwner call. The requestor + member is set to the window requesting the selection. The + selection member is set to the atom that names the selection. + For example, PRIMARY is used to indicate the primary selection. + The target member is set to the atom that indicates the type + the selection is desired in. The property member can be a + property name or None. The time member is set to the timestamp + or CurrentTime value from the ConvertSelection request. + + The owner should convert the selection based on the specified + target type and send a SelectionNotify event back to the + requestor. A complete specification for using selections is + given in the X Consortium standard Inter-Client Communication + Conventions Manual. + +SelectionNotify Events + + This event is generated by the X server in response to a + ConvertSelection protocol request when there is no owner for + the selection. When there is an owner, it should be generated + by the owner of the selection by using XSendEvent. The owner of + a selection should send this event to a requestor when a + selection has been converted and stored as a property or when a + selection conversion could not be performed (which is indicated + by setting the property member to None). + + If None is specified as the property in the ConvertSelection + protocol request, the owner should choose a property name, + store the result as that property on the requestor window, and + then send a SelectionNotify giving that actual property name. + + The structure for this event type contains: + + + +typedef struct { + int type; /* SelectionNotify */ + unsigned long serial; /* # of last request processed by server +*/ + Bool send_event; /* true if this came from a SendEvent req +uest */ + Display *display; /* Display the event was read from */ + Window requestor; + Atom selection; + Atom target; + Atom property; /* atom or None */ + Time time; +} XSelectionEvent; + + The requestor member is set to the window associated with the + requestor of the selection. The selection member is set to the + atom that indicates the selection. For example, PRIMARY is used + for the primary selection. The target member is set to the atom + that indicates the converted type. For example, PIXMAP is used + for a pixmap. The property member is set to the atom that + indicates which property the result was stored on. If the + conversion failed, the property member is set to None. The time + member is set to the time the conversion took place and can be + a timestamp or CurrentTime. + +Chapter 11. Event Handling Functions + + Table of Contents + + Selecting Events + Handling the Output Buffer + Event Queue Management + Manipulating the Event Queue + + Returning the Next Event + Selecting Events Using a Predicate Procedure + Selecting Events Using a Window or Event Mask + + Putting an Event Back into the Queue + Sending Events to Other Applications + Getting Pointer Motion History + Handling Protocol Errors + + Enabling or Disabling Synchronization + Using the Default Error Handlers + + This chapter discusses the Xlib functions you can use to: + * Select events + * Handle the output buffer and the event queue + * Select events from the event queue + * Send and get events + * Handle protocol errors + +Note + + Some toolkits use their own event-handling functions and do not + allow you to interchange these event-handling functions with + those in Xlib. For further information, see the documentation + supplied with the toolkit. + + Most applications simply are event loops: they wait for an + event, decide what to do with it, execute some amount of code + that results in changes to the display, and then wait for the + next event. + +Selecting Events + + There are two ways to select the events you want reported to + your client application. One way is to set the event_mask + member of the XSetWindowAttributes structure when you call + XCreateWindow and XChangeWindowAttributes. Another way is to + use XSelectInput. + + XSelectInput(Display *display, Window w, long event_mask); + + display + + Specifies the connection to the X server. + + w + + Specifies the window whose events you are interested in. + + event_mask + + Specifies the event mask. + + The XSelectInput function requests that the X server report the + events associated with the specified event mask. Initially, X + will not report any of these events. Events are reported + relative to a window. If a window is not interested in a device + event, it usually propagates to the closest ancestor that is + interested, unless the do_not_propagate mask prohibits it. + + Setting the event-mask attribute of a window overrides any + previous call for the same window but not for other clients. + Multiple clients can select for the same events on the same + window with the following restrictions: + * Multiple clients can select events on the same window + because their event masks are disjoint. When the X server + generates an event, it reports it to all interested + clients. + * Only one client at a time can select CirculateRequest, + ConfigureRequest, or MapRequest events, which are + associated with the event mask SubstructureRedirectMask. + * Only one client at a time can select a ResizeRequest event, + which is associated with the event mask ResizeRedirectMask. + * Only one client at a time can select a ButtonPress event, + which is associated with the event mask ButtonPressMask. + + The server reports the event to all interested clients. + + XSelectInput can generate a BadWindow error. + +Handling the Output Buffer + + The output buffer is an area used by Xlib to store requests. + The functions described in this section flush the output buffer + if the function would block or not return an event. That is, + all requests residing in the output buffer that have not yet + been sent are transmitted to the X server. These functions + differ in the additional tasks they might perform. + + To flush the output buffer, use XFlush. + + XFlush(Display *display); + + display + + Specifies the connection to the X server. + + The XFlush function flushes the output buffer. Most client + applications need not use this function because the output + buffer is automatically flushed as needed by calls to XPending, + XNextEvent, and XWindowEvent. Events generated by the server + may be enqueued into the library's event queue. + + To flush the output buffer and then wait until all requests + have been processed, use XSync. + + XSync(Display *display, Bool discard); + + display + + Specifies the connection to the X server. + + discard + + Specifies a Boolean value that indicates whether XSync discards + all events on the event queue. + + The XSync function flushes the output buffer and then waits + until all requests have been received and processed by the X + server. Any errors generated must be handled by the error + handler. For each protocol error received by Xlib, XSync calls + the client application's error handling routine (see section + 11.8.2). Any events generated by the server are enqueued into + the library's event queue. + + Finally, if you passed False, XSync does not discard the events + in the queue. If you passed True, XSync discards all events in + the queue, including those events that were on the queue before + XSync was called. Client applications seldom need to call + XSync. + +Event Queue Management + + Xlib maintains an event queue. However, the operating system + also may be buffering data in its network connection that is + not yet read into the event queue. + + To check the number of events in the event queue, use + XEventsQueued. + + int XEventsQueued(Display *display, int mode); + + display + + Specifies the connection to the X server. + + mode + + Specifies the mode. You can pass QueuedAlready, + QueuedAfterFlush, or QueuedAfterReading. + + If mode is QueuedAlready, XEventsQueued returns the number of + events already in the event queue (and never performs a system + call). If mode is QueuedAfterFlush, XEventsQueued returns the + number of events already in the queue if the number is nonzero. + If there are no events in the queue, XEventsQueued flushes the + output buffer, attempts to read more events out of the + application's connection, and returns the number read. If mode + is QueuedAfterReading, XEventsQueued returns the number of + events already in the queue if the number is nonzero. If there + are no events in the queue, XEventsQueued attempts to read more + events out of the application's connection without flushing the + output buffer and returns the number read. + + XEventsQueued always returns immediately without I/O if there + are events already in the queue. XEventsQueued with mode + QueuedAfterFlush is identical in behavior to XPending. + XEventsQueued with mode QueuedAlready is identical to the + XQLength function. + + To return the number of events that are pending, use XPending. + + int XPending(Display *display); + + display + + Specifies the connection to the X server. + + The XPending function returns the number of events that have + been received from the X server but have not been removed from + the event queue. XPending is identical to XEventsQueued with + the mode QueuedAfterFlush specified. + +Manipulating the Event Queue + + Xlib provides functions that let you manipulate the event + queue. This section discusses how to: + * Obtain events, in order, and remove them from the queue + * Peek at events in the queue without removing them + * Obtain events that match the event mask or the arbitrary + predicate procedures that you provide + +Returning the Next Event + + To get the next event and remove it from the queue, use + XNextEvent. + + XNextEvent(Display *display, XEvent *event_return); + + display + + Specifies the connection to the X server. + + event_return + + Returns the next event in the queue. + + The XNextEvent function copies the first event from the event + queue into the specified XEvent structure and then removes it + from the queue. If the event queue is empty, XNextEvent flushes + the output buffer and blocks until an event is received. + + To peek at the event queue, use XPeekEvent. + + XPeekEvent(Display *display, XEvent *event_return); + + display + + Specifies the connection to the X server. + + event_return + + Returns a copy of the matched event's associated structure. + + The XPeekEvent function returns the first event from the event + queue, but it does not remove the event from the queue. If the + queue is empty, XPeekEvent flushes the output buffer and blocks + until an event is received. It then copies the event into the + client-supplied XEvent structure without removing it from the + event queue. + +Selecting Events Using a Predicate Procedure + + Each of the functions discussed in this section requires you to + pass a predicate procedure that determines if an event matches + what you want. Your predicate procedure must decide if the + event is useful without calling any Xlib functions. If the + predicate directly or indirectly causes the state of the event + queue to change, the result is not defined. If Xlib has been + initialized for threads, the predicate is called with the + display locked and the result of a call by the predicate to any + Xlib function that locks the display is not defined unless the + caller has first called XLockDisplay. + + The predicate procedure and its associated arguments are: + + Bool(Display *display, XEvent *event, XPointer arg); + + display + + Specifies the connection to the X server. + + event + + Specifies the XEvent structure. + + arg + + Specifies the argument passed in from the XIfEvent, + XCheckIfEvent, or XPeekIfEvent function. + + The predicate procedure is called once for each event in the + queue until it finds a match. After finding a match, the + predicate procedure must return True. If it did not find a + match, it must return False. + + To check the event queue for a matching event and, if found, + remove the event from the queue, use XIfEvent. + + XIfEvent(Display *display, XEvent *event_return, Bool + (*predicate)(), XPointer arg); + + display + + Specifies the connection to the X server. + + event_return + + Returns the matched event's associated structure. + + predicate + + Specifies the procedure that is to be called to determine if + the next event in the queue matches what you want. + + arg + + Specifies the user-supplied argument that will be passed to the + predicate procedure. + + The XIfEvent function completes only when the specified + predicate procedure returns True for an event, which indicates + an event in the queue matches. XIfEvent flushes the output + buffer if it blocks waiting for additional events. XIfEvent + removes the matching event from the queue and copies the + structure into the client-supplied XEvent structure. + + To check the event queue for a matching event without blocking, + use XCheckIfEvent. + + Bool XCheckIfEvent(Display *display, XEvent *event_return, Bool + (*predicate)(), XPointer arg); + + display + + Specifies the connection to the X server. + + event_return + + Returns a copy of the matched event's associated structure. + + predicate + + Specifies the procedure that is to be called to determine if + the next event in the queue matches what you want. + + arg + + Specifies the user-supplied argument that will be passed to the + predicate procedure. + + When the predicate procedure finds a match, XCheckIfEvent + copies the matched event into the client-supplied XEvent + structure and returns True. (This event is removed from the + queue.) If the predicate procedure finds no match, + XCheckIfEvent returns False, and the output buffer will have + been flushed. All earlier events stored in the queue are not + discarded. + + To check the event queue for a matching event without removing + the event from the queue, use XPeekIfEvent. + + XPeekIfEvent(Display *display, XEvent *event_return, Bool + (*predicate)(), XPointer arg); + + display + + Specifies the connection to the X server. + + event_return + + Returns a copy of the matched event's associated structure. + + predicate + + Specifies the procedure that is to be called to determine if + the next event in the queue matches what you want. + + arg + + Specifies the user-supplied argument that will be passed to the + predicate procedure. + + The XPeekIfEvent function returns only when the specified + predicate procedure returns True for an event. After the + predicate procedure finds a match, XPeekIfEvent copies the + matched event into the client-supplied XEvent structure without + removing the event from the queue. XPeekIfEvent flushes the + output buffer if it blocks waiting for additional events. + +Selecting Events Using a Window or Event Mask + + The functions discussed in this section let you select events + by window or event types, allowing you to process events out of + order. + + To remove the next event that matches both a window and an + event mask, use XWindowEvent. + + XWindowEvent(Display *display, Window w, long event_mask, + XEvent *event_return); + + display + + Specifies the connection to the X server. + + w + + Specifies the window whose events you are interested in. + + event_mask + + Specifies the event mask. + + event_return + + Returns the matched event's associated structure. + + The XWindowEvent function searches the event queue for an event + that matches both the specified window and event mask. When it + finds a match, XWindowEvent removes that event from the queue + and copies it into the specified XEvent structure. The other + events stored in the queue are not discarded. If a matching + event is not in the queue, XWindowEvent flushes the output + buffer and blocks until one is received. + + To remove the next event that matches both a window and an + event mask (if any), use XCheckWindowEvent. This function is + similar to XWindowEvent except that it never blocks and it + returns a Bool indicating if the event was returned. + + Bool XCheckWindowEvent(Display *display, Window w, long + event_mask, XEvent *event_return); + + display + + Specifies the connection to the X server. + + w + + Specifies the window whose events you are interested in. + + event_mask + + Specifies the event mask. + + event_return + + Returns the matched event's associated structure. + + The XCheckWindowEvent function searches the event queue and + then the events available on the server connection for the + first event that matches the specified window and event mask. + If it finds a match, XCheckWindowEvent removes that event, + copies it into the specified XEvent structure, and returns + True. The other events stored in the queue are not discarded. + If the event you requested is not available, XCheckWindowEvent + returns False, and the output buffer will have been flushed. + + To remove the next event that matches an event mask, use + XMaskEvent. + + XMaskEvent(Display *display, long event_mask, XEvent + *event_return); + + display + + Specifies the connection to the X server. + + event_mask + + Specifies the event mask. + + event_return + + Returns the matched event's associated structure. + + The XMaskEvent function searches the event queue for the events + associated with the specified mask. When it finds a match, + XMaskEvent removes that event and copies it into the specified + XEvent structure. The other events stored in the queue are not + discarded. If the event you requested is not in the queue, + XMaskEvent flushes the output buffer and blocks until one is + received. + + To return and remove the next event that matches an event mask + (if any), use XCheckMaskEvent. This function is similar to + XMaskEvent except that it never blocks and it returns a Bool + indicating if the event was returned. + + Bool XCheckMaskEvent(Display *display, long event_mask, XEvent + *event_return); + + display + + Specifies the connection to the X server. + + event_mask + + Specifies the event mask. + + event_return + + Returns the matched event's associated structure. + + The XCheckMaskEvent function searches the event queue and then + any events available on the server connection for the first + event that matches the specified mask. If it finds a match, + XCheckMaskEvent removes that event, copies it into the + specified XEvent structure, and returns True. The other events + stored in the queue are not discarded. If the event you + requested is not available, XCheckMaskEvent returns False, and + the output buffer will have been flushed. + + To return and remove the next event in the queue that matches + an event type, use XCheckTypedEvent. + + Bool XCheckTypedEvent(Display *display, int event_type, XEvent + *event_return); + + display + + Specifies the connection to the X server. + + event_type + + Specifies the event type to be compared. + + event_return + + Returns the matched event's associated structure. + + The XCheckTypedEvent function searches the event queue and then + any events available on the server connection for the first + event that matches the specified type. If it finds a match, + XCheckTypedEvent removes that event, copies it into the + specified XEvent structure, and returns True. The other events + in the queue are not discarded. If the event is not available, + XCheckTypedEvent returns False, and the output buffer will have + been flushed. + + To return and remove the next event in the queue that matches + an event type and a window, use XCheckTypedWindowEvent. + + Bool XCheckTypedWindowEvent(Display *display, Window w, int + event_type, XEvent *event_return); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + event_type + + Specifies the event type to be compared. + + event_return + + Returns the matched event's associated structure. + + The XCheckTypedWindowEvent function searches the event queue + and then any events available on the server connection for the + first event that matches the specified type and window. If it + finds a match, XCheckTypedWindowEvent removes the event from + the queue, copies it into the specified XEvent structure, and + returns True. The other events in the queue are not discarded. + If the event is not available, XCheckTypedWindowEvent returns + False, and the output buffer will have been flushed. + +Putting an Event Back into the Queue + + To push an event back into the event queue, use XPutBackEvent. + + XPutBackEvent(Display *display, XEvent *event); + + display + + Specifies the connection to the X server. + + event + + Specifies the event. + + The XPutBackEvent function pushes an event back onto the head + of the display's event queue by copying the event into the + queue. This can be useful if you read an event and then decide + that you would rather deal with it later. There is no limit to + the number of times in succession that you can call + XPutBackEvent. + +Sending Events to Other Applications + + To send an event to a specified window, use XSendEvent. This + function is often used in selection processing. For example, + the owner of a selection should use XSendEvent to send a + SelectionNotify event to a requestor when a selection has been + converted and stored as a property. + + Status XSendEvent(Display *display, Window w, Bool propagate, + long event_mask, XEvent *event_send); + + display + + Specifies the connection to the X server. + + w + + Specifies the window the event is to be sent to, or + PointerWindow, or InputFocus. + + propagate + + Specifies a Boolean value. + + event_mask + + Specifies the event mask. + + event_send + + Specifies the event that is to be sent. + + The XSendEvent function identifies the destination window, + determines which clients should receive the specified events, + and ignores any active grabs. This function requires you to + pass an event mask. For a discussion of the valid event mask + names, see section 10.3. This function uses the w argument to + identify the destination window as follows: + * If w is PointerWindow, the destination window is the window + that contains the pointer. + * If w is InputFocus and if the focus window contains the + pointer, the destination window is the window that contains + the pointer; otherwise, the destination window is the focus + window. + + To determine which clients should receive the specified events, + XSendEvent uses the propagate argument as follows: + * If event_mask is the empty set, the event is sent to the + client that created the destination window. If that client + no longer exists, no event is sent. + * If propagate is False, the event is sent to every client + selecting on destination any of the event types in the + event_mask argument. + * If propagate is True and no clients have selected on + destination any of the event types in event-mask, the + destination is replaced with the closest ancestor of + destination for which some client has selected a type in + event-mask and for which no intervening window has that + type in its do-not-propagate-mask. If no such window exists + or if the window is an ancestor of the focus window and + InputFocus was originally specified as the destination, the + event is not sent to any clients. Otherwise, the event is + reported to every client selecting on the final destination + any of the types specified in event_mask. + + The event in the XEvent structure must be one of the core + events or one of the events defined by an extension (or a + BadValue error results) so that the X server can correctly + byte-swap the contents as necessary. The contents of the event + are otherwise unaltered and unchecked by the X server except to + force send_event to True in the forwarded event and to set the + serial number in the event correctly; therefore these fields + and the display field are ignored by XSendEvent. + + XSendEvent returns zero if the conversion to wire protocol + format failed and returns nonzero otherwise. + + XSendEvent can generate BadValue and BadWindow errors. + +Getting Pointer Motion History + + Some X server implementations will maintain a more complete + history of pointer motion than is reported by event + notification. The pointer position at each pointer hardware + interrupt may be stored in a buffer for later retrieval. This + buffer is called the motion history buffer. For example, a few + applications, such as paint programs, want to have a precise + history of where the pointer traveled. However, this historical + information is highly excessive for most applications. + + To determine the approximate maximum number of elements in the + motion buffer, use XDisplayMotionBufferSize. + + unsigned long(Display *display); + + display + + Specifies the connection to the X server. + + The server may retain the recent history of the pointer motion + and do so to a finer granularity than is reported by + MotionNotify events. The function makes this history available. + + To get the motion history for a specified window and time, use + . + + XTimeCoord *XGetMotionEvents(Display *display, Window w, Time + start, Time stop, int *nevents_return); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + start + + stop + + Specify the time interval in which the events are returned from + the motion history buffer. You can pass a timestamp or + CurrentTime. + + nevents_return + + Returns the number of events from the motion history buffer. + + The function returns all events in the motion history buffer + that fall between the specified start and stop times, + inclusive, and that have coordinates that lie within the + specified window (including its borders) at its present + placement. If the server does not support motion history, if + the start time is later than the stop time, or if the start + time is in the future, no events are returned; returns NULL. If + the stop time is in the future, it is equivalent to specifying + CurrentTime. The return type for this function is a structure + defined as follows: + + + +typedef struct { + Time time; + short x, y; +} XTimeCoord; + + The time member is set to the time, in milliseconds. The x and + y members are set to the coordinates of the pointer and are + reported relative to the origin of the specified window. To + free the data returned from this call, use XFree. + + can generate a BadWindow error. + +Handling Protocol Errors + + Xlib provides functions that you can use to enable or disable + synchronization and to use the default error handlers. + +Enabling or Disabling Synchronization + + When debugging X applications, it often is very convenient to + require Xlib to behave synchronously so that errors are + reported as they occur. The following function lets you disable + or enable synchronous behavior. Note that graphics may occur 30 + or more times more slowly when synchronization is enabled. On + POSIX-conformant systems, there is also a global variable + _Xdebug that, if set to nonzero before starting a program under + a debugger, will force synchronous library behavior. + + After completing their work, all Xlib functions that generate + protocol requests call what is known as an after function. sets + which function is to be called. + + int(Display *display, int (*procedure)()); + + display + + Specifies the connection to the X server. + + procedure + + Specifies the procedure to be called. + + The specified procedure is called with only a display pointer. + returns the previous after function. + + To enable or disable synchronization, use XSynchronize. + + int(Display *display, Bool onoff); + + display + + Specifies the connection to the X server. + + onoff + + Specifies a Boolean value that indicates whether to enable or + disable synchronization. + + The XSynchronize function returns the previous after function. + If onoff is True, XSynchronize turns on synchronous behavior. + If onoff is False, XSynchronize turns off synchronous behavior. + +Using the Default Error Handlers + + There are two default error handlers in Xlib: one to handle + typically fatal conditions (for example, the connection to a + display server dying because a machine crashed) and one to + handle protocol errors from the X server. These error handlers + can be changed to user-supplied routines if you prefer your own + error handling and can be changed as often as you like. If + either function is passed a NULL pointer, it will reinvoke the + default handler. The action of the default handlers is to print + an explanatory message and exit. + + To set the error handler, use XSetErrorHandler. + + int *XSetErrorHandler(int *handler); + + handler + + Specifies the program's supplied error handler. + + Xlib generally calls the program's supplied error handler + whenever an error is received. It is not called on BadName + errors from OpenFont, LookupColor, or AllocNamedColor protocol + requests or on BadFont errors from a QueryFont protocol + request. These errors generally are reflected back to the + program through the procedural interface. Because this + condition is not assumed to be fatal, it is acceptable for your + error handler to return; the returned value is ignored. + However, the error handler should not call any functions + (directly or indirectly) on the display that will generate + protocol requests or that will look for input events. The + previous error handler is returned. + + The XErrorEvent structure contains: + + + +typedef struct { + int type; + Display *display; /* Display the event was read from */ + unsigned long serial; /* serial number of failed reque +st */ + unsigned char error_code; /* error code of failed request +*/ + unsigned char request_code; /* Major op-code of failed reque +st */ + unsigned char minor_code; /* Minor op-code of failed reque +st */ + XID resourceid; /* resource id */ +} XErrorEvent; + + The serial member is the number of requests, starting from one, + sent over the network connection since it was opened. It is the + number that was the value of NextRequest immediately before the + failing call was made. The request_code member is a protocol + request of the procedure that failed, as defined in + . The following error codes can be returned by + the functions described in this chapter: + Error Code Description + BadAccess + + A client attempts to grab a key/button combination already + grabbed by another client. + + A client attempts to free a colormap entry that it had not + already allocated or to free an entry in a colormap that was + created with all entries writable. + + A client attempts to store into a read-only or unallocated + colormap entry. + + A client attempts to modify the access control list from other + than the local (or otherwise authorized) host. + + A client attempts to select an event type that another client + has already selected. + BadAlloc The server fails to allocate the requested resource. + Note that the explicit listing of BadAlloc errors in requests + only covers allocation errors at a very coarse level and is not + intended to (nor can it in practice hope to) cover all cases of + a server running out of allocation space in the middle of + service. The semantics when a server runs out of allocation + space are left unspecified, but a server may generate a + BadAlloc error on any request for this reason, and clients + should be prepared to receive such errors and handle or discard + them. + BadAtom A value for an atom argument does not name a defined + atom. + BadColor A value for a colormap argument does not name a + defined colormap. + BadCursor A value for a cursor argument does not name a defined + cursor. + BadDrawable A value for a drawable argument does not name a + defined window or pixmap. + BadFont A value for a font argument does not name a defined + font (or, in some cases, GContext). + BadGC A value for a GContext argument does not name a defined + GContext. + BadIDChoice The value chosen for a resource identifier either + is not included in the range assigned to the client or is + already in use. Under normal circumstances, this cannot occur + and should be considered a server or Xlib error. + BadImplementation The server does not implement some aspect of + the request. A server that generates this error for a core + request is deficient. As such, this error is not listed for any + of the requests, but clients should be prepared to receive such + errors and handle or discard them. + BadLength + + The length of a request is shorter or longer than that required + to contain the arguments. This is an internal Xlib or server + error. + + The length of a request exceeds the maximum length accepted by + the server. + BadMatch + + In a graphics request, the root and depth of the graphics + context do not match those of the drawable. + + An InputOnly window is used as a drawable. + + Some argument or pair of arguments has the correct type and + range, but it fails to match in some other way required by the + request. + + An InputOnly window lacks this attribute. + BadName A font or color of the specified name does not exist. + BadPixmap A value for a pixmap argument does not name a defined + pixmap. + BadRequest The major or minor opcode does not specify a valid + request. This usually is an Xlib or server error. + BadValue Some numeric value falls outside of the range of + values accepted by the request. Unless a specific range is + specified for an argument, the full range defined by the + argument's type is accepted. Any argument defined as a set of + alternatives typically can generate this error (due to the + encoding). + BadWindow A value for a window argument does not name a defined + window. + +Note + + The BadAtom, BadColor, BadCursor, BadDrawable, BadFont, BadGC, + BadPixmap, and BadWindow errors are also used when the argument + type is extended by a set of fixed alternatives. + + To obtain textual descriptions of the specified error code, use + XGetErrorText. + + XGetErrorText(Display *display, int code, char *buffer_return, + int length); + + display + + Specifies the connection to the X server. + + code + + Specifies the error code for which you want to obtain a + description. + + buffer_return + + Returns the error description. + + length + + Specifies the size of the buffer. + + The XGetErrorText function copies a null-terminated string + describing the specified error code into the specified buffer. + The returned text is in the encoding of the current locale. It + is recommended that you use this function to obtain an error + description because extensions to Xlib may define their own + error codes and error strings. + + To obtain error messages from the error database, use + XGetErrorDatabaseText. + + XGetErrorDatabaseText(Display *display, char *name, char + *message, char *default_string, char *buffer_return, int + length); + + display + + Specifies the connection to the X server. + + name + + Specifies the name of the application. + + message + + Specifies the type of the error message. + + default_string + + Specifies the default error message if none is found in the + database. + + buffer_return + + Returns the error description. + + length + + Specifies the size of the buffer. + + The XGetErrorDatabaseText function returns a null-terminated + message (or the default message) from the error message + database. Xlib uses this function internally to look up its + error messages. The text in the default_string argument is + assumed to be in the encoding of the current locale, and the + text stored in the buffer_return argument is in the encoding of + the current locale. + + The name argument should generally be the name of your + application. The message argument should indicate which type of + error message you want. If the name and message are not in the + Host Portable Character Encoding, the result is + implementation-dependent. Xlib uses three predefined + ``application names'' to report errors. In these names, + uppercase and lowercase matter. + + XProtoError + + The protocol error number is used as a string for the message + argument. + + XlibMessage + + These are the message strings that are used internally by the + library. + + XRequest + + For a core protocol request, the major request protocol number + is used for the message argument. For an extension request, the + extension name (as given by InitExtension) followed by a period + (.) and the minor request protocol number is used for the + message argument. If no string is found in the error database, + the default_string is returned to the buffer argument. + + To report an error to the user when the requested display does + not exist, use XDisplayName. + + char *XDisplayName(char *string); + + string + + Specifies the character string. + + The XDisplayName function returns the name of the display that + XOpenDisplay would attempt to use. If a NULL string is + specified, XDisplayName looks in the environment for the + display and returns the display name that XOpenDisplay would + attempt to use. This makes it easier to report to the user + precisely which display the program attempted to open when the + initial connection attempt failed. + + To handle fatal I/O errors, use XSetIOErrorHandler. + + int(int(*handler)(Display *)); + + handler + + Specifies the program's supplied error handler. + + The XSetIOErrorHandler sets the fatal I/O error handler. Xlib + calls the program's supplied error handler if any sort of + system call error occurs (for example, the connection to the + server was lost). This is assumed to be a fatal condition, and + the called routine should not return. If the I/O error handler + does return, the client process exits. + + Note that the previous error handler is returned. + +Chapter 12. Input Device Functions + + Table of Contents + + Pointer Grabbing + Keyboard Grabbing + Resuming Event Processing + Moving the Pointer + Controlling Input Focus + Manipulating the Keyboard and Pointer Settings + Manipulating the Keyboard Encoding + + You can use the Xlib input device functions to: + * Grab the pointer and individual buttons on the pointer + * Grab the keyboard and individual keys on the keyboard + * Resume event processing + * Move the pointer + * Set the input focus + * Manipulate the keyboard and pointer settings + * Manipulate the keyboard encoding + +Pointer Grabbing + + Xlib provides functions that you can use to control input from + the pointer, which usually is a mouse. Usually, as soon as + keyboard and mouse events occur, the X server delivers them to + the appropriate client, which is determined by the window and + input focus. The X server provides sufficient control over + event delivery to allow window managers to support mouse ahead + and various other styles of user interface. Many of these user + interfaces depend on synchronous delivery of events. The + delivery of pointer and keyboard events can be controlled + independently. + + When mouse buttons or keyboard keys are grabbed, events will be + sent to the grabbing client rather than the normal client who + would have received the event. If the keyboard or pointer is in + asynchronous mode, further mouse and keyboard events will + continue to be processed. If the keyboard or pointer is in + synchronous mode, no further events are processed until the + grabbing client allows them (see XAllowEvents). The keyboard or + pointer is considered frozen during this interval. The event + that triggered the grab can also be replayed. + + Note that the logical state of a device (as seen by client + applications) may lag the physical state if device event + processing is frozen. + + There are two kinds of grabs: active and passive. An active + grab occurs when a single client grabs the keyboard and/or + pointer explicitly (see XGrabPointer and XGrabKeyboard). A + passive grab occurs when clients grab a particular keyboard key + or pointer button in a window, and the grab will activate when + the key or button is actually pressed. Passive grabs are + convenient for implementing reliable pop-up menus. For example, + you can guarantee that the pop-up is mapped before the up + pointer button event occurs by grabbing a button requesting + synchronous behavior. The down event will trigger the grab and + freeze further processing of pointer events until you have the + chance to map the pop-up window. You can then allow further + event processing. The up event will then be correctly processed + relative to the pop-up window. + + For many operations, there are functions that take a time + argument. The X server includes a timestamp in various events. + One special time, called CurrentTime, represents the current + server time. The X server maintains the time when the input + focus was last changed, when the keyboard was last grabbed, + when the pointer was last grabbed, or when a selection was last + changed. Your application may be slow reacting to an event. You + often need some way to specify that your request should not + occur if another application has in the meanwhile taken control + of the keyboard, pointer, or selection. By providing the + timestamp from the event in the request, you can arrange that + the operation not take effect if someone else has performed an + operation in the meanwhile. + + A timestamp is a time value, expressed in milliseconds. It + typically is the time since the last server reset. Timestamp + values wrap around (after about 49.7 days). The server, given + its current time is represented by timestamp T, always + interprets timestamps from clients by treating half of the + timestamp space as being later in time than T. One timestamp + value, named CurrentTime, is never generated by the server. + This value is reserved for use in requests to represent the + current server time. + + For many functions in this section, you pass pointer event mask + bits. The valid pointer event mask bits are: ButtonPressMask, + ButtonReleaseMask, EnterWindowMask, LeaveWindowMask, + PointerMotionMask, PointerMotionHintMask, Button1MotionMask, + Button2MotionMask, Button3MotionMask, Button4MotionMask, + Button5MotionMask, ButtonMotionMask, and KeymapStateMask. For + other functions in this section, you pass keymask bits. The + valid keymask bits are: ShiftMask, LockMask, ControlMask, + Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, and Mod5Mask. + + To grab the pointer, use XGrabPointer. + + int XGrabPointer(Display *display, Window grab_window, Bool + owner_events, unsigned int event_mask, int pointer_mode, int + keyboard_mode, Window confine_to, Cursor cursor, Time time); + + display + + Specifies the connection to the X server. + + grab_window + + Specifies the grab window. + + owner_events + + Specifies a Boolean value that indicates whether the pointer + events are to be reported as usual or reported with respect to + the grab window if selected by the event mask. + + event_mask + + Specifies which pointer events are reported to the client. The + mask is the bitwise inclusive OR of the valid pointer event + mask bits. + + pointer_mode + + Specifies further processing of pointer events. You can pass + GrabModeSync or GrabModeAsync. + + keyboard_mode + + Specifies further processing of keyboard events. You can pass + GrabModeSync or GrabModeAsync. + + confine_to + + Specifies the window to confine the pointer in or None. + + cursor + + Specifies the cursor that is to be displayed during the grab or + None. + + time + + Specifies the time. You can pass either a timestamp or + CurrentTime. + + The XGrabPointer function actively grabs control of the pointer + and returns GrabSuccess if the grab was successful. Further + pointer events are reported only to the grabbing client. + XGrabPointer overrides any active pointer grab by this client. + If owner_events is False, all generated pointer events are + reported with respect to grab_window and are reported only if + selected by event_mask. If owner_events is True and if a + generated pointer event would normally be reported to this + client, it is reported as usual. Otherwise, the event is + reported with respect to the grab_window and is reported only + if selected by event_mask. For either value of owner_events, + unreported events are discarded. + + If the pointer_mode is GrabModeAsync, pointer event processing + continues as usual. If the pointer is currently frozen by this + client, the processing of events for the pointer is resumed. If + the pointer_mode is GrabModeSync, the state of the pointer, as + seen by client applications, appears to freeze, and the X + server generates no further pointer events until the grabbing + client calls XAllowEvents or until the pointer grab is + released. Actual pointer changes are not lost while the pointer + is frozen; they are simply queued in the server for later + processing. + + If the keyboard_mode is GrabModeAsync, keyboard event + processing is unaffected by activation of the grab. If the + keyboard_mode is GrabModeSync, the state of the keyboard, as + seen by client applications, appears to freeze, and the X + server generates no further keyboard events until the grabbing + client calls XAllowEvents or until the pointer grab is + released. Actual keyboard changes are not lost while the + pointer is frozen; they are simply queued in the server for + later processing. + + If a cursor is specified, it is displayed regardless of what + window the pointer is in. If None is specified, the normal + cursor for that window is displayed when the pointer is in + grab_window or one of its subwindows; otherwise, the cursor for + grab_window is displayed. + + If a confine_to window is specified, the pointer is restricted + to stay contained in that window. The confine_to window need + have no relationship to the grab_window. If the pointer is not + initially in the confine_to window, it is warped automatically + to the closest edge just before the grab activates and + enter/leave events are generated as usual. If the confine_to + window is subsequently reconfigured, the pointer is warped + automatically, as necessary, to keep it contained in the + window. + + The time argument allows you to avoid certain circumstances + that come up if applications take a long time to respond or if + there are long network delays. Consider a situation where you + have two applications, both of which normally grab the pointer + when clicked on. If both applications specify the timestamp + from the event, the second application may wake up faster and + successfully grab the pointer before the first application. The + first application then will get an indication that the other + application grabbed the pointer before its request was + processed. + + XGrabPointer generates EnterNotify and LeaveNotify events. + + Either if grab_window or confine_to window is not viewable or + if the confine_to window lies completely outside the boundaries + of the root window, XGrabPointer fails and returns + GrabNotViewable. If the pointer is actively grabbed by some + other client, it fails and returns AlreadyGrabbed. If the + pointer is frozen by an active grab of another client, it fails + and returns GrabFrozen. If the specified time is earlier than + the last-pointer-grab time or later than the current X server + time, it fails and returns GrabInvalidTime. Otherwise, the + last-pointer-grab time is set to the specified time + (CurrentTime is replaced by the current X server time). + + XGrabPointer can generate BadCursor, BadValue, and BadWindow + errors. + + To ungrab the pointer, use XUngrabPointer. + + XUngrabPointer(Display *display, Time time); + + display + + Specifies the connection to the X server. + + time + + Specifies the time. You can pass either a timestamp or + CurrentTime. + + The XUngrabPointer function releases the pointer and any queued + events if this client has actively grabbed the pointer from + XGrabPointer, XGrabButton, or from a normal button press. + XUngrabPointer does not release the pointer if the specified + time is earlier than the last-pointer-grab time or is later + than the current X server time. It also generates EnterNotify + and LeaveNotify events. The X server performs an UngrabPointer + request automatically if the event window or confine_to window + for an active pointer grab becomes not viewable or if window + reconfiguration causes the confine_to window to lie completely + outside the boundaries of the root window. + + To change an active pointer grab, use XChangeActivePointerGrab. + + XChangeActivePointerGrab(Display *display, unsigned int + event_mask, Cursor cursor, Time time); + + display + + Specifies the connection to the X server. + + event_mask + + Specifies which pointer events are reported to the client. The + mask is the bitwise inclusive OR of the valid pointer event + mask bits. + + cursor + + Specifies the cursor that is to be displayed or None. + + time + + Specifies the time. You can pass either a timestamp or + CurrentTime. + + The XChangeActivePointerGrab function changes the specified + dynamic parameters if the pointer is actively grabbed by the + client and if the specified time is no earlier than the + last-pointer-grab time and no later than the current X server + time. This function has no effect on the passive parameters of + an XGrabButton. The interpretation of event_mask and cursor is + the same as described in XGrabPointer. + + XChangeActivePointerGrab can generate BadCursor and BadValue + errors. + + To grab a pointer button, use XGrabButton. + + XGrabButton(Display *display, unsigned int button, unsigned int + modifiers, Window grab_window, Bool owner_events, unsigned int + event_mask, int pointer_mode, int keyboard_mode, Window + confine_to, Cursor cursor); + + display + + Specifies the connection to the X server. + + button + + Specifies the pointer button that is to be grabbed or + AnyButton. + + modifiers + + Specifies the set of keymasks or AnyModifier. The mask is the + bitwise inclusive OR of the valid keymask bits. + + grab_window + + Specifies the grab window. + + owner_events + + Specifies a Boolean value that indicates whether the pointer + events are to be reported as usual or reported with respect to + the grab window if selected by the event mask. + + event_mask + + Specifies which pointer events are reported to the client. The + mask is the bitwise inclusive OR of the valid pointer event + mask bits. + + pointer_mode + + Specifies further processing of pointer events. You can pass + GrabModeSync or GrabModeAsync. + + keyboard_mode + + Specifies further processing of keyboard events. You can pass + GrabModeSync or GrabModeAsync. + + confine_to + + Specifies the window to confine the pointer in or None. + + cursor + + Specifies the cursor that is to be displayed or None. + + The XGrabButton function establishes a passive grab. In the + future, the pointer is actively grabbed (as for XGrabPointer), + the last-pointer-grab time is set to the time at which the + button was pressed (as transmitted in the ButtonPress event), + and the ButtonPress event is reported if all of the following + conditions are true: + * The pointer is not grabbed, and the specified button is + logically pressed when the specified modifier keys are + logically down, and no other buttons or modifier keys are + logically down. + * The grab_window contains the pointer. + * The confine_to window (if any) is viewable. + * A passive grab on the same button/key combination does not + exist on any ancestor of grab_window. + + The interpretation of the remaining arguments is as for + XGrabPointer. The active grab is terminated automatically when + the logical state of the pointer has all buttons released + (independent of the state of the logical modifier keys). + + Note that the logical state of a device (as seen by client + applications) may lag the physical state if device event + processing is frozen. + + This request overrides all previous grabs by the same client on + the same button/key combinations on the same window. A + modifiers of AnyModifier is equivalent to issuing the grab + request for all possible modifier combinations (including the + combination of no modifiers). It is not required that all + modifiers specified have currently assigned KeyCodes. A button + of AnyButton is equivalent to issuing the request for all + possible buttons. Otherwise, it is not required that the + specified button currently be assigned to a physical button. + + If some other client has already issued an XGrabButton with the + same button/key combination on the same window, a BadAccess + error results. When using AnyModifier or AnyButton, the request + fails completely, and a BadAccess error results (no grabs are + established) if there is a conflicting grab for any + combination. XGrabButton has no effect on an active grab. + + XGrabButton can generate BadCursor, BadValue, and BadWindow + errors. + + To ungrab a pointer button, use XUngrabButton. + + XUngrabButton(Display *display, unsigned int button, unsigned + int modifiers, Window grab_window); + + display + + Specifies the connection to the X server. + + button + + Specifies the pointer button that is to be released or + AnyButton. + + modifiers + + Specifies the set of keymasks or AnyModifier. The mask is the + bitwise inclusive OR of the valid keymask bits. + + grab_window + + Specifies the grab window. + + The XUngrabButton function releases the passive button/key + combination on the specified window if it was grabbed by this + client. A modifiers of AnyModifier is equivalent to issuing the + ungrab request for all possible modifier combinations, + including the combination of no modifiers. A button of + AnyButton is equivalent to issuing the request for all possible + buttons. XUngrabButton has no effect on an active grab. + + XUngrabButton can generate BadValue and BadWindow errors. + +Keyboard Grabbing + + Xlib provides functions that you can use to grab or ungrab the + keyboard as well as allow events. + + For many functions in this section, you pass keymask bits. The + valid keymask bits are: ShiftMask, LockMask, ControlMask, + Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, and Mod5Mask. + + To grab the keyboard, use XGrabKeyboard. + + int XGrabKeyboard(Display *display, Window grab_window, Bool + owner_events, int pointer_mode, int keyboard_mode, Time time); + + display + + Specifies the connection to the X server. + + grab_window + + Specifies the grab window. + + owner_events + + Specifies a Boolean value that indicates whether the keyboard + events are to be reported as usual. + + pointer_mode + + Specifies further processing of pointer events. You can pass + GrabModeSync or GrabModeAsync. + + keyboard_mode + + Specifies further processing of keyboard events. You can pass + GrabModeSync or GrabModeAsync. + + time + + Specifies the time. You can pass either a timestamp or + CurrentTime. + + The XGrabKeyboard function actively grabs control of the + keyboard and generates FocusIn and FocusOut events. Further key + events are reported only to the grabbing client. XGrabKeyboard + overrides any active keyboard grab by this client. If + owner_events is False, all generated key events are reported + with respect to grab_window. If owner_events is True and if a + generated key event would normally be reported to this client, + it is reported normally; otherwise, the event is reported with + respect to the grab_window. Both KeyPress and KeyRelease events + are always reported, independent of any event selection made by + the client. + + If the keyboard_mode argument is GrabModeAsync, keyboard event + processing continues as usual. If the keyboard is currently + frozen by this client, then processing of keyboard events is + resumed. If the keyboard_mode argument is GrabModeSync, the + state of the keyboard (as seen by client applications) appears + to freeze, and the X server generates no further keyboard + events until the grabbing client issues a releasing + XAllowEvents call or until the keyboard grab is released. + Actual keyboard changes are not lost while the keyboard is + frozen; they are simply queued in the server for later + processing. + + If pointer_mode is GrabModeAsync, pointer event processing is + unaffected by activation of the grab. If pointer_mode is + GrabModeSync, the state of the pointer (as seen by client + applications) appears to freeze, and the X server generates no + further pointer events until the grabbing client issues a + releasing XAllowEvents call or until the keyboard grab is + released. Actual pointer changes are not lost while the pointer + is frozen; they are simply queued in the server for later + processing. + + If the keyboard is actively grabbed by some other client, + XGrabKeyboard fails and returns AlreadyGrabbed. If grab_window + is not viewable, it fails and returns GrabNotViewable. If the + keyboard is frozen by an active grab of another client, it + fails and returns GrabFrozen. If the specified time is earlier + than the last-keyboard-grab time or later than the current X + server time, it fails and returns GrabInvalidTime. Otherwise, + the last-keyboard-grab time is set to the specified time + (CurrentTime is replaced by the current X server time). + + XGrabKeyboard can generate BadValue and BadWindow errors. + + To ungrab the keyboard, use XUngrabKeyboard. + + XUngrabKeyboard(Display *display, Time time); + + display + + Specifies the connection to the X server. + + time + + Specifies the time. You can pass either a timestamp or + CurrentTime. + + The XUngrabKeyboard function releases the keyboard and any + queued events if this client has it actively grabbed from + either XGrabKeyboard or XGrabKey. XUngrabKeyboard does not + release the keyboard and any queued events if the specified + time is earlier than the last-keyboard-grab time or is later + than the current X server time. It also generates FocusIn and + FocusOut events. The X server automatically performs an + UngrabKeyboard request if the event window for an active + keyboard grab becomes not viewable. + + To passively grab a single key of the keyboard, use XGrabKey. + + XGrabKey(Display *display, int keycode, unsigned int modifiers, + Window grab_window, Bool owner_events, int pointer_mode, int + keyboard_mode); + + display + + Specifies the connection to the X server. + + keycode + + Specifies the KeyCode or AnyKey. + + modifiers + + Specifies the set of keymasks or AnyModifier. The mask is the + bitwise inclusive OR of the valid keymask bits. + + grab_window + + Specifies the grab window. + + owner_events + + Specifies a Boolean value that indicates whether the keyboard + events are to be reported as usual. + + pointer_mode + + Specifies further processing of pointer events. You can pass + GrabModeSync or GrabModeAsync. + + keyboard_mode + + Specifies further processing of keyboard events. You can pass + GrabModeSync or GrabModeAsync. + + The XGrabKey function establishes a passive grab on the + keyboard. In the future, the keyboard is actively grabbed (as + for XGrabKeyboard), the last-keyboard-grab time is set to the + time at which the key was pressed (as transmitted in the + KeyPress event), and the KeyPress event is reported if all of + the following conditions are true: + * The keyboard is not grabbed and the specified key (which + can itself be a modifier key) is logically pressed when the + specified modifier keys are logically down, and no other + modifier keys are logically down. + * Either the grab_window is an ancestor of (or is) the focus + window, or the grab_window is a descendant of the focus + window and contains the pointer. + * A passive grab on the same key combination does not exist + on any ancestor of grab_window. + + The interpretation of the remaining arguments is as for + XGrabKeyboard. The active grab is terminated automatically when + the logical state of the keyboard has the specified key + released (independent of the logical state of the modifier + keys). + + Note that the logical state of a device (as seen by client + applications) may lag the physical state if device event + processing is frozen. + + A modifiers argument of AnyModifier is equivalent to issuing + the request for all possible modifier combinations (including + the combination of no modifiers). It is not required that all + modifiers specified have currently assigned KeyCodes. A keycode + argument of AnyKey is equivalent to issuing the request for all + possible KeyCodes. Otherwise, the specified keycode must be in + the range specified by min_keycode and max_keycode in the + connection setup, or a BadValue error results. + + If some other client has issued a XGrabKey with the same key + combination on the same window, a BadAccess error results. When + using AnyModifier or AnyKey, the request fails completely, and + a BadAccess error results (no grabs are established) if there + is a conflicting grab for any combination. + + XGrabKey can generate BadAccess, BadValue, and BadWindow + errors. + + To ungrab a key, use XUngrabKey. + + XUngrabKey(Display *display, int keycode, unsigned int + modifiers, Window grab_window); + + display + + Specifies the connection to the X server. + + keycode + + Specifies the KeyCode or AnyKey. + + modifiers + + Specifies the set of keymasks or AnyModifier. The mask is the + bitwise inclusive OR of the valid keymask bits. + + grab_window + + Specifies the grab window. + + The XUngrabKey function releases the key combination on the + specified window if it was grabbed by this client. It has no + effect on an active grab. A modifiers of AnyModifier is + equivalent to issuing the request for all possible modifier + combinations (including the combination of no modifiers). A + keycode argument of AnyKey is equivalent to issuing the request + for all possible key codes. + + XUngrabKey can generate BadValue and BadWindow errors. + +Resuming Event Processing + + The previous sections discussed grab mechanisms with which + processing of events by the server can be temporarily + suspended. This section describes the mechanism for resuming + event processing. + + To allow further events to be processed when the device has + been frozen, use XAllowEvents. + + XAllowEvents(Display *display, int event_mode, Time time); + + display + + Specifies the connection to the X server. + + event_mode + + Specifies the event mode. You can pass AsyncPointer, + SyncPointer, AsyncKeyboard, SyncKeyboard, ReplayPointer, + ReplayKeyboard, AsyncBoth, or SyncBoth. + + time + + Specifies the time. You can pass either a timestamp or + CurrentTime. + + The XAllowEvents function releases some queued events if the + client has caused a device to freeze. It has no effect if the + specified time is earlier than the last-grab time of the most + recent active grab for the client or if the specified time is + later than the current X server time. Depending on the + event_mode argument, the following occurs: + AsyncPointer If the pointer is frozen by the client, pointer + event processing continues as usual. If the pointer is frozen + twice by the client on behalf of two separate grabs, + AsyncPointer thaws for both. AsyncPointer has no effect if the + pointer is not frozen by the client, but the pointer need not + be grabbed by the client. + SyncPointer If the pointer is frozen and actively grabbed by + the client, pointer event processing continues as usual until + the next ButtonPress or ButtonRelease event is reported to the + client. At this time, the pointer again appears to freeze. + However, if the reported event causes the pointer grab to be + released, the pointer does not freeze. SyncPointer has no + effect if the pointer is not frozen by the client or if the + pointer is not grabbed by the client. + ReplayPointer If the pointer is actively grabbed by the client + and is frozen as the result of an event having been sent to the + client (either from the activation of an XGrabButton or from a + previous XAllowEvents with mode SyncPointer but not from an + XGrabPointer), the pointer grab is released and that event is + completely reprocessed. This time, however, the function + ignores any passive grabs at or above (toward the root of) the + grab_window of the grab just released. The request has no + effect if the pointer is not grabbed by the client or if the + pointer is not frozen as the result of an event. + AsyncKeyboard If the keyboard is frozen by the client, keyboard + event processing continues as usual. If the keyboard is frozen + twice by the client on behalf of two separate grabs, + AsyncKeyboard thaws for both. AsyncKeyboard has no effect if + the keyboard is not frozen by the client, but the keyboard need + not be grabbed by the client. + SyncKeyboard If the keyboard is frozen and actively grabbed by + the client, keyboard event processing continues as usual until + the next KeyPress or KeyRelease event is reported to the + client. At this time, the keyboard again appears to freeze. + However, if the reported event causes the keyboard grab to be + released, the keyboard does not freeze. SyncKeyboard has no + effect if the keyboard is not frozen by the client or if the + keyboard is not grabbed by the client. + ReplayKeyboard If the keyboard is actively grabbed by the + client and is frozen as the result of an event having been sent + to the client (either from the activation of an XGrabKey or + from a previous XAllowEvents with mode SyncKeyboard but not + from an XGrabKeyboard), the keyboard grab is released and that + event is completely reprocessed. This time, however, the + function ignores any passive grabs at or above (toward the root + of) the grab_window of the grab just released. The request has + no effect if the keyboard is not grabbed by the client or if + the keyboard is not frozen as the result of an event. + SyncBoth If both pointer and keyboard are frozen by the client, + event processing for both devices continues as usual until the + next ButtonPress, ButtonRelease, KeyPress, or KeyRelease event + is reported to the client for a grabbed device (button event + for the pointer, key event for the keyboard), at which time the + devices again appear to freeze. However, if the reported event + causes the grab to be released, then the devices do not freeze + (but if the other device is still grabbed, then a subsequent + event for it will still cause both devices to freeze). SyncBoth + has no effect unless both pointer and keyboard are frozen by + the client. If the pointer or keyboard is frozen twice by the + client on behalf of two separate grabs, SyncBoth thaws for both + (but a subsequent freeze for SyncBoth will only freeze each + device once). + AsyncBoth If the pointer and the keyboard are frozen by the + client, event processing for both devices continues as usual. + If a device is frozen twice by the client on behalf of two + separate grabs, AsyncBoth thaws for both. AsyncBoth has no + effect unless both pointer and keyboard are frozen by the + client. + + AsyncPointer, SyncPointer, and ReplayPointer have no effect on + the processing of keyboard events. AsyncKeyboard, SyncKeyboard, + and ReplayKeyboard have no effect on the processing of pointer + events. It is possible for both a pointer grab and a keyboard + grab (by the same or different clients) to be active + simultaneously. If a device is frozen on behalf of either grab, + no event processing is performed for the device. It is possible + for a single device to be frozen because of both grabs. In this + case, the freeze must be released on behalf of both grabs + before events can again be processed. If a device is frozen + twice by a single client, then a single XAllowEvents releases + both. + + XAllowEvents can generate a BadValue error. + +Moving the Pointer + + Although movement of the pointer normally should be left to the + control of the end user, sometimes it is necessary to move the + pointer to a new position under program control. + + To move the pointer to an arbitrary point in a window, use + XWarpPointer. + + XWarpPointer(Display *display, Window src_w, Window dest_w, int + src_x, int src_y, unsigned int src_width, unsigned int + src_height, int dest_x, int dest_y); + + display + + Specifies the connection to the X server. + + src_w + + Specifies the source window or None. + + dest_w + + Specifies the destination window or None. + + src_x + + src_y + + src_width + + src_height + + Specify a rectangle in the source window. + + dest_x + + dest_y + + Specify the x and y coordinates within the destination window. + + If dest_w is None, XWarpPointer moves the pointer by the + offsets (dest_x, dest_y) relative to the current position of + the pointer. If dest_w is a window, XWarpPointer moves the + pointer to the offsets (dest_x, dest_y) relative to the origin + of dest_w. However, if src_w is a window, the move only takes + place if the window src_w contains the pointer and if the + specified rectangle of src_w contains the pointer. + + The src_x and src_y coordinates are relative to the origin of + src_w. If src_height is zero, it is replaced with the current + height of src_w minus src_y. If src_width is zero, it is + replaced with the current width of src_w minus src_x. + + There is seldom any reason for calling this function. The + pointer should normally be left to the user. If you do use this + function, however, it generates events just as if the user had + instantaneously moved the pointer from one position to another. + Note that you cannot use XWarpPointer to move the pointer + outside the confine_to window of an active pointer grab. An + attempt to do so will only move the pointer as far as the + closest edge of the confine_to window. + + XWarpPointer can generate a BadWindow error. + +Controlling Input Focus + + Xlib provides functions that you can use to set and get the + input focus. The input focus is a shared resource, and + cooperation among clients is required for correct interaction. + See the Inter-Client Communication Conventions Manual for input + focus policy. + + To set the input focus, use XSetInputFocus. + + XSetInputFocus(Display *display, Window focus, int revert_to, + Time time); + + display + + Specifies the connection to the X server. + + focus + + Specifies the window, PointerRoot, or None. + + revert_to + + Specifies where the input focus reverts to if the window + becomes not viewable. You can pass RevertToParent, + RevertToPointerRoot, or RevertToNone. + + time + + Specifies the time. You can pass either a timestamp or + CurrentTime. + + The XSetInputFocus function changes the input focus and the + last-focus-change time. It has no effect if the specified time + is earlier than the current last-focus-change time or is later + than the current X server time. Otherwise, the + last-focus-change time is set to the specified time + (CurrentTime is replaced by the current X server time). + XSetInputFocus causes the X server to generate FocusIn and + FocusOut events. + + Depending on the focus argument, the following occurs: + * If focus is None, all keyboard events are discarded until a + new focus window is set, and the revert_to argument is + ignored. + * If focus is a window, it becomes the keyboard's focus + window. If a generated keyboard event would normally be + reported to this window or one of its inferiors, the event + is reported as usual. Otherwise, the event is reported + relative to the focus window. + * If focus is PointerRoot, the focus window is dynamically + taken to be the root window of whatever screen the pointer + is on at each keyboard event. In this case, the revert_to + argument is ignored. + + The specified focus window must be viewable at the time + XSetInputFocus is called, or a BadMatch error results. If the + focus window later becomes not viewable, the X server evaluates + the revert_to argument to determine the new focus window as + follows: + * If revert_to is RevertToParent, the focus reverts to the + parent (or the closest viewable ancestor), and the new + revert_to value is taken to be RevertToNone. + * If revert_to is RevertToPointerRoot or RevertToNone, the + focus reverts to PointerRoot or None, respectively. When + the focus reverts, the X server generates FocusIn and + FocusOut events, but the last-focus-change time is not + affected. + + XSetInputFocus can generate BadMatch, BadValue, and BadWindow + errors. + + To obtain the current input focus, use XGetInputFocus. + + XGetInputFocus(Display *display, Window *focus_return, int + *revert_to_return); + + display + + Specifies the connection to the X server. + + focus_return + + Returns the focus window, PointerRoot, or None. + + revert_to_return + + Returns the current focus state (RevertToParent, + RevertToPointerRoot, or RevertToNone). + + The XGetInputFocus function returns the focus window and the + current focus state. + +Manipulating the Keyboard and Pointer Settings + + Xlib provides functions that you can use to change the keyboard + control, obtain a list of the auto-repeat keys, turn keyboard + auto-repeat on or off, ring the bell, set or obtain the pointer + button or keyboard mapping, and obtain a bit vector for the + keyboard. + + This section discusses the user-preference options of bell, key + click, pointer behavior, and so on. The default values for many + of these options are server dependent. Not all implementations + will actually be able to control all of these parameters. + + The XChangeKeyboardControl function changes control of a + keyboard and operates on a XKeyboardControl structure: +/* Mask bits for ChangeKeyboardControl */ + + +#define KBBellPercent (1L<<0) +#define KBBellPitch (1L<<1) +#define KBBellDuration (1L<<2) +#define KBLed (1L<<3) +#define KBLedMode (1L<<4) +#define KBKey (1L<<5) +#define KBAutoRepeatMode (1L<<6) + + +/* Values */ + +typedef struct { +int key_click_percent; +int bell_percent; +int bell_pitch; +int bell_duration; +int led; +int led_mode; /* LedModeOn, LedModeOff */ +int key; +int auto_repeat_mode; /* AutoRepeatModeOff, AutoRepeatModeOn, + AutoRepeatModeDefault */ +} XKeyboardControl; + + + The key_click_percent member sets the volume for key clicks + between 0 (off) and 100 (loud) inclusive, if possible. A + setting of -1 restores the default. Other negative values + generate a BadValue error. + + The bell_percent sets the base volume for the bell between 0 + (off) and 100 (loud) inclusive, if possible. A setting of -1 + restores the default. Other negative values generate a BadValue + error. The bell_pitch member sets the pitch (specified in Hz) + of the bell, if possible. A setting of -1 restores the default. + Other negative values generate a BadValue error. The + bell_duration member sets the duration of the bell specified in + milliseconds, if possible. A setting of -1 restores the + default. Other negative values generate a BadValue error. + + If both the led_mode and led members are specified, the state + of that LED is changed, if possible. The led_mode member can be + set to LedModeOn or LedModeOff. If only led_mode is specified, + the state of all LEDs are changed, if possible. At most 32 LEDs + numbered from one are supported. No standard interpretation of + LEDs is defined. If led is specified without led_mode, a + BadMatch error results. + + If both the auto_repeat_mode and key members are specified, the + auto_repeat_mode of that key is changed (according to + AutoRepeatModeOn, AutoRepeatModeOff, or AutoRepeatModeDefault), + if possible. If only auto_repeat_mode is specified, the global + auto_repeat_mode for the entire keyboard is changed, if + possible, and does not affect the per-key settings. If a key is + specified without an auto_repeat_mode, a BadMatch error + results. Each key has an individual mode of whether or not it + should auto-repeat and a default setting for the mode. In + addition, there is a global mode of whether auto-repeat should + be enabled or not and a default setting for that mode. When + global mode is AutoRepeatModeOn, keys should obey their + individual auto-repeat modes. When global mode is + AutoRepeatModeOff, no keys should auto-repeat. An + auto-repeating key generates alternating KeyPress and + KeyRelease events. When a key is used as a modifier, it is + desirable for the key not to auto-repeat, regardless of its + auto-repeat setting. + + A bell generator connected with the console but not directly on + a keyboard is treated as if it were part of the keyboard. The + order in which controls are verified and altered is + server-dependent. If an error is generated, a subset of the + controls may have been altered. + + XChangeKeyboardControl(Display *display, unsigned long + value_mask, XKeyboardControl *values); + + display + + Specifies the connection to the X server. + + value_mask + + Specifies which controls to change. This mask is the bitwise + inclusive OR of the valid control mask bits. + + values + + Specifies one value for each bit set to 1 in the mask. + + The XChangeKeyboardControl function controls the keyboard + characteristics defined by the XKeyboardControl structure. The + value_mask argument specifies which values are to be changed. + + XChangeKeyboardControl can generate BadMatch and BadValue + errors. + + To obtain the current control values for the keyboard, use + XGetKeyboardControl. + + XGetKeyboardControl(Display *display, XKeyboardState + *values_return); + + display + + Specifies the connection to the X server. + + values_return + + Returns the current keyboard controls in the specified + XKeyboardState structure. + + The XGetKeyboardControl function returns the current control + values for the keyboard to the XKeyboardState structure. + + + +typedef struct { + int key_click_percent; + int bell_percent; + unsigned int bell_pitch, bell_duration; + unsigned long led_mask; + int global_auto_repeat; + char auto_repeats[32]; +} XKeyboardState; + + For the LEDs, the least significant bit of led_mask corresponds + to LED one, and each bit set to 1 in led_mask indicates an LED + that is lit. The global_auto_repeat member can be set to + AutoRepeatModeOn or AutoRepeatModeOff. The auto_repeats member + is a bit vector. Each bit set to 1 indicates that auto-repeat + is enabled for the corresponding key. The vector is represented + as 32 bytes. Byte N (from 0) contains the bits for keys 8N to + 8N + 7 with the least significant bit in the byte representing + key 8N. + + To turn on keyboard auto-repeat, use XAutoRepeatOn. + + XAutoRepeatOn(Display *display); + + display + + Specifies the connection to the X server. + + The XAutoRepeatOn function turns on auto-repeat for the + keyboard on the specified display. + + To turn off keyboard auto-repeat, use XAutoRepeatOff. + + XAutoRepeatOff(Display *display); + + display + + Specifies the connection to the X server. + + The XAutoRepeatOff function turns off auto-repeat for the + keyboard on the specified display. + + To ring the bell, use XBell. + + XBell(Display *display, int percent); + + display + + Specifies the connection to the X server. + + percent + + Specifies the volume for the bell, which can range from -100 to + 100 inclusive. + + The XBell function rings the bell on the keyboard on the + specified display, if possible. The specified volume is + relative to the base volume for the keyboard. If the value for + the percent argument is not in the range -100 to 100 inclusive, + a BadValue error results. The volume at which the bell rings + when the percent argument is nonnegative is: + * base - [(base * percent) / 100] + percent + + The volume at which the bell rings when the percent argument is + negative is: + * base + [(base * percent) / 100] + + To change the base volume of the bell, use + XChangeKeyboardControl. + + XBell can generate a BadValue error. + + To obtain a bit vector that describes the state of the + keyboard, use XQueryKeymap. + + XQueryKeymap(Display *display, char keys_return[32]); + + display + + Specifies the connection to the X server. + + keys_return + + Returns an array of bytes that identifies which keys are + pressed down. Each bit represents one key of the keyboard. + + The XQueryKeymap function returns a bit vector for the logical + state of the keyboard, where each bit set to 1 indicates that + the corresponding key is currently pressed down. The vector is + represented as 32 bytes. Byte N (from 0) contains the bits for + keys 8N to 8N + 7 with the least significant bit in the byte + representing key 8N. + + Note that the logical state of a device (as seen by client + applications) may lag the physical state if device event + processing is frozen. + + To set the mapping of the pointer buttons, use + XSetPointerMapping. + + int XSetPointerMapping(Display *display, unsignedchar map[], + int nmap); + + display + + Specifies the connection to the X server. + + map + + Specifies the mapping list. + + nmap + + Specifies the number of items in the mapping list. + + The XSetPointerMapping function sets the mapping of the + pointer. If it succeeds, the X server generates a MappingNotify + event, and XSetPointerMapping returns MappingSuccess. Element + map[i] defines the logical button number for the physical + button i+1. The length of the list must be the same as + XGetPointerMapping would return, or a BadValue error results. A + zero element disables a button, and elements are not restricted + in value by the number of physical buttons. However, no two + elements can have the same nonzero value, or a BadValue error + results. If any of the buttons to be altered are logically in + the down state, XSetPointerMapping returns MappingBusy, and the + mapping is not changed. + + XSetPointerMapping can generate a BadValue error. + + To get the pointer mapping, use XGetPointerMapping. + + int XGetPointerMapping(Display *display, unsignedchar + map_return[], int nmap); + + display + + Specifies the connection to the X server. + + map_return + + Returns the mapping list. + + nmap + + Specifies the number of items in the mapping list. + + The XGetPointerMapping function returns the current mapping of + the pointer. Pointer buttons are numbered starting from one. + XGetPointerMapping returns the number of physical buttons + actually on the pointer. The nominal mapping for a pointer is + map[i]=i+1. The nmap argument specifies the length of the array + where the pointer mapping is returned, and only the first nmap + elements are returned in map_return. + + To control the pointer's interactive feel, use + XChangePointerControl. + + XChangePointerControl(Display *display, Bool do_accel, Bool + do_threshold, int accel_numerator, int accel_denominator, int + threshold); + + display + + Specifies the connection to the X server. + + do_accel + + Specifies a Boolean value that controls whether the values for + the accel_numerator or accel_denominator are used. + + do_threshold + + Specifies a Boolean value that controls whether the value for + the threshold is used. + + accel_numerator + + Specifies the numerator for the acceleration multiplier. + + accel_denominator + + Specifies the denominator for the acceleration multiplier. + + threshold + + Specifies the acceleration threshold. + + The XChangePointerControl function defines how the pointing + device moves. The acceleration, expressed as a fraction, is a + multiplier for movement. For example, specifying 3/1 means the + pointer moves three times as fast as normal. The fraction may + be rounded arbitrarily by the X server. Acceleration only takes + effect if the pointer moves more than threshold pixels at once + and only applies to the amount beyond the value in the + threshold argument. Setting a value to -1 restores the default. + The values of the do_accel and do_threshold arguments must be + True for the pointer values to be set, or the parameters are + unchanged. Negative values (other than -1) generate a BadValue + error, as does a zero value for the accel_denominator argument. + + XChangePointerControl can generate a BadValue error. + + To get the current pointer parameters, use XGetPointerControl. + + XGetPointerControl(Display *display, int + *accel_numerator_return, int *accel_denominator_return, int + *threshold_return); + + display + + Specifies the connection to the X server. + + accel_numerator_return + + Returns the numerator for the acceleration multiplier. + + accel_denominator_return + + Returns the denominator for the acceleration multiplier. + + threshold_return + + Returns the acceleration threshold. + + The XGetPointerControl function returns the pointer's current + acceleration multiplier and acceleration threshold. + +Manipulating the Keyboard Encoding + + A KeyCode represents a physical (or logical) key. KeyCodes lie + in the inclusive range [8,255]. A KeyCode value carries no + intrinsic information, although server implementors may attempt + to encode geometry (for example, matrix) information in some + fashion so that it can be interpreted in a server-dependent + fashion. The mapping between keys and KeyCodes cannot be + changed. + + A KeySym is an encoding of a symbol on the cap of a key. The + set of defined KeySyms includes the ISO Latin character sets + (1-4), Katakana, Arabic, Cyrillic, Greek, Technical, Special, + Publishing, APL, Hebrew, Thai, Korean and a miscellany of keys + found on keyboards (Return, Help, Tab, and so on). To the + extent possible, these sets are derived from international + standards. In areas where no standards exist, some of these + sets are derived from Digital Equipment Corporation standards. + The list of defined symbols can be found in . + Unfortunately, some C preprocessors have limits on the number + of defined symbols. If you must use KeySyms not in the Latin + 1-4, Greek, and miscellaneous classes, you may have to define a + symbol for those sets. Most applications usually only include + , which defines symbols for ISO Latin 1-4, Greek, + and miscellaneous. + + A list of KeySyms is associated with each KeyCode. The list is + intended to convey the set of symbols on the corresponding key. + If the list (ignoring trailing NoSymbol entries) is a single + KeySym ``K'', then the list is treated as if it were the list + ``K NoSymbol K NoSymbol''. If the list (ignoring trailing + NoSymbol entries) is a pair of KeySyms ``K1 K2'', then the list + is treated as if it were the list ``K1 K2 K1 K2''. If the list + (ignoring trailing NoSymbol entries) is a triple of KeySyms + ``K1 K2 K3'', then the list is treated as if it were the list + ``K1 K2 K3 NoSymbol''. When an explicit ``void'' element is + desired in the list, the value VoidSymbol can be used. + + The first four elements of the list are split into two groups + of KeySyms. Group 1 contains the first and second KeySyms; + Group 2 contains the third and fourth KeySyms. Within each + group, if the second element of the group is NoSymbol, then the + group should be treated as if the second element were the same + as the first element, except when the first element is an + alphabetic KeySym ``K'' for which both lowercase and uppercase + forms are defined. In that case, the group should be treated as + if the first element were the lowercase form of ``K'' and the + second element were the uppercase form of ``K''. + + The standard rules for obtaining a KeySym from a KeyPress event + make use of only the Group 1 and Group 2 KeySyms; no + interpretation of other KeySyms in the list is given. Which + group to use is determined by the modifier state. Switching + between groups is controlled by the KeySym named MODE SWITCH, + by attaching that KeySym to some KeyCode and attaching that + KeyCode to any one of the modifiers Mod1 through Mod5. This + modifier is called the group modifier. For any KeyCode, Group 1 + is used when the group modifier is off, and Group 2 is used + when the group modifier is on. + + The Lock modifier is interpreted as CapsLock when the KeySym + named XK_Caps_Lock is attached to some KeyCode and that KeyCode + is attached to the Lock modifier. The Lock modifier is + interpreted as ShiftLock when the KeySym named XK_Shift_Lock is + attached to some KeyCode and that KeyCode is attached to the + Lock modifier. If the Lock modifier could be interpreted as + both CapsLock and ShiftLock, the CapsLock interpretation is + used. + + The operation of keypad keys is controlled by the KeySym named + XK_Num_Lock, by attaching that KeySym to some KeyCode and + attaching that KeyCode to any one of the modifiers Mod1 through + Mod5. This modifier is called the numlock modifier. The + standard KeySyms with the prefix ``XK_KP_'' in their name are + called keypad KeySyms; these are KeySyms with numeric value in + the hexadecimal range 0xFF80 to 0xFFBD inclusive. In addition, + vendor-specific KeySyms in the hexadecimal range 0x11000000 to + 0x1100FFFF are also keypad KeySyms. + + Within a group, the choice of KeySym is determined by applying + the first rule that is satisfied from the following list: + * The numlock modifier is on and the second KeySym is a + keypad KeySym. In this case, if the Shift modifier is on, + or if the Lock modifier is on and is interpreted as + ShiftLock, then the first KeySym is used, otherwise the + second KeySym is used. + * The Shift and Lock modifiers are both off. In this case, + the first KeySym is used. + * The Shift modifier is off, and the Lock modifier is on and + is interpreted as CapsLock. In this case, the first KeySym + is used, but if that KeySym is lowercase alphabetic, then + the corresponding uppercase KeySym is used instead. + * The Shift modifier is on, and the Lock modifier is on and + is interpreted as CapsLock. In this case, the second KeySym + is used, but if that KeySym is lowercase alphabetic, then + the corresponding uppercase KeySym is used instead. + * The Shift modifier is on, or the Lock modifier is on and is + interpreted as ShiftLock, or both. In this case, the second + KeySym is used. + + No spatial geometry of the symbols on the key is defined by + their order in the KeySym list, although a geometry might be + defined on a server-specific basis. The X server does not use + the mapping between KeyCodes and KeySyms. Rather, it merely + stores it for reading and writing by clients. + + To obtain the legal KeyCodes for a display, use + XDisplayKeycodes. + + XDisplayKeycodes(Display *display, int *min_keycodes_return, + int *max_keycodes_return); + + display + + Specifies the connection to the X server. + + min_keycodes_return + + Returns the minimum number of KeyCodes. + + max_keycodes_return + + Returns the maximum number of KeyCodes. + + The XDisplayKeycodes function returns the min-keycodes and + max-keycodes supported by the specified display. The minimum + number of KeyCodes returned is never less than 8, and the + maximum number of KeyCodes returned is never greater than 255. + Not all KeyCodes in this range are required to have + corresponding keys. + + To obtain the symbols for the specified KeyCodes, use + XGetKeyboardMapping. + + KeySym *XGetKeyboardMapping(Display *display, KeyCode + first_keycode, int keycode_count, int + *keysyms_per_keycode_return); + + display + + Specifies the connection to the X server. + + first_keycode + + Specifies the first KeyCode that is to be returned. + + keycode_count + + Specifies the number of KeyCodes that are to be returned. + + keysyms_per_keycode_return + + Returns the number of KeySyms per KeyCode. + + The XGetKeyboardMapping function returns the symbols for the + specified number of KeyCodes starting with first_keycode. The + value specified in first_keycode must be greater than or equal + to min_keycode as returned by XDisplayKeycodes, or a BadValue + error results. In addition, the following expression must be + less than or equal to max_keycode as returned by + XDisplayKeycodes: + +first_keycode + keycode_count - 1 + + If this is not the case, a BadValue error results. The number + of elements in the KeySyms list is: + +keycode_count * keysyms_per_keycode_return + + KeySym number N, counting from zero, for KeyCode K has the + following index in the list, counting from zero: +(K - first_code) * keysyms_per_code_return + N + + The X server arbitrarily chooses the keysyms_per_keycode_return + value to be large enough to report all requested symbols. A + special KeySym value of NoSymbol is used to fill in unused + elements for individual KeyCodes. To free the storage returned + by XGetKeyboardMapping, use XFree. + + XGetKeyboardMapping can generate a BadValue error. + + To change the keyboard mapping, use XChangeKeyboardMapping. + + XChangeKeyboardMapping(Display *display, int first_keycode, int + keysyms_per_keycode, KeySym *keysyms, int num_codes); + + display + + Specifies the connection to the X server. + + first_keycode + + Specifies the first KeyCode that is to be changed. + + keysyms_per_keycode + + Specifies the number of KeySyms per KeyCode. + + keysyms + + Specifies an array of KeySyms. + + num_codes + + Specifies the number of KeyCodes that are to be changed. + + The XChangeKeyboardMapping function defines the symbols for the + specified number of KeyCodes starting with first_keycode. The + symbols for KeyCodes outside this range remain unchanged. The + number of elements in keysyms must be: + +num_codes * keysyms_per_keycode + + The specified first_keycode must be greater than or equal to + min_keycode returned by XDisplayKeycodes, or a BadValue error + results. In addition, the following expression must be less + than or equal to max_keycode as returned by XDisplayKeycodes, + or a BadValue error results: + +first_keycode + num_codes - 1 + + KeySym number N, counting from zero, for KeyCode K has the + following index in keysyms, counting from zero: + +(K - first_keycode) * keysyms_per_keycode + N + + The specified keysyms_per_keycode can be chosen arbitrarily by + the client to be large enough to hold all desired symbols. A + special KeySym value of NoSymbol should be used to fill in + unused elements for individual KeyCodes. It is legal for + NoSymbol to appear in nontrailing positions of the effective + list for a KeyCode. XChangeKeyboardMapping generates a + MappingNotify event. + + There is no requirement that the X server interpret this + mapping. It is merely stored for reading and writing by + clients. + + XChangeKeyboardMapping can generate BadAlloc and BadValue + errors. + + The next six functions make use of the XModifierKeymap data + structure, which contains: + + + +typedef struct { + int max_keypermod; /* This server's max number of keys per +modifier */ + KeyCode *modifiermap; /* An 8 by max_keypermod array of the mo +difiers */ +} XModifierKeymap; + + To create an XModifierKeymap structure, use XNewModifiermap. + + XModifierKeymap *XNewModifiermap(int max_keys_per_mod); + + max_keys_per_mod + + Specifies the number of KeyCode entries preallocated to the + modifiers in the map. + + The XNewModifiermap function returns a pointer to + XModifierKeymap structure for later use. + + To add a new entry to an XModifierKeymap structure, use + XInsertModifiermapEntry. + + XModifierKeymap *XInsertModifiermapEntry(XModifierKeymap + *modmap, KeyCode keycode_entry, int modifier); + + modmap + + Specifies the XModifierKeymap structure. + + keycode_entry + + Specifies the KeyCode. + + modifier + + Specifies the modifier. + + The XInsertModifiermapEntry function adds the specified KeyCode + to the set that controls the specified modifier and returns the + resulting XModifierKeymap structure (expanded as needed). + + To delete an entry from an XModifierKeymap structure, use + XDeleteModifiermapEntry. + + XModifierKeymap *XDeleteModifiermapEntry(XModifierKeymap + *modmap, KeyCode keycode_entry, int modifier); + + modmap + + Specifies the XModifierKeymap structure. + + keycode_entry + + Specifies the KeyCode. + + modifier + + Specifies the modifier. + + The XDeleteModifiermapEntry function deletes the specified + KeyCode from the set that controls the specified modifier and + returns a pointer to the resulting XModifierKeymap structure. + + To destroy an XModifierKeymap structure, use XFreeModifiermap. + + XFreeModifiermap(XModifierKeymap *modmap); + + modmap + + Specifies the XModifierKeymap structure. + + The XFreeModifiermap function frees the specified + XModifierKeymap structure. + + To set the KeyCodes to be used as modifiers, use + XSetModifierMapping. + + int XSetModifierMapping(Display *display, XModifierKeymap + *modmap); + + display + + Specifies the connection to the X server. + + modmap + + Specifies the XModifierKeymap structure. + + The XSetModifierMapping function specifies the KeyCodes of the + keys (if any) that are to be used as modifiers. If it succeeds, + the X server generates a MappingNotify event, and + XSetModifierMapping returns MappingSuccess. X permits at most 8 + modifier keys. If more than 8 are specified in the + XModifierKeymap structure, a BadLength error results. + + The modifiermap member of the XModifierKeymap structure + contains 8 sets of max_keypermod KeyCodes, one for each + modifier in the order Shift, Lock, Control, Mod1, Mod2, Mod3, + Mod4, and Mod5. Only nonzero KeyCodes have meaning in each set, + and zero KeyCodes are ignored. In addition, all of the nonzero + KeyCodes must be in the range specified by min_keycode and + max_keycode in the Display structure, or a BadValue error + results. + + An X server can impose restrictions on how modifiers can be + changed, for example, if certain keys do not generate up + transitions in hardware, if auto-repeat cannot be disabled on + certain keys, or if multiple modifier keys are not supported. + If some such restriction is violated, the status reply is + MappingFailed, and none of the modifiers are changed. If the + new KeyCodes specified for a modifier differ from those + currently defined and any (current or new) keys for that + modifier are in the logically down state, XSetModifierMapping + returns MappingBusy, and none of the modifiers is changed. + + XSetModifierMapping can generate BadAlloc and BadValue errors. + + To obtain the KeyCodes used as modifiers, use + XGetModifierMapping. + + XModifierKeymap *XGetModifierMapping(Display *display); + + display + + Specifies the connection to the X server. + + The XGetModifierMapping function returns a pointer to a newly + created XModifierKeymap structure that contains the keys being + used as modifiers. The structure should be freed after use by + calling XFreeModifiermap. If only zero values appear in the set + for any modifier, that modifier is disabled. + +Chapter 13. Locales and Internationalized Text Functions + + Table of Contents + + X Locale Management + Locale and Modifier Dependencies + Variable Argument Lists + Output Methods + + Output Method Overview + Output Method Functions + X Output Method Values + Output Context Functions + Output Context Values + Creating and Freeing a Font Set + Obtaining Font Set Metrics + Drawing Text Using Font Sets + + Input Methods + + Input Method Overview + Input Method Management + Input Method Functions + Input Method Values + Input Context Functions + Input Context Values + Input Method Callback Semantics + Event Filtering + Getting Keyboard Input + Input Method Conventions + + String Constants + + An internationalized application is one that is adaptable to + the requirements of different native languages, local customs, + and character string encodings. The process of adapting the + operation to a particular native language, local custom, or + string encoding is called localization. A goal of + internationalization is to permit localization without program + source modifications or recompilation. + + As one of the localization mechanisms, Xlib provides an X Input + Method (XIM) functional interface for internationalized text + input and an X Output Method (XOM) functional interface for + internationalized text output. + + Internationalization in X is based on the concept of a locale. + A locale defines the localized behavior of a program at run + time. Locales affect Xlib in its: + * Encoding and processing of input method text + * Encoding of resource files and values + * Encoding and imaging of text strings + * Encoding and decoding for inter-client text communication + + o Encoding and decoding for inter-client text communication + Characters from various languages are represented in a computer + using an encoding. Different languages have different + encodings, and there are even different encodings for the same + characters in the same language. + + This chapter defines support for localized text imaging and + text input and describes the locale mechanism that controls all + locale-dependent Xlib functions. Sets of functions are provided + for multibyte (char *) text as well as wide character (wchar_t) + text in the form supported by the host C language environment. + The multibyte and wide character functions are equivalent + except for the form of the text argument. + + The Xlib internationalization functions are not meant to + provide support for multilingual applications (mixing multiple + languages within a single piece of text), but they make it + possible to implement applications that work in limited fashion + with more than one language in independent contexts. + + The remainder of this chapter discusses: + * X locale management + * Locale and modifier dependencies + * Variable argument lists + * Output methods + * Input methods + * String constants + +X Locale Management + + X supports one or more of the locales defined by the host + environment. On implementations that conform to the ANSI C + library, the locale announcement method is setlocale. This + function configures the locale operation of both the host C + library and Xlib. The operation of Xlib is governed by the + LC_CTYPE category; this is called the current locale. An + implementation is permitted to provide implementation-dependent + mechanisms for announcing the locale in addition to setlocale. + + On implementations that do not conform to the ANSI C library, + the locale announcement method is Xlib + implementation-dependent. + + The mechanism by which the semantic operation of Xlib is + defined for a specific locale is implementation-dependent. + + X is not required to support all the locales supported by the + host. To determine if the current locale is supported by X, use + XSupportsLocale. + + Bool XSupportsLocale(void); + + The XSupportsLocale function returns True if Xlib functions are + capable of operating under the current locale. If it returns + False, Xlib locale-dependent functions for which the + XLocaleNotSupported return status is defined will return + XLocaleNotSupported. Other Xlib locale-dependent routines will + operate in the ``C'' locale. + + The client is responsible for selecting its locale and X + modifiers. Clients should provide a means for the user to + override the clients' locale selection at client invocation. + Most single-display X clients operate in a single locale for + both X and the host processing environment. They will configure + the locale by calling three functions: the host locale + configuration function, XSupportsLocale, and + XSetLocaleModifiers. + + The semantics of certain categories of X internationalization + capabilities can be configured by setting modifiers. Modifiers + are named by implementation-dependent and locale-specific + strings. The only standard use for this capability at present + is selecting one of several styles of keyboard input method. + + To configure Xlib locale modifiers for the current locale, use + XSetLocaleModifiers. + + char *XSetLocaleModifiers(char *modifier_list); + + modifier_list + + Specifies the modifiers. + + The XSetLocaleModifiers function sets the X modifiers for the + current locale setting. The modifier_list argument is a + null-terminated string of the form ``{@category=value}'', that + is, having zero or more concatenated ``@category=value'' + entries, where category is a category name and value is the + (possibly empty) setting for that category. The values are + encoded in the current locale. Category names are restricted to + the POSIX Portable Filename Character Set. + + The local host X locale modifiers announcer (on POSIX-compliant + systems, the XMODIFIERS environment variable) is appended to + the modifier_list to provide default values on the local host. + If a given category appears more than once in the list, the + first setting in the list is used. If a given category is not + included in the full modifier list, the category is set to an + implementation-dependent default for the current locale. An + empty value for a category explicitly specifies the + implementation-dependent default. + + If the function is successful, it returns a pointer to a + string. The contents of the string are such that a subsequent + call with that string (in the same locale) will restore the + modifiers to the same settings. If modifier_list is a NULL + pointer, XSetLocaleModifiers also returns a pointer to such a + string, and the current locale modifiers are not changed. + + If invalid values are given for one or more modifier categories + supported by the locale, a NULL pointer is returned, and none + of the current modifiers are changed. + + At program startup, the modifiers that are in effect are + unspecified until the first successful call to set them. + Whenever the locale is changed, the modifiers that are in + effect become unspecified until the next successful call to set + them. Clients should always call XSetLocaleModifiers with a + non-NULL modifier_list after setting the locale before they + call any locale-dependent Xlib routine. + + The only standard modifier category currently defined is + ``im'', which identifies the desired input method. The values + for input method are not standardized. A single locale may use + multiple input methods, switching input method under user + control. The modifier may specify the initial input method in + effect or an ordered list of input methods. Multiple input + methods may be specified in a single im value string in an + implementation-dependent manner. + + The returned modifiers string is owned by Xlib and should not + be modified or freed by the client. It may be freed by Xlib + after the current locale or modifiers are changed. Until freed, + it will not be modified by Xlib. + + The recommended procedure for clients initializing their locale + and modifiers is to obtain locale and modifier announcers + separately from one of the following prioritized sources: + * A command line option + * A resource + * The empty string ("") + + The first of these that is defined should be used. Note that + when a locale command line option or locale resource is + defined, the effect should be to set all categories to the + specified locale, overriding any category-specific settings in + the local host environment. + +Locale and Modifier Dependencies + + The internationalized Xlib functions operate in the current + locale configured by the host environment and X locale + modifiers set by XSetLocaleModifiers or in the locale and + modifiers configured at the time some object supplied to the + function was created. For each locale-dependent function, the + following table describes the locale (and modifiers) + dependency: + Locale from Affects the Function In + Locale Query/Configuration: + setlocale XSupportsLocale Locale queried + XSetLocaleModifiers Locale modified + Resources: + setlocale + + XrmGetFileDatabase + + XrmGetStringDatabase + Locale of XrmDatabase + XrmDatabase + + XrmPutFileDatabase + + XrmLocaleOfDatabase + Locale of XrmDatabase + Setting Standard Properties: + setlocale XmbSetWMProperties Encoding of supplied/returned text + (some WM_ property text in environment locale) + setlocale + + XmbTextPropertyToTextList + + XwcTextPropertyToTextList + + XmbTextListToTextProperty + + XwcTextListToTextProperty + Encoding of supplied/returned text + Text Input: + setlocale XOpenIM XIM input method selection + XRegisterIMInstantiateCallback XIM selection + XUnregisterIMInstantiateCallback XIM selection + XIM XCreateIC XIC input method configuration + XLocaleOfIM, and so on Queried locale + XIC XmbLookupString Keyboard layout + XwcLookupString Encoding of returned text + Text Drawing: + setlocale XOpenOM XOM output method selection + XCreateFontSet Charsets of fonts in XFontSet + XOM XCreateOC XOC output method configuration + XLocaleOfOM, and so on Queried locale + XFontSet XmbDrawText, Locale of supplied text + XwcDrawText, and so on Locale of supplied text + + XExtentsOfFontSet, and so on + + XmbTextExtents, + + XwcTextExtents, and so on + Locale-dependent metrics + Xlib Errors: + setlocale + + XGetErrorDatabaseText, + + XGetErrorText, and so on + Locale of error message + + Clients may assume that a locale-encoded text string returned + by an X function can be passed to a C library routine, or vice + versa, if the locale is the same at the two calls. + + All text strings processed by internationalized Xlib functions + are assumed to begin in the initial state of the encoding of + the locale, if the encoding is state-dependent. + + All Xlib functions behave as if they do not change the current + locale or X modifier setting. (This means that if they do + change locale or call XSetLocaleModifiers with a non-NULL + argument, they must save and restore the current state on entry + and exit.) Also, Xlib functions on implementations that conform + to the ANSI C library do not alter the global state associated + with the ANSI C functions mblen, mbtowc, wctomb, and strtok. + +Variable Argument Lists + + Various functions in this chapter have arguments that conform + to the ANSI C variable argument list calling convention. Each + function denoted with an argument of the form ``...'' takes a + variable-length list of name and value pairs, where each name + is a string and each value is of type XPointer. A name argument + that is NULL identifies the end of the list. + + A variable-length argument list may contain a nested list. If + the name XNVaNestedList is specified in place of an argument + name, then the following value is interpreted as an + XVaNestedList value that specifies a list of values logically + inserted into the original list at the point of declaration. A + NULL identifies the end of a nested list. + + To allocate a nested variable argument list dynamically, use + XVaCreateNestedList. + + XVaNestedList XVaCreateNestedList(int dummy); + + dummy + + Specifies an unused argument (required by ANSI C). + + ... + + Specifies the variable length argument list(Al. + + The XVaCreateNestedList function allocates memory and copies + its arguments into a single list pointer, which may be used as + a value for arguments requiring a list value. Any entries are + copied as specified. Data passed by reference is not copied; + the caller must ensure data remains valid for the lifetime of + the nested list. The list should be freed using XFree when it + is no longer needed. + +Output Methods + + This section provides discussions of the following X Output + Method (XOM) topics: + * Output method overview + * Output method functions + * Output method values + * Output context functions + * Output context values + * Creating and freeing a font set + * Obtaining font set metrics + * Drawing text using font sets + +Output Method Overview + + Locale-dependent text may include one or more text components, + each of which may require different fonts and character set + encodings. In some languages, each component might have a + different drawing direction, and some components might contain + context-dependent characters that change shape based on + relationships with neighboring characters. + + When drawing such locale-dependent text, some locale-specific + knowledge is required; for example, what fonts are required to + draw the text, how the text can be separated into components, + and which fonts are selected to draw each component. Further, + when bidirectional text must be drawn, the internal + representation order of the text must be changed into the + visual representation order to be drawn. + + An X Output Method provides a functional interface so that + clients do not have to deal directly with such locale-dependent + details. Output methods provide the following capabilities: + * Creating a set of fonts required to draw locale-dependent + text. + * Drawing locale-dependent text with a font set without the + caller needing to be aware of locale dependencies. + * Obtaining the escapement and extents in pixels of + locale-dependent text. + * Determining if bidirectional or context-dependent drawing + is required in a specific locale with a specific font set. + + Two different abstractions are used in the representation of + the output method for clients. + + The abstraction used to communicate with an output method is an + opaque data structure represented by the XOM data type. The + abstraction for representing the state of a particular output + thread is called an output context. The Xlib representation of + an output context is an XOC, which is compatible with XFontSet + in terms of its functional interface, but is a broader, more + generalized abstraction. + +Output Method Functions + + To open an output method, use XOpenOM. + + XOM XOpenOM(Display *display, XrmDatabase db, char *res_name, + char *res_class); + + display + + Specifies the connection to the X server. + + db + + Specifies a pointer to the resource database. + + res_name + + Specifies the full resource name of the application. + + res_class + + Specifies the full class name of the application. + + The XOpenOM function opens an output method matching the + current locale and modifiers specification. The current locale + and modifiers are bound to the output method when XOpenOM is + called. The locale associated with an output method cannot be + changed. + + The specific output method to which this call will be routed is + identified on the basis of the current locale and modifiers. + XOpenOM will identify a default output method corresponding to + the current locale. That default can be modified using + XSetLocaleModifiers to set the output method modifier. + + The db argument is the resource database to be used by the + output method for looking up resources that are private to the + output method. It is not intended that this database be used to + look up values that can be set as OC values in an output + context. If db is NULL, no database is passed to the output + method. + + The res_name and res_class arguments specify the resource name + and class of the application. They are intended to be used as + prefixes by the output method when looking up resources that + are common to all output contexts that may be created for this + output method. The characters used for resource names and + classes must be in the X Portable Character Set. The resources + looked up are not fully specified if res_name or res_class is + NULL. + + The res_name and res_class arguments are not assumed to exist + beyond the call to XOpenOM. The specified resource database is + assumed to exist for the lifetime of the output method. + + XOpenOM returns NULL if no output method could be opened. + + To close an output method, use XCloseOM. + + Status XCloseOM(XOM om); + + om + + Specifies the output method. + + The XCloseOM function closes the specified output method. + + To set output method attributes, use XSetOMValues. + + char *XSetOMValues(XOM om); + + om + + Specifies the output method. + + ... + + Specifies the variable-length argument list to set XOM values. + + The XSetOMValues function presents a variable argument list + programming interface for setting properties or features of the + specified output method. This function returns NULL if it + succeeds; otherwise, it returns the name of the first argument + that could not be obtained. + + No standard arguments are currently defined by Xlib. + + To query an output method, use XGetOMValues. + + char *XGetOMValues(XOM om); + + om + + Specifies the output method. + + ... + + Specifies the variable-length argument list to get XOM values. + + The XGetOMValues function presents a variable argument list + programming interface for querying properties or features of + the specified output method. This function returns NULL if it + succeeds; otherwise, it returns the name of the first argument + that could not be obtained. + + To obtain the display associated with an output method, use + XDisplayOfOM. + + Display *XDisplayOfOM(XOM om); + + om + + Specifies the output method. + + The XDisplayOfOM function returns the display associated with + the specified output method. + + To get the locale associated with an output method, use + XLocaleOfOM. + + char *XLocaleOfOM(XOM om); + + om + + Specifies the output method. + + The XLocaleOfOM returns the locale associated with the + specified output method. + +X Output Method Values + + The following table describes how XOM values are interpreted by + an output method. The first column lists the XOM values. The + second column indicates how each of the XOM values are treated + by a particular output style. + + The following key applies to this table. + Key Explanation + G This value may be read using XGetOMValues. + + XOM Value Key + XNRequiredCharSet G + XNQueryOrientation G + XNDirectionalDependentDrawing G + XNContextualDrawing G + +Required Char Set + + The XNRequiredCharSet argument returns the list of charsets + that are required for loading the fonts needed for the locale. + The value of the argument is a pointer to a structure of type + XOMCharSetList. + + The XOMCharSetList structure is defined as follows: + + +typedef struct { + int charset_count; + char **charset_list; +} XOMCharSetList; + + The charset_list member is a list of one or more + null-terminated charset names, and the charset_count member is + the number of charset names. + + The required charset list is owned by Xlib and should not be + modified or freed by the client. It will be freed by a call to + XCloseOM with the associated XOM. Until freed, its contents + will not be modified by Xlib. + +Query Orientation + + The XNQueryOrientation argument returns the global orientation + of text when drawn. Other than XOMOrientation_LTR_TTB, the set + of orientations supported is locale-dependent. The value of the + argument is a pointer to a structure of type XOMOrientation. + Clients are responsible for freeing the XOMOrientation + structure by using XFree; this also frees the contents of the + structure. + + +typedef struct { + int num_orientation; + XOrientation *orientation; /* Input Text description */ +} XOMOrientation; + +typedef enum { + XOMOrientation_LTR_TTB, + XOMOrientation_RTL_TTB, + XOMOrientation_TTB_LTR, + XOMOrientation_TTB_RTL, + XOMOrientation_Context +} XOrientation; + + The possible value for XOrientation may be: + * XOMOrientation_LTR_TTB left-to-right, top-to-bottom global + orientation + * XOMOrientation_RTL_TTB right-to-left, top-to-bottom global + orientation + * XOMOrientation_TTB_LTR top-to-bottom, left-to-right global + orientation + * XOMOrientation_TTB_RTL top-to-bottom, right-to-left global + orientation + * XOMOrientation_Context contextual global orientation + +Directional Dependent Drawing + + The XNDirectionalDependentDrawing argument indicates whether + the text rendering functions implement implicit handling of + directional text. If this value is True, the output method has + knowledge of directional dependencies and reorders text as + necessary when rendering text. If this value is False, the + output method does not implement any directional text handling, + and all character directions are assumed to be left-to-right. + + Regardless of the rendering order of characters, the origins of + all characters are on the primary draw direction side of the + drawing origin. + + This OM value presents functionality identical to the + XDirectionalDependentDrawing function. + +Context Dependent Drawing + + The XNContextualDrawing argument indicates whether the text + rendering functions implement implicit context-dependent + drawing. If this value is True, the output method has knowledge + of context dependencies and performs character shape editing, + combining glyphs to present a single character as necessary. + The actual shape editing is dependent on the locale + implementation and the font set used. + + This OM value presents functionality identical to the + XContextualDrawing function. + +Output Context Functions + + An output context is an abstraction that contains both the data + required by an output method and the information required to + display that data. There can be multiple output contexts for + one output method. The programming interfaces for creating, + reading, or modifying an output context use a variable argument + list. The name elements of the argument lists are referred to + as XOC values. It is intended that output methods be controlled + by these XOC values. As new XOC values are created, they should + be registered with the X Consortium. An XOC can be used + anywhere an XFontSet can be used, and vice versa; XFontSet is + retained for compatibility with previous releases. The concepts + of output methods and output contexts include broader, more + generalized abstraction than font set, supporting complex and + more intelligent text display, and dealing not only with + multiple fonts but also with context dependencies. However, + XFontSet is widely used in several interfaces, so XOC is + defined as an upward compatible type of XFontSet. + + To create an output context, use XCreateOC. + + XOC XCreateOC(XOM om); + + om + + Specifies the output method. + + ... + + Specifies the variable-length argument list to set XOC values. + + The XCreateOC function creates an output context within the + specified output method. + + The base font names argument is mandatory at creation time, and + the output context will not be created unless it is provided. + All other output context values can be set later. + + XCreateOC returns NULL if no output context could be created. + NULL can be returned for any of the following reasons: + * A required argument was not set. + * A read-only argument was set. + * An argument name is not recognized. + * The output method encountered an output method + implementation-dependent error. + + XCreateOC can generate a BadAtom error. + + To destroy an output context, use XDestroyOC. + + void XDestroyOC(XOC oc); + + oc + + Specifies the output context. + + The XDestroyOC function destroys the specified output context. + + To get the output method associated with an output context, use + XOMOfOC. + + XOM XOMOfOC(XOC oc); + + oc + + Specifies the output context. + + The XOMOfOC function returns the output method associated with + the specified output context. + + Xlib provides two functions for setting and reading output + context values, respectively, XSetOCValues and XGetOCValues. + Both functions have a variable-length argument list. In that + argument list, any XOC value's name must be denoted with a + character string using the X Portable Character Set. + + To set XOC values, use XSetOCValues. + + char *XSetOCValues(XOC oc); + + oc + + Specifies the output context. + + ... + + Specifies the variable-length argument list to set XOC values. + + The XSetOCValues function returns NULL if no error occurred; + otherwise, it returns the name of the first argument that could + not be set. An argument might not be set for any of the + following reasons: + * The argument is read-only. + * The argument name is not recognized. + * An implementation-dependent error occurs. + + Each value to be set must be an appropriate datum, matching the + data type imposed by the semantics of the argument. + + XSetOCValues can generate a BadAtom error. + + To obtain XOC values, use XGetOCValues. + + char *XGetOCValues(XOC oc); + + oc + + Specifies the output context. + + ... + + Specifies the variable-length argument list to get XOC values. + + The XGetOCValues function returns NULL if no error occurred; + otherwise, it returns the name of the first argument that could + not be obtained. An argument might not be obtained for any of + the following reasons: + * The argument name is not recognized. + * An implementation-dependent error occurs. + + Each argument value following a name must point to a location + where the value is to be stored. + +Output Context Values + + The following table describes how XOC values are interpreted by + an output method. The first column lists the XOC values. The + second column indicates the alternative interfaces that + function identically and are provided for compatibility with + previous releases. The third column indicates how each of the + XOC values is treated. + + The following keys apply to this table. + Key Explanation + C This value must be set with XCreateOC. + D This value may be set using XCreateOC. If it is not set,a + default is provided. + G This value may be read using XGetOCValues. + S This value must be set using XSetOCValues. + + XOC Value Alternative Interface Key + BaseFontName XCreateFontSet C-G + MissingCharSet XCreateFontSet G + DefaultString XCreateFontSet G + Orientation - D-S-G + ResourceName - S-G + ResourceClass - S-G + FontInfo XFontsOfFontSet G + OMAutomatic - G + +Base Font Name + + The XNBaseFontName argument is a list of base font names that + Xlib uses to load the fonts needed for the locale. The base + font names are a comma-separated list. The string is + null-terminated and is assumed to be in the Host Portable + Character Encoding; otherwise, the result is + implementation-dependent. White space immediately on either + side of a separating comma is ignored. + + Use of XLFD font names permits Xlib to obtain the fonts needed + for a variety of locales from a single locale-independent base + font name. The single base font name should name a family of + fonts whose members are encoded in the various charsets needed + by the locales of interest. + + An XLFD base font name can explicitly name a charset needed for + the locale. This allows the user to specify an exact font for + use with a charset required by a locale, fully controlling the + font selection. + + If a base font name is not an XLFD name, Xlib will attempt to + obtain an XLFD name from the font properties for the font. If + Xlib is successful, the XGetOCValues function will return this + XLFD name instead of the client-supplied name. + + This argument must be set at creation time and cannot be + changed. If no fonts exist for any of the required charsets, or + if the locale definition in Xlib requires that a font exist for + a particular charset and a font is not found for that charset, + XCreateOC returns NULL. + + When querying for the XNBaseFontName XOC value, XGetOCValues + returns a null-terminated string identifying the base font + names that Xlib used to load the fonts needed for the locale. + This string is owned by Xlib and should not be modified or + freed by the client. The string will be freed by a call to + XDestroyOC with the associated XOC. Until freed, the string + contents will not be modified by Xlib. + +Missing CharSet + + The XNMissingCharSet argument returns the list of required + charsets that are missing from the font set. The value of the + argument is a pointer to a structure of type XOMCharSetList. + + If fonts exist for all of the charsets required by the current + locale, charset_list is set to NULL and charset_count is set to + zero. If no fonts exist for one or more of the required + charsets, charset_list is set to a list of one or more + null-terminated charset names for which no fonts exist, and + charset_count is set to the number of missing charsets. The + charsets are from the list of the required charsets for the + encoding of the locale and do not include any charsets to which + Xlib may be able to remap a required charset. + + The missing charset list is owned by Xlib and should not be + modified or freed by the client. It will be freed by a call to + XDestroyOC with the associated XOC. Until freed, its contents + will not be modified by Xlib. + +Default String + + When a drawing or measuring function is called with an XOC that + has missing charsets, some characters in the locale will not be + drawable. The XNDefaultString argument returns a pointer to a + string that represents the glyphs that are drawn with this XOC + when the charsets of the available fonts do not include all + glyphs required to draw a character. The string does not + necessarily consist of valid characters in the current locale + and is not necessarily drawn with the fonts loaded for the font + set, but the client can draw or measure the default glyphs by + including this string in a string being drawn or measured with + the XOC. + + If the XNDefaultString argument returned the empty string (""), + no glyphs are drawn and the escapement is zero. The returned + string is null-terminated. It is owned by Xlib and should not + be modified or freed by the client. It will be freed by a call + to XDestroyOC with the associated XOC. Until freed, its + contents will not be modified by Xlib. + +Orientation + + The XNOrientation argument specifies the current orientation of + text when drawn. The value of this argument is one of the + values returned by the XGetOMValues function with the + XNQueryOrientation argument specified in the XOrientation list. + The value of the argument is of type XOrientation. When + XNOrientation is queried, the value specifies the current + orientation. When XNOrientation is set, a value is used to set + the current orientation. + + When XOMOrientation_Context is set, the text orientation of the + text is determined according to an implementation-defined + method (for example, ISO 6429 control sequences), and the + initial text orientation for locale-dependent Xlib functions is + assumed to be XOMOrientation_LTR_TTB. + + The XNOrientation value does not change the prime drawing + direction for Xlib drawing functions. + +Resource Name and Class + + The XNResourceName and XNResourceClass arguments are strings + that specify the full name and class used by the client to + obtain resources for the display of the output context. These + values should be used as prefixes for name and class when + looking up resources that may vary according to the output + context. If these values are not set, the resources will not be + fully specified. + + It is not intended that values that can be set as XOM values be + set as resources. + + When querying for the XNResourceName or XNResourceClass XOC + value, XGetOCValues returns a null-terminated string. This + string is owned by Xlib and should not be modified or freed by + the client. The string will be freed by a call to XDestroyOC + with the associated XOC or when the associated value is changed + via XSetOCValues. Until freed, the string contents will not be + modified by Xlib. + +Font Info + + The XNFontInfo argument specifies a list of one or more + XFontStruct structures and font names for the fonts used for + drawing by the given output context. The value of the argument + is a pointer to a structure of type XOMFontInfo. + + + +typedef struct { + int num_font; + XFontStruct **font_struct_list; + char **font_name_list; +} XOMFontInfo; + + A list of pointers to the XFontStruct structures is returned to + font_struct_list. A list of pointers to null-terminated, + fully-specified font name strings in the locale of the output + context is returned to font_name_list. The font_name_list order + corresponds to the font_struct_list order. The number of + XFontStruct structures and font names is returned to num_font. + + Because it is not guaranteed that a given character will be + imaged using a single font glyph, there is no provision for + mapping a character or default string to the font properties, + font ID, or direction hint for the font for the character. The + client may access the XFontStruct list to obtain these values + for all the fonts currently in use. + + Xlib does not guarantee that fonts are loaded from the server + at the creation of an XOC. Xlib may choose to cache font data, + loading it only as needed to draw text or compute text + dimensions. Therefore, existence of the per_char metrics in the + XFontStruct structures in the XFontStructSet is undefined. + Also, note that all properties in the XFontStruct structures + are in the STRING encoding. + + The client must not free the XOMFontInfo struct itself; it will + be freed when the XOC is closed. + +OM Automatic + + The XNOMAutomatic argument returns whether the associated + output context was created by XCreateFontSet or not. Because + the XFreeFontSet function not only destroys the output context + but also closes the implicit output method associated with it, + XFreeFontSet should be used with any output context created by + XCreateFontSet. However, it is possible that a client does not + know how the output context was created. Before a client + destroys the output context, it can query whether XNOMAutomatic + is set to determine whether XFreeFontSet or XDestroyOC should + be used to destroy the output context. + +Creating and Freeing a Font Set + + Xlib international text drawing is done using a set of one or + more fonts, as needed for the locale of the text. Fonts are + loaded according to a list of base font names supplied by the + client and the charsets required by the locale. The XFontSet is + an opaque type representing the state of a particular output + thread and is equivalent to the type XOC. + + The XCreateFontSet function is a convenience function for + creating an output context using only default values. The + returned XFontSet has an implicitly created XOM. This XOM has + an OM value XNOMAutomatic automatically set to True so that the + output context self indicates whether it was created by + XCreateOC or XCreateFontSet. + + XFontSet XCreateFontSet(Display *display, char + *base_font_name_list, char ***missing_charset_list_return, int + *missing_charset_count_return, char **def_string_return); + + display + + Specifies the connection to the X server. + + base_font_name_list + + Specifies the base font names. + + missing_charset_list_return + + Returns the missing charsets. + + missing_charset_count_return + + Returns the number of missing charsets. + + def_string_return + + Returns the string drawn for missing charsets. + + The XCreateFontSet function creates a font set for the + specified display. The font set is bound to the current locale + when XCreateFontSet is called. The font set may be used in + subsequent calls to obtain font and character information and + to image text in the locale of the font set. + + The base_font_name_list argument is a list of base font names + that Xlib uses to load the fonts needed for the locale. The + base font names are a comma-separated list. The string is + null-terminated and is assumed to be in the Host Portable + Character Encoding; otherwise, the result is + implementation-dependent. White space immediately on either + side of a separating comma is ignored. + + Use of XLFD font names permits Xlib to obtain the fonts needed + for a variety of locales from a single locale-independent base + font name. The single base font name should name a family of + fonts whose members are encoded in the various charsets needed + by the locales of interest. + + An XLFD base font name can explicitly name a charset needed for + the locale. This allows the user to specify an exact font for + use with a charset required by a locale, fully controlling the + font selection. + + If a base font name is not an XLFD name, Xlib will attempt to + obtain an XLFD name from the font properties for the font. If + this action is successful in obtaining an XLFD name, the + XBaseFontNameListOfFontSet function will return this XLFD name + instead of the client-supplied name. + + Xlib uses the following algorithm to select the fonts that will + be used to display text with the XFontSet. + + For each font charset required by the locale, the base font + name list is searched for the first appearance of one of the + following cases that names a set of fonts that exist at the + server: + * The first XLFD-conforming base font name that specifies the + required charset or a superset of the required charset in + its CharSetRegistry and CharSetEncoding fields. The + implementation may use a base font name whose specified + charset is a superset of the required charset, for example, + an ISO8859-1 font for an ASCII charset. + * The first set of one or more XLFD-conforming base font + names that specify one or more charsets that can be + remapped to support the required charset. The Xlib + implementation may recognize various mappings from a + required charset to one or more other charsets and use the + fonts for those charsets. For example, JIS Roman is ASCII + with tilde and backslash replaced by yen and overbar; Xlib + may load an ISO8859-1 font to support this character set if + a JIS Roman font is not available. + * The first XLFD-conforming font name or the first non-XLFD + font name for which an XLFD font name can be obtained, + combined with the required charset (replacing the + CharSetRegistry and CharSetEncoding fields in the XLFD font + name). As in case 1, the implementation may use a charset + that is a superset of the required charset. + * The first font name that can be mapped in some + implementation-dependent manner to one or more fonts that + support imaging text in the charset. + + For example, assume that a locale required the charsets: + +ISO8859-1 +JISX0208.1983 +JISX0201.1976 +GB2312-1980.0 + + The user could supply a base_font_name_list that explicitly + specifies the charsets, ensuring that specific fonts are used + if they exist. For example: + +"-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240-JISX0208.1983-0,\\ +-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120-JISX0201.1976-0,\\ +-GB-Fixed-Medium-R-Normal--26-180-100-100-C-240-GB2312-1980.0,\\ +-Adobe-Courier-Bold-R-Normal--25-180-75-75-M-150-ISO8859-1" + + Alternatively, the user could supply a base_font_name_list that + omits the charsets, letting Xlib select font charsets required + for the locale. For example: + +"-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240,\\ +-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120,\\ +-GB-Fixed-Medium-R-Normal--26-180-100-100-C-240,\\ +-Adobe-Courier-Bold-R-Normal--25-180-100-100-M-150" + + Alternatively, the user could simply supply a single base font + name that allows Xlib to select from all available fonts that + meet certain minimum XLFD property requirements. For example: + +"-*-*-*-R-Normal--*-180-100-100-*-*" + + If XCreateFontSet is unable to create the font set, either + because there is insufficient memory or because the current + locale is not supported, XCreateFontSet returns NULL, + missing_charset_list_return is set to NULL, and + missing_charset_count_return is set to zero. If fonts exist for + all of the charsets required by the current locale, + XCreateFontSet returns a valid XFontSet, + missing_charset_list_return is set to NULL, and + missing_charset_count_return is set to zero. + + If no font exists for one or more of the required charsets, + XCreateFontSet sets missing_charset_list_return to a list of + one or more null-terminated charset names for which no font + exists and sets missing_charset_count_return to the number of + missing fonts. The charsets are from the list of the required + charsets for the encoding of the locale and do not include any + charsets to which Xlib may be able to remap a required charset. + + If no font exists for any of the required charsets or if the + locale definition in Xlib requires that a font exist for a + particular charset and a font is not found for that charset, + XCreateFontSet returns NULL. Otherwise, XCreateFontSet returns + a valid XFontSet to font_set. + + When an Xmb/wc drawing or measuring function is called with an + XFontSet that has missing charsets, some characters in the + locale will not be drawable. If def_string_return is non-NULL, + XCreateFontSet returns a pointer to a string that represents + the glyphs that are drawn with this XFontSet when the charsets + of the available fonts do not include all font glyphs required + to draw a codepoint. The string does not necessarily consist of + valid characters in the current locale and is not necessarily + drawn with the fonts loaded for the font set, but the client + can draw and measure the default glyphs by including this + string in a string being drawn or measured with the XFontSet. + + If the string returned to def_string_return is the empty string + (""), no glyphs are drawn, and the escapement is zero. The + returned string is null-terminated. It is owned by Xlib and + should not be modified or freed by the client. It will be freed + by a call to XFreeFontSet with the associated XFontSet. Until + freed, its contents will not be modified by Xlib. + + The client is responsible for constructing an error message + from the missing charset and default string information and may + choose to continue operation in the case that some fonts did + not exist. + + The returned XFontSet and missing charset list should be freed + with XFreeFontSet and XFreeStringList, respectively. The + client-supplied base_font_name_list may be freed by the client + after calling XCreateFontSet. + + To obtain a list of XFontStruct structures and full font names + given an XFontSet, use XFontsOfFontSet. + + int XFontsOfFontSet(XFontSet font_set, XFontStruct + ***font_struct_list_return, char ***font_name_list_return); + + font_set + + Specifies the font set. + + font_struct_list_return + + Returns the list of font structs. + + font_name_list_return + + Returns the list of font names. + + The XFontsOfFontSet function returns a list of one or more + XFontStructs and font names for the fonts used by the Xmb and + Xwc layers for the given font set. A list of pointers to the + XFontStruct structures is returned to font_struct_list_return. + A list of pointers to null-terminated, fully specified font + name strings in the locale of the font set is returned to + font_name_list_return. The font_name_list order corresponds to + the font_struct_list order. The number of XFontStruct + structures and font names is returned as the value of the + function. + + Because it is not guaranteed that a given character will be + imaged using a single font glyph, there is no provision for + mapping a character or default string to the font properties, + font ID, or direction hint for the font for the character. The + client may access the XFontStruct list to obtain these values + for all the fonts currently in use. + + Xlib does not guarantee that fonts are loaded from the server + at the creation of an XFontSet. Xlib may choose to cache font + data, loading it only as needed to draw text or compute text + dimensions. Therefore, existence of the per_char metrics in the + XFontStruct structures in the XFontStructSet is undefined. + Also, note that all properties in the XFontStruct structures + are in the STRING encoding. + + The XFontStruct and font name lists are owned by Xlib and + should not be modified or freed by the client. They will be + freed by a call to XFreeFontSet with the associated XFontSet. + Until freed, their contents will not be modified by Xlib. + + To obtain the base font name list and the selected font name + list given an XFontSet, use XBaseFontNameListOfFontSet. + + char *XBaseFontNameListOfFontSet(XFontSet font_set); + + font_set + + Specifies the font set. + + The XBaseFontNameListOfFontSet function returns the original + base font name list supplied by the client when the XFontSet + was created. A null-terminated string containing a list of + comma-separated font names is returned as the value of the + function. White space may appear immediately on either side of + separating commas. + + If XCreateFontSet obtained an XLFD name from the font + properties for the font specified by a non-XLFD base name, the + XBaseFontNameListOfFontSet function will return the XLFD name + instead of the non-XLFD base name. + + The base font name list is owned by Xlib and should not be + modified or freed by the client. It will be freed by a call to + XFreeFontSet with the associated XFontSet. Until freed, its + contents will not be modified by Xlib. + + To obtain the locale name given an XFontSet, use + XLocaleOfFontSet. + + char *XLocaleOfFontSet(XFontSet font_set); + + font_set + + Specifies the font set. + + The XLocaleOfFontSet function returns the name of the locale + bound to the specified XFontSet, as a null-terminated string. + + The returned locale name string is owned by Xlib and should not + be modified or freed by the client. It may be freed by a call + to XFreeFontSet with the associated XFontSet. Until freed, it + will not be modified by Xlib. + + The XFreeFontSet function is a convenience function for freeing + an output context. XFreeFontSet also frees its associated XOM + if the output context was created by XCreateFontSet. + + void XFreeFontSet(Display *display, XFontSet font_set); + + display + + Specifies the connection to the X server. + + font_set + + Specifies the font set. + + The XFreeFontSet function frees the specified font set. The + associated base font name list, font name list, XFontStruct + list, and XFontSetExtents, if any, are freed. + +Obtaining Font Set Metrics + + Metrics for the internationalized text drawing functions are + defined in terms of a primary draw direction, which is the + default direction in which the character origin advances for + each succeeding character in the string. The Xlib interface is + currently defined to support only a left-to-right primary draw + direction. The drawing origin is the position passed to the + drawing function when the text is drawn. The baseline is a line + drawn through the drawing origin parallel to the primary draw + direction. Character ink is the pixels painted in the + foreground color and does not include interline or + intercharacter spacing or image text background pixels. + + The drawing functions are allowed to implement implicit text + directionality control, reversing the order in which characters + are rendered along the primary draw direction in response to + locale-specific lexical analysis of the string. + + Regardless of the character rendering order, the origins of all + characters are on the primary draw direction side of the + drawing origin. The screen location of a particular character + image may be determined with XmbTextPerCharExtents or + XwcTextPerCharExtents. + + The drawing functions are allowed to implement + context-dependent rendering, where the glyphs drawn for a + string are not simply a concatenation of the glyphs that + represent each individual character. A string of two characters + drawn with XmbDrawString may render differently than if the two + characters were drawn with separate calls to XmbDrawString. If + the client appends or inserts a character in a previously drawn + string, the client may need to redraw some adjacent characters + to obtain proper rendering. + + To find out about direction-dependent rendering, use + XDirectionalDependentDrawing. + + Bool XDirectionalDependentDrawing(XFontSet font_set); + + font_set + + Specifies the font set. + + The XDirectionalDependentDrawing function returns True if the + drawing functions implement implicit text directionality; + otherwise, it returns False. + + To find out about context-dependent rendering, use + XContextualDrawing. + + Bool XContextualDrawing(XFontSet font_set); + + font_set + + Specifies the font set. + + The XContextualDrawing function returns True if text drawn with + the font set might include context-dependent drawing; + otherwise, it returns False. + + To find out about context-dependent or direction-dependent + rendering, use XContextDependentDrawing. + + Bool XContextDependentDrawing(XFontSet font_set); + + font_set + + Specifies the font set. + + The XContextDependentDrawing function returns True if the + drawing functions implement implicit text directionality or if + text drawn with the font_set might include context-dependent + drawing; otherwise, it returns False. + + The drawing functions do not interpret newline, tab, or other + control characters. The behavior when nonprinting characters + other than space are drawn is implementation-dependent. It is + the client's responsibility to interpret control characters in + a text stream. + + The maximum character extents for the fonts that are used by + the text drawing layers can be accessed by the XFontSetExtents + structure: + + + +typedef struct { + XRectangle max_ink_extent; /* over all drawable characters */ + XRectangle max_logical_extent; /* over all drawable characters */ +} XFontSetExtents; + + The XRectangle structures used to return font set metrics are + the usual Xlib screen-oriented rectangles with x, y giving the + upper left corner, and width and height always positive. + + The max_ink_extent member gives the maximum extent, over all + drawable characters, of the rectangles that bound the character + glyph image drawn in the foreground color, relative to a + constant origin. See XmbTextExtents and XwcTextExtents for + detailed semantics. + + The max_logical_extent member gives the maximum extent, over + all drawable characters, of the rectangles that specify minimum + spacing to other graphical features, relative to a constant + origin. Other graphical features drawn by the client, for + example, a border surrounding the text, should not intersect + this rectangle. The max_logical_extent member should be used to + compute minimum interline spacing and the minimum area that + must be allowed in a text field to draw a given number of + arbitrary characters. + + Due to context-dependent rendering, appending a given character + to a string may change the string's extent by an amount other + than that character's individual extent. + + The rectangles for a given character in a string can be + obtained from XmbTextPerCharExtents or XwcTextPerCharExtents. + + To obtain the maximum extents structure given an XFontSet, use + XExtentsOfFontSet. + + XFontSetExtents *XExtentsOfFontSet(XFontSet font_set); + + font_set + + Specifies the font set. + + The XExtentsOfFontSet function returns an XFontSetExtents + structure for the fonts used by the Xmb and Xwc layers for the + given font set. + + The XFontSetExtents structure is owned by Xlib and should not + be modified or freed by the client. It will be freed by a call + to XFreeFontSet with the associated XFontSet. Until freed, its + contents will not be modified by Xlib. + + To obtain the escapement in pixels of the specified text as a + value, use XmbTextEscapement or XwcTextEscapement. + + int XmbTextEscapement(XFontSet font_set, char *string, int + num_bytes); + + int XwcTextEscapement(XFontSet font_set, wchar_t *string, int + num_wchars); + + font_set + + Specifies the font set. + + string + + Specifies the character string. + + num_bytes + + Specifies the number of bytes in the string argument. + + num_wchars + + Specifies the number of characters in the string argument. + + The XmbTextEscapement and XwcTextEscapement functions return + the escapement in pixels of the specified string as a value, + using the fonts loaded for the specified font set. The + escapement is the distance in pixels in the primary draw + direction from the drawing origin to the origin of the next + character to be drawn, assuming that the rendering of the next + character is not dependent on the supplied string. + + Regardless of the character rendering order, the escapement is + always positive. + + To obtain the overall_ink_return and overall_logical_return + arguments, the overall bounding box of the string's image, and + a logical bounding box, use XmbTextExtents or XwcTextExtents. + + int XmbTextExtents(XFontSet font_set, char *string, int + num_bytes, XRectangle *overall_ink_return, XRectangle + *overall_logical_return); + + int XwcTextExtents(XFontSet font_set, wchar_t *string, int + num_wchars, XRectangle *overall_ink_return, XRectangle + *overall_logical_return); + + font_set + + Specifies the font set. + + string + + Specifies the character string. + + num_bytes + + Specifies the number of bytes in the string argument. + + num_wchars + + Specifies the number of characters in the string argument. + + overall_ink_return + + Returns the overall ink dimensions. + + overall_logical_return + + Returns the overall logical dimensions. + + The XmbTextExtents and XwcTextExtents functions set the + components of the specified overall_ink_return and + overall_logical_return arguments to the overall bounding box of + the string's image and a logical bounding box for spacing + purposes, respectively. They return the value returned by + XmbTextEscapement or XwcTextEscapement. These metrics are + relative to the drawing origin of the string, using the fonts + loaded for the specified font set. + + If the overall_ink_return argument is non-NULL, it is set to + the bounding box of the string's character ink. The + overall_ink_return for a nondescending, horizontally drawn + Latin character is conventionally entirely above the baseline; + that is, overall_ink_return.height <= -overall_ink_return.y. + The overall_ink_return for a nonkerned character is entirely + at, and to the right of, the origin; that is, + overall_ink_return.x >= 0. A character consisting of a single + pixel at the origin would set overall_ink_return fields y = 0, + x = 0, width = 1, and height = 1. + + If the overall_logical_return argument is non-NULL, it is set + to the bounding box that provides minimum spacing to other + graphical features for the string. Other graphical features, + for example, a border surrounding the text, should not + intersect this rectangle. + + When the XFontSet has missing charsets, metrics for each + unavailable character are taken from the default string + returned by XCreateFontSet so that the metrics represent the + text as it will actually be drawn. The behavior for an invalid + codepoint is undefined. + + To determine the effective drawing origin for a character in a + drawn string, the client should call XmbTextPerCharExtents on + the entire string, then on the character, and subtract the x + values of the returned rectangles for the character. This is + useful to redraw portions of a line of text or to justify + words, but for context-dependent rendering, the client should + not assume that it can redraw the character by itself and get + the same rendering. + + To obtain per-character information for a text string, use + XmbTextPerCharExtents or XwcTextPerCharExtents. + + Status XmbTextPerCharExtents(XFontSet font_set, char *string, + int num_bytes, XRectangle *ink_array_return, XRectangle + *logical_array_return, int array_size, int *num_chars_return, + XRectangle *overall_ink_return, XRectangle + *overall_logical_return); + + Status XwcTextPerCharExtents(XFontSet font_set, wchar_t + *string, int num_wchars, XRectangle *ink_array_return, + XRectangle *logical_array_return, int array_size, int + *num_chars_return, XRectangle *overall_ink_return, XRectangle + *overall_logical_return); + + font_set + + Specifies the font set. + + string + + Specifies the character string. + + num_bytes + + Specifies the number of bytes in the string argument. + + num_wchars + + Specifies the number of characters in the string argument. + + ink_array_return + + Returns the ink dimensions for each character. + + logical_array_return + + Returns the logical dimensions for each character. + + array_size + + Specifies the size of ink_array_return and + logical_array_return. The caller must pass in arrays of this + size. + + num_chars_return + + Returns the number of characters in the string argument. + + overall_ink_return + + Returns the overall ink dimensions. + + overall_logical_return + + Returns the overall logical dimensions. + + The XmbTextPerCharExtents and XwcTextPerCharExtents functions + return the text dimensions of each character of the specified + text, using the fonts loaded for the specified font set. Each + successive element of ink_array_return and logical_array_return + is set to the successive character's drawn metrics, relative to + the drawing origin of the string and one rectangle for each + character in the supplied text string. The number of elements + of ink_array_return and logical_array_return that have been set + is returned to num_chars_return. + + Each element of ink_array_return is set to the bounding box of + the corresponding character's drawn foreground color. Each + element of logical_array_return is set to the bounding box that + provides minimum spacing to other graphical features for the + corresponding character. Other graphical features should not + intersect any of the logical_array_return rectangles. + + Note that an XRectangle represents the effective drawing + dimensions of the character, regardless of the number of font + glyphs that are used to draw the character or the direction in + which the character is drawn. If multiple characters map to a + single character glyph, the dimensions of all the XRectangles + of those characters are the same. + + When the XFontSet has missing charsets, metrics for each + unavailable character are taken from the default string + returned by XCreateFontSet so that the metrics represent the + text as it will actually be drawn. The behavior for an invalid + codepoint is undefined. + + If the array_size is too small for the number of characters in + the supplied text, the functions return zero and + num_chars_return is set to the number of rectangles required. + Otherwise, the functions return a nonzero value. + + If the overall_ink_return or overall_logical_return argument is + non-NULL, XmbTextPerCharExtents and XwcTextPerCharExtents + return the maximum extent of the string's metrics to + overall_ink_return or overall_logical_return, as returned by + XmbTextExtents or XwcTextExtents. + +Drawing Text Using Font Sets + + The functions defined in this section draw text at a specified + location in a drawable. They are similar to the functions + XDrawText, XDrawString, and XDrawImageString except that they + work with font sets instead of single fonts and interpret the + text based on the locale of the font set instead of treating + the bytes of the string as direct font indexes. See section 8.6 + for details of the use of Graphics Contexts (GCs) and possible + protocol errors. If a BadFont error is generated, characters + prior to the offending character may have been drawn. + + The text is drawn using the fonts loaded for the specified font + set; the font in the GC is ignored and may be modified by the + functions. No validation that all fonts conform to some width + rule is performed. + + The text functions XmbDrawText and XwcDrawText use the + following structures: + + + +typedef struct { + char *chars; /* pointer to string */ + int nchars; /* number of bytes */ + int delta; /* pixel delta between strings */ + XFontSet font_set; /* fonts, None means don't change */ +} XmbTextItem; + + + +typedef struct { + wchar_t *chars; /* pointer to wide char string */ + int nchars; /* number of wide characters */ + int delta; /* pixel delta between strings */ + XFontSet font_set; /* fonts, None means don't change */ +} XwcTextItem; + + To draw text using multiple font sets in a given drawable, use + XmbDrawText or XwcDrawText. + + void XmbDrawText(Display *display, Drawable d, GC gc, int x, + int y, XmbTextItem *items, int nitems); + + void XwcDrawText(Display *display, Drawable d, GC gc, int x, + int y, XwcTextItem *items, int nitems); + + display + + Specifies the connection to the X server. + + d + + Specifies the drawable. + + gc + + Specifies the GC. + + x + + y + + Specify the x and y coordinates of the position in the new + parent window. + + items + + Specifies an array of text items. + + nitems + + Specifies the number of text items in the array. + + The XmbDrawText and XwcDrawText functions allow complex spacing + and font set shifts between text strings. Each text item is + processed in turn, with the origin of a text element advanced + in the primary draw direction by the escapement of the previous + text item. A text item delta specifies an additional escapement + of the text item drawing origin in the primary draw direction. + A font_set member other than None in an item causes the font + set to be used for this and subsequent text items in the + text_items list. Leading text items with a font_set member set + to None will not be drawn. + + XmbDrawText and XwcDrawText do not perform any + context-dependent rendering between text segments. Clients may + compute the drawing metrics by passing each text segment to + XmbTextExtents and XwcTextExtents or XmbTextPerCharExtents and + XwcTextPerCharExtents. When the XFontSet has missing charsets, + each unavailable character is drawn with the default string + returned by XCreateFontSet. The behavior for an invalid + codepoint is undefined. + + To draw text using a single font set in a given drawable, use + XmbDrawString or XwcDrawString. + + void XmbDrawString(Display *display, Drawable d, XFontSet + font_set, GC gc, int x, int y, char *string, int num_bytes); + + void XwcDrawString(Display *display, Drawable d, XFontSet + font_set, GC gc, int x, int y, wchar_t *string, int + num_wchars); + + display + + Specifies the connection to the X server. + + d + + Specifies the drawable. + + font_set + + Specifies the font set. + + gc + + Specifies the GC. + + x + + y + + Specify the x and y coordinates of the position in the new + parent window. + + string + + Specifies the character string. + + num_bytes + + Specifies the number of bytes in the string argument. + + num_wchars + + Specifies the number of characters in the string argument. + + The XmbDrawString and XwcDrawString functions draw the + specified text with the foreground pixel. When the XFontSet has + missing charsets, each unavailable character is drawn with the + default string returned by XCreateFontSet. The behavior for an + invalid codepoint is undefined. + + To draw image text using a single font set in a given drawable, + use XmbDrawImageString or XwcDrawImageString. + + void XmbDrawImageString(Display *display, Drawable d, XFontSet + font_set, GC gc, int x, int y, char *string, int num_bytes); + + void XwcDrawImageString(Display *display, Drawable d, XFontSet + font_set, GC gc, int x, int y, wchar_t *string, int + num_wchars); + + display + + Specifies the connection to the X server. + + d + + Specifies the drawable. + + font_set + + Specifies the font set. + + gc + + Specifies the GC. + + x + + y + + Specify the x and y coordinates of the position in the new + parent window. + + string + + Specifies the character string. + + num_bytes + + Specifies the number of bytes in the string argument. + + num_wchars + + Specifies the number of characters in the string argument. + + The XmbDrawImageString and XwcDrawImageString functions fill a + destination rectangle with the background pixel defined in the + GC and then paint the text with the foreground pixel. The + filled rectangle is the rectangle returned to + overall_logical_return by XmbTextExtents or XwcTextExtents for + the same text and XFontSet. + + When the XFontSet has missing charsets, each unavailable + character is drawn with the default string returned by + XCreateFontSet. The behavior for an invalid codepoint is + undefined. + +Input Methods + + This section provides discussions of the following X Input + Method (XIM) topics: + * Input method overview + * Input method management + * Input method functions + * Input method values + * Input context functions + * Input context values + * Input method callback semantics + * Event filtering + * Getting keyboard input + * Input method conventions + +Input Method Overview + + This section provides definitions for terms and concepts used + for internationalized text input and a brief overview of the + intended use of the mechanisms provided by Xlib. + + A large number of languages in the world use alphabets + consisting of a small set of symbols (letters) to form words. + To enter text into a computer in an alphabetic language, a user + usually has a keyboard on which there exist key symbols + corresponding to the alphabet. Sometimes, a few characters of + an alphabetic language are missing on the keyboard. Many + computer users who speak a Latin-alphabet-based language only + have an English-based keyboard. They need to hit a combination + of keystrokes to enter a character that does not exist directly + on the keyboard. A number of algorithms have been developed for + entering such characters. These are known as European input + methods, compose input methods, or dead-key input methods. + + Japanese is an example of a language with a phonetic symbol + set, where each symbol represents a specific sound. There are + two phonetic symbol sets in Japanese: Katakana and Hiragana. In + general, Katakana is used for words that are of foreign origin, + and Hiragana is used for writing native Japanese words. + Collectively, the two systems are called Kana. Each set + consists of 48 characters. + + Korean also has a phonetic symbol set, called Hangul. Each of + the 24 basic phonetic symbols (14 consonants and 10 vowels) + represents a specific sound. A syllable is composed of two or + three parts: the initial consonants, the vowels, and the + optional last consonants. With Hangul, syllables can be treated + as the basic units on which text processing is done. For + example, a delete operation may work on a phonetic symbol or a + syllable. Korean code sets include several thousands of these + syllables. A user types the phonetic symbols that make up the + syllables of the words to be entered. The display may change as + each phonetic symbol is entered. For example, when the second + phonetic symbol of a syllable is entered, the first phonetic + symbol may change its shape and size. Likewise, when the third + phonetic symbol is entered, the first two phonetic symbols may + change their shape and size. + + Not all languages rely solely on alphabetic or phonetic + systems. Some languages, including Japanese and Korean, employ + an ideographic writing system. In an ideographic system, rather + than taking a small set of symbols and combining them in + different ways to create words, each word consists of one + unique symbol (or, occasionally, several symbols). The number + of symbols can be very large: approximately 50,000 have been + identified in Hanzi, the Chinese ideographic system. + + Two major aspects of ideographic systems impact their use with + computers. First, the standard computer character sets in + Japan, China, and Korea include roughly 8,000 characters, while + sets in Taiwan have between 15,000 and 30,000 characters. This + makes it necessary to use more than one byte to represent a + character. Second, it obviously is impractical to have a + keyboard that includes all of a given language's ideographic + symbols. Therefore, a mechanism is required for entering + characters so that a keyboard with a reasonable number of keys + can be used. Those input methods are usually based on + phonetics, but there also exist methods based on the graphical + properties of characters. + + In Japan, both Kana and the ideographic system Kanji are used. + In Korea, Hangul and sometimes the ideographic system Hanja are + used. Now consider entering ideographs in Japan, Korea, China, + and Taiwan. + + In Japan, either Kana or English characters are typed and then + a region is selected (sometimes automatically) for conversion + to Kanji. Several Kanji characters may have the same phonetic + representation. If that is the case with the string entered, a + menu of characters is presented and the user must choose the + appropriate one. If no choice is necessary or a preference has + been established, the input method does the substitution + directly. When Latin characters are converted to Kana or Kanji, + it is called a romaji conversion. + + In Korea, it is usually acceptable to keep Korean text in + Hangul form, but some people may choose to write + Hanja-originated words in Hanja rather than in Hangul. To + change Hangul to Hanja, the user selects a region for + conversion and then follows the same basic method as that + described for Japanese. + + Probably because there are well-accepted phonetic writing + systems for Japanese and Korean, computer input methods in + these countries for entering ideographs are fairly standard. + Keyboard keys have both English characters and phonetic symbols + engraved on them, and the user can switch between the two sets. + + The situation is different for Chinese. While there is a + phonetic system called Pinyin promoted by authorities, there is + no consensus for entering Chinese text. Some vendors use a + phonetic decomposition (Pinyin or another), others use + ideographic decomposition of Chinese words, with various + implementations and keyboard layouts. There are about 16 known + methods, none of which is a clear standard. + + Also, there are actually two ideographic sets used: Traditional + Chinese (the original written Chinese) and Simplified Chinese. + Several years ago, the People's Republic of China launched a + campaign to simplify some ideographic characters and eliminate + redundancies altogether. Under the plan, characters would be + streamlined every five years. Characters have been revised + several times now, resulting in the smaller, simpler set that + makes up Simplified Chinese. + +Input Method Architecture + + As shown in the previous section, there are many different + input methods in use today, each varying with language, + culture, and history. A common feature of many input methods is + that the user may type multiple keystrokes to compose a single + character (or set of characters). The process of composing + characters from keystrokes is called preediting. It may require + complex algorithms and large dictionaries involving substantial + computer resources. + + Input methods may require one or more areas in which to show + the feedback of the actual keystrokes, to propose + disambiguation to the user, to list dictionaries, and so on. + The input method areas of concern are as follows: + * The status area is a logical extension of the LEDs that + exist on the physical keyboard. It is a window that is + intended to present the internal state of the input method + that is critical to the user. The status area may consist + of text data and bitmaps or some combination. + * The preedit area displays the intermediate text for those + languages that are composing prior to the client handling + the data. + * The auxiliary area is used for pop-up menus and customizing + dialogs that may be required for an input method. There may + be multiple auxiliary areas for an input method. Auxiliary + areas are managed by the input method independent of the + client. Auxiliary areas are assumed to be separate dialogs, + which are maintained by the input method. + + There are various user interaction styles used for preediting. + The ones supported by Xlib are as follows: + * For on-the-spot input methods, preediting data will be + displayed directly in the application window. Application + data is moved to allow preedit data to appear at the point + of insertion. + * Over-the-spot preediting means that the data is displayed + in a preedit window that is placed over the point of + insertion. + * Off-the-spot preediting means that the preedit window is + inside the application window but not at the point of + insertion. Often, this type of window is placed at the + bottom of the application window. + * Root-window preediting refers to input methods that use a + preedit window that is the child of RootWindow. + + It would require a lot of computing resources if portable + applications had to include input methods for all the languages + in the world. To avoid this, a goal of the Xlib design is to + allow an application to communicate with an input method placed + in a separate process. Such a process is called an input + server. The server to which the application should connect is + dependent on the environment when the application is started + up, that is, the user language and the actual encoding to be + used for it. The input method connection is said to be + locale-dependent. It is also user-dependent. For a given + language, the user can choose, to some extent, the user + interface style of input method (if choice is possible among + several). + + Using an input server implies communication overhead, but + applications can be migrated without relinking. Input methods + can be implemented either as a stub communicating to an input + server or as a local library. + + An input method may be based on a front-end or a back-end + architecture. In a front-end architecture, there are two + separate connections to the X server: keystrokes go directly + from the X server to the input method on one connection and + other events to the regular client connection. The input method + is then acting as a filter and sends composed strings to the + client. A front-end architecture requires synchronization + between the two connections to avoid lost key events or locking + issues. + + In a back-end architecture, a single X server connection is + used. A dispatching mechanism must decide on this channel to + delegate appropriate keystrokes to the input method. For + instance, it may retain a Help keystroke for its own purpose. + In the case where the input method is a separate process (that + is, a server), there must be a special communication protocol + between the back-end client and the input server. + + A front-end architecture introduces synchronization issues and + a filtering mechanism for noncharacter keystrokes (Function + keys, Help, and so on). A back-end architecture sometimes + implies more communication overhead and more process switching. + If all three processes (X server, input server, client) are + running on a single workstation, there are two process switches + for each keystroke in a back-end architecture, but there is + only one in a front-end architecture. + + The abstraction used by a client to communicate with an input + method is an opaque data structure represented by the XIM data + type. This data structure is returned by the XOpenIM function, + which opens an input method on a given display. Subsequent + operations on this data structure encapsulate all communication + between client and input method. There is no need for an X + client to use any networking library or natural language + package to use an input method. + + A single input server may be used for one or more languages, + supporting one or more encoding schemes. But the strings + returned from an input method will always be encoded in the + (single) locale associated with the XIM object. + +Input Contexts + + Xlib provides the ability to manage a multi-threaded state for + text input. A client may be using multiple windows, each window + with multiple text entry areas, and the user possibly switching + among them at any time. The abstraction for representing the + state of a particular input thread is called an input context. + The Xlib representation of an input context is an XIC. + + An input context is the abstraction retaining the state, + properties, and semantics of communication between a client and + an input method. An input context is a combination of an input + method, a locale specifying the encoding of the character + strings to be returned, a client window, internal state + information, and various layout or appearance characteristics. + The input context concept somewhat matches for input the + graphics context abstraction defined for graphics output. + + One input context belongs to exactly one input method. + Different input contexts may be associated with the same input + method, possibly with the same client window. An XIC is created + with the XCreateIC function, providing an XIM argument and + affiliating the input context to the input method for its + lifetime. When an input method is closed with XCloseIM, all of + its affiliated input contexts should not be used any more (and + should preferably be destroyed before closing the input + method). + + Considering the example of a client window with multiple text + entry areas, the application programmer could, for example, + choose to implement as follows: + * As many input contexts are created as text entry areas, and + the client will get the input accumulated on each context + each time it looks up in that context. + * A single context is created for a top-level window in the + application. If such a window contains several text entry + areas, each time the user moves to another text entry area, + the client has to indicate changes in the context. + + A range of choices can be made by application designers to use + either a single or multiple input contexts, according to the + needs of their application. + +Getting Keyboard Input + + To obtain characters from an input method, a client must call + the function XmbLookupString or XwcLookupString with an input + context created from that input method. Both a locale and + display are bound to an input method when it is opened, and an + input context inherits this locale and display. Any strings + returned by XmbLookupString or XwcLookupString will be encoded + in that locale. + +Focus Management + + For each text entry area in which the XmbLookupString or + XwcLookupString functions are used, there will be an associated + input context. + + When the application focus moves to a text entry area, the + application must set the input context focus to the input + context associated with that area. The input context focus is + set by calling XSetICFocus with the appropriate input context. + + Also, when the application focus moves out of a text entry + area, the application should unset the focus for the associated + input context by calling XUnsetICFocus. As an optimization, if + XSetICFocus is called successively on two different input + contexts, setting the focus on the second will automatically + unset the focus on the first. + + To set and unset the input context focus correctly, it is + necessary to track application-level focus changes. Such focus + changes do not necessarily correspond to X server focus + changes. + + If a single input context is being used to do input for + multiple text entry areas, it will also be necessary to set the + focus window of the input context whenever the focus window + changes (see section 13.5.6.3). + +Geometry Management + + In most input method architectures (on-the-spot being the + notable exception), the input method will perform the display + of its own data. To provide better visual locality, it is often + desirable to have the input method areas embedded within a + client. To do this, the client may need to allocate space for + an input method. Xlib provides support that allows the size and + position of input method areas to be provided by a client. The + input method areas that are supported for geometry management + are the status area and the preedit area. + + The fundamental concept on which geometry management for input + method windows is based is the proper division of + responsibilities between the client (or toolkit) and the input + method. The division of responsibilities is as follows: + * The client is responsible for the geometry of the input + method window. + * The input method is responsible for the contents of the + input method window. + + An input method is able to suggest a size to the client, but it + cannot suggest a placement. Also the input method can only + suggest a size. It does not determine the size, and it must + accept the size it is given. + + Before a client provides geometry management for an input + method, it must determine if geometry management is needed. The + input method indicates the need for geometry management by + setting XIMPreeditArea or XIMStatusArea in its XIMStyles value + returned by XGetIMValues. When a client has decided that it + will provide geometry management for an input method, it + indicates that decision by setting the XNInputStyle value in + the XIC. + + After a client has established with the input method that it + will do geometry management, the client must negotiate the + geometry with the input method. The geometry is negotiated by + the following steps: + * The client suggests an area to the input method by setting + the XNAreaNeeded value for that area. If the client has no + constraints for the input method, it either will not + suggest an area or will set the width and height to zero. + Otherwise, it will set one of the values. + * The client will get the XIC value XNAreaNeeded. The input + method will return its suggested size in this value. The + input method should pay attention to any constraints + suggested by the client. + * The client sets the XIC value XNArea to inform the input + method of the geometry of its window. The client should try + to honor the geometry requested by the input method. The + input method must accept this geometry. + + Clients doing geometry management must be aware that setting + other XIC values may affect the geometry desired by an input + method. For example, XNFontSet and XNLineSpace may change the + geometry desired by the input method. + + The table of XIC values (see section 13.5.6) indicates the + values that can cause the desired geometry to change when they + are set. It is the responsibility of the client to renegotiate + the geometry of the input method window when it is needed. + + In addition, a geometry management callback is provided by + which an input method can initiate a geometry change. + +Event Filtering + + A filtering mechanism is provided to allow input methods to + capture X events transparently to clients. It is expected that + toolkits (or clients) using XmbLookupString or XwcLookupString + will call this filter at some point in the event processing + mechanism to make sure that events needed by an input method + can be filtered by that input method. + + If there were no filter, a client could receive and discard + events that are necessary for the proper functioning of an + input method. The following provides a few examples of such + events: + * Expose events on preedit window in local mode. + * Events may be used by an input method to communicate with + an input server. Such input server protocol-related events + have to be intercepted if one does not want to disturb + client code. + * Key events can be sent to a filter before they are bound to + translations such as those the X Toolkit Intrinsics library + provides. + + Clients are expected to get the XIC value XNFilterEvents and + augment the event mask for the client window with that event + mask. This mask may be zero. + +Callbacks + + When an on-the-spot input method is implemented, only the + client can insert or delete preedit data in place and possibly + scroll existing text. This means that the echo of the + keystrokes has to be achieved by the client itself, tightly + coupled with the input method logic. + + When the user enters a keystroke, the client calls + XmbLookupString or XwcLookupString. At this point, in the + on-the-spot case, the echo of the keystroke in the preedit has + not yet been done. Before returning to the client logic that + handles the input characters, the look-up function must call + the echoing logic to insert the new keystroke. If the + keystrokes entered so far make up a character, the keystrokes + entered need to be deleted, and the composed character will be + returned. Hence, what happens is that, while being called by + client code, the input method logic has to call back to the + client before it returns. The client code, that is, a callback + procedure, is called from the input method logic. + + There are a number of cases where the input method logic has to + call back the client. Each of those cases is associated with a + well-defined callback action. It is possible for the client to + specify, for each input context, what callback is to be called + for each action. + + There are also callbacks provided for feedback of status + information and a callback to initiate a geometry request for + an input method. + +Visible Position Feedback Masks + + In the on-the-spot input style, there is a problem when + attempting to draw preedit strings that are longer than the + available space. Once the display area is exceeded, it is not + clear how best to display the preedit string. The visible + position feedback masks of XIMText help resolve this problem by + allowing the input method to specify hints that indicate the + essential portions of the preedit string. For example, such + hints can help developers implement scrolling of a long preedit + string within a short preedit display area. + +Preedit String Management + + As highlighted before, the input method architecture provides + preediting, which supports a type of preprocessor input + composition. In this case, composition consists of interpreting + a sequence of key events and returning a committed string via + XmbLookupString or XwcLookupString. This provides the basics + for input methods. + + In addition to preediting based on key events, a general + framework is provided to give a client that desires it more + advanced preediting based on the text within the client. This + framework is called string conversion and is provided using XIC + values. The fundamental concept of string conversion is to + allow the input method to manipulate the client's text + independent of any user preediting operation. + + The need for string conversion is based on language needs and + input method capabilities. The following are some examples of + string conversion: + * Transliteration conversion provides language-specific + conversions within the input method. In the case of Korean + input, users wish to convert a Hangul string into a Hanja + string while in preediting, after preediting, or in other + situations (for example, on a selected string). The + conversion is triggered when the user presses a + Hangul-to-Hanja key sequence (which may be input method + specific). Sometimes the user may want to invoke the + conversion after finishing preediting or on a user-selected + string. Thus, the string to be converted is in an + application buffer, not in the preedit area of the input + method. The string conversion services allow the client to + request this transliteration conversion from the input + method. There are many other transliteration conversions + defined for various languages, for example, Kana-to-Kanji + conversion in Japanese. The key to remember is that + transliteration conversions are triggered at the request of + the user and returned to the client immediately without + affecting the preedit area of the input method. + * Reconversion of a previously committed string or a selected + string is supported by many input methods as a convenience + to the user. For example, a user tends to mistype the + commit key while preediting. In that case, some input + methods provide a special key sequence to request a + ``reconvert'' operation on the committed string, similiar + to the undo facility provided by most text editors. Another + example is where the user is proofreading a document that + has some misconversions from preediting and wants to + correct the misconverted text. Such reconversion is again + triggered by the user invoking some special action, but + reconversions should not affect the state of the preedit + area. + * Context-sensitive conversion is required for some languages + and input methods that need to retrieve text that surrounds + the current spot location (cursor position) of the client's + buffer. Such text is needed when the preediting operation + depends on some surrounding characters (usually preceding + the spot location). For example, in Thai language input, + certain character sequences may be invalid and the input + method may want to check whether characters constitute a + valid word. Input methods that do such context-dependent + checking need to retrieve the characters surrounding the + current cursor position to obtain complete words. Unlike + other conversions, this conversion is not explicitly + requested by the user. Input methods that provide such + context-sensitive conversion continuously need to request + context from the client, and any change in the context of + the spot location may affect such conversions. The client's + context would be needed if the user moves the cursor and + starts editing again. For this reason, an input method + supporting this type of conversion should take notice of + when the client calls XmbResetIC or XwcResetIC, which is + usually an indication of a context change. + + Context-sensitive conversions just need a copy of the client's + text, while other conversions replace the client's text with + new text to achieve the reconversion or transliteration. Yet in + all cases the result of a conversion, either immediately or via + preediting, is returned by the XmbLookupString and + XwcLookupString functions. + + String conversion support is dependent on the availability of + the XNStringConversion or XNStringConversionCallback XIC + values. Because the input method may not support string + conversions, clients have to query the availability of string + conversion operations by checking the supported XIC values list + by calling XGetIMValues with the XNQueryICValuesList IM value. + + The difference between these two values is whether the + conversion is invoked by the client or the input method. The + XNStringConversion XIC value is used by clients to request a + string conversion from the input method. The client is + responsible for determining which events are used to trigger + the string conversion and whether the string to be converted + should be copied or deleted. The type of conversion is + determined by the input method; the client can only pass the + string to be converted. The client is guaranteed that no + XNStringConversionCallback will be issued when this value is + set; thus, the client need only set one of these values. + + The XNStringConversionCallback XIC value is used by the client + to notify the input method that it will accept requests from + the input method for string conversion. If this value is set, + it is the input method's responsibility to determine which + events are used to trigger the string conversion. When such + events occur, the input method issues a call to the + client-supplied procedure to retrieve the string to be + converted. The client's callback procedure is notified whether + to copy or delete the string and is provided with hints as to + the amount of text needed. The + XIMStringConversionCallbackStruct specifies which text should + be passed back to the input method. + + Finally, the input method may call the client's + XNStringConversionCallback procedure multiple times if the + string returned from the callback is not sufficient to perform + a successful conversion. The arguments to the client's + procedure allow the input method to define a position (in + character units) relative to the client's cursor position and + the size of the text needed. By varying the position and size + of the desired text in subsequent callbacks, the input method + can retrieve additional text. + +Input Method Management + + The interface to input methods might appear to be simply + creating an input method (XOpenIM) and freeing an input method + (XCloseIM). However, input methods may require complex + communication with input method servers (IM servers), for + example: + * If the X server, IM server, and X clients are started + asynchronously, some clients may attempt to connect to the + IM server before it is fully operational, and fail. + Therefore, some mechanism is needed to allow clients to + detect when an IM server has started. + + It is up to clients to decide what should be done when an IM + server is not available (for example, wait, or use some other + IM server). + + * Some input methods may allow the underlying IM server to be + switched. Such customization may be desired without + restarting the entire client. + + To support management of input methods in these cases, the + following functions are provided: + XRegisterIMInstantiateCallback This function allows clients to + register a callback procedure to be called when Xlib detects + that an IM server is up and available. + XOpenIM A client calls this function as a result of the + callback procedure being called. + XSetIMValues, XSetICValues These functions use the XIM and XIC + values, XNDestroyCallback, to allow a client to register a + callback procedure to be called when Xlib detects that an IM + server that was associated with an opened input method is no + longer available. In addition, this function can be used to + switch IM servers for those input methods that support such + functionality. The IM value for switching IM servers is + implementation-dependent; see the description below about + switching IM servers. + XUnregisterIMInstantiateCallback This function removes a + callback procedure registered by the client. + + Input methods that support switching of IM servers may exhibit + some side-effects: + * The input method will ensure that any new IM server + supports any of the input styles being used by input + contexts already associated with the input method. However, + the list of supported input styles may be different. + + * Geometry management requests on previously created input + contexts may be initiated by the new IM server. + +Hot Keys + + Some clients need to guarantee which keys can be used to escape + from the input method, regardless of the input method state; + for example, the client-specific Help key or the keys to move + the input focus. The HotKey mechanism allows clients to specify + a set of keys for this purpose. However, the input method might + not allow clients to specify hot keys. Therefore, clients have + to query support of hot keys by checking the supported XIC + values list by calling XGetIMValues with the + XNQueryICValuesList IM value. When the hot keys specified + conflict with the key bindings of the input method, hot keys + take precedence over the key bindings of the input method. + +Preedit State Operation + + An input method may have several internal states, depending on + its implementation and the locale. However, one state that is + independent of locale and implementation is whether the input + method is currently performing a preediting operation. Xlib + provides the ability for an application to manage the preedit + state programmatically. Two methods are provided for retrieving + the preedit state of an input context. One method is to query + the state by calling XGetICValues with the XNPreeditState XIC + value. Another method is to receive notification whenever the + preedit state is changed. To receive such notification, an + application needs to register a callback by calling + XSetICValues with the XNPreeditStateNotifyCallback XIC value. + In order to change the preedit state programmatically, an + application needs to call XSetICValues with XNPreeditState. + + Availability of the preedit state is input method dependent. + The input method may not provide the ability to set the state + or to retrieve the state programmatically. Therefore, clients + have to query availability of preedit state operations by + checking the supported XIC values list by calling XGetIMValues + with the XNQueryICValuesList IM value. + +Input Method Functions + + To open a connection, use XOpenIM. + + XIM XOpenIM(Display *display, XrmDatabase db, char *res_name, + char *res_class); + + display + + Specifies the connection to the X server. + + db + + Specifies a pointer to the resource database. + + res_name + + Specifies the full resource name of the application. + + res_class + + Specifies the full class name of the application. + + The XOpenIM function opens an input method, matching the + current locale and modifiers specification. Current locale and + modifiers are bound to the input method at opening time. The + locale associated with an input method cannot be changed + dynamically. This implies that the strings returned by + XmbLookupString or XwcLookupString, for any input context + affiliated with a given input method, will be encoded in the + locale current at the time the input method is opened. + + The specific input method to which this call will be routed is + identified on the basis of the current locale. XOpenIM will + identify a default input method corresponding to the current + locale. That default can be modified using XSetLocaleModifiers + for the input method modifier. + + The db argument is the resource database to be used by the + input method for looking up resources that are private to the + input method. It is not intended that this database be used to + look up values that can be set as IC values in an input + context. If db is NULL, no database is passed to the input + method. + + The res_name and res_class arguments specify the resource name + and class of the application. They are intended to be used as + prefixes by the input method when looking up resources that are + common to all input contexts that may be created for this input + method. The characters used for resource names and classes must + be in the X Portable Character Set. The resources looked up are + not fully specified if res_name or res_class is NULL. + + The res_name and res_class arguments are not assumed to exist + beyond the call to XOpenIM. The specified resource database is + assumed to exist for the lifetime of the input method. + + XOpenIM returns NULL if no input method could be opened. + + To close a connection, use XCloseIM. + + Status XCloseIM(XIM im); + + im + + Specifies the input method. + + The XCloseIM function closes the specified input method. + + To set input method attributes, use XSetIMValues. + + char *XSetIMValues(XIM im); + + im + + Specifies the input method. + + ... + + Specifies the variable-length argument list to set XIM values. + + The XSetIMValues function presents a variable argument list + programming interface for setting attributes of the specified + input method. It returns NULL if it succeeds; otherwise, it + returns the name of the first argument that could not be set. + Xlib does not attempt to set arguments from the supplied list + that follow the failed argument; all arguments in the list + preceding the failed argument have been set correctly. + + To query an input method, use XGetIMValues. + + char *XGetIMValues(XIM im); + + im + + Specifies the input method. + + ... + + Specifies the variable length argument list to get XIM values. + + The XGetIMValues function presents a variable argument list + programming interface for querying properties or features of + the specified input method. This function returns NULL if it + succeeds; otherwise, it returns the name of the first argument + that could not be obtained. + + Each XIM value argument (following a name) must point to a + location where the XIM value is to be stored. That is, if the + XIM value is of type T, the argument must be of type T*. If T + itself is a pointer type, then XGetIMValues allocates memory to + store the actual data, and the client is responsible for + freeing this data by calling XFree with the returned pointer. + + To obtain the display associated with an input method, use + XDisplayOfIM. + + Display *XDisplayOfIM(XIM im); + + im + + Specifies the input method. + + The XDisplayOfIM function returns the display associated with + the specified input method. + + To get the locale associated with an input method, use + XLocaleOfIM. + + char *XLocaleOfIM(XIM im); + + im + + Specifies the input method. + + The XLocaleOfIM function returns the locale associated with the + specified input method. + + To register an input method instantiate callback, use + XRegisterIMInstantiateCallback. + + Bool XRegisterIMInstantiateCallback(Display *display, + XrmDatabase db, char *res_name, char *res_class, XIMProc + callback, XPointer *client_data); + + display + + Specifies the connection to the X server. + + db + + Specifies a pointer to the resource database. + + res_name + + Specifies the full resource name of the application. + + res_class + + Specifies the full class name of the application. + + callback + + Specifies a pointer to the input method instantiate callback. + + client_data + + Specifies the additional client data. + + The XRegisterIMInstantiateCallback function registers a + callback to be invoked whenever a new input method becomes + available for the specified display that matches the current + locale and modifiers. + + The function returns True if it succeeds; otherwise, it returns + False. + + The generic prototype is as follows: + + void IMInstantiateCallback(Display *display, XPointer + client_data, XPointer call_data); + + display + + Specifies the connection to the X server. + + client_data + + Specifies the additional client data. + + call_data + + Not used for this callback and always passed as NULL. + + To unregister an input method instantiation callback, use + XUnregisterIMInstantiateCallback. + + Bool XUnregisterIMInstantiateCallback(Display *display, + XrmDatabase db, char *res_name, char *res_class, XIMProc + callback, XPointer *client_data); + + display + + Specifies the connection to the X server. + + db + + Specifies a pointer to the resource database. + + res_name + + Specifies the full resource name of the application. + + res_class + + Specifies the full class name of the application. + + callback + + Specifies a pointer to the input method instantiate callback. + + client_data + + Specifies the additional client data. + + The XUnregisterIMInstantiateCallback function removes an input + method instantiation callback previously registered. The + function returns True if it succeeds; otherwise, it returns + False. + +Input Method Values + + The following table describes how XIM values are interpreted by + an input method. The first column lists the XIM values. The + second column indicates how each of the XIM values are treated + by that input style. + + The following keys apply to this table. + Key Explanation + D This value may be set using XSetIMValues. If it is not set, a + default is provided. + S This value may be set using XSetIMValues. + G This value may be read using XGetIMValues. + + XIM Value Key + XNQueryInputStyle G + XNResourceName D-S-G + XNResourceClass D-S-G + XNDestroyCallback D-S-G + XNQueryIMValuesList G + XNQueryICValuesList G + XNVisiblePosition G + XNR6PreeditCallback D-S-G + + XNR6PreeditCallback is obsolete and its use is not recommended + (see section 13.5.4.6). + +Query Input Style + + A client should always query the input method to determine + which input styles are supported. The client should then find + an input style it is capable of supporting. + + If the client cannot find an input style that it can support, + it should negotiate with the user the continuation of the + program (exit, choose another input method, and so on). + + The argument value must be a pointer to a location where the + returned value will be stored. The returned value is a pointer + to a structure of type XIMStyles. Clients are responsible for + freeing the XIMStyles structure. To do so, use XFree. + + The XIMStyles structure is defined as follows: +typedef unsigned long XIMStyle; + + +#define XIMPreeditArea 0x0001L +#define XIMPreeditCallbacks 0x0002L +#define XIMPreeditPosition 0x0004L +#define XIMPreeditNothing 0x0008L +#define XIMPreeditNone 0x0010L + +#define XIMStatusArea 0x0100L +#define XIMStatusCallbacks 0x0200L +#define XIMStatusNothing 0x0400L +#define XIMStatusNone 0x0800L + +typedef struct { + unsigned short count_styles; + XIMStyle * supported_styles; +} XIMStyles; + + + An XIMStyles structure contains the number of input styles + supported in its count_styles field. This is also the size of + the supported_styles array. + + The supported styles is a list of bitmask combinations, which + indicate the combination of styles for each of the areas + supported. These areas are described later. Each element in the + list should select one of the bitmask values for each area. The + list describes the complete set of combinations supported. Only + these combinations are supported by the input method. + + The preedit category defines what type of support is provided + by the input method for preedit information. + XIMPreeditArea If chosen, the input method would require the + client to provide some area values for it to do its preediting. + Refer to XIC values XNArea and XNAreaNeeded. + XIMPreeditPosition If chosen, the input method would require + the client to provide positional values. Refer to XIC values + XNSpotLocation and XNFocusWindow. + XIMPreeditCallbacks If chosen, the input method would require + the client to define the set of preedit callbacks. Refer to XIC + values XNPreeditStartCallback, XNPreeditDoneCallback, + XNPreeditDrawCallback, and XNPreeditCaretCallback. + XIMPreeditNothing If chosen, the input method can function + without any preedit values. + XIMPreeditNone The input method does not provide any preedit + feedback. Any preedit value is ignored. This style is mutually + exclusive with the other preedit styles. + + The status category defines what type of support is provided by + the input method for status information. + XIMStatusArea The input method requires the client to provide + some area values for it to do its status feedback. See XNArea + and XNAreaNeeded. + XIMStatusCallbacks The input method requires the client to + define the set of status callbacks, XNStatusStartCallback, + XNStatusDoneCallback, and XNStatusDrawCallback. + XIMStatusNothing The input method can function without any + status values. + XIMStatusNone The input method does not provide any status + feedback. If chosen, any status value is ignored. This style is + mutually exclusive with the other status styles. + +Resource Name and Class + + The XNResourceName and XNResourceClass arguments are strings + that specify the full name and class used by the input method. + These values should be used as prefixes for the name and class + when looking up resources that may vary according to the input + method. If these values are not set, the resources will not be + fully specified. + + It is not intended that values that can be set as XIM values be + set as resources. + +Destroy Callback + + The XNDestroyCallback argument is a pointer to a structure of + type XIMCallback. XNDestroyCallback is triggered when an input + method stops its service for any reason. After the callback is + invoked, the input method is closed and the associated input + context(s) are destroyed by Xlib. Therefore, the client should + not call XCloseIM or XDestroyIC. + + The generic prototype of this callback function is as follows: + + void DestroyCallback(XIM im, XPointer client_data, XPointer + call_data); + + im + + Specifies the input method. + + client_data + + Specifies the additional client data. + + call_data + + Not used for this callback and always passed as NULL. + + A DestroyCallback is always called with a NULL call_data + argument. + +Query IM/IC Values List + + XNQueryIMValuesList and XNQueryICValuesList are used to query + about XIM and XIC values supported by the input method. + + The argument value must be a pointer to a location where the + returned value will be stored. The returned value is a pointer + to a structure of type XIMValuesList. Clients are responsible + for freeing the XIMValuesList structure. To do so, use XFree. + + The XIMValuesList structure is defined as follows: + + +typedef struct { + unsigned short count_values; + char **supported_values; +} XIMValuesList; + +Visible Position + + The XNVisiblePosition argument indicates whether the visible + position masks of XIMFeedback in XIMText are available. + + The argument value must be a pointer to a location where the + returned value will be stored. The returned value is of type + Bool. If the returned value is True, the input method uses the + visible position masks of XIMFeedback in XIMText; otherwise, + the input method does not use the masks. + + Because this XIM value is optional, a client should call + XGetIMValues with argument XNQueryIMValuesList before using + this argument. If the XNVisiblePosition does not exist in the + IM values list returned from XNQueryIMValuesList, the visible + position masks of XIMFeedback in XIMText are not used to + indicate the visible position. + +Preedit Callback Behavior + + The XNR6PreeditCallback argument originally included in the + X11R6 specification has been deprecated.\(dg During formulation + of the X11R6 specification, the behavior of the R6 + PreeditDrawCallbacks was going to differ significantly from + that of the R5 callbacks. Late changes to the specification + converged the R5 and R6 behaviors, eliminating the need for + XNR6PreeditCallback. Unfortunately, this argument was not + removed from the R6 specification before it was published. + + The XNR6PreeditCallback argument indicates whether the behavior + of preedit callbacks regarding XIMPreeditDrawCallbackStruct + values follows Release 5 or Release 6 semantics. + + The value is of type Bool. When querying for + XNR6PreeditCallback, if the returned value is True, the input + method uses the Release 6 behavior; otherwise, it uses the + Release 5 behavior. The default value is False. In order to use + Release 6 semantics, the value of XNR6PreeditCallback must be + set to True. + + Because this XIM value is optional, a client should call + XGetIMValues with argument XNQueryIMValuesList before using + this argument. If the XNR6PreeditCallback does not exist in the + IM values list returned from XNQueryIMValuesList, the + PreeditCallback behavior is Release 5 semantics. + +Input Context Functions + + An input context is an abstraction that is used to contain both + the data required (if any) by an input method and the + information required to display that data. There may be + multiple input contexts for one input method. The programming + interfaces for creating, reading, or modifying an input context + use a variable argument list. The name elements of the argument + lists are referred to as XIC values. It is intended that input + methods be controlled by these XIC values. As new XIC values + are created, they should be registered with the X Consortium. + + To create an input context, use XCreateIC. + + XIC XCreateIC(XIM im); + + im + + Specifies the input method. + + ... + + Specifies the variable length argument list to set XIC values. + + The XCreateIC function creates a context within the specified + input method. + + Some of the arguments are mandatory at creation time, and the + input context will not be created if those arguments are not + provided. The mandatory arguments are the input style and the + set of text callbacks (if the input style selected requires + callbacks). All other input context values can be set later. + + XCreateIC returns a NULL value if no input context could be + created. A NULL value could be returned for any of the + following reasons: + * A required argument was not set. + * A read-only argument was set (for example, XNFilterEvents). + * The argument name is not recognized. + * The input method encountered an input method + implementation-dependent error. + + XCreateIC can generate BadAtom, BadColor, BadPixmap, and + BadWindow errors. + + To destroy an input context, use XDestroyIC. + + void XDestroyIC(XIC ic); + + ic + + Specifies the input context. + + XDestroyIC destroys the specified input context. + + To communicate to and synchronize with input method for any + changes in keyboard focus from the client side, use XSetICFocus + and XUnsetICFocus. + + void XSetICFocus(XIC ic); + + ic + + Specifies the input context. + + The XSetICFocus function allows a client to notify an input + method that the focus window attached to the specified input + context has received keyboard focus. The input method should + take action to provide appropriate feedback. Complete feedback + specification is a matter of user interface policy. + + Calling XSetICFocus does not affect the focus window value. + + void XUnsetICFocus(XIC ic); + + ic + + Specifies the input context. + + The XUnsetICFocus function allows a client to notify an input + method that the specified input context has lost the keyboard + focus and that no more input is expected on the focus window + attached to that input context. The input method should take + action to provide appropriate feedback. Complete feedback + specification is a matter of user interface policy. + + Calling XUnsetICFocus does not affect the focus window value; + the client may still receive events from the input method that + are directed to the focus window. + + To reset the state of an input context to its initial state, + use XmbResetIC or XwcResetIC. + + char *XmbResetIC(XIC ic); + + wchar_t *XwcResetIC(XIC ic); + + ic + + Specifies the input context. + + When XNResetState is set to XIMInitialState, XmbResetIC and + XwcResetIC reset an input context to its initial state; when + XNResetState is set to XIMPreserveState, the current input + context state is preserved. In both cases, any input pending on + that context is deleted. The input method is required to clear + the preedit area, if any, and update the status accordingly. + Calling XmbResetIC or XwcResetIC does not change the focus. + + The return value of XmbResetIC is its current preedit string as + a multibyte string. If there is any preedit text drawn or + visible to the user, then these procedures must return a + non-NULL string. If there is no visible preedit text, then it + is input method implementation-dependent whether these + procedures return a non-NULL string or NULL. + + The client should free the returned string by calling XFree. + + To get the input method associated with an input context, use + XIMOfIC. + + XIM XIMOfIC(XIC ic); + + ic + + Specifies the input context. + + The XIMOfIC function returns the input method associated with + the specified input context. + + Xlib provides two functions for setting and reading XIC values, + respectively, XSetICValues and XGetICValues. Both functions + have a variable-length argument list. In that argument list, + any XIC value's name must be denoted with a character string + using the X Portable Character Set. + + To set XIC values, use XSetICValues. + + char *XSetICValues(XIC ic); + + ic + + Specifies the input context. + + ... + + Specifies the variable length argument list to set XIC values. + + The XSetICValues function returns NULL if no error occurred; + otherwise, it returns the name of the first argument that could + not be set. An argument might not be set for any of the + following reasons: + * The argument is read-only (for example, XNFilterEvents). + * The argument name is not recognized. + * An implementation-dependent error occurs. + + Each value to be set must be an appropriate datum, matching the + data type imposed by the semantics of the argument. + + XSetICValues can generate BadAtom, BadColor, BadCursor, + BadPixmap, and BadWindow errors. + + To obtain XIC values, use XGetICValues. + + char *XGetICValues(XIC ic); + + ic + + Specifies the input context. + + ... + + Specifies the variable length argument list to get XIC values. + + The XGetICValues function returns NULL if no error occurred; + otherwise, it returns the name of the first argument that could + not be obtained. An argument could not be obtained for any of + the following reasons: + * The argument name is not recognized. + * The input method encountered an implementation-dependent + error. + + Each IC attribute value argument (following a name) must point + to a location where the IC value is to be stored. That is, if + the IC value is of type T, the argument must be of type T*. If + T itself is a pointer type, then XGetICValues allocates memory + to store the actual data, and the client is responsible for + freeing this data by calling XFree with the returned pointer. + The exception to this rule is for an IC value of type + XVaNestedList (for preedit and status attributes). In this + case, the argument must also be of type XVaNestedList. Then, + the rule of changing type T to T* and freeing the allocated + data applies to each element of the nested list. + +Input Context Values + + The following tables describe how XIC values are interpreted by + an input method depending on the input style chosen by the + user. + + The first column lists the XIC values. The second column + indicates which values are involved in affecting, negotiating, + and setting the geometry of the input method windows. The + subentries under the third column indicate the different input + styles that are supported. Each of these columns indicates how + each of the XIC values are treated by that input style. + + The following keys apply to these tables. + Key Explanation + C This value must be set with XCreateIC. + D This value may be set using XCreateIC.> If it is not set,> a + default is provided. + G This value may be read using XGetICValues. + GN This value may cause geometry negotiation when its value is + set by means of XCreateIC or XSetICValues. + GR This value will be the response of the input method when any + GN value is changed. + GS This value will cause the geometry of the input method + window to be set. + O This value must be set once and only once. It need not be set + at create time. + S This value may be set with XSetICValues. + Ignored This value is ignored by the input method for the given + input style. + + XIC Value Geometry Mangement Preedit Callback Preedit Position + Input Style Preedit Area Preedit Nothing Preedit None + Input Style C-G C-G C-G C-G C-G + Client Window O-G O-G O-G O-G Ignored + Focus Window GN D-S-G D-S-G D-S-G D-S-G Ignored + Resource Name Ignored D-S-G D-S-G D-S-G Ignored + Resource Class Ignored D-S-G D-S-G D-S-G Ignored + Geometry Callback Ignored Ignored D-S-G Ignored Ignored + Filter Events G G G G Ignored + Destroy Callback D-S-G D-S-G D-S-G D-S-G D-S-G + String Conversion Callback S-G S-G S-G S-G S-G + String Conversion D-S-G D-S-G D-S-G D-S-G D-S-G + Reset State D-S-G D-S-G D-S-G D-S-G Ignored + HotKey S-G S-G S-G S-G Ignored + HotKeyState D-S-G D-S-G D-S-G D-S-G Ignored + Preedit + Area GS Ignored D-S-G D-S-G Ignored Ignored + Area Needed GN-GR Ignored Ignored S-G Ignored Ignored + Spot Location Ignored D-S-G Ignored Ignored Ignored + Colormap Ignored D-S-G D-S-G D-S-G Ignored + Foreground Ignored D-S-G D-S-G D-S-G Ignored + Background Ignored D-S-G D-S-G D-S-G Ignored + Background Pixmap Ignored D-S-G D-S-G D-S-G Ignored + Font Set GN Ignored D-S-G D-S-G D-S-G Ignored + Line Spacing GN Ignored D-S-G D-S-G D-S-G Ignored + Cursor Ignored D-S-G D-S-G D-S-G Ignored + Preedit State D-S-G D-S-G D-S-G D-S-G Ignored + Preedit State Notify Callback S-G S-G S-G S-G Ignored + Preedit Callbacks C-S-G Ignored Ignored Ignored Ignored + + XIC Value Geomentry Management Status Callback Status Area + Status Nothing Status None + Input Style C-G C-G C-G C-G + Client Window O-G O-G O-G Ignored + Focus Window GN D-S-G D-S-G D-S-G Ignored + Resource Name Ignored D-S-G D-S-G Ignored + Resource Class Ignored D-S-G D-S-G Ignored + Geometry Callback Ignored D-S-G Ignored Ignored + Filter Events G G G G + Status + Area GS Ignored D-S-G Ignored Ignored + Area Needed GN-GR Ignored S-G Ignored Ignored + Colormap Ignored D-S-G D-S-G Ignored + Foreground Ignored D-S-G D-S-G Ignored + Background Ignored D-S-G D-S-G Ignored + Background Pixmap Ignored D-S-G D-S-G Ignored + Font Set GN Ignored D-S-G D-S-G Ignored + Line Spacing GN Ignored D-S-G D-S-G Ignored + Cursor Ignored D-S-G D-S-G Ignored + Status Callbacks C-S-G Ignored Ignored Ignored + +Input Style + + The XNInputStyle argument specifies the input style to be used. + The value of this argument must be one of the values returned + by the XGetIMValues function with the XNQueryInputStyle + argument specified in the supported_styles list. + + Note that this argument must be set at creation time and cannot + be changed. + +Client Window + + The XNClientWindow argument specifies to the input method the + client window in which the input method can display data or + create subwindows. Geometry values for input method areas are + given with respect to the client window. Dynamic change of + client window is not supported. This argument may be set only + once and should be set before any input is done using this + input context. If it is not set, the input method may not + operate correctly. + + If an attempt is made to set this value a second time with + XSetICValues, the string XNClientWindow will be returned by + XSetICValues, and the client window will not be changed. + + If the client window is not a valid window ID on the display + attached to the input method, a BadWindow error can be + generated when this value is used by the input method. + +Focus Window + + The XNFocusWindow argument specifies the focus window. The + primary purpose of the XNFocusWindow is to identify the window + that will receive the key event when input is composed. In + addition, the input method may possibly affect the focus window + as follows: + * Select events on it + * Send events to it + * Modify its properties + * Grab the keyboard within that window + + The associated value must be of type Window. If the focus + window is not a valid window ID on the display attached to the + input method, a BadWindow error can be generated when this + value is used by the input method. + + When this XIC value is left unspecified, the input method will + use the client window as the default focus window. + +Resource Name and Class + + The XNResourceName and XNResourceClass arguments are strings + that specify the full name and class used by the client to + obtain resources for the client window. These values should be + used as prefixes for name and class when looking up resources + that may vary according to the input context. If these values + are not set, the resources will not be fully specified. + + It is not intended that values that can be set as XIC values be + set as resources. + +Geometry Callback + + The XNGeometryCallback argument is a structure of type + XIMCallback (see section 13.5.6.13.12). + + The XNGeometryCallback argument specifies the geometry callback + that a client can set. This callback is not required for + correct operation of either an input method or a client. It can + be set for a client whose user interface policy permits an + input method to request the dynamic change of that input + method's window. An input method that does dynamic change will + need to filter any events that it uses to initiate the change. + +Filter Events + + The XNFilterEvents argument returns the event mask that an + input method needs to have selected for. The client is expected + to augment its own event mask for the client window with this + one. + + This argument is read-only, is set by the input method at + create time, and is never changed. + + The type of this argument is unsigned long. Setting this value + will cause an error. + +Destroy Callback + + The XNDestroyCallback argument is a pointer to a structure of + type XIMCallback (see section 13.5.6.13.12). This callback is + triggered when the input method stops its service for any + reason; for example, when a connection to an IM server is + broken. After the destroy callback is called, the input context + is destroyed and the input method is closed. Therefore, the + client should not call XDestroyIC and XCloseIM. + +String Conversion Callback + + The XNStringConversionCallback argument is a structure of type + XIMCallback (see section 13.5.6.13.12). + + The XNStringConversionCallback argument specifies a string + conversion callback. This callback is not required for correct + operation of either the input method or the client. It can be + set by a client to support string conversions that may be + requested by the input method. An input method that does string + conversions will filter any events that it uses to initiate the + conversion. + + Because this XIC value is optional, a client should call + XGetIMValues with argument XNQueryICValuesList before using + this argument. + +String Conversion + + The XNStringConversion argument is a structure of type + XIMStringConversionText. + + The XNStringConversion argument specifies the string to be + converted by an input method. This argument is not required for + correct operation of either the input method or the client. + + String conversion facilitates the manipulation of text + independent of preediting. It is essential for some input + methods and clients to manipulate text by performing + context-sensitive conversion, reconversion, or transliteration + conversion on it. + + Because this XIC value is optional, a client should call + XGetIMValues with argument XNQueryICValuesList before using + this argument. + + The XIMStringConversionText structure is defined as follows: + + +typedef struct _XIMStringConversionText { + unsigned short length; + XIMStringConversionFeedback *feedback; + Bool encoding_is_wchar; + union { + char *mbs; + wchar_t *wcs; + } string; +} XIMStringConversionText; + +typedef unsigned long XIMStringConversionFeedback; + + The feedback member is reserved for future use. The text to be + converted is defined by the string and length members. The + length is indicated in characters. To prevent the library from + freeing memory pointed to by an uninitialized pointer, the + client should set the feedback element to NULL. + +Reset State + + The XNResetState argument specifies the state the input context + will return to after calling XmbResetIC or XwcResetIC. + + The XIC state may be set to its initial state, as specified by + the XNPreeditState value when XCreateIC was called, or it may + be set to preserve the current state. + + The valid masks for XIMResetState are as follows: + +typedef unsigned long XIMResetState; + +#define XIMInitialState (1L) +#define XIMPreserveState (1L<<1) + + + If XIMInitialState is set, then XmbResetIC and XwcResetIC will + return to the initial XNPreeditState state of the XIC. + + If XIMPreserveState is set, then XmbResetIC and XwcResetIC will + preserve the current state of the XIC. + + If XNResetState is left unspecified, the default is + XIMInitialState. + + XIMResetState values other than those specified above will + default to XIMInitialState. + + Because this XIC value is optional, a client should call + XGetIMValues with argument XNQueryICValuesList before using + this argument. + +Hot Keys + + The XNHotKey argument specifies the hot key list to the XIC. + The hot key list is a pointer to the structure of type + XIMHotKeyTriggers, which specifies the key events that must be + received without any interruption of the input method. For the + hot key list set with this argument to be utilized, the client + must also set XNHotKeyState to XIMHotKeyStateON. + + Because this XIC value is optional, a client should call + XGetIMValues with argument XNQueryICValuesList before using + this functionality. + + The value of the argument is a pointer to a structure of type + XIMHotKeyTriggers. + + If an event for a key in the hot key list is found, then the + process will receive the event and it will be processed inside + the client. + + + +typedef struct { + KeySym keysym; + unsigned int modifier; + unsigned int modifier_mask; +} XIMHotKeyTrigger; + +typedef struct { + int num_hot_key; + XIMHotKeyTrigger *key; +} XIMHotKeyTriggers; + + The combination of modifier and modifier_mask are used to + represent one of three states for each modifier: either the + modifier must be on, or the modifier must be off, or the + modifier is a ``don't care'' - it may be on or off. When a + modifier_mask bit is set to 0, the state of the associated + modifier is ignored when evaluating whether the key is hot or + not. + Modifier Bit Mask Bit Meaning + 0 1 The modifier must be off. + 1 1 The modifier must be on. + n/a 0 Do not care if the modifier is on or off. + +Hot Key State + + The XNHotKeyState argument specifies the hot key state of the + input method. This is usually used to switch the input method + between hot key operation and normal input processing. + + The value of the argument is a pointer to a structure of type + XIMHotKeyState . +typedef unsigned long XIMHotKeyState; + +#define XIMHotKeyStateON (0x0001L) +#define XIMHotKeyStateOFF (0x0002L) + + + If not specified, the default is XIMHotKeyStateOFF. + +Preedit and Status Attributes + + The XNPreeditAttributes and XNStatusAttributes arguments + specify to an input method the attributes to be used for the + preedit and status areas, if any. Those attributes are passed + to XSetICValues or XGetICValues as a nested variable-length + list. The names to be used in these lists are described in the + following sections. + +Area + + The value of the XNArea argument must be a pointer to a + structure of type XRectangle. The interpretation of the XNArea + argument is dependent on the input method style that has been + set. + + If the input method style is XIMPreeditPosition, XNArea + specifies the clipping region within which preediting will take + place. If the focus window has been set, the coordinates are + assumed to be relative to the focus window. Otherwise, the + coordinates are assumed to be relative to the client window. If + neither has been set, the results are undefined. + + If XNArea is not specified, is set to NULL, or is invalid, the + input method will default the clipping region to the geometry + of the XNFocusWindow. If the area specified is NULL or invalid, + the results are undefined. + + If the input style is XIMPreeditArea or XIMStatusArea, XNArea + specifies the geometry provided by the client to the input + method. The input method may use this area to display its data, + either preedit or status depending on the area designated. The + input method may create a window as a child of the client + window with dimensions that fit the XNArea. The coordinates are + relative to the client window. If the client window has not + been set yet, the input method should save these values and + apply them when the client window is set. If XNArea is not + specified, is set to NULL, or is invalid, the results are + undefined. + +Area Needed + + When set, the XNAreaNeeded argument specifies the geometry + suggested by the client for this area (preedit or status). The + value associated with the argument must be a pointer to a + structure of type XRectangle. Note that the x, y values are not + used and that nonzero values for width or height are the + constraints that the client wishes the input method to respect. + + When read, the XNAreaNeeded argument specifies the preferred + geometry desired by the input method for the area. + + This argument is only valid if the input style is + XIMPreeditArea or XIMStatusArea. It is used for geometry + negotiation between the client and the input method and has no + other effect on the input method (see section 13.5.1.5). + +Spot Location + + The XNSpotLocation argument specifies to the input method the + coordinates of the spot to be used by an input method executing + with XNInputStyle set to XIMPreeditPosition. When specified to + any input method other than XIMPreeditPosition, this XIC value + is ignored. + + The x coordinate specifies the position where the next + character would be inserted. The y coordinate is the position + of the baseline used by the current text line in the focus + window. The x and y coordinates are relative to the focus + window, if it has been set; otherwise, they are relative to the + client window. If neither the focus window nor the client + window has been set, the results are undefined. + + The value of the argument is a pointer to a structure of type + XPoint. + +Colormap + + Two different arguments can be used to indicate what colormap + the input method should use to allocate colors, a colormap ID, + or a standard colormap name. + + The XNColormap argument is used to specify a colormap ID. The + argument value is of type Colormap. An invalid argument may + generate a BadColor error when it is used by the input method. + + The XNStdColormap argument is used to indicate the name of the + standard colormap in which the input method should allocate + colors. The argument value is an Atom that should be a valid + atom for calling XGetRGBColormaps. An invalid argument may + generate a BadAtom error when it is used by the input method. + + If the colormap is left unspecified, the client window colormap + becomes the default. + +Foreground and Background + + The XNForeground and XNBackground arguments specify the + foreground and background pixel, respectively. The argument + value is of type unsigned long. It must be a valid pixel in the + input method colormap. + + If these values are left unspecified, the default is determined + by the input method. + +Background Pixmap + + The XNBackgroundPixmap argument specifies a background pixmap + to be used as the background of the window. The value must be + of type Pixmap. An invalid argument may generate a BadPixmap + error when it is used by the input method. + + If this value is left unspecified, the default is determined by + the input method. + +Font Set + + The XNFontSet argument specifies to the input method what font + set is to be used. The argument value is of type XFontSet. + + If this value is left unspecified, the default is determined by + the input method. + +Line Spacing + + The XNLineSpace argument specifies to the input method what + line spacing is to be used in the preedit window if more than + one line is to be used. This argument is of type int. + + If this value is left unspecified, the default is determined by + the input method. + +Cursor + + The XNCursor argument specifies to the input method what cursor + is to be used in the specified window. This argument is of type + Cursor. + + An invalid argument may generate a BadCursor error when it is + used by the input method. If this value is left unspecified, + the default is determined by the input method. + +Preedit State + + The XNPreeditState argument specifies the state of input + preediting for the input method. Input preediting can be on or + off. + + The valid mask names for XNPreeditState are as follows: + +typedef unsigned long XIMPreeditState; + +#define XIMPreeditUnknown 0L +#define XIMPreeditEnable 1L +#define XIMPreeditDisable (1L<<1) + + + If a value of XIMPreeditEnable is set, then input preediting is + turned on by the input method. + + If a value of XIMPreeditDisable is set, then input preediting + is turned off by the input method. + + If XNPreeditState is left unspecified, then the state will be + implementation-dependent. + + When XNResetState is set to XIMInitialState, the XNPreeditState + value specified at the creation time will be reflected as the + initial state for XmbResetIC and XwcResetIC. + + Because this XIC value is optional, a client should call + XGetIMValues with argument XNQueryICValuesList before using + this argument. + +Preedit State Notify Callback + + The preedit state notify callback is triggered by the input + method when the preediting state has changed. The value of the + XNPreeditStateNotifyCallback argument is a pointer to a + structure of type XIMCallback. The generic prototype is as + follows: + + void PreeditStateNotifyCallback(XIC ic, XPointer client_data, + XIMPreeditStateNotifyCallbackStruct *call_data); + + ic + + Specifies the input context. + + client_data + + Specifies the additional client data. + + call_data + + Specifies the current preedit state. + + The XIMPreeditStateNotifyCallbackStruct structure is defined as + follows: + + + +typedef struct _XIMPreeditStateNotifyCallbackStruct { + XIMPreeditState state; +} XIMPreeditStateNotifyCallbackStruct; + + Because this XIC value is optional, a client should call + XGetIMValues with argument XNQueryICValuesList before using + this argument. + +Preedit and Status Callbacks + + A client that wants to support the input style + XIMPreeditCallbacks must provide a set of preedit callbacks to + the input method. The set of preedit callbacks is as follows: + XNPreeditStartCallback This is called when the input method + starts preedit. + XNPreeditDoneCallback This is called when the input method + stops preedit. + XNPreeditDrawCallback This is called when a number of preedit + keystrokes should be echoed. + XNPreeditCaretCallback This is called to move the text + insertion point within the preedit string. + + A client that wants to support the input style + XIMStatusCallbacks must provide a set of status callbacks to + the input method. The set of status callbacks is as follows: + XNStatusStartCallback This is called when the input method + initializes the status area. + XNStatusDoneCallback This is called when the input method no + longer needs the status area. + XNStatusDrawCallback This is called when updating of the status + area is required. + + The value of any status or preedit argument is a pointer to a + structure of type XIMCallback. + + + +typedef void (*XIMProc)(); + +typedef struct { + XPointer client_data; + XIMProc callback; +} XIMCallback; + + Each callback has some particular semantics and will carry the + data that expresses the environment necessary to the client + into a specific data structure. This paragraph only describes + the arguments to be used to set the callback. + + Setting any of these values while doing preedit may cause + unexpected results. + +Input Method Callback Semantics + + XIM callbacks are procedures defined by clients or text drawing + packages that are to be called from the input method when + selected events occur. Most clients will use a text editing + package or a toolkit and, hence, will not need to define such + callbacks. This section defines the callback semantics, when + they are triggered, and what their arguments are. This + information is mostly useful for X toolkit implementors. + + Callbacks are mostly provided so that clients (or text editing + packages) can implement on-the-spot preediting in their own + window. In that case, the input method needs to communicate and + synchronize with the client. The input method needs to + communicate changes in the preedit window when it is under + control of the client. Those callbacks allow the client to + initialize the preedit area, display a new preedit string, move + the text insertion point during preedit, terminate preedit, or + update the status area. + + All callback procedures follow the generic prototype: + + void CallbackPrototype(XIC ic, XPointer client_data, SomeType + call_data); + + ic + + Specifies the input context. + + client_data + + Specifies the additional client data. + + call_data + + Specifies data specific to the callback. + + The call_data argument is a structure that expresses the + arguments needed to achieve the semantics; that is, it is a + specific data structure appropriate to the callback. In cases + where no data is needed in the callback, this call_data + argument is NULL. The client_data argument is a closure that + has been initially specified by the client when specifying the + callback and passed back. It may serve, for example, to inherit + application context in the callback. + + The following paragraphs describe the programming semantics and + specific data structure associated with the different reasons. + +Geometry Callback + + The geometry callback is triggered by the input method to + indicate that it wants the client to negotiate geometry. The + generic prototype is as follows: + + void GeometryCallback(XIC ic, XPointer client_data, XPointer + call_data); + + ic + + Specifies the input context. + + client_data + + Specifies the additional client data. + + call_data + + Not used for this callback and always passed as NULL. + + The callback is called with a NULL call_data argument. + +Destroy Callback + + The destroy callback is triggered by the input method when it + stops service for any reason. After the callback is invoked, + the input context will be freed by Xlib. The generic prototype + is as follows: + + void DestroyCallback(XIC ic, XPointer client_data, XPointer + call_data); + + ic + + Specifies the input context. + + client_data + + Specifies the additional client data. + + call_data + + Not used for this callback and always passed as NULL. + + The callback is called with a NULL call_data argument. + +String Conversion Callback + + The string conversion callback is triggered by the input method + to request the client to return the string to be converted. The + returned string may be either a multibyte or wide character + string, with an encoding matching the locale bound to the input + context. The callback prototype is as follows: + + void StringConversionCallback(XIC ic, XPointer client_data, + XIMStringConversionCallbackStruct *call_data); + + ic + + Specifies the input method. + + client_data + + Specifies the additional client data. + + call_data + + Specifies the amount of the string to be converted. + + The callback is passed an XIMStringConversionCallbackStruct + structure in the call_data argument. The text member is an + XIMStringConversionText structure (see section 13.5.6.9) to be + filled in by the client and describes the text to be sent to + the input method. The data pointed to by the string and + feedback elements of the XIMStringConversionText structure will + be freed using XFree by the input method after the callback + returns. So the client should not point to internal buffers + that are critical to the client. Similarly, because the + feedback element is currently reserved for future use, the + client should set feedback to NULL to prevent the library from + freeing memory at some random location due to an uninitialized + pointer. + + The XIMStringConversionCallbackStruct structure is defined as + follows: + +typedef struct _XIMStringConversionCallbackStruct { + XIMStringConversionPosition position; + XIMCaretDirection direction; + short factor; + XIMStringConversionOperation operation; + XIMStringConversionText *text; +} XIMStringConversionCallbackStruct; + +typedef short XIMStringConversionPosition; + +typedef unsigned short XIMStringConversionOperation; + +#define XIMStringConversionSubstitution (0x0001) +#define XIMStringConversionRetrieval (0x0001) + + + XIMStringConversionPosition specifies the starting position of + the string to be returned in the XIMStringConversionText + structure. The value identifies a position, in units of + characters, relative to the client's cursor position in the + client's buffer. + + The ending position of the text buffer is determined by the + direction and factor members. Specifically, it is the character + position relative to the starting point as defined by the + XIMCaretDirection. The factor member of + XIMStringConversionCallbackStruct specifies the number of + XIMCaretDirection positions to be applied. For example, if the + direction specifies XIMLineEnd and factor is 1, then all + characters from the starting position to the end of the current + display line are returned. If the direction specifies + XIMForwardChar or XIMBackwardChar, then the factor specifies a + relative position, indicated in characters, from the starting + position. + + XIMStringConversionOperation specifies whether the string to be + converted should be deleted (substitution) or copied + (retrieval) from the client's buffer. When the + XIMStringConversionOperation is + XIMStringConversionSubstitution, the client must delete the + string to be converted from its own buffer. When the + XIMStringConversionOperation is XIMStringConversionRetrieval, + the client must not delete the string to be converted from its + buffer. The substitute operation is typically used for + reconversion and transliteration conversion, while the + retrieval operation is typically used for context-sensitive + conversion. + +Preedit State Callbacks + + When the input method turns preediting on or off, a + PreeditStartCallback or PreeditDoneCallback callback is + triggered to let the toolkit do the setup or the cleanup for + the preedit region. + + int PreeditStartCallback(XIC ic, XPointer client_data, XPointer + call_data); + + ic + + Specifies the input context. + + client_data + + Specifies the additional client data. + + call_data + + Not used for this callback and always passed as NULL. + + When preedit starts on the specified input context, the + callback is called with a NULL call_data argument. + PreeditStartCallback will return the maximum size of the + preedit string. A positive number indicates the maximum number + of bytes allowed in the preedit string, and a value of -1 + indicates there is no limit. + + void PreeditDoneCallback(XIC ic, XPointer client_data, XPointer + call_data); + + ic + + Specifies the input context. + + client_data + + Specifies the additional client data. + + call_data + + Not used for this callback and always passed as NULL. + + When preedit stops on the specified input context, the callback + is called with a NULL call_data argument. The client can + release the data allocated by PreeditStartCallback. + + PreeditStartCallback should initialize appropriate data needed + for displaying preedit information and for handling further + PreeditDrawCallback calls. Once PreeditStartCallback is called, + it will not be called again before PreeditDoneCallback has been + called. + +Preedit Draw Callback + + This callback is triggered to draw and insert, delete or + replace, preedit text in the preedit region. The preedit text + may include unconverted input text such as Japanese Kana, + converted text such as Japanese Kanji characters, or characters + of both kinds. That string is either a multibyte or wide + character string, whose encoding matches the locale bound to + the input context. The callback prototype is as follows: + + void PreeditDrawCallback(XIC ic, XPointer client_data, + XIMPreeditDrawCallbackStruct *call_data); + + ic + + Specifies the input context. + + client_data + + Specifies the additional client data. + + call_data + + Specifies the preedit drawing information. + + The callback is passed an XIMPreeditDrawCallbackStruct + structure in the call_data argument. The text member of this + structure contains the text to be drawn. After the string has + been drawn, the caret should be moved to the specified + location. + + The XIMPreeditDrawCallbackStruct structure is defined as + follows: + + + +typedef struct _XIMPreeditDrawCallbackStruct { + int caret; /* Cursor offset within preedit string */ + int chg_first; /* Starting change position */ + int chg_length; /* Length of the change in character count */ + XIMText *text; +} XIMPreeditDrawCallbackStruct; + + The client must keep updating a buffer of the preedit text and + the callback arguments referring to indexes in that buffer. The + call_data fields have specific meanings according to the + operation, as follows: + * To indicate text deletion, the call_data member specifies a + NULL text field. The text to be deleted is then the current + text in the buffer from position chg_first (starting at + zero) on a character length of chg_length. + * When text is non-NULL, it indicates insertion or + replacement of text in the buffer. + * The chg_length member identifies the number of characters + in the current preedit buffer that are affected by this + call. A positive chg_length indicates that chg_length + number of characters, starting at chg_first, must be + deleted or must be replaced by text, whose length is + specified in the XIMText structure. + * A chg_length value of zero indicates that text must be + inserted right at the position specified by chg_first. A + value of zero for chg_first specifies the first character + in the buffer. + * chg_length and chg_first combine to identify the + modification required to the preedit buffer; beginning at + chg_first, replace chg_length number of characters with the + text in the supplied XIMText structure. For example, + suppose the preedit buffer contains the string "ABCDE". + * + +Text: A B C D E + ^ ^ ^ ^ ^ ^ +CharPos: 0 1 2 3 4 5 + + + + The CharPos in the diagram shows the location of the + character position relative to the character. + * If the value of chg_first is 1 and the value of chg_length + is 3, this says to replace 3 characters beginning at + character position 1 with the string in the XIMText + structure. Hence, BCD would be replaced by the value in the + structure. + * Though chg_length and chg_first are both signed integers + they will never have a negative value. + * The caret member identifies the character position before + which the cursor should be placed - after modification to + the preedit buffer has been completed. For example, if + caret is zero, the cursor is at the beginning of the + buffer. If the caret is one, the cursor is between the + first and second character. + + +typedef struct _XIMText { + unsigned short length; + XIMFeedback * feedback; + Bool encoding_is_wchar; + union { + char * multi_byte; + wchar_t * wide_char; + } string; +} XIMText; + + The text string passed is actually a structure specifying as + follows: + * The length member is the text length in characters. + * The encoding_is_wchar member is a value that indicates if + the text string is encoded in wide character or multibyte + format. The text string may be passed either as multibyte + or as wide character; the input method controls in which + form data is passed. The client's callback routine must be + able to handle data passed in either form. + * The string member is the text string. + * The feedback member indicates rendering type for each + character in the string member. If string is NULL + (indicating that only highlighting of the existing preedit + buffer should be updated), feedback points to length + highlight elements that should be applied to the existing + preedit buffer, beginning at chg_first. + + The feedback member expresses the types of rendering feedback + the callback should apply when drawing text. Rendering of the + text to be drawn is specified either in generic ways (for + example, primary, secondary) or in specific ways (reverse, + underline). When generic indications are given, the client is + free to choose the rendering style. It is necessary, however, + that primary and secondary be mapped to two distinct rendering + styles. + + If an input method wants to control display of the preedit + string, an input method can indicate the visibility hints using + feedbacks in a specific way. The XIMVisibleToForward, + XIMVisibleToBackword, and XIMVisibleToCenter masks are + exclusively used for these visibility hints. The + XIMVisibleToForward mask indicates that the preedit text is + preferably displayed in the primary draw direction from the + caret position in the preedit area forward. The + XIMVisibleToBackword mask indicates that the preedit text is + preferably displayed from the caret position in the preedit + area backward, relative to the primary draw direction. The + XIMVisibleToCenter mask indicates that the preedit text is + preferably displayed with the caret position in the preedit + area centered. + + The insertion point of the preedit string could exist outside + of the visible area when visibility hints are used. Only one of + the masks is valid for the entire preedit string, and only one + character can hold one of these feedbacks for a given input + context at one time. This feedback may be OR'ed together with + another highlight (such as XIMReverse). Only the most recently + set feedback is valid, and any previous feedback is + automatically canceled. This is a hint to the client, and the + client is free to choose how to display the preedit string. + + The feedback member also specifies how rendering of the text + argument should be performed. If the feedback is NULL, the + callback should apply the same feedback as is used for the + surrounding characters in the preedit buffer; if chg_first is + at a highlight boundary, the client can choose which of the two + highlights to use. If feedback is not NULL, feedback specifies + an array defining the rendering for each character of the + string, and the length of the array is thus length. + + If an input method wants to indicate that it is only updating + the feedback of the preedit text without changing the content + of it, the XIMText structure will contain a NULL value for the + string field, the number of characters affected (relative to + chg_first) will be in the length field, and the feedback field + will point to an array of XIMFeedback. + + Each element in the feedback array is a bitmask represented by + a value of type XIMFeedback. The valid mask names are as + follows: + +typedef unsigned long XIMFeedback; + +#define XIMReverse 1L +#define XIMUnderline (1L<<1) +#define XIMHighlight (1L<<2) +#define XIMPrimary (1L<<5)* +#define XIMSecondary (1L<<6)* +#define XIMTertiary (1L<<7)* +#define XIMVisibleToForward (1L<<8) +#define XIMVisibleToBackward (1L<<9) +#define XIMVisibleToCenter (1L<<10) + +*/- The values for XIMPrimary, XIMSecondary, and XIMTertiary were incorr +ectly defined in +the R5 specification. The X Consortium's X11R5 implementation correctly +implemented the values for these highlights. The value of these highligh +ts has +been corrected in this specification to agree with the values in the +Consortium's X11R5 and X11R6 implementations. + + + Characters drawn with the XIMReverse highlight should be drawn + by swapping the foreground and background colors used to draw + normal, unhighlighted characters. Characters drawn with the + XIMUnderline highlight should be underlined. Characters drawn + with the XIMHighlight, XIMPrimary, XIMSecondary, and + XIMTertiary highlights should be drawn in some unique manner + that must be different from XIMReverse and XIMUnderline. The + values for XIMPrimary, XIMSecondary, and XIMTertiary were + incorrectly defined in the R5 specification. The X Consortium's + X11R5 implementation correctly implemented the values for these + highlights. The value of these highlights has been corrected in + this specification to agree with the values in the Consortium's + X11R5 and X11R6 implementations. + +Preedit Caret Callback + + An input method may have its own navigation keys to allow the + user to move the text insertion point in the preedit area (for + example, to move backward or forward). Consequently, input + method needs to indicate to the client that it should move the + text insertion point. It then calls the PreeditCaretCallback. + + void PreeditCaretCallback(XIC ic, XPointer client_data, + XIMPreeditCaretCallbackStruct *call_data); + + ic + + Specifies the input context. + + client_data + + Specifies the additional client data. + + call_data + + Specifies the preedit caret information. + + The input method will trigger PreeditCaretCallback to move the + text insertion point during preedit. The call_data argument + contains a pointer to an XIMPreeditCaretCallbackStruct + structure, which indicates where the caret should be moved. The + callback must move the insertion point to its new location and + return, in field position, the new offset value from the + initial position. + + The XIMPreeditCaretCallbackStruct structure is defined as + follows: + + + +typedef struct _XIMPreeditCaretCallbackStruct { + int position; /* Caret offset within preedit string */ + XIMCaretDirection direction; /* Caret moves direction */ + XIMCaretStyle style; /* Feedback of the caret */ +} XIMPreeditCaretCallbackStruct; + + The XIMCaretStyle structure is defined as follows: + + + +typedef enum { + XIMIsInvisible, /* Disable caret feedback */ + XIMIsPrimary, /* UI defined caret feedback */ + XIMIsSecondary, /* UI defined caret feedback */ +} XIMCaretStyle; + + The XIMCaretDirection structure is defined as follows: + + + +typedef enum { + XIMForwardChar, XIMBackwardChar, + XIMForwardWord, XIMBackwardWord, + XIMCaretUp, XIMCaretDown, + XIMNextLine, XIMPreviousLine, + XIMLineStart, XIMLineEnd, + XIMAbsolutePosition, + XIMDontChange, + } XIMCaretDirection; + + These values are defined as follows: + XIMForwardChar Move the caret forward one character position. + XIMBackwardChar Move the caret backward one character position. + XIMForwardWord Move the caret forward one word. + XIMBackwardWord Move the caret backward one word. + XIMCaretUp Move the caret up one line keeping the current + horizontal offset. + XIMCaretDown Move the caret down one line keeping the current + horizontal offset. + XIMPreviousLine Move the caret to the beginning of the previous + line. + XIMNextLine Move the caret to the beginning of the next line. + XIMLineStart Move the caret to the beginning of the current + display line that contains the caret. + XIMLineEnd Move the caret to the end of the current display + line that contains the caret. + XIMAbsolutePosition The callback must move to the location + specified by the position field of the callback data, indicated + in characters, starting from the beginning of the preedit text. + Hence, a value of zero means move back to the beginning of the + preedit text. + XIMDontChange The caret position does not change. + +Status Callbacks + + An input method may communicate changes in the status of an + input context (for example, created, destroyed, or focus + changes) with three status callbacks: StatusStartCallback, + StatusDoneCallback, and StatusDrawCallback. + + When the input context is created or gains focus, the input + method calls the StatusStartCallback callback. + + void StatusStartCallback(XIC ic, XPointer client_data, XPointer + call_data); + + ic + + Specifies the input context. + + client_data + + Specifies the additional client data. + + call_data + + Not used for this callback and always passed as NULL. + + The callback should initialize appropriate data for displaying + status and for responding to StatusDrawCallback calls. Once + StatusStartCallback is called, it will not be called again + before StatusDoneCallback has been called. + + When an input context is destroyed or when it loses focus, the + input method calls StatusDoneCallback. + + void StatusDoneCallback(XIC ic, XPointer client_data, XPointer + call_data); + + ic + + Specifies the input context. + + client_data + + Specifies the additional client data. + + call_data + + Not used for this callback and always passed as NULL. + + The callback may release any data allocated on StatusStart. + + When an input context status has to be updated, the input + method calls StatusDrawCallback. + + void StatusDrawCallback(XIC ic, XPointer client_data, + XIMStatusDrawCallbackStruct *call_data); + + ic + + Specifies the input context. + + client_data + + Specifies the additional client data. + + call_data + + Specifies the status drawing information. + + The callback should update the status area by either drawing a + string or imaging a bitmap in the status area. + + The XIMStatusDataType and XIMStatusDrawCallbackStruct + structures are defined as follows: + + + +typedef enum { + XIMTextType, + XIMBitmapType, +} XIMStatusDataType; + +typedef struct _XIMStatusDrawCallbackStruct { + XIMStatusDataType type; + union { + XIMText *text; + Pixmap bitmap; + } data; +} XIMStatusDrawCallbackStruct; + + The feedback styles XIMVisibleToForward, XIMVisibleToBackword, + and XIMVisibleToCenter are not relevant and will not appear in + the XIMFeedback element of the XIMText structure. + +Event Filtering + + Xlib provides the ability for an input method to register a + filter internal to Xlib. This filter is called by a client (or + toolkit) by calling XFilterEvent after calling XNextEvent. Any + client that uses the XIM interface should call XFilterEvent to + allow input methods to process their events without knowledge + of the client's dispatching mechanism. A client's user + interface policy may determine the priority of event filters + with respect to other event-handling mechanisms (for example, + modal grabs). + + Clients may not know how many filters there are, if any, and + what they do. They may only know if an event has been filtered + on return of XFilterEvent. Clients should discard filtered + events. + + To filter an event, use XFilterEvent. + + Bool XFilterEvent(XEvent *event, Window w); + + event + + Specifies the event to filter. + + w + + Specifies the window for which the filter is to be applied. + + If the window argument is None, XFilterEvent applies the filter + to the window specified in the XEvent structure. The window + argument is provided so that layers above Xlib that do event + redirection can indicate to which window an event has been + redirected. + + If XFilterEvent returns True, then some input method has + filtered the event, and the client should discard the event. If + XFilterEvent returns False, then the client should continue + processing the event. + + If a grab has occurred in the client and XFilterEvent returns + True, the client should ungrab the keyboard. + +Getting Keyboard Input + + To get composed input from an input method, use XmbLookupString + or XwcLookupString. + + int XmbLookupString(XIC ic, XKeyPressedEvent *event, char + *buffer_return, int bytes_buffer, KeySym *keysym_return, Status + *status_return); + + int XwcLookupString(XIC ic, XKeyPressedEvent *event, wchar_t + *buffer_return, int wchars_buffer, KeySym *keysym_return, + Status *status_return); + + ic + + Specifies the input context. + + event + + Specifies the key event to be used. + + buffer_return + + Returns a multibyte string or wide character string (if any) + from the input method. + + bytes_buffer + + wchars_buffer + + Specifies space available in the return buffer. + + keysym_return + + Returns the KeySym computed from the event if this argument is + not NULL. + + status_return + + Returns a value indicating what kind of data is returned. + + The XmbLookupString and XwcLookupString functions return the + string from the input method specified in the buffer_return + argument. If no string is returned, the buffer_return argument + is unchanged. + + The KeySym into which the KeyCode from the event was mapped is + returned in the keysym_return argument if it is non-NULL and + the status_return argument indicates that a KeySym was + returned. If both a string and a KeySym are returned, the + KeySym value does not necessarily correspond to the string + returned. + + XmbLookupString returns the length of the string in bytes, and + XwcLookupString returns the length of the string in characters. + Both XmbLookupString and XwcLookupString return text in the + encoding of the locale bound to the input method of the + specified input context. + + Each string returned by XmbLookupString and XwcLookupString + begins in the initial state of the encoding of the locale (if + the encoding of the locale is state-dependent). + +Note + + To insure proper input processing, it is essential that the + client pass only KeyPress events to XmbLookupString and + XwcLookupString. Their behavior when a client passes a + KeyRelease event is undefined. + + Clients should check the status_return argument before using + the other returned values. These two functions both return a + value to status_return that indicates what has been returned in + the other arguments. The possible values returned are: + XBufferOverflow The input string to be returned is too large + for the supplied buffer_return. The required size + (XmbLookupString in bytes; XwcLookupString in characters) is + returned as the value of the function, and the contents of + buffer_return and keysym_return are not modified. The client + should recall the function with the same event and a buffer of + adequate size to obtain the string. + XLookupNone No consistent input has been composed so far. The + contents of buffer_return and keysym_return are not modified, + and the function returns zero. + XLookupChars Some input characters have been composed. They are + placed in the buffer_return argument, and the string length is + returned as the value of the function. The string is encoded in + the locale bound to the input context. The content of the + keysym_return argument is not modified. + XLookupKeySym A KeySym has been returned instead of a string + and is returned in keysym_return. The content of the + buffer_return argument is not modified, and the function + returns zero. + XLookupBoth Both a KeySym and a string are returned; + XLookupChars and XLookupKeySym occur simultaneously. + + It does not make any difference if the input context passed as + an argument to XmbLookupString and XwcLookupString is the one + currently in possession of the focus or not. Input may have + been composed within an input context before it lost the focus, + and that input may be returned on subsequent calls to + XmbLookupString or XwcLookupString even though it does not have + any more keyboard focus. + +Input Method Conventions + + The input method architecture is transparent to the client. + However, clients should respect a number of conventions in + order to work properly. Clients must also be aware of possible + effects of synchronization between input method and library in + the case of a remote input server. + +Client Conventions + + A well-behaved client (or toolkit) should first query the input + method style. If the client cannot satisfy the requirements of + the supported styles (in terms of geometry management or + callbacks), it should negotiate with the user continuation of + the program or raise an exception or error of some sort. + +Synchronization Conventions + + A KeyPress event with a KeyCode of zero is used exclusively as + a signal that an input method has composed input that can be + returned by XmbLookupString or XwcLookupString. No other use is + made of a KeyPress event with KeyCode of zero. + + Such an event may be generated by either a front-end or a + back-end input method in an implementation-dependent manner. + Some possible ways to generate this event include: + * A synthetic event sent by an input method server + * An artificial event created by a input method filter and + pushed onto a client's event queue + * A KeyPress event whose KeyCode value is modified by an + input method filter + + When callback support is specified by the client, input methods + will not take action unless they explicitly called back the + client and obtained no response (the callback is not specified + or returned invalid data). + +String Constants + + The following symbols for string constants are defined in + . Although they are shown here with particular + macro definitions, they may be implemented as macros, as global + symbols, or as a mixture of the two. The string pointer value + itself is not significant; clients must not assume that + inequality of two values implies inequality of the actual + string data. +#define XNVaNestedList "XNVaNestedList" +#define XNSeparatorofNestedList "separatorofNestedList" +#define XNQueryInputStyle "queryInputStyle" +#define XNClientWindow "clientWindow" +#define XNInputStyle "inputStyle" +#define XNFocusWindow "focusWindow" +#define XNResourceName "resourceName" +#define XNResourceClass "resourceClass" +#define XNGeometryCallback "geometryCallback" +#define XNDestroyCallback "destroyCallback" +#define XNFilterEvents "filterEvents" +#define XNPreeditStartCallback "preeditStartCallback" +#define XNPreeditDoneCallback "preeditDoneCallback" +#define XNPreeditDrawCallback "preeditDrawCallback" +#define XNPreeditCaretCallback "preeditCaretCallback" +#define XNPreeditStateNotifyCallback "preeditStateNotifyCallback +" +#define XNPreeditAttributes "preeditAttributes" +#define XNStatusStartCallback "statusStartCallback" +#define XNStatusDoneCallback "statusDoneCallback" +#define XNStatusDrawCallback "statusDrawCallback" +#define XNStatusAttributes "statusAttributes" +#define XNArea "area" +#define XNAreaNeeded "areaNeeded" +#define XNSpotLocation "spotLocation" +#define XNColormap "colorMap" +#define XNStdColormap "stdColorMap" +#define XNForeground "foreground" +#define XNBackground "background" +#define XNBackgroundPixmap "backgroundPixmap" +#define XNFontSet "fontSet" +#define XNLineSpace "lineSpace" +#define XNCursor "cursor" +#define XNQueryIMValuesList "queryIMValuesList" +#define XNQueryICValuesList "queryICValuesList" +#define XNStringConversionCallback "stringConversionCallback" +#define XNStringConversion "stringConversion" +#define XNResetState "resetState" +#define XNHotKey "hotkey" +#define XNHotKeyState "hotkeyState" +#define XNPreeditState "preeditState" +#define XNVisiblePosition "visiblePosition" +#define XNR6PreeditCallbackBehavior "r6PreeditCallback" +#define XNRequiredCharSet "requiredCharSet" +#define XNQueryOrientation "queryOrientation" +#define XNDirectionalDependentDrawing "directionalDependentDrawin +g" +#define XNContextualDrawing "contextualDrawing" +#define XNBaseFontName "baseFontName" +#define XNMissingCharSet "missingCharSet" +#define XNDefaultString "defaultString" +#define XNOrientation "orientation" +#define XNFontInfo "fontInfo" +#define XNOMAutomatic "omAutomatic" + + +Chapter 14. Inter-Client Communication Functions + + Table of Contents + + Client to Window Manager Communication + + Manipulating Top-Level Windows + Converting String Lists + Setting and Reading Text Properties + Setting and Reading the WM_NAME Property + Setting and Reading the WM_ICON_NAME Property + Setting and Reading the WM_HINTS Property + Setting and Reading the WM_NORMAL_HINTS Property + Setting and Reading the WM_CLASS Property + Setting and Reading the WM_TRANSIENT_FOR Property + Setting and Reading the WM_PROTOCOLS Property + Setting and Reading the WM_COLORMAP_WINDOWS Property + Setting and Reading the WM_ICON_SIZE Property + Using Window Manager Convenience Functions + + Client to Session Manager Communication + + Setting and Reading the WM_COMMAND Property + Setting and Reading the WM_CLIENT_MACHINE Property + + Standard Colormaps + + Standard Colormap Properties and Atoms + Setting and Obtaining Standard Colormaps + + The Inter-Client Communication Conventions Manual, hereafter + referred to as the ICCCM, details the X Consortium approved + conventions that govern inter-client communications. These + conventions ensure peer-to-peer client cooperation in the use + of selections, cut buffers, and shared resources as well as + client cooperation with window and session managers. For + further information, see the Inter-Client Communication + Conventions Manual. + + Xlib provides a number of standard properties and programming + interfaces that are ICCCM compliant. The predefined atoms for + some of these properties are defined in the + header file, where to avoid name conflicts with user symbols + their #define name has an XA_ prefix. For further information + about atoms and properties, see section 4.3. + + Xlib's selection and cut buffer mechanisms provide the primary + programming interfaces by which peer client applications + communicate with each other (see sections 4.5 and 16.6). The + functions discussed in this chapter provide the primary + programming interfaces by which client applications communicate + with their window and session managers as well as share + standard colormaps. + + The standard properties that are of special interest for + communicating with window and session managers are: + Name Type Format Description + WM_CLASS STRING 8 Set by application programs to allow window + and session managers to obtain the application's resources from + the resource database. + WM_CLIENT_MACHINE TEXT The string name of the machine on + which the client application is running. + WM_COLORMAP_WINDOWS WINDOWS 32 The list of window IDs that may + need a different colormap from that of their top-level window. + WM_COMMAND TEXT The command and arguments, null separated, + used to invoke the application. + WM_HINTS WM_HINTS 32 Additional hints set by the client for use + by the window manager. The C type of this property is XWMHints. + WM_ICON_NAME TEXT The name to be used in an icon. + WM_ICON_SIZE WM_ICON_SIZE 32 The window manager may set this + property on the root window to specify the icon sizes it + supports. The C type of this property is XIconSize. + WM_NAME TEXT The name of the application. + WM_NORMAL_HINTS WM_NORMAL_HINTS 32 Size hints for a window in + its normal state. The C type of this property is XSizeHints. + WM_PROTOCOLS ATOM 32 List of atoms that identify the + communications protocols between the client and window manager + in which the client is willing to participate. + WM_STATE WM_STATE 32 Intended for communication between window + and session managers only. + WM_TRANSIENT_FOR WINDOW 32 Set by application programs to + indicate to the window manager that a transient top-level + window, such as a dialog box. + + The remainder of this chapter discusses: + * Client to window manager communication + * Client to session manager communication + * Standard colormaps + +Client to Window Manager Communication + + This section discusses how to: + * Manipulate top-level windows + * Convert string lists + * Set and read text properties + * Set and read the WM_NAME property + * Set and read the WM_ICON_NAME property + * Set and read the WM_HINTS property + * Set and read the WM_NORMAL_HINTS property + * Set and read the WM_CLASS property + * Set and read the WM_TRANSIENT_FOR property + * Set and read the WM_PROTOCOLS property + * Set and read the WM_COLORMAP_WINDOWS property + * Set and read the WM_ICON_SIZE property + * Use window manager convenience functions + +Manipulating Top-Level Windows + + Xlib provides functions that you can use to change the + visibility or size of top-level windows (that is, those that + were created as children of the root window). Note that the + subwindows that you create are ignored by window managers. + Therefore, you should use the basic window functions described + in chapter 3 to manipulate your application's subwindows. + + To request that a top-level window be iconified, use + XIconifyWindow. + + Status XIconifyWindow(Display *display, Window w, int + screen_number); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + screen_number + + Specifies the appropriate screen number on the host server. + + The XIconifyWindow function sends a WM_CHANGE_STATE + ClientMessage event with a format of 32 and a first data + element of IconicState (as described in section 4.1.4 of the + Inter-Client Communication Conventions Manual) and a window of + w to the root window of the specified screen with an event mask + set to SubstructureNotifyMask | SubstructureRedirectMask. + Window managers may elect to receive this message and if the + window is in its normal state, may treat it as a request to + change the window's state from normal to iconic. If the + WM_CHANGE_STATE property cannot be interned, XIconifyWindow + does not send a message and returns a zero status. It returns a + nonzero status if the client message is sent successfully; + otherwise, it returns a zero status. + + To request that a top-level window be withdrawn, use + XWithdrawWindow. + + Status XWithdrawWindow(Display *display, Window w, int + screen_number); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + screen_number + + Specifies the appropriate screen number on the host server. + + The XWithdrawWindow function unmaps the specified window and + sends a synthetic UnmapNotify event to the root window of the + specified screen. Window managers may elect to receive this + message and may treat it as a request to change the window's + state to withdrawn. When a window is in the withdrawn state, + neither its normal nor its iconic representations is visible. + It returns a nonzero status if the UnmapNotify event is + successfully sent; otherwise, it returns a zero status. + + XWithdrawWindow can generate a BadWindow error. + + To request that a top-level window be reconfigured, use + XReconfigureWMWindow. + + Status XReconfigureWMWindow(Display *display, Window w, int + screen_number, unsigned int value_mask, XWindowChanges + *values); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + screen_number + + Specifies the appropriate screen number on the host server. + + value_mask + + Specifies which values are to be set using information in the + values structure. This mask is the bitwise inclusive OR of the + valid configure window values bits. + + values + + Specifies the XWindowChanges structure. + + The XReconfigureWMWindow function issues a ConfigureWindow + request on the specified top-level window. If the stacking mode + is changed and the request fails with a BadMatch error, the + error is trapped by Xlib and a synthetic ConfigureRequestEvent + containing the same configuration parameters is sent to the + root of the specified window. Window managers may elect to + receive this event and treat it as a request to reconfigure the + indicated window. It returns a nonzero status if the request or + event is successfully sent; otherwise, it returns a zero + status. + + XReconfigureWMWindow can generate BadValue and BadWindow + errors. + +Converting String Lists + + Many of the text properties allow a variety of types and + formats. Because the data stored in these properties are not + simple null-terminated strings, an XTextProperty structure is + used to describe the encoding, type, and length of the text as + well as its value. The XTextProperty structure contains: + + +typedef struct { + unsigned char *value; /* property data */ + Atom encoding; /* type of property */ + int format; /* 8, 16, or 32 */ + unsigned long nitems; /* number of items in value */ +} XTextProperty; + + Xlib provides functions to convert localized text to or from + encodings that support the inter-client communication + conventions for text. In addition, functions are provided for + converting between lists of pointers to character strings and + text properties in the STRING encoding. + + The functions for localized text return a signed integer error + status that encodes Success as zero, specific error conditions + as negative numbers, and partial conversion as a count of + unconvertible characters. + +#define #XNoMemory -1 +#define #XLocaleNotSupported -2 +#define #XConverterNotFound -3 + +typedef enum { + XStringStyle, /* STRING */ + XCompoundTextStyle, /* COMPOUND_TEXT */ + XTextStyle, /* text in owner's encoding (current loc +ale) */ + XStdICCTextStyle /* STRING, else COMPOUND_TEXT */ +} XICCEncodingStyle; + + To convert a list of text strings to an XTextProperty + structure, use XmbTextListToTextProperty or + XwcTextListToTextProperty. + + int XmbTextListToTextProperty(Display *display, char **list, + int count, XICCEncodingStyle style, XTextProperty + *text_prop_return); + + int XwcTextListToTextProperty(Display *display, wchar_t **list, + int count, XICCEncodingStyle style, XTextProperty + *text_prop_return); + + display + + Specifies the connection to the X server. + + list + + Specifies a list of null-terminated character strings. + + count + + Specifies the number of strings specified. + + style + + Specifies the manner in which the property is encoded. + + text_prop_return + + Returns the XTextProperty structure. + + The XmbTextListToTextProperty and XwcTextListToTextProperty + functions set the specified XTextProperty value to a set of + null-separated elements representing the concatenation of the + specified list of null-terminated text strings. A final + terminating null is stored at the end of the value field of + text_prop_return but is not included in the nitems member. + + The functions set the encoding field of text_prop_return to an + Atom for the specified display naming the encoding determined + by the specified style and convert the specified text list to + this encoding for storage in the text_prop_return value field. + If the style XStringStyle or XCompoundTextStyle is specified, + this encoding is ``STRING'' or ``COMPOUND_TEXT'', respectively. + If the style XTextStyle is specified, this encoding is the + encoding of the current locale. If the style XStdICCTextStyle + is specified, this encoding is ``STRING'' if the text is fully + convertible to STRING, else ``COMPOUND_TEXT''. + + If insufficient memory is available for the new value string, + the functions return XNoMemory. If the current locale is not + supported, the functions return XLocaleNotSupported. In both of + these error cases, the functions do not set text_prop_return. + + To determine if the functions are guaranteed not to return + XLocaleNotSupported, use XSupportsLocale. + + If the supplied text is not fully convertible to the specified + encoding, the functions return the number of unconvertible + characters. Each unconvertible character is converted to an + implementation-defined and encoding-specific default string. + Otherwise, the functions return Success. Note that full + convertibility to all styles except XStringStyle is guaranteed. + + To free the storage for the value field, use XFree. + + To obtain a list of text strings from an XTextProperty + structure, use XmbTextPropertyToTextList or + XwcTextPropertyToTextList. + + int XmbTextPropertyToTextList(Display *display, XTextProperty + *text_prop, char ***list_return, int *count_return); + + int XwcTextPropertyToTextList(Display *display, XTextProperty + *text_prop, wchar_t ***list_return, int *count_return); + + display + + Specifies the connection to the X server. + + text_prop + + Specifies the XTextProperty structure to be used. + + list_return + + Returns a list of null-terminated character strings. + + count_return + + Returns the number of strings. + + The XmbTextPropertyToTextList and XwcTextPropertyToTextList + functions return a list of text strings in the current locale + representing the null-separated elements of the specified + XTextProperty structure. The data in text_prop must be format + 8. + + Multiple elements of the property (for example, the strings in + a disjoint text selection) are separated by a null byte. The + contents of the property are not required to be + null-terminated; any terminating null should not be included in + text_prop.nitems. + + If insufficient memory is available for the list and its + elements, XmbTextPropertyToTextList and + XwcTextPropertyToTextList return XNoMemory. If the current + locale is not supported, the functions return + XLocaleNotSupported. Otherwise, if the encoding field of + text_prop is not convertible to the encoding of the current + locale, the functions return XConverterNotFound. For supported + locales, existence of a converter from COMPOUND_TEXT, STRING or + the encoding of the current locale is guaranteed if + XSupportsLocale returns True for the current locale (but the + actual text may contain unconvertible characters). Conversion + of other encodings is implementation-dependent. In all of these + error cases, the functions do not set any return values. + + Otherwise, XmbTextPropertyToTextList and + XwcTextPropertyToTextList return the list of null-terminated + text strings to list_return and the number of text strings to + count_return. + + If the value field of text_prop is not fully convertible to the + encoding of the current locale, the functions return the number + of unconvertible characters. Each unconvertible character is + converted to a string in the current locale that is specific to + the current locale. To obtain the value of this string, use + XDefaultString. Otherwise, XmbTextPropertyToTextList and + XwcTextPropertyToTextList return Success. + + To free the storage for the list and its contents returned by + XmbTextPropertyToTextList, use XFreeStringList. To free the + storage for the list and its contents returned by + XwcTextPropertyToTextList, use XwcFreeStringList. + + To free the in-memory data associated with the specified wide + character string list, use XwcFreeStringList. + + void XwcFreeStringList(wchar_t **list); + + list + + Specifies the list of strings to be freed. + + The XwcFreeStringList function frees memory allocated by + XwcTextPropertyToTextList. + + To obtain the default string for text conversion in the current + locale, use + + char *XDefaultString(void); + + The XDefaultString function returns the default string used by + Xlib for text conversion (for example, in + XmbTextPropertyToTextList). The default string is the string in + the current locale that is output when an unconvertible + character is found during text conversion. If the string + returned by XDefaultString is the empty string (""), no + character is output in the converted text. XDefaultString does + not return NULL. + + The string returned by XDefaultString is independent of the + default string for text drawing; see XCreateFontSet to obtain + the default string for an XFontSet. + + The behavior when an invalid codepoint is supplied to any Xlib + function is undefined. + + The returned string is null-terminated. It is owned by Xlib and + should not be modified or freed by the client. It may be freed + after the current locale is changed. Until freed, it will not + be modified by Xlib. + + To set the specified list of strings in the STRING encoding to + a XTextProperty structure, use XStringListToTextProperty. + + Status XStringListToTextProperty(char **list, int count, + XTextProperty *text_prop_return); + + list + + Specifies a list of null-terminated character strings. + + count + + Specifies the number of strings. + + text_prop_return + + Returns the XTextProperty structure. + + The XStringListToTextProperty function sets the specified + XTextProperty to be of type STRING (format 8) with a value + representing the concatenation of the specified list of + null-separated character strings. An extra null byte (which is + not included in the nitems member) is stored at the end of the + value field of text_prop_return. The strings are assumed + (without verification) to be in the STRING encoding. If + insufficient memory is available for the new value string, + XStringListToTextProperty does not set any fields in the + XTextProperty structure and returns a zero status. Otherwise, + it returns a nonzero status. To free the storage for the value + field, use XFree. + + To obtain a list of strings from a specified XTextProperty + structure in the STRING encoding, use + XTextPropertyToStringList. + + Status XTextPropertyToStringList(XTextProperty *text_prop, char + ***list_return, int *count_return); + + text_prop + + Specifies the XTextProperty structure to be used. + + list_return + + Returns a list of null-terminated character strings. + + count_return + + Returns the number of strings. + + The XTextPropertyToStringList function returns a list of + strings representing the null-separated elements of the + specified XTextProperty structure. The data in text_prop must + be of type STRING and format 8. Multiple elements of the + property (for example, the strings in a disjoint text + selection) are separated by NULL (encoding 0). The contents of + the property are not null-terminated. If insufficient memory is + available for the list and its elements, + XTextPropertyToStringList sets no return values and returns a + zero status. Otherwise, it returns a nonzero status. To free + the storage for the list and its contents, use XFreeStringList. + + To free the in-memory data associated with the specified string + list, use XFreeStringList. + + void XFreeStringList(char **list); + + list + + Specifies the list of strings to be freed. + + The XFreeStringList function releases memory allocated by + XmbTextPropertyToTextList and XTextPropertyToStringList and the + missing charset list allocated by XCreateFontSet. + +Setting and Reading Text Properties + + Xlib provides two functions that you can use to set and read + the text properties for a given window. You can use these + functions to set and read those properties of type TEXT + (WM_NAME, WM_ICON_NAME, WM_COMMAND, and WM_CLIENT_MACHINE). In + addition, Xlib provides separate convenience functions that you + can use to set each of these properties. For further + information about these convenience functions, see sections + 14.1.4, 14.1.5, 14.2.1, and 14.2.2, respectively. + + To set one of a window's text properties, use XSetTextProperty. + + void XSetTextProperty(Display *display, Window w, XTextProperty + *text_prop, Atom property); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + text_prop + + Specifies the XTextProperty structure to be used. + + property + + Specifies the property name. + + The XSetTextProperty function replaces the existing specified + property for the named window with the data, type, format, and + number of items determined by the value field, the encoding + field, the format field, and the nitems field, respectively, of + the specified XTextProperty structure. If the property does not + already exist, XSetTextProperty sets it for the specified + window. + + XSetTextProperty can generate BadAlloc, BadAtom, BadValue, and + BadWindow errors. + + To read one of a window's text properties, use + XGetTextProperty. + + Status XGetTextProperty(Display *display, Window w, + XTextProperty *text_prop_return, Atom property); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + text_prop_return + + Returns the XTextProperty structure. + + property + + Specifies the property name. + + The XGetTextProperty function reads the specified property from + the window and stores the data in the returned XTextProperty + structure. It stores the data in the value field, the type of + the data in the encoding field, the format of the data in the + format field, and the number of items of data in the nitems + field. An extra byte containing null (which is not included in + the nitems member) is stored at the end of the value field of + text_prop_return. The particular interpretation of the + property's encoding and data as text is left to the calling + application. If the specified property does not exist on the + window, XGetTextProperty sets the value field to NULL, the + encoding field to None, the format field to zero, and the + nitems field to zero. + + If it was able to read and store the data in the XTextProperty + structure, XGetTextProperty returns a nonzero status; + otherwise, it returns a zero status. + + XGetTextProperty can generate BadAtom and BadWindow errors. + +Setting and Reading the WM_NAME Property + + Xlib provides convenience functions that you can use to set and + read the WM_NAME property for a given window. + + To set a window's WM_NAME property with the supplied + convenience function, use XSetWMName. + + void XSetWMName(Display *display, Window w, XTextProperty + *text_prop); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + text_prop + + Specifies the XTextProperty structure to be used. + + The XSetWMName convenience function calls XSetTextProperty to + set the WM_NAME property. + + To read a window's WM_NAME property with the supplied + convenience function, use XGetWMName. + + Status XGetWMName(Display *display, Window w, XTextProperty + *text_prop_return); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + text_prop_return + + Returns the XTextProperty structure. + + The XGetWMName convenience function calls XGetTextProperty to + obtain the WM_NAME property. It returns a nonzero status on + success; otherwise, it returns a zero status. + + The following two functions have been superseded by XSetWMName + and XGetWMName, respectively. You can use these additional + convenience functions for window names that are encoded as + STRING properties. + + To assign a name to a window, use XStoreName. + + XStoreName(Display *display, Window w, char *window_name); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + window_name + + Specifies the window name, which should be a null-terminated + string. + + The XStoreName function assigns the name passed to window_name + to the specified window. A window manager can display the + window name in some prominent place, such as the title bar, to + allow users to identify windows easily. Some window managers + may display a window's name in the window's icon, although they + are encouraged to use the window's icon name if one is provided + by the application. If the string is not in the Host Portable + Character Encoding, the result is implementation-dependent. + + XStoreName can generate BadAlloc and BadWindow errors. + + To get the name of a window, use XFetchName. + + Status XFetchName(Display *display, Window w, char + **window_name_return); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + window_name_return + + Returns the window name, which is a null-terminated string. + + The XFetchName function returns the name of the specified + window. If it succeeds, it returns a nonzero status; otherwise, + no name has been set for the window, and it returns zero. If + the WM_NAME property has not been set for this window, + XFetchName sets window_name_return to NULL. If the data + returned by the server is in the Latin Portable Character + Encoding, then the returned string is in the Host Portable + Character Encoding. Otherwise, the result is + implementation-dependent. When finished with it, a client must + free the window name string using XFree. + + XFetchName can generate a BadWindow error. + +Setting and Reading the WM_ICON_NAME Property + + Xlib provides convenience functions that you can use to set and + read the WM_ICON_NAME property for a given window. + + To set a window's WM_ICON_NAME property, use XSetWMIconName. + + void XSetWMIconName(Display *display, Window w, XTextProperty + *text_prop); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + text_prop + + Specifies the XTextProperty structure to be used. + + The XSetWMIconName convenience function calls XSetTextProperty + to set the WM_ICON_NAME property. + + To read a window's WM_ICON_NAME property, use XGetWMIconName. + + Status XGetWMIconName(Display *display, Window w, XTextProperty + *text_prop_return); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + text_prop_return + + Returns the XTextProperty structure. + + The XGetWMIconName convenience function calls XGetTextProperty + to obtain the WM_ICON_NAME property. It returns a nonzero + status on success; otherwise, it returns a zero status. + + The next two functions have been superseded by XSetWMIconName + and XGetWMIconName, respectively. You can use these additional + convenience functions for window names that are encoded as + STRING properties. + + To set the name to be displayed in a window's icon, use + XSetIconName. + + XSetIconName(Display *display, Window w, char *icon_name); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + icon_name + + Specifies the icon name, which should be a null-terminated + string. + + If the string is not in the Host Portable Character Encoding, + the result is implementation-dependent. XSetIconName can + generate BadAlloc and BadWindow errors. + + To get the name a window wants displayed in its icon, use + XGetIconName. + + Status XGetIconName(Display *display, Window w, char + **icon_name_return); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + icon_name_return + + Returns the window's icon name, which is a null-terminated + string. + + The XGetIconName function returns the name to be displayed in + the specified window's icon. If it succeeds, it returns a + nonzero status; otherwise, if no icon name has been set for the + window, it returns zero. If you never assigned a name to the + window, XGetIconName sets icon_name_return to NULL. If the data + returned by the server is in the Latin Portable Character + Encoding, then the returned string is in the Host Portable + Character Encoding. Otherwise, the result is + implementation-dependent. When finished with it, a client must + free the icon name string using XFree. + + XGetIconName can generate a BadWindow error. + +Setting and Reading the WM_HINTS Property + + Xlib provides functions that you can use to set and read the + WM_HINTS property for a given window. These functions use the + flags and the XWMHints structure, as defined in the + header file. + + To allocate an XWMHints structure, use XAllocWMHints. + + XWMHints *XAllocWMHints(void); + + The XAllocWMHints function allocates and returns a pointer to + an XWMHints structure. Note that all fields in the XWMHints + structure are initially set to zero. If insufficient memory is + available, XAllocWMHints returns NULL. To free the memory + allocated to this structure, use XFree. + + The XWMHints structure contains: +/* Window manager hints mask bits */ + +#define InputHint (1L<<0) +#define StateHint (1L<<1) +#define IconPixmapHint (1L<<2) +#define IconWindowHint (1L<<3) +#define IconPositionHint (1L<<4) +#define IconMaskHint (1L<<5) +#define WindowGroupHint (1L<<6) +#define UrgencyHint (1L<<8) +#define AllHints (InputHint|StateHint|IconPixmapHin +t| + IconWIndowHint|IconPositionHint| + IconMaskHint|WindowGroupHint) + + +/* Values */ + +typedef struct { + long flags; /* marks which fields in this structure +are defined */ + Bool input; /* does this application rely on the win +dow manager to + get keyboard input? */ + int initial_state; /* see below */ + Pixmap icon_pixmap; /* pixmap to be used as icon */ + Window icon_window; /* window to be used as icon */ + int icon_x, icon_y; /* initial position of icon */ + Pixmap icon_mask; /* pixmap to be used as mask for icon_pi +xmap */ + XID window_group; /* id of related window group */ + /* this structure may be extended in the future */ +} XWMHints; + + The input member is used to communicate to the window manager + the input focus model used by the application. Applications + that expect input but never explicitly set focus to any of + their subwindows (that is, use the push model of focus + management), such as X Version 10 style applications that use + real-estate driven focus, should set this member to True. + Similarly, applications that set input focus to their + subwindows only when it is given to their top-level window by a + window manager should also set this member to True. + Applications that manage their own input focus by explicitly + setting focus to one of their subwindows whenever they want + keyboard input (that is, use the pull model of focus + management) should set this member to False. Applications that + never expect any keyboard input also should set this member to + False. + + Pull model window managers should make it possible for push + model applications to get input by setting input focus to the + top-level windows of applications whose input member is True. + Push model window managers should make sure that pull model + applications do not break them by resetting input focus to + PointerRoot when it is appropriate (for example, whenever an + application whose input member is False sets input focus to one + of its subwindows). + + The definitions for the initial_state flag are: +#define WithdrawnState 0 +#define NormalState 1 /* most applications start this way */ +#define IconicState 3 /* application wants to start as an icon + */ + + + The icon_mask specifies which pixels of the icon_pixmap should + be used as the icon. This allows for nonrectangular icons. Both + icon_pixmap and icon_mask must be bitmaps. The icon_window lets + an application provide a window for use as an icon for window + managers that support such use. The window_group lets you + specify that this window belongs to a group of other windows. + For example, if a single application manipulates multiple + top-level windows, this allows you to provide enough + information that a window manager can iconify all of the + windows rather than just the one window. + + The UrgencyHint flag, if set in the flags field, indicates that + the client deems the window contents to be urgent, requiring + the timely response of the user. The window manager will make + some effort to draw the user's attention to this window while + this flag is set. The client must provide some means by which + the user can cause the urgency flag to be cleared (either + mitigating the condition that made the window urgent or merely + shutting off the alarm) or the window to be withdrawn. + + To set a window's WM_HINTS property, use XSetWMHints. + + XSetWMHints(Display *display, Window w, XWMHints *wmhints); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + wmhints + + Specifies the XWMHints structure to be used. + + The XSetWMHints function sets the window manager hints that + include icon information and location, the initial state of the + window, and whether the application relies on the window + manager to get keyboard input. + + XSetWMHints can generate BadAlloc and BadWindow errors. + + To read a window's WM_HINTS property, use XGetWMHints. + + XWMHints *XGetWMHints(Display *display, Window w); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + The XGetWMHints function reads the window manager hints and + returns NULL if no WM_HINTS property was set on the window or + returns a pointer to an XWMHints structure if it succeeds. When + finished with the data, free the space used for it by calling + XFree. + + XGetWMHints can generate a BadWindow error. + +Setting and Reading the WM_NORMAL_HINTS Property + + Xlib provides functions that you can use to set or read the + WM_NORMAL_HINTS property for a given window. The functions use + the flags and the XSizeHints structure, as defined in the + header file. + + The size of the XSizeHints structure may grow in future + releases, as new components are added to support new ICCCM + features. Passing statically allocated instances of this + structure into Xlib may result in memory corruption when + running against a future release of the library. As such, it is + recommended that only dynamically allocated instances of the + structure be used. + + To allocate an XSizeHints structure, use XAllocSizeHints. + + XSizeHints *XAllocSizeHints(void); + + The XAllocSizeHints function allocates and returns a pointer to + an XSizeHints structure. Note that all fields in the XSizeHints + structure are initially set to zero. If insufficient memory is + available, XAllocSizeHints returns NULL. To free the memory + allocated to this structure, use XFree. + + The XSizeHints structure contains: +/* Size hints mask bits */ + +#define USPosition (1L<<0) /* user specified x,y */ +#define USSize (1L<<1) /* user specified width,he +ight */ +#define PPosition (1L<<2) /* program specified posis +tion */ +#define PSize (1L<<3) /* program specified size +*/ +#define PMinSize (1L<<4) /* program specified minim +um size */ +#define PMaxSize (1L<<5) /* program specified maxim +um size */ +#define PResizeInc (1L<<5) /* program specified resiz +e increments */ +#define PAspect (1L<<6) /* program specified min a +nd max aspect ratios */ +#define PBaseSize (1L<<8) +#define PWinGravity (1L<<9) +#define PAllHints (PPosition|Psize| + PMinSize|PMaxSize| + PResizeInc|PAspect) + + +/* Values */ + +typedef struct { + long flags; /* marks which fields in this structure +are defined */ + int x, y; /* Obsolete */ + int width, height; /* Obsolete */ + int min_width, min_height; + int max_width, max_height; + int width_inc, height_inc; + struct { + int x; /* numerator */ + int y; /* denominator */ + } min_aspect, max_aspect; + int base_width, base_height; + int win_gravity; + /* this structure may be extended in the future */ +} XSizeHints; + + The x, y, width, and height members are now obsolete and are + left solely for compatibility reasons. The min_width and + min_height members specify the minimum window size that still + allows the application to be useful. The max_width and + max_height members specify the maximum window size. The + width_inc and height_inc members define an arithmetic + progression of sizes (minimum to maximum) into which the window + prefers to be resized. The min_aspect and max_aspect members + are expressed as ratios of x and y, and they allow an + application to specify the range of aspect ratios it prefers. + The base_width and base_height members define the desired size + of the window. The window manager will interpret the position + of the window and its border width to position the point of the + outer rectangle of the overall window specified by the + win_gravity member. The outer rectangle of the window includes + any borders or decorations supplied by the window manager. In + other words, if the window manager decides to place the window + where the client asked, the position on the parent window's + border named by the win_gravity will be placed where the client + window would have been placed in the absence of a window + manager. + + Note that use of the PAllHints macro is highly discouraged. + + To set a window's WM_NORMAL_HINTS property, use + XSetWMNormalHints. + + void XSetWMNormalHints(Display *display, Window w, XSizeHints + *hints); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + hints + + Specifies the size hints for the window in its normal state. + + The XSetWMNormalHints function replaces the size hints for the + WM_NORMAL_HINTS property on the specified window. If the + property does not already exist, XSetWMNormalHints sets the + size hints for the WM_NORMAL_HINTS property on the specified + window. The property is stored with a type of WM_SIZE_HINTS and + a format of 32. + + XSetWMNormalHints can generate BadAlloc and BadWindow errors. + + To read a window's WM_NORMAL_HINTS property, use + XGetWMNormalHints. + + Status XGetWMNormalHints(Display *display, Window w, XSizeHints + *hints_return, long *supplied_return); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + hints_return + + Returns the size hints for the window in its normal state. + + supplied_return + + Returns the hints that were supplied by the user. + + The XGetWMNormalHints function returns the size hints stored in + the WM_NORMAL_HINTS property on the specified window. If the + property is of type WM_SIZE_HINTS, is of format 32, and is long + enough to contain either an old (pre-ICCCM) or new size hints + structure, XGetWMNormalHints sets the various fields of the + XSizeHints structure, sets the supplied_return argument to the + list of fields that were supplied by the user (whether or not + they contained defined values), and returns a nonzero status. + Otherwise, it returns a zero status. + + If XGetWMNormalHints returns successfully and a pre-ICCCM size + hints property is read, the supplied_return argument will + contain the following bits: + +(USPosition|USSize|PPosition|PSize|PMinSize| + PMaxSize|PResizeInc|PAspect) + + If the property is large enough to contain the base size and + window gravity fields as well, the supplied_return argument + will also contain the following bits: + +PBaseSize|PWinGravity + + XGetWMNormalHints can generate a BadWindow error. + + To set a window's WM_SIZE_HINTS property, use XSetWMSizeHints. + + void XSetWMSizeHints(Display *display, Window w, XSizeHints + *hints, Atom property); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + hints + + Specifies the XSizeHints structure to be used. + + property + + Specifies the property name. + + The XSetWMSizeHints function replaces the size hints for the + specified property on the named window. If the specified + property does not already exist, XSetWMSizeHints sets the size + hints for the specified property on the named window. The + property is stored with a type of WM_SIZE_HINTS and a format of + 32. To set a window's normal size hints, you can use the + XSetWMNormalHints function. + + XSetWMSizeHints can generate BadAlloc, BadAtom, and BadWindow + errors. + + To read a window's WM_SIZE_HINTS property, use XGetWMSizeHints. + + Status XGetWMSizeHints(Display *display, Window w, XSizeHints + *hints_return, long *supplied_return, Atom property); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + hints_return + + Returns the XSizeHints structure. + + supplied_return + + Returns the hints that were supplied by the user. + + property + + Specifies the property name. + + The XGetWMSizeHints function returns the size hints stored in + the specified property on the named window. If the property is + of type WM_SIZE_HINTS, is of format 32, and is long enough to + contain either an old (pre-ICCCM) or new size hints structure, + XGetWMSizeHints sets the various fields of the XSizeHints + structure, sets the supplied_return argument to the list of + fields that were supplied by the user (whether or not they + contained defined values), and returns a nonzero status. + Otherwise, it returns a zero status. To get a window's normal + size hints, you can use the XGetWMNormalHints function. + + If XGetWMSizeHints returns successfully and a pre-ICCCM size + hints property is read, the supplied_return argument will + contain the following bits: + +(USPosition|USSize|PPosition|PSize|PMinSize| + PMaxSize|PResizeInc|PAspect) + + If the property is large enough to contain the base size and + window gravity fields as well, the supplied_return argument + will also contain the following bits: + +PBaseSize|PWinGravity + + XGetWMSizeHints can generate BadAtom and BadWindow errors. + +Setting and Reading the WM_CLASS Property + + Xlib provides functions that you can use to set and get the + WM_CLASS property for a given window. These functions use the + XClassHint structure, which is defined in the + header file. + + To allocate an XClassHint structure, use XAllocClassHint. + + XClassHint *XAllocClassHint(void); + + The XAllocClassHint function allocates and returns a pointer to + an XClassHint structure. Note that the pointer fields in the + XClassHint structure are initially set to NULL. If insufficient + memory is available, XAllocClassHint returns NULL. To free the + memory allocated to this structure, use XFree. + + The XClassHint contains: + + + +typedef struct { + char *res_name; + char *res_class; +} XClassHint; + + The res_name member contains the application name, and the + res_class member contains the application class. Note that the + name set in this property may differ from the name set as + WM_NAME. That is, WM_NAME specifies what should be displayed in + the title bar and, therefore, can contain temporal information + (for example, the name of a file currently in an editor's + buffer). On the other hand, the name specified as part of + WM_CLASS is the formal name of the application that should be + used when retrieving the application's resources from the + resource database. + + To set a window's WM_CLASS property, use XSetClassHint. + + XSetClassHint(Display *display, Window w, XClassHint + *class_hints); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + class_hints + + Specifies the XClassHint structure that is to be used. + + The XSetClassHint function sets the class hint for the + specified window. If the strings are not in the Host Portable + Character Encoding, the result is implementation-dependent. + + XSetClassHint can generate BadAlloc and BadWindow errors. + + To read a window's WM_CLASS property, use XGetClassHint. + + Status XGetClassHint(Display *display, Window w, XClassHint + *class_hints_return); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + class_hints_return + + Returns the XClassHint structure. + + The XGetClassHint function returns the class hint of the + specified window to the members of the supplied structure. If + the data returned by the server is in the Latin Portable + Character Encoding, then the returned strings are in the Host + Portable Character Encoding. Otherwise, the result is + implementation-dependent. It returns a nonzero status on + success; otherwise, it returns a zero status. To free res_name + and res_class when finished with the strings, use XFree on each + individually. + + XGetClassHint can generate a BadWindow error. + +Setting and Reading the WM_TRANSIENT_FOR Property + + Xlib provides functions that you can use to set and read the + WM_TRANSIENT_FOR property for a given window. + + To set a window's WM_TRANSIENT_FOR property, use + XSetTransientForHint. + + XSetTransientForHint(Display *display, Window w, Window + prop_window); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + prop_window + + Specifies the window that the WM_TRANSIENT_FOR property is to + be set to. + + The XSetTransientForHint function sets the WM_TRANSIENT_FOR + property of the specified window to the specified prop_window. + + XSetTransientForHint can generate BadAlloc and BadWindow + errors. + + To read a window's WM_TRANSIENT_FOR property, use + XGetTransientForHint. + + Status XGetTransientForHint(Display *display, Window w, Window + *prop_window_return); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + prop_window_return + + Returns the WM_TRANSIENT_FOR property of the specified window. + + The XGetTransientForHint function returns the WM_TRANSIENT_FOR + property for the specified window. It returns a nonzero status + on success; otherwise, it returns a zero status. + + XGetTransientForHint can generate a BadWindow error. + +Setting and Reading the WM_PROTOCOLS Property + + Xlib provides functions that you can use to set and read the + WM_PROTOCOLS property for a given window. + + To set a window's WM_PROTOCOLS property, use XSetWMProtocols. + + Status XSetWMProtocols(Display *display, Window w, Atom + *protocols, int count); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + protocols + + Specifies the list of protocols. + + count + + Specifies the number of protocols in the list. + + The XSetWMProtocols function replaces the WM_PROTOCOLS property + on the specified window with the list of atoms specified by the + protocols argument. If the property does not already exist, + XSetWMProtocols sets the WM_PROTOCOLS property on the specified + window to the list of atoms specified by the protocols + argument. The property is stored with a type of ATOM and a + format of 32. If it cannot intern the WM_PROTOCOLS atom, + XSetWMProtocols returns a zero status. Otherwise, it returns a + nonzero status. + + XSetWMProtocols can generate BadAlloc and BadWindow errors. + + To read a window's WM_PROTOCOLS property, use XGetWMProtocols. + + Status XGetWMProtocols(Display *display, Window w, Atom + **protocols_return, int *count_return); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + protocols_return + + Returns the list of protocols. + + count_return + + Returns the number of protocols in the list. + + The XGetWMProtocols function returns the list of atoms stored + in the WM_PROTOCOLS property on the specified window. These + atoms describe window manager protocols in which the owner of + this window is willing to participate. If the property exists, + is of type ATOM, is of format 32, and the atom WM_PROTOCOLS can + be interned, XGetWMProtocols sets the protocols_return argument + to a list of atoms, sets the count_return argument to the + number of elements in the list, and returns a nonzero status. + Otherwise, it sets neither of the return arguments and returns + a zero status. To release the list of atoms, use XFree. + + XGetWMProtocols can generate a BadWindow error. + +Setting and Reading the WM_COLORMAP_WINDOWS Property + + Xlib provides functions that you can use to set and read the + WM_COLORMAP_WINDOWS property for a given window. + + To set a window's WM_COLORMAP_WINDOWS property, use + XSetWMColormapWindows. + + Status XSetWMColormapWindows(Display *display, Window w, Window + *colormap_windows, int count); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + colormap_windows + + Specifies the list of windows. + + count + + Specifies the number of windows in the list. + + The XSetWMColormapWindows function replaces the + WM_COLORMAP_WINDOWS property on the specified window with the + list of windows specified by the colormap_windows argument. If + the property does not already exist, XSetWMColormapWindows sets + the WM_COLORMAP_WINDOWS property on the specified window to the + list of windows specified by the colormap_windows argument. The + property is stored with a type of WINDOW and a format of 32. If + it cannot intern the WM_COLORMAP_WINDOWS atom, + XSetWMColormapWindows returns a zero status. Otherwise, it + returns a nonzero status. + + XSetWMColormapWindows can generate BadAlloc and BadWindow + errors. + + To read a window's WM_COLORMAP_WINDOWS property, use + XGetWMColormapWindows. + + Status XGetWMColormapWindows(Display *display, Window w, Window + **colormap_windows_return, int *count_return); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + colormap_windows_return + + Returns the list of windows. + + count_return + + Returns the number of windows in the list. + + The XGetWMColormapWindows function returns the list of window + identifiers stored in the WM_COLORMAP_WINDOWS property on the + specified window. These identifiers indicate the colormaps that + the window manager may need to install for this window. If the + property exists, is of type WINDOW, is of format 32, and the + atom WM_COLORMAP_WINDOWS can be interned, XGetWMColormapWindows + sets the windows_return argument to a list of window + identifiers, sets the count_return argument to the number of + elements in the list, and returns a nonzero status. Otherwise, + it sets neither of the return arguments and returns a zero + status. To release the list of window identifiers, use XFree. + + XGetWMColormapWindows can generate a BadWindow error. + +Setting and Reading the WM_ICON_SIZE Property + + Xlib provides functions that you can use to set and read the + WM_ICON_SIZE property for a given window. These functions use + the XIconSize structure, which is defined in the + header file. + + To allocate an XIconSize structure, use XAllocIconSize. + + XIconSize *XAllocIconSize(void); + + The XAllocIconSize function allocates and returns a pointer to + an XIconSize structure. Note that all fields in the XIconSize + structure are initially set to zero. If insufficient memory is + available, XAllocIconSize returns NULL. To free the memory + allocated to this structure, use XFree. + + The XIconSize structure contains: + + + +typedef struct { + int min_width, min_height; + int max_width, max_height; + int width_inc, height_inc; +} XIconSize; + + The width_inc and height_inc members define an arithmetic + progression of sizes (minimum to maximum) that represent the + supported icon sizes. + + To set a window's WM_ICON_SIZE property, use XSetIconSizes. + + XSetIconSizes(Display *display, Window w, XIconSize *size_list, + int count); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + size_list + + Specifies the size list. + + count + + Specifies the number of items in the size list. + + The XSetIconSizes function is used only by window managers to + set the supported icon sizes. + + XSetIconSizes can generate BadAlloc and BadWindow errors. + + To read a window's WM_ICON_SIZE property, use XGetIconSizes. + + Status XGetIconSizes(Display *display, Window w, XIconSize + **size_list_return, int *count_return); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + size_list_return + + Returns the size list. + + count_return + + Returns the number of items in the size list. + + The XGetIconSizes function returns zero if a window manager has + not set icon sizes; otherwise, it returns nonzero. + XGetIconSizes should be called by an application that wants to + find out what icon sizes would be most appreciated by the + window manager under which the application is running. The + application should then use XSetWMHints to supply the window + manager with an icon pixmap or window in one of the supported + sizes. To free the data allocated in size_list_return, use + XFree. + + XGetIconSizes can generate a BadWindow error. + +Using Window Manager Convenience Functions + + The XmbSetWMProperties function stores the standard set of + window manager properties, with text properties in standard + encodings for internationalized text communication. The + standard window manager properties for a given window are + WM_NAME, WM_ICON_NAME, WM_HINTS, WM_NORMAL_HINTS, WM_CLASS, + WM_COMMAND, WM_CLIENT_MACHINE, and WM_LOCALE_NAME. + + void XmbSetWMProperties(Display *display, Window w, char + *window_name, char *icon_name, char *argv[], int argc, + XSizeHints *normal_hints, XWMHints *wm_hints, XClassHint + *class_hints); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + window_name + + Specifies the window name, which should be a null-terminated + string. + + icon_name + + Specifies the icon name, which should be a null-terminated + string. + + argv + + Specifies the application's argument list. + + argc + + Specifies the number of arguments. + + hints + + Specifies the size hints for the window in its normal state. + + wm_hints + + Specifies the XWMHints structure to be used. + + class_hints + + Specifies the XClassHint structure to be used. + + The XmbSetWMProperties convenience function provides a simple + programming interface for setting those essential window + properties that are used for communicating with other clients + (particularly window and session managers). + + If the window_name argument is non-NULL, XmbSetWMProperties + sets the WM_NAME property. If the icon_name argument is + non-NULL, XmbSetWMProperties sets the WM_ICON_NAME property. + The window_name and icon_name arguments are null-terminated + strings in the encoding of the current locale. If the arguments + can be fully converted to the STRING encoding, the properties + are created with type ``STRING''; otherwise, the arguments are + converted to Compound Text, and the properties are created with + type ``COMPOUND_TEXT''. + + If the normal_hints argument is non-NULL, XmbSetWMProperties + calls XSetWMNormalHints, which sets the WM_NORMAL_HINTS + property (see section 14.1.7). If the wm_hints argument is + non-NULL, XmbSetWMProperties calls XSetWMHints, which sets the + WM_HINTS property (see section 14.1.6). + + If the argv argument is non-NULL, XmbSetWMProperties sets the + WM_COMMAND property from argv and argc. An argc of zero + indicates a zero-length command. + + The hostname of the machine is stored using XSetWMClientMachine + (see section 14.2.2). + + If the class_hints argument is non-NULL, XmbSetWMProperties + sets the WM_CLASS property. If the res_name member in the + XClassHint structure is set to the NULL pointer and the + RESOURCE_NAME environment variable is set, the value of the + environment variable is substituted for res_name. If the + res_name member is NULL, the environment variable is not set, + and argv and argv[0] are set, then the value of argv[0], + stripped of any directory prefixes, is substituted for + res_name. + + It is assumed that the supplied class_hints.res_name and argv, + the RESOURCE_NAME environment variable, and the hostname of the + machine are in the encoding of the locale announced for the + LC_CTYPE category (on POSIX-compliant systems, the LC_CTYPE, + else LANG environment variable). The corresponding WM_CLASS, + WM_COMMAND, and WM_CLIENT_MACHINE properties are typed + according to the local host locale announcer. No encoding + conversion is performed prior to storage in the properties. + + For clients that need to process the property text in a locale, + XmbSetWMProperties sets the WM_LOCALE_NAME property to be the + name of the current locale. The name is assumed to be in the + Host Portable Character Encoding and is converted to STRING for + storage in the property. + + XmbSetWMProperties can generate BadAlloc and BadWindow errors. + + To set a window's standard window manager properties with + strings in client-specified encodings, use XSetWMProperties. + The standard window manager properties for a given window are + WM_NAME, WM_ICON_NAME, WM_HINTS, WM_NORMAL_HINTS, WM_CLASS, + WM_COMMAND, and WM_CLIENT_MACHINE. + + void XSetWMProperties(Display *display, Window w, XTextProperty + *window_name, XTextProperty *icon_name, char **argv, int argc, + XSizeHints *normal_hints, XWMHints *wm_hints, XClassHint + *class_hints); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + window_name + + Specifies the window name, which should be a null-terminated + string. + + icon_name + + Specifies the icon name, which should be a null-terminated + string. + + argv + + Specifies the application's argument list. + + argc + + Specifies the number of arguments. + + normal_hints + + Specifies the size hints for the window in its normal state. + + wm_hints + + Specifies the XWMHints structure to be used. + + class_hints + + Specifies the XClassHint structure to be used. + + The XSetWMProperties convenience function provides a single + programming interface for setting those essential window + properties that are used for communicating with other clients + (particularly window and session managers). + + If the window_name argument is non-NULL, XSetWMProperties calls + XSetWMName, which, in turn, sets the WM_NAME property (see + section 14.1.4). If the icon_name argument is non-NULL, + XSetWMProperties calls XSetWMIconName, which sets the + WM_ICON_NAME property (see section 14.1.5). If the argv + argument is non-NULL, XSetWMProperties calls XSetCommand, which + sets the WM_COMMAND property (see section 14.2.1). Note that an + argc of zero is allowed to indicate a zero-length command. Note + also that the hostname of this machine is stored using + XSetWMClientMachine (see section 14.2.2). + + If the normal_hints argument is non-NULL, XSetWMProperties + calls XSetWMNormalHints, which sets the WM_NORMAL_HINTS + property (see section 14.1.7). If the wm_hints argument is + non-NULL, XSetWMProperties calls XSetWMHints, which sets the + WM_HINTS property (see section 14.1.6). + + If the class_hints argument is non-NULL, XSetWMProperties calls + XSetClassHint, which sets the WM_CLASS property (see section + 14.1.8). If the res_name member in the XClassHint structure is + set to the NULL pointer and the RESOURCE_NAME environment + variable is set, then the value of the environment variable is + substituted for res_name. If the res_name member is NULL, the + environment variable is not set, and argv and argv[0] are set, + then the value of argv[0], stripped of any directory prefixes, + is substituted for res_name. + + XSetWMProperties can generate BadAlloc and BadWindow errors. + +Client to Session Manager Communication + + This section discusses how to: + * Set and read the WM_COMMAND property + * Set and read the WM_CLIENT_MACHINE property + +Setting and Reading the WM_COMMAND Property + + Xlib provides functions that you can use to set and read the + WM_COMMAND property for a given window. + + To set a window's WM_COMMAND property, use XSetCommand. + + XSetCommand(Display *display, Window w, char **argv, int argc); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + argv + + Specifies the application's argument list. + + argc + + Specifies the number of arguments. + + The XSetCommand function sets the command and arguments used to + invoke the application. (Typically, argv is the argv array of + your main program.) If the strings are not in the Host Portable + Character Encoding, the result is implementation-dependent. + + XSetCommand can generate BadAlloc and BadWindow errors. + + To read a window's WM_COMMAND property, use XGetCommand. + + Status XGetCommand(Display *display, Window w, char + ***argv_return, int *argc_return); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + argv_return + + Returns the application's argument list. + + argc_return + + Returns the number of arguments returned. + + The XGetCommand function reads the WM_COMMAND property from the + specified window and returns a string list. If the WM_COMMAND + property exists, it is of type STRING and format 8. If + sufficient memory can be allocated to contain the string list, + XGetCommand fills in the argv_return and argc_return arguments + and returns a nonzero status. Otherwise, it returns a zero + status. If the data returned by the server is in the Latin + Portable Character Encoding, then the returned strings are in + the Host Portable Character Encoding. Otherwise, the result is + implementation-dependent. To free the memory allocated to the + string list, use XFreeStringList. + +Setting and Reading the WM_CLIENT_MACHINE Property + + Xlib provides functions that you can use to set and read the + WM_CLIENT_MACHINE property for a given window. + + To set a window's WM_CLIENT_MACHINE property, use + XSetWMClientMachine. + + void XSetWMClientMachine(Display *display, Window w, + XTextProperty *text_prop); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + text_prop + + Specifies the XTextProperty structure to be used. + + The XSetWMClientMachine convenience function calls + XSetTextProperty to set the WM_CLIENT_MACHINE property. + + To read a window's WM_CLIENT_MACHINE property, use + XGetWMClientMachine. + + Status XGetWMClientMachine(Display *display, Window w, + XTextProperty *text_prop_return); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + text_prop_return + + Returns the XTextProperty structure. + + The XGetWMClientMachine convenience function performs an + XGetTextProperty on the WM_CLIENT_MACHINE property. It returns + a nonzero status on success; otherwise, it returns a zero + status. + +Standard Colormaps + + Applications with color palettes, smooth-shaded drawings, or + digitized images demand large numbers of colors. In addition, + these applications often require an efficient mapping from + color triples to pixel values that display the appropriate + colors. + + As an example, consider a three-dimensional display program + that wants to draw a smoothly shaded sphere. At each pixel in + the image of the sphere, the program computes the intensity and + color of light reflected back to the viewer. The result of each + computation is a triple of red, green, and blue (RGB) + coefficients in the range 0.0 to 1.0. To draw the sphere, the + program needs a colormap that provides a large range of + uniformly distributed colors. The colormap should be arranged + so that the program can convert its RGB triples into pixel + values very quickly, because drawing the entire sphere requires + many such conversions. + + On many current workstations, the display is limited to 256 or + fewer colors. Applications must allocate colors carefully, not + only to make sure they cover the entire range they need but + also to make use of as many of the available colors as + possible. On a typical X display, many applications are active + at once. Most workstations have only one hardware look-up table + for colors, so only one application colormap can be installed + at a given time. The application using the installed colormap + is displayed correctly, and the other applications go + technicolor and are displayed with false colors. + + As another example, consider a user who is running an image + processing program to display earth-resources data. The image + processing program needs a colormap set up with 8 reds, 8 + greens, and 4 blues, for a total of 256 colors. Because some + colors are already in use in the default colormap, the image + processing program allocates and installs a new colormap. + + The user decides to alter some of the colors in the image by + invoking a color palette program to mix and choose colors. The + color palette program also needs a colormap with eight reds, + eight greens, and four blues, so just like the image processing + program, it must allocate and install a new colormap. + + Because only one colormap can be installed at a time, the color + palette may be displayed incorrectly whenever the image + processing program is active. Conversely, whenever the palette + program is active, the image may be displayed incorrectly. The + user can never match or compare colors in the palette and + image. Contention for colormap resources can be reduced if + applications with similar color needs share colormaps. + + The image processing program and the color palette program + could share the same colormap if there existed a convention + that described how the colormap was set up. Whenever either + program was active, both would be displayed correctly. + + The standard colormap properties define a set of commonly used + colormaps. Applications that share these colormaps and + conventions display true colors more often and provide a better + interface to the user. + + Standard colormaps allow applications to share commonly used + color resources. This allows many applications to be displayed + in true colors simultaneously, even when each application needs + an entirely filled colormap. + + Several standard colormaps are described in this section. + Usually, a window manager creates these colormaps. Applications + should use the standard colormaps if they already exist. + + To allocate an XStandardColormap structure, use + XAllocStandardColormap. + + XStandardColormap *XAllocStandardColormap(void); + + The XAllocStandardColormap function allocates and returns a + pointer to an XStandardColormap structure. Note that all fields + in the XStandardColormap structure are initially set to zero. + If insufficient memory is available, XAllocStandardColormap + returns NULL. To free the memory allocated to this structure, + use XFree. + + The XStandardColormap structure contains: +/* Hints */ + +#define ReeaseByFreeingColormap ((XID)1L) + +/* Values */ + +typedef struct { + Colormap colormap; + unsigned long red_max; + unsigned long red_mult; + unsigned long green_max; + unsigned long green_mult; + unsigned long blue_max; + unsigned long blue_mult; + unsigned long base_pixel; + VisualID visualid; + XID killid; +} XStandardColormap; + + The colormap member is the colormap created by the + XCreateColormap function. The red_max, green_max, and blue_max + members give the maximum red, green, and blue values, + respectively. Each color coefficient ranges from zero to its + max, inclusive. For example, a common colormap allocation is + 3/3/2 (3 planes for red, 3 planes for green, and 2 planes for + blue). This colormap would have red_max = 7, green_max = 7, and + blue_max = 3. An alternate allocation that uses only 216 colors + is red_max = 5, green_max = 5, and blue_max = 5. + + The red_mult, green_mult, and blue_mult members give the scale + factors used to compose a full pixel value. (See the discussion + of the base_pixel members for further information.) For a 3/3/2 + allocation, red_mult might be 32, green_mult might be 4, and + blue_mult might be 1. For a 6-colors-each allocation, red_mult + might be 36, green_mult might be 6, and blue_mult might be 1. + + The base_pixel member gives the base pixel value used to + compose a full pixel value. Usually, the base_pixel is obtained + from a call to the XAllocColorPlanes function. Given integer + red, green, and blue coefficients in their appropriate ranges, + one then can compute a corresponding pixel value by using the + following expression: + + + +(r * red_mult + g * green_mult + b * blue_mult + base_pixel) & 0xFFFFFFF +F + + For GrayScale colormaps, only the colormap, red_max, red_mult, + and base_pixel members are defined. The other members are + ignored. To compute a GrayScale pixel value, use the following + expression: + + + +(gray * red_mult + base_pixel) & 0xFFFFFFFF + + Negative multipliers can be represented by converting the 2's + complement representation of the multiplier into an unsigned + long and storing the result in the appropriate _mult field. The + step of masking by 0xFFFFFFFF effectively converts the + resulting positive multiplier into a negative one. The masking + step will take place automatically on many machine + architectures, depending on the size of the integer type used + to do the computation. + + The visualid member gives the ID number of the visual from + which the colormap was created. The killid member gives a + resource ID that indicates whether the cells held by this + standard colormap are to be released by freeing the colormap ID + or by calling the XKillClient function on the indicated + resource. (Note that this method is necessary for allocating + out of an existing colormap.) + + The properties containing the XStandardColormap information + have the type RGB_COLOR_MAP. + + The remainder of this section discusses standard colormap + properties and atoms as well as how to manipulate standard + colormaps. + +Standard Colormap Properties and Atoms + + Several standard colormaps are available. Each standard + colormap is defined by a property, and each such property is + identified by an atom. The following list names the atoms and + describes the colormap associated with each one. The + header file contains the definitions for each of + the following atoms, which are prefixed with XA_. + + RGB_DEFAULT_MAP + + This atom names a property. The value of the property is an + array of XStandardColormap structures. Each entry in the array + describes an RGB subset of the default color map for the Visual + specified by visual_id. + + Some applications only need a few RGB colors and may be able to + allocate them from the system default colormap. This is the + ideal situation because the fewer colormaps that are active in + the system the more applications are displayed with correct + colors at all times. + + A typical allocation for the RGB_DEFAULT_MAP on 8-plane + displays is 6 reds, 6 greens, and 6 blues. This gives 216 + uniformly distributed colors (6 intensities of 36 different + hues) and still leaves 40 elements of a 256-element colormap + available for special-purpose colors for text, borders, and so + on. + + RGB_BEST_MAP + + This atom names a property. The value of the property is an + XStandardColormap. + + The property defines the best RGB colormap available on the + screen. (Of course, this is a subjective evaluation.) Many + image processing and three-dimensional applications need to use + all available colormap cells and to distribute as many + perceptually distinct colors as possible over those cells. This + implies that there may be more green values available than red, + as well as more green or red than blue. + + For an 8-plane PseudoColor visual, RGB_BEST_MAP is likely to be + a 3/3/2 allocation. For a 24-plane DirectColor visual, + RGB_BEST_MAP is normally an 8/8/8 allocation. + + RGB_RED_MAP,RGB_GREEN_MAP,RGB_BLUE_MAP + + These atoms name properties. The value of each property is an + XStandardColormap. + + The properties define all-red, all-green, and all-blue + colormaps, respectively. These maps are used by applications + that want to make color-separated images. For example, a user + might generate a full-color image on an 8-plane display both by + rendering an image three times (once with high color resolution + in red, once with green, and once with blue) and by multiply + exposing a single frame in a camera. + + RGB_GRAY_MAP + + This atom names a property. The value of the property is an + XStandardColormap. + + The property describes the best GrayScale colormap available on + the screen. As previously mentioned, only the colormap, + red_max, red_mult, and base_pixel members of the + XStandardColormap structure are used for GrayScale colormaps. + +Setting and Obtaining Standard Colormaps + + Xlib provides functions that you can use to set and obtain an + XStandardColormap structure. + + To set an XStandardColormap structure, use XSetRGBColormaps. + + void XSetRGBColormaps(Display *display, Window w, + XStandardColormap *std_colormap, int count, Atom property); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + std_colormap + + Specifies the XStandardColormap structure to be used. + + count + + Specifies the number of colormaps. + + property + + Specifies the property name. + + The XSetRGBColormaps function replaces the RGB colormap + definition in the specified property on the named window. If + the property does not already exist, XSetRGBColormaps sets the + RGB colormap definition in the specified property on the named + window. The property is stored with a type of RGB_COLOR_MAP and + a format of 32. Note that it is the caller's responsibility to + honor the ICCCM restriction that only RGB_DEFAULT_MAP contain + more than one definition. + + The XSetRGBColormaps function usually is only used by window or + session managers. To create a standard colormap, follow this + procedure: + * Open a new connection to the same server. + * Grab the server. + * See if the property is on the property list of the root + window for the screen. + * If the desired property is not present: + * Create a colormap (unless you are using the default + colormap of the screen). + * Determine the color characteristics of the visual. + * Allocate cells in the colormap (or create it with + AllocAll). + * Call XStoreColors to store appropriate color values in the + colormap. + * Fill in the descriptive members in the XStandardColormap + structure. + * Attach the property to the root window. + * Use XSetCloseDownMode to make the resource permanent. + * Ungrab the server. + + XSetRGBColormaps can generate BadAlloc, BadAtom, and BadWindow + errors. + + To obtain the XStandardColormap structure associated with the + specified property, use XGetRGBColormaps. + + Status XGetRGBColormaps(Display *display, Window w, + XStandardColormap **std_colormap_return, int *count_return, + Atom property); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + std_colormap_return + + Returns the XStandardColormap structure. + + count_return + + Returns the number of colormaps. + + property + + Specifies the property name. + + The XGetRGBColormaps function returns the RGB colormap + definitions stored in the specified property on the named + window. If the property exists, is of type RGB_COLOR_MAP, is of + format 32, and is long enough to contain a colormap definition, + XGetRGBColormaps allocates and fills in space for the returned + colormaps and returns a nonzero status. If the visualid is not + present, XGetRGBColormaps assumes the default visual for the + screen on which the window is located; if the killid is not + present, None is assumed, which indicates that the resources + cannot be released. Otherwise, none of the fields are set, and + XGetRGBColormaps returns a zero status. Note that it is the + caller's responsibility to honor the ICCCM restriction that + only RGB_DEFAULT_MAP contain more than one definition. + + XGetRGBColormaps can generate BadAtom and BadWindow errors. + +Chapter 15. Resource Manager Functions + + Table of Contents + + Resource File Syntax + Resource Manager Matching Rules + Quarks + Creating and Storing Databases + Merging Resource Databases + Looking Up Resources + Storing into a Resource Database + Enumerating Database Entries + Parsing Command Line Options + + A program often needs a variety of options in the X environment + (for example, fonts, colors, icons, and cursors). Specifying + all of these options on the command line is awkward because + users may want to customize many aspects of the program and + need a convenient way to establish these customizations as the + default settings. The resource manager is provided for this + purpose. Resource specifications are usually stored in + human-readable files and in server properties. + + The resource manager is a database manager with a twist. In + most database systems, you perform a query using an imprecise + specification, and you get back a set of records. The resource + manager, however, allows you to specify a large set of values + with an imprecise specification, to query the database with a + precise specification, and to get back only a single value. + This should be used by applications that need to know what the + user prefers for colors, fonts, and other resources. It is this + use as a database for dealing with X resources that inspired + the name "Resource Manager," although the resource manager can + be and is used in other ways. + + For example, a user of your application may want to specify + that all windows should have a blue background but that all + mail-reading windows should have a red background. With + well-engineered and coordinated applications, a user can define + this information using only two lines of specifications. + + As an example of how the resource manager works, consider a + mail-reading application called xmh. Assume that it is designed + so that it uses a complex window hierarchy all the way down to + individual command buttons, which may be actual small + subwindows in some toolkits. These are often called objects or + widgets. In such toolkit systems, each user interface object + can be composed of other objects and can be assigned a name and + a class. Fully qualified names or classes can have arbitrary + numbers of component names, but a fully qualified name always + has the same number of component names as a fully qualified + class. This generally reflects the structure of the application + as composed of these objects, starting with the application + itself. + + For example, the xmh mail program has a name "xmh" and is one + of a class of "Mail" programs. By convention, the first + character of class components is capitalized, and the first + letter of name components is in lowercase. Each name and class + finally has an attribute (for example, "foreground" or "font"). + If each window is properly assigned a name and class, it is + easy for the user to specify attributes of any portion of the + application. + + At the top level, the application might consist of a paned + window (that is, a window divided into several sections) named + "toc". One pane of the paned window is a button box window + named "buttons" and is filled with command buttons. One of + these command buttons is used to incorporate new mail and has + the name "incorporate". This window has a fully qualified name, + "xmh.toc.buttons.incorporate", and a fully qualified class, + "Xmh.Paned.Box.Command". Its fully qualified name is the name + of its parent, "xmh.toc.buttons", followed by its name, + "incorporate". Its class is the class of its parent, + "Xmh.Paned.Box", followed by its particular class, "Command". + The fully qualified name of a resource is the attribute's name + appended to the object's fully qualified name, and the fully + qualified class is its class appended to the object's class. + + The incorporate button might need the following resources: + Title string, Font, Foreground color for its inactive state, + Background color for its inactive state, Foreground color for + its active state, and Background color for its active state. + Each resource is considered to be an attribute of the button + and, as such, has a name and a class. For example, the + foreground color for the button in its active state might be + named "activeForeground", and its class might be "Foreground". + + When an application looks up a resource (for example, a color), + it passes the complete name and complete class of the resource + to a look-up routine. The resource manager compares this + complete specification against the incomplete specifications of + entries in the resource database, finds the best match, and + returns the corresponding value for that entry. + + The definitions for the resource manager are contained in + . + +Resource File Syntax + + The syntax of a resource file is a sequence of resource lines + terminated by newline characters or the end of the file. The + syntax of an individual resource line is: + + + +ResourceLine = Comment | IncludeFile | ResourceSpec | +Comment = "!" {} +IncludeFile = "#" WhiteSpace "include" WhiteSpace FileName White +Space +FileName = +ResourceSpec = WhiteSpace ResourceName WhiteSpace ":" WhiteSpace + Value +ResourceName = [Binding] {Component Binding} ComponentName +Binding = "." | "*" +WhiteSpace = { | } +Component = "?" | ComponentName +ComponentName = NameChar {NameChar} +NameChar = "a"-"z" | "A"-"Z" | "0"-"9" | "_" | "-" +Value = {} + + Elements separated by vertical bar (|) are alternatives. Curly + braces ({......}) indicate zero or more repetitions of the + enclosed elements. Square brackets ([......]) indicate that the + enclosed element is optional. Quotes ("......") are used around + literal characters. + + IncludeFile lines are interpreted by replacing the line with + the contents of the specified file. The word "include" must be + in lowercase. The file name is interpreted relative to the + directory of the file in which the line occurs (for example, if + the file name contains no directory or contains a relative + directory specification). + + If a ResourceName contains a contiguous sequence of two or more + Binding characters, the sequence will be replaced with a single + ".." character if the sequence contains only ".." characters; + otherwise, the sequence will be replaced with a single "*" + character. + + A resource database never contains more than one entry for a + given ResourceName. If a resource file contains multiple lines + with the same ResourceName, the last line in the file is used. + + Any white space characters before or after the name or colon in + a ResourceSpec are ignored. To allow a Value to begin with + white space, the two-character sequence "\\space" (backslash + followed by space) is recognized and replaced by a space + character, and the two-character sequence "\\tab" (backslash + followed by horizontal tab) is recognized and replaced by a + horizontal tab character. To allow a Value to contain embedded + newline characters, the two-character sequence "\\n" is + recognized and replaced by a newline character. To allow a + Value to be broken across multiple lines in a text file, the + two-character sequence "\\newline" (backslash followed by + newline) is recognized and removed from the value. To allow a + Value to contain arbitrary character codes, the four-character + sequence "\\nnn", where each n is a digit character in the + range of "0"-"7", is recognized and replaced with a single byte + that contains the octal value specified by the sequence. + Finally, the two-character sequence "\newline" is recognized + and replaced with a single backslash. + + As an example of these sequences, the following resource line + contains a value consisting of four characters: a backslash, a + null, a "z", and a newline: +magic.values: \\000\ +z\n + +Resource Manager Matching Rules + + The algorithm for determining which resource database entry + matches a given query is the heart of the resource manager. All + queries must fully specify the name and class of the desired + resource (use of the characters "*" and "?" is not permitted). + The library supports up to 100 components in a full name or + class. Resources are stored in the database with only partially + specified names and classes, using pattern matching constructs. + An asterisk (*) is a loose binding and is used to represent any + number of intervening components, including none. A period (.) + is a tight binding and is used to separate immediately adjacent + components. A question mark (?) is used to match any single + component name or class. A database entry cannot end in a loose + binding; the final component (which cannot be the character + "?") must be specified. The lookup algorithm searches the + database for the entry that most closely matches (is most + specific for) the full name and class being queried. When more + than one database entry matches the full name and class, + precedence rules are used to select just one. + + The full name and class are scanned from left to right (from + highest level in the hierarchy to lowest), one component at a + time. At each level, the corresponding component and/or binding + of each matching entry is determined, and these matching + components and bindings are compared according to precedence + rules. Each of the rules is applied at each level before moving + to the next level, until a rule selects a single entry over all + others. The rules, in order of precedence, are: + * An entry that contains a matching component (whether name, + class, or the character "?") takes precedence over entries + that elide the level (that is, entries that match the level + in a loose binding). + * An entry with a matching name takes precedence over both + entries with a matching class and entries that match using + the character "?". An entry with a matching class takes + precedence over entries that match using the character "?". + * An entry preceded by a tight binding takes precedence over + entries preceded by a loose binding. + + To illustrate these rules, consider the following resource + database entries: + + +xmh*Paned*activeForeground: red (entry A) +*incorporate.Foreground: blue (entry B) +xmh.toc*Command*activeForeground: green (entry C) +xmh.toc*?.Foreground: white (entry D) +xmh.toc*Command.activeForeground: black (entry E) + + Consider a query for the resource: + + + +xmh.toc.messagefunctions.incorporate.activeForeground (name) +Xmh.Paned.Box.Command.Foreground (class) + + At the first level (xmh, Xmh), rule 1 eliminates entry B. At + the second level (toc, Paned), rule 2 eliminates entry A. At + the third level (messagefunctions, Box), no entries are + eliminated. At the fourth level (incorporate, Command), rule 2 + eliminates entry D. At the fifth level (activeForeground, + Foreground), rule 3 eliminates entry C. + +Quarks + + Most uses of the resource manager involve defining names, + classes, and representation types as string constants. However, + always referring to strings in the resource manager can be + slow, because it is so heavily used in some toolkits. To solve + this problem, a shorthand for a string is used in place of the + string in many of the resource manager functions. Simple + comparisons can be performed rather than string comparisons. + The shorthand name for a string is called a quark and is the + type XrmQuark. On some occasions, you may want to allocate a + quark that has no string equivalent. + + A quark is to a string what an atom is to a string in the + server, but its use is entirely local to your application. + + To allocate a new quark, use XrmUniqueQuark. + + XrmQuark XrmUniqueQuark(void); + + The XrmUniqueQuark function allocates a quark that is + guaranteed not to represent any string that is known to the + resource manager. + + Each name, class, and representation type is typedef'd as an + XrmQuark. + +typedef int XrmQuark, *XrmQuarkList; +typedef XrmQuark XrmName; +typedef XrmQuark XrmClass; +typedef XrmQuark XrmRepresentation; +#define NULLQUARK ((XrmQuark) 0) + + Lists are represented as null-terminated arrays of quarks. The + size of the array must be large enough for the number of + components used. + +typedef XrmQuarkList XrmNameList; +typedef XrmQuarkList XrmClassList; + + To convert a string to a quark, use XrmStringToQuark or + XrmPermStringToQuark. +#define XrmStringToName(string) XrmStringToQuark(string) +#define XrmStringToClass(string) XrmStringToQuark(string) +#define XrmStringToRepresentation(string) XrmStringToQuark(string) + + XrmQuark XrmStringToQuark(char *string); + + string + + Specifies the string for which a quark(Ql is to be allocated. + + These functions can be used to convert from string to quark + representation. If the string is not in the Host Portable + Character Encoding, the conversion is implementation-dependent. + The string argument to XrmStringToQuark need not be permanently + allocated storage. XrmPermStringToQuark is just like + XrmStringToQuark, except that Xlib is permitted to assume the + string argument is permanently allocated, and, hence, that it + can be used as the value to be returned by XrmQuarkToString. + + For any given quark, if XrmStringToQuark returns a non-NULL + value, all future calls will return the same value (identical + address). + + To convert a quark to a string, use XrmQuarkToString. +#define XrmNameToString(name) XrmQuarkToString(name) +#define XrmClassToString(class) XrmQuarkToString(name) +#define XrmRepresentationToString(type) XrmQuarkToString(type) + + char *XrmQuarkToString(XrmQuark quark); + + quark + + Specifies the quark for which the equivalent string is desired. + + These functions can be used to convert from quark + representation to string. The string pointed to by the return + value must not be modified or freed. The returned string is + byte-for-byte equal to the original string passed to one of the + string-to-quark routines. If no string exists for that quark, + XrmQuarkToString returns NULL. For any given quark, if + XrmQuarkToString returns a non-NULL value, all future calls + will return the same value (identical address). + + To convert a string with one or more components to a quark + list, use XrmStringToQuarkList. +#define XrmStringToNameList(str,name) XrmStringToQuarkList((str), (name +)) +#define XrmStringToClassList(str,class) XrmStringToQuarkList((str), (cl +ass)) + + void XrmStringToQuarkList(char *string, XrmQuarkList + quarks_return); + + string + + Specifies the string for which a quark list is to be allocated. + + quarks_return + + Returns the list of quarks. The caller must allocate sufficient + space for the quarks list before calling XrmStringToQuarkList. + + The XrmStringToQuarkList function converts the null-terminated + string (generally a fully qualified name) to a list of quarks. + Note that the string must be in the valid ResourceName format + (see section 15.1). If the string is not in the Host Portable + Character Encoding, the conversion is implementation-dependent. + + A binding list is a list of type XrmBindingList and indicates + if components of name or class lists are bound tightly or + loosely (that is, if wildcarding of intermediate components is + specified). + +typedef enum {XrmBindTightly, XrmBindLoosely} XrmBinding, *XrmBindingLis +t; + + XrmBindTightly indicates that a period separates the + components, and XrmBindLoosely indicates that an asterisk + separates the components. + + To convert a string with one or more components to a binding + list and a quark list, use XrmStringToBindingQuarkList. + + XrmStringToBindingQuarkList(char *string, XrmBindingList + bindings_return, XrmQuarkList quarks_return); + + string + + Specifies the string for which a quark list is to be allocated. + + bindings_return + + Returns the binding list. The caller must allocate sufficient + space for the binding list before calling + XrmStringToBindingQuarkList. + + quarks_return + + Returns the list of quarks. The caller must allocate sufficient + space for the quarks list before calling + XrmStringToBindingQuarkList. + + Component names in the list are separated by a period or an + asterisk character. The string must be in the format of a valid + ResourceName (see section 15.1). If the string does not start + with a period or an asterisk, a tight binding is assumed. For + example, the string ``*a.b*c'' becomes: + + + +quarks: a b c +bindings: loose tight loose + +Creating and Storing Databases + + A resource database is an opaque type, XrmDatabase. Each + database value is stored in an XrmValue structure. This + structure consists of a size, an address, and a representation + type. The size is specified in bytes. The representation type + is a way for you to store data tagged by some + application-defined type (for example, the strings ``font'' or + ``color''). It has nothing to do with the C data type or with + its class. The XrmValue structure is defined as: + + + +typedef struct { + unsigned int size; + XPointer addr; +} XrmValue, *XrmValuePtr; + + To initialize the resource manager, use XrmInitialize. + + void XrmInitialize(void XrmInitialize(\|)); + + To retrieve a database from disk, use XrmGetFileDatabase. + + XrmDatabase XrmGetFileDatabase(char *filename); + + filename + + Specifies the resource database file name. + + The XrmGetFileDatabase function opens the specified file, + creates a new resource database, and loads it with the + specifications read in from the specified file. The specified + file should contain a sequence of entries in valid ResourceLine + format (see section 15.1); the database that results from + reading a file with incorrect syntax is + implementation-dependent. The file is parsed in the current + locale, and the database is created in the current locale. If + it cannot open the specified file, XrmGetFileDatabase returns + NULL. + + To store a copy of a database to disk, use XrmPutFileDatabase. + + void XrmPutFileDatabase(XrmDatabase database, char *stored_db); + + database + + Specifies the database that is to be used. + + stored_db + + Specifies the file name for the stored database. + + The XrmPutFileDatabase function stores a copy of the specified + database in the specified file. Text is written to the file as + a sequence of entries in valid ResourceLine format (see section + 15.1). The file is written in the locale of the database. + Entries containing resource names that are not in the Host + Portable Character Encoding or containing values that are not + in the encoding of the database locale, are written in an + implementation-dependent manner. The order in which entries are + written is implementation-dependent. Entries with + representation types other than ``String'' are ignored. + + To obtain a pointer to the screen-independent resources of a + display, use XResourceManagerString. + + char *XResourceManagerString(Display *display); + + display + + Specifies the connection to the X server. + + The XResourceManagerString function returns the + RESOURCE_MANAGER property from the server's root window of + screen zero, which was returned when the connection was opened + using XOpenDisplay. The property is converted from type STRING + to the current locale. The conversion is identical to that + produced by XmbTextPropertyToTextList for a single element + STRING property. The returned string is owned by Xlib and + should not be freed by the client. The property value must be + in a format that is acceptable to XrmGetStringDatabase. If no + property exists, NULL is returned. + + To obtain a pointer to the screen-specific resources of a + screen, use XScreenResourceString. + + char *XScreenResourceString(Screen *screen); + + screen + + Specifies the screen. + + The XScreenResourceString function returns the SCREEN_RESOURCES + property from the root window of the specified screen. The + property is converted from type STRING to the current locale. + The conversion is identical to that produced by + XmbTextPropertyToTextList for a single element STRING property. + The property value must be in a format that is acceptable to + XrmGetStringDatabase. If no property exists, NULL is returned. + The caller is responsible for freeing the returned string by + using XFree. + + To create a database from a string, use XrmGetStringDatabase. + + XrmDatabase XrmGetStringDatabase(char *data); + + data + + Specifies the database contents using a string. + + The XrmGetStringDatabase function creates a new database and + stores the resources specified in the specified null-terminated + string. XrmGetStringDatabase is similar to XrmGetFileDatabase + except that it reads the information out of a string instead of + out of a file. The string should contain a sequence of entries + in valid ResourceLine format (see section 15.1) terminated by a + null character; the database that results from using a string + with incorrect syntax is implementation-dependent. The string + is parsed in the current locale, and the database is created in + the current locale. + + To obtain the locale name of a database, use + XrmLocaleOfDatabase. + + char *XrmLocaleOfDatabase(XrmDatabase database); + + database + + Specifies the resource database. + + The XrmLocaleOfDatabase function returns the name of the locale + bound to the specified database, as a null-terminated string. + The returned locale name string is owned by Xlib and should not + be modified or freed by the client. Xlib is not permitted to + free the string until the database is destroyed. Until the + string is freed, it will not be modified by Xlib. + + To destroy a resource database and free its allocated memory, + use XrmDestroyDatabase. + + void XrmDestroyDatabase(XrmDatabase database); + + database + + Specifies the resource database. + + If database is NULL, XrmDestroyDatabase returns immediately. + + To associate a resource database with a display, use + XrmSetDatabase. + + void XrmSetDatabase(Display *display, XrmDatabase database); + + display + + Specifies the connection to the X server. + + database + + Specifies the resource database. + + The XrmSetDatabase function associates the specified resource + database (or NULL) with the specified display. The database + previously associated with the display (if any) is not + destroyed. A client or toolkit may find this function + convenient for retaining a database once it is constructed. + + To get the resource database associated with a display, use + XrmGetDatabase. + + XrmDatabase XrmGetDatabase(Display *display); + + display + + Specifies the connection to the X server. + + The XrmGetDatabase function returns the database associated + with the specified display. It returns NULL if a database has + not yet been set. + +Merging Resource Databases + + To merge the contents of a resource file into a database, use + XrmCombineFileDatabase. + + Status XrmCombineFileDatabase(char *filename, XrmDatabase + *target_db, Bool override); + + filename + + Specifies the resource database file name. + + target_db + + Specifies the resource database into which the source database + is to be merged. + + override + + Specifies whether source entries override target ones. + + The XrmCombineFileDatabase function merges the contents of a + resource file into a database. If the same specifier is used + for an entry in both the file and the database, the entry in + the file will replace the entry in the database if override is + True; otherwise, the entry in the file is discarded. The file + is parsed in the current locale. If the file cannot be read, a + zero status is returned; otherwise, a nonzero status is + returned. If target_db contains NULL, XrmCombineFileDatabase + creates and returns a new database to it. Otherwise, the + database pointed to by target_db is not destroyed by the merge. + The database entries are merged without changing values or + types, regardless of the locale of the database. The locale of + the target database is not modified. + + To merge the contents of one database into another database, + use XrmCombineDatabase. + + void XrmCombineDatabase(XrmDatabase source_db, XrmDatabase + *target_db, Bool override); + + source_db + + Specifies the resource database that is to be merged into the + target database. + + target_db + + Specifies the resource database into which the source database + is to be merged. + + override + + Specifies whether source entries override target ones. + + The XrmCombineDatabase function merges the contents of one + database into another. If the same specifier is used for an + entry in both databases, the entry in the source_db will + replace the entry in the target_db if override is True; + otherwise, the entry in source_db is discarded. If target_db + contains NULL, XrmCombineDatabase simply stores source_db in + it. Otherwise, source_db is destroyed by the merge, but the + database pointed to by target_db is not destroyed. The database + entries are merged without changing values or types, regardless + of the locales of the databases. The locale of the target + database is not modified. + + To merge the contents of one database into another database + with override semantics, use XrmMergeDatabases. + + void XrmMergeDatabases(XrmDatabase source_db, XrmDatabase + *target_db); + + source_db + + Specifies the resource database that is to be merged into the + target database. + + target_db + + Specifies the resource database into which the source database + is to be merged. + + Calling the XrmMergeDatabases function is equivalent to calling + the XrmCombineDatabase function with an override argument of + True. + +Looking Up Resources + + To retrieve a resource from a resource database, use + XrmGetResource, XrmQGetResource, or XrmQGetSearchResource. + + Bool XrmGetResource(XrmDatabase database, char *str_name, char + *str_class, char **str_type_return, XrmValue *value_return); + + database + + Specifies the database that is to be used. + + str_name + + Specifies the fully qualified name of the value being retrieved + (as a string). + + str_class + + Specifies the fully qualified class of the value being + retrieved (as a string). + + str_type_return + + Returns the representation type of the destination (as a + string). + + value_return + + Returns the value in the database. + + Bool XrmQGetResource(XrmDatabase database, XrmNameList + quark_name, XrmClassList quark_class, XrmRepresentation + *quark_type_return, XrmValue *value_return); + + database + + Specifies the database that is to be used. + + quark_name + + Specifies the fully qualified name of the value being retrieved + (as a quark). + + quark_class + + Specifies the fully qualified class of the value being + retrieved (as a quark). + + quark_type_return + + Returns the representation type of the destination (as a + quark). + + value_return + + Returns the value in the database. + + The XrmGetResource and XrmQGetResource functions retrieve a + resource from the specified database. Both take a fully + qualified name/class pair, a destination resource + representation, and the address of a value (size/address pair). + The value and returned type point into database memory; + therefore, you must not modify the data. + + The database only frees or overwrites entries on + XrmPutResource, XrmQPutResource, or XrmMergeDatabases. A client + that is not storing new values into the database or is not + merging the database should be safe using the address passed + back at any time until it exits. If a resource was found, both + XrmGetResource and XrmQGetResource return True; otherwise, they + return False. + + Most applications and toolkits do not make random probes into a + resource database to fetch resources. The X toolkit access + pattern for a resource database is quite stylized. A series of + from 1 to 20 probes is made with only the last name/class + differing in each probe. The XrmGetResource function is at + worst a 2^n algorithm, where n is the length of the name/class + list. This can be improved upon by the application programmer + by prefetching a list of database levels that might match the + first part of a name/class list. + + To obtain a list of database levels, use XrmQGetSearchList. + + Bool XrmQGetSearchResource(XrmDatabase database, XrmNameList + names, XrmClassList classes, XrmSearchList list_return, int + list_length); + + database + + Specifies the database that is to be used. + + names + + Specifies a list of resource names. + + classes + + Specifies a list of resource classes. + + list_return + + Returns a search list for further use. The caller must allocate + sufficient space for the list before calling XrmQGetSearchList. + + list_length + + Specifies the number of entries (not the byte size) allocated + for list_return. + + The XrmQGetSearchList function takes a list of names and + classes and returns a list of database levels where a match + might occur. The returned list is in best-to-worst order and + uses the same algorithm as XrmGetResource for determining + precedence. If list_return was large enough for the search + list, XrmQGetSearchList returns True; otherwise, it returns + False. + + The size of the search list that the caller must allocate is + dependent upon the number of levels and wildcards in the + resource specifiers that are stored in the database. The worst + case length is 3^n, where n is the number of name or class + components in names or classes. + + When using XrmQGetSearchList followed by multiple probes for + resources with a common name and class prefix, only the common + prefix should be specified in the name and class list to + XrmQGetSearchList. + + To search resource database levels for a given resource, use + XrmQGetSearchResource. + + Bool XrmQGetSearchResource(XrmSearchList list, XrmName name, + XrmClass class, XrmRepresentation *type_return, XrmValue + *value_return); + + list + + Specifies the search list returned by XrmQGetSearchList. + + name + + Specifies the resource name. + + class + + Specifies the resource class. + + type_return + + Returns data representation type. + + value_return + + Returns the value in the database. + + The XrmQGetSearchResource function searches the specified + database levels for the resource that is fully identified by + the specified name and class. The search stops with the first + match. XrmQGetSearchResource returns True if the resource was + found; otherwise, it returns False. + + A call to XrmQGetSearchList with a name and class list + containing all but the last component of a resource name + followed by a call to XrmQGetSearchResource with the last + component name and class returns the same database entry as + XrmGetResource and XrmQGetResource with the fully qualified + name and class. + +Storing into a Resource Database + + To store resources into the database, use XrmPutResource or + XrmQPutResource. Both functions take a partial resource + specification, a representation type, and a value. This value + is copied into the specified database. + + void XrmPutResource(XrmDatabase *database, char *specifier, + char *type, XrmValue *value); + + database + + Specifies the resource database. + + specifier + + Specifies a complete or partial specification of the resource. + + type + + Specifies the type of the resource. + + value + + Specifies the value of the resource, which is specified as a + string. + + If database contains NULL, XrmPutResource creates a new + database and returns a pointer to it. XrmPutResource is a + convenience function that calls XrmStringToBindingQuarkList + followed by: + +XrmQPutResource(database, bindings, quarks, XrmStringToQuark(type), valu +e) + + If the specifier and type are not in the Host Portable + Character Encoding, the result is implementation-dependent. The + value is stored in the database without modification. + + void XrmQPutResource(XrmDatabase *database, XrmBindingList + bindings, XrmQuarkList quarks, XrmRepresentation type, XrmValue + *value); + + database + + Specifies the resource database. + + bindings + + Specifies a list of bindings. + + quarks + + Specifies the complete or partial name or the class list of the + resource. + + type + + Specifies the type of the resource. + + value + + Specifies the value of the resource, which is specified as a + string. + + If database contains NULL, XrmQPutResource creates a new + database and returns a pointer to it. If a resource entry with + the identical bindings and quarks already exists in the + database, the previous type and value are replaced by the new + specified type and value. The value is stored in the database + without modification. + + To add a resource that is specified as a string, use + XrmPutStringResource. + + void XrmPutStringResource(XrmDatabase *database, char + *specifier, char *value); + + database + + Specifies the resource database. + + specifier + + Specifies a complete or partial specification of the resource. + + value + + Specifies the value of the resource, which is specified as a + string. + + If database contains NULL, XrmPutStringResource creates a new + database and returns a pointer to it. XrmPutStringResource adds + a resource with the specified value to the specified database. + XrmPutStringResource is a convenience function that first calls + XrmStringToBindingQuarkList on the specifier and then calls + XrmQPutResource, using a ``String'' representation type. If the + specifier is not in the Host Portable Character Encoding, the + result is implementation-dependent. The value is stored in the + database without modification. + + To add a string resource using quarks as a specification, use + XrmQPutStringResource. + + void XrmQPutStringResource(XrmDatabase *database, + XrmBindingList bindings, XrmQuarkList quarks, char *value); + + database + + Specifies the resource database. + + bindings + + Specifies a list of bindings. + + quarks + + Specifies the complete or partial name or the class list of the + resource. + + value + + Specifies the value of the resource, which is specified as a + string. + + If database contains NULL, XrmQPutStringResource creates a new + database and returns a pointer to it. XrmQPutStringResource is + a convenience routine that constructs an XrmValue for the value + string (by calling strlen to compute the size) and then calls + XrmQPutResource, using a ``String'' representation type. The + value is stored in the database without modification. + + To add a single resource entry that is specified as a string + that contains both a name and a value, use XrmPutLineResource. + + void XrmPutLineResource(XrmDatabase *database, char *line); + + database + + Specifies the resource database. + + line + + Specifies the resource name and value pair as a single string. + + If database contains NULL, XrmPutLineResource creates a new + database and returns a pointer to it. XrmPutLineResource adds a + single resource entry to the specified database. The line + should be in valid ResourceLine format (see section 15.1) + terminated by a newline or null character; the database that + results from using a string with incorrect syntax is + implementation-dependent. The string is parsed in the locale of + the database. If the ResourceName is not in the Host Portable + Character Encoding, the result is implementation-dependent. + Note that comment lines are not stored. + +Enumerating Database Entries + + To enumerate the entries of a database, use + XrmEnumerateDatabase. +#define XrmEnumAllLevels 0 +#define XrmEnumOneLevel 0 + + Bool XrmEnumerateDatabase(XrmDatabase database, XrmNameList + name_prefix, XrmClassList class_prefix, int mode, Bool + (*proc)(), XPointer arg); + + database + + Specifies the resource database. + + name_prefix + + Specifies the resource name prefix. + + class_prefix + + Specifies the resource class prefix. + + mode + + Specifies the number of levels to enumerate. + + proc + + Specifies the procedure that is to be called for each matching + entry. + + arg + + Specifies the user-supplied argument that will be passed to the + procedure. + + The XrmEnumerateDatabase function calls the specified procedure + for each resource in the database that would match some + completion of the given name/class resource prefix. The order + in which resources are found is implementation-dependent. If + mode is XrmEnumOneLevel, a resource must match the given + name/class prefix with just a single name and class appended. + If mode is XrmEnumAllLevels, the resource must match the given + name/class prefix with one or more names and classes appended. + If the procedure returns True, the enumeration terminates and + the function returns True. If the procedure always returns + False, all matching resources are enumerated and the function + returns False. + + The procedure is called with the following arguments: + + + +(*proc)(database, bindings, quarks, type, value, arg) + XrmDatabase *database; + XrmBindingList bindings; + XrmQuarkList quarks; + XrmRepresentation *type; + XrmValue *value; + XPointer arg; + + The bindings and quarks lists are terminated by NULLQUARK. Note + that pointers to the database and type are passed, but these + values should not be modified. + + The procedure must not modify the database. If Xlib has been + initialized for threads, the procedure is called with the + database locked and the result of a call by the procedure to + any Xlib function using the same database is not defined. + +Parsing Command Line Options + + The XrmParseCommand function can be used to parse the command + line arguments to a program and modify a resource database with + selected entries from the command line. + + + +typedef enum { + XrmoptionNoArg, /* Value is specified in XrmOptionDescRec.value + */ + XrmoptionIsArg, /* Value is the option string itself */ + XrmoptionStickyArg, /* Value is characters immediately followin +g option */ + XrmoptionSepArg, /* Value is next argument in argv */ + XrmoptionResArg, /* Resource and value in next argument in argv + */ + XrmoptionSkipArg, /* Ignore this option and the next argument i +n argv */ + XrmoptionSkipLine, /* Ignore this option and the rest of argv * +/ + XrmoptionSkipNArgs /* Ignore this option and the next + \ \ \ XrmOptionDescRec.value arguments in argv */ +} XrmOptionKind; + + Note that XrmoptionSkipArg is equivalent to XrmoptionSkipNArgs + with the XrmOptionDescRec.value field containing the value one. + Note also that the value zero for XrmoptionSkipNArgs indicates + that only the option itself is to be skipped. + + + +typedef struct { + char *option; /* Option specification string in argv + */ + char *specifier; /* Binding and resource name (sans application + name) */ + XrmOptionKind argKind; /* Which style of option it is * +/ + XPointer value; /* Value to provide if XrmoptionNoArg or + \ \ \ XrmoptionSkipNArgs */ +} XrmOptionDescRec, *XrmOptionDescList; + + To load a resource database from a C command line, use + XrmParseCommand. + + void XrmParseCommand(XrmDatabase *database, XrmOptionDescList + table, int table_count, char *name, int *argc_in_out, char + **argv_in_out); + + database + + Specifies the resource database. + + table + + Specifies the table of command line arguments to be parsed. + + table_count + + Specifies the number of entries in the table. + + name + + Specifies the application name. + + argc_in_out + + Specifies the number of arguments and returns the number of + remaining arguments. + + argv_in_out + + Specifies the command line arguments and returns the remaining + arguments. + + The XrmParseCommand function parses an (argc, argv) pair + according to the specified option table, loads recognized + options into the specified database with type ``String,'' and + modifies the (argc, argv) pair to remove all recognized + options. If database contains NULL, XrmParseCommand creates a + new database and returns a pointer to it. Otherwise, entries + are added to the database specified. If a database is created, + it is created in the current locale. + + The specified table is used to parse the command line. + Recognized options in the table are removed from argv, and + entries are added to the specified resource database in the + order they occur in argv. The table entries contain information + on the option string, the option name, the style of option, and + a value to provide if the option kind is XrmoptionNoArg. The + option names are compared byte-for-byte to arguments in argv, + independent of any locale. The resource values given in the + table are stored in the resource database without modification. + All resource database entries are created using a ``String'' + representation type. The argc argument specifies the number of + arguments in argv and is set on return to the remaining number + of arguments that were not parsed. The name argument should be + the name of your application for use in building the database + entry. The name argument is prefixed to the resourceName in the + option table before storing a database entry. The name argument + is treated as a single component, even if it has embedded + periods. No separating (binding) character is inserted, so the + table must contain either a period (.) or an asterisk (*) as + the first character in each resourceName entry. To specify a + more completely qualified resource name, the resourceName entry + can contain multiple components. If the name argument and the + resourceNames are not in the Host Portable Character Encoding, + the result is implementation-dependent. + + The following provides a sample option table: + + + +static XrmOptionDescRec opTable[] = { +{"-background", "*background", XrmoptionSepArg, ( +XPointer) NULL}, +{"-bd", "*borderColor", XrmoptionSepArg, ( +XPointer) NULL}, +{"-bg", "*background", XrmoptionSepArg, ( +XPointer) NULL}, +{"-borderwidth", "*TopLevelShell.borderWidth", XrmoptionSepArg, ( +XPointer) NULL}, +{"-bordercolor", "*borderColor", XrmoptionSepArg, ( +XPointer) NULL}, +{"-bw", "*TopLevelShell.borderWidth", XrmoptionSepArg, ( +XPointer) NULL}, +{"-display", ".display", XrmoptionSepArg, ( +XPointer) NULL}, +{"-fg", "*foreground", XrmoptionSepArg, ( +XPointer) NULL}, +{"-fn", "*font", XrmoptionSepArg, ( +XPointer) NULL}, +{"-font", "*font", XrmoptionSepArg, ( +XPointer) NULL}, +{"-foreground", "*foreground", XrmoptionSepArg, ( +XPointer) NULL}, +{"-geometry", ".TopLevelShell.geometry", XrmoptionSepArg, ( +XPointer) NULL}, +{"-iconic", ".TopLevelShell.iconic", XrmoptionNoArg, ( +XPointer) "on"}, +{"-name", ".name", XrmoptionSepArg, ( +XPointer) NULL}, +{"-reverse", "*reverseVideo", XrmoptionNoArg, ( +XPointer) "on"}, +{"-rv", "*reverseVideo", XrmoptionNoArg, ( +XPointer) "on"}, +{"-synchronous", "*synchronous", XrmoptionNoArg, ( +XPointer) "on"}, +{"-title", ".TopLevelShell.title", XrmoptionSepArg, ( +XPointer) NULL}, +{"-xrm", NULL, XrmoptionResArg, ( +XPointer) NULL}, +}; + + In this table, if the -background (or -bg) option is used to + set background colors, the stored resource specifier matches + all resources of attribute background. If the -borderwidth + option is used, the stored resource specifier applies only to + border width attributes of class TopLevelShell (that is, + outer-most windows, including pop-up windows). If the -title + option is used to set a window name, only the topmost + application windows receive the resource. + + When parsing the command line, any unique unambiguous + abbreviation for an option name in the table is considered a + match for the option. Note that uppercase and lowercase matter. + +Chapter 16. Application Utility Functions + + Table of Contents + + Using Keyboard Utility Functions + + KeySym Classification Macros + + Using Latin-1 Keyboard Event Functions + Allocating Permanent Storage + Parsing the Window Geometry + Manipulating Regions + + Creating, Copying, or Destroying Regions + Moving or Shrinking Regions + Computing with Regions + Determining if Regions Are Empty or Equal + Locating a Point or a Rectangle in a Region + + Using Cut Buffers + Determining the Appropriate Visual Type + Manipulating Images + Manipulating Bitmaps + Using the Context Manager + + Once you have initialized the X system, you can use the Xlib + utility functions to: + * Use keyboard utility functions + * Use Latin-1 keyboard event functions + * Allocate permanent storage + * Parse the window geometry + * Manipulate regions + * Use cut buffers + * Determine the appropriate visual type + * Manipulate images + * Manipulate bitmaps + * Use the context manager + + As a group, the functions discussed in this chapter provide the + functionality that is frequently needed and that spans + toolkits. Many of these functions do not generate actual + protocol requests to the server. + +Using Keyboard Utility Functions + + This section discusses mapping between KeyCodes and KeySyms, + classifying KeySyms, and mapping between KeySyms and string + names. The first three functions in this section operate on a + cached copy of the server keyboard mapping. The first four + KeySyms for each KeyCode are modified according to the rules + given in section 12.7. To obtain the untransformed KeySyms + defined for a key, use the functions described in section 12.7. + + To obtain a KeySym for the KeyCode of an event, use + XLookupKeysym. + + KeySym XLookupKeysym(XKeyEvent *key_event, int index); + + key_event + + Specifies the KeyPress or KeyRelease event. + + index + + Specifies the index into the KeySyms list for the event's + KeyCode. + + The XLookupKeysym function uses a given keyboard event and the + index you specified to return the KeySym from the list that + corresponds to the KeyCode member in the XKeyPressedEvent or + XKeyReleasedEvent structure. If no KeySym is defined for the + KeyCode of the event, XLookupKeysym returns NoSymbol. + + To obtain a KeySym for a specific KeyCode, use + XKeycodeToKeysym. + + KeySym XKeycodeToKeysym(Display *display, KeyCode keycode, int + index); + + display + + Specifies the connection to the X server. + + keycode + + Specifies the KeyCode. + + index + + Specifies the element of KeyCode vector. + + The XKeycodeToKeysym function uses internal Xlib tables and + returns the KeySym defined for the specified KeyCode and the + element of the KeyCode vector. If no symbol is defined, + XKeycodeToKeysym returns NoSymbol. + + To obtain a KeyCode for a key having a specific KeySym, use + XKeysymToKeycode. + + KeyCode XKeysymToKeycode(Display *display, KeySym keysym); + + display + + Specifies the connection to the X server. + + keysym + + Specifies the KeySym that is to be searched for. + + If the specified KeySym is not defined for any KeyCode, + XKeysymToKeycode returns zero. + + The mapping between KeyCodes and KeySyms is cached internal to + Xlib. When this information is changed at the server, an Xlib + function must be called to refresh the cache. To refresh the + stored modifier and keymap information, use + XRefreshKeyboardMapping. + + XRefreshKeyboardMapping(XMappingEvent *event_map); + + event_map + + Specifies the mapping event that is to be used. + + The XRefreshKeyboardMapping function refreshes the stored + modifier and keymap information. You usually call this function + when a MappingNotify event with a request member of + MappingKeyboard or MappingModifier occurs. The result is to + update Xlib's knowledge of the keyboard. + + To obtain the uppercase and lowercase forms of a KeySym, use + XConvertCase. + + void XConvertCase(KeySym keysym, KeySym *lower_return, KeySym + *upper_return); + + keysym + + Specifies the KeySym that is to be converted. + + lower_return + + Returns the lowercase form of keysym, or keysym. + + upper_return + + Returns the uppercase form of keysym, or keysym. + + The XConvertCase function returns the uppercase and lowercase + forms of the specified Keysym, if the KeySym is subject to case + conversion; otherwise, the specified KeySym is returned to both + lower_return and upper_return. Support for conversion of other + than Latin and Cyrillic KeySyms is implementation-dependent. + + KeySyms have string names as well as numeric codes. To convert + the name of the KeySym to the KeySym code, use XStringToKeysym. + + KeySym XStringToKeysym(char *string); + + string + + Specifies the name of the KeySym that is to be converted. + + Standard KeySym names are obtained from by + removing the XK_ prefix from each name. KeySyms that are not + part of the Xlib standard also may be obtained with this + function. The set of KeySyms that are available in this manner + and the mechanisms by which Xlib obtains them is + implementation-dependent. + + If the KeySym name is not in the Host Portable Character + Encoding, the result is implementation-dependent. If the + specified string does not match a valid KeySym, XStringToKeysym + returns NoSymbol. + + To convert a KeySym code to the name of the KeySym, use + XKeysymToString. + + char *XKeysymToString(KeySym keysym); + + keysym + + Specifies the KeySym that is to be converted. + + The returned string is in a static area and must not be + modified. The returned string is in the Host Portable Character + Encoding. If the specified KeySym is not defined, + XKeysymToString returns a NULL. + +KeySym Classification Macros + + You may want to test if a KeySym is, for example, on the keypad + or on one of the function keys. You can use KeySym macros to + perform the following tests. + + IsCursorKey(keysym) + + keysym + + Specifies the KeySym that is to be tested. + + Returns True if the specified KeySym is a cursor key. + + IsFunctionKey(keysym) + + keysym + + Specifies the KeySym that is to be tested. + + Returns True if the specified KeySym is a function key. + + IsKeypadKey(keysym) + + keysym + + Specifies the KeySym that is to be tested. + + Returns True if the specified KeySym is a standard keypad key. + + IsPrivateKeypadKey(keysym) + + keysym + + Specifies the KeySym that is to be tested. + + Returns True if the specified KeySym is a vendor-private keypad + key. + + IsMiscFunctionKey(keysym) + + keysym + + Specifies the KeySym that is to be tested. + + Returns True if the specified KeySym is a miscellaneous + function key. + + IsModifierKey(keysym) + + keysym + + Specifies the KeySym that is to be tested. + + Returns True if the specified KeySym is a modifier key. + + IsPFKey(keysym) + + keysym + + Specifies the KeySym that is to be tested. + + Returns True if the specified KeySym is a PF key. + +Using Latin-1 Keyboard Event Functions + + Chapter 13 describes internationalized text input facilities, + but sometimes it is expedient to write an application that only + deals with Latin-1 characters and ASCII controls, so Xlib + provides a simple function for that purpose. XLookupString + handles the standard modifier semantics described in section + 12.7. This function does not use any of the input method + facilities described in chapter 13 and does not depend on the + current locale. + + To map a key event to an ISO Latin-1 string, use XLookupString. + + int XLookupString(XKeyEvent *event_struct, char *buffer_return, + int bytes_buffer, KeySym *keysym_return, XComposeStatus + *status_in_out); + + event_struct + + Specifies the key event structure to be used. You can pass + XKeyPressedEvent or XKeyReleasedEvent. + + buffer_return + + Returns the translated characters. + + bytes_buffer + + Specifies the length of the buffer. No more than bytes_buffer + of translation are returned. + + keysym_return + + Returns the KeySym computed from the event if this argument is + not NULL. + + status_in_out + + Specifies or returns the XComposeStatus structure or NULL. + + The XLookupString function translates a key event to a KeySym + and a string. The KeySym is obtained by using the standard + interpretation of the Shift, Lock, group, and numlock modifiers + as defined in the X Protocol specification. If the KeySym has + been rebound (see XRebindKeysym), the bound string will be + stored in the buffer. Otherwise, the KeySym is mapped, if + possible, to an ISO Latin-1 character or (if the Control + modifier is on) to an ASCII control character, and that + character is stored in the buffer. XLookupString returns the + number of characters that are stored in the buffer. + + If present (non-NULL), the XComposeStatus structure records the + state, which is private to Xlib, that needs preservation across + calls to XLookupString to implement compose processing. The + creation of XComposeStatus structures is + implementation-dependent; a portable program must pass NULL for + this argument. + + XLookupString depends on the cached keyboard information + mentioned in the previous section, so it is necessary to use + XRefreshKeyboardMapping to keep this information up-to-date. + + To rebind the meaning of a KeySym for XLookupString, use + XRebindKeysym. + + XRebindKeysym(Display *display, KeySym keysym, KeySym list[], + int mod_count, unsignedchar *string, int num_bytes); + + display + + Specifies the connection to the X server. + + keysym + + Specifies the KeySym that is to be rebound. + + list + + Specifies the KeySyms to be used as modifiers. + + mod_count + + Specifies the number of modifiers in the modifier list. + + string + + Specifies the string that is copied and will be returned by + XLookupString. + + num_bytes + + Specifies the number of bytes in the string argument. + + The XRebindKeysym function can be used to rebind the meaning of + a KeySym for the client. It does not redefine any key in the X + server but merely provides an easy way for long strings to be + attached to keys. XLookupString returns this string when the + appropriate set of modifier keys are pressed and when the + KeySym would have been used for the translation. No text + conversions are performed; the client is responsible for + supplying appropriately encoded strings. Note that you can + rebind a KeySym that may not exist. + +Allocating Permanent Storage + + To allocate some memory you will never give back, use + Xpermalloc. + + char *Xpermalloc(unsigned int size); + + The Xpermalloc function allocates storage that can never be + freed for the life of the program. The memory is allocated with + alignment for the C type double. This function may provide some + performance and space savings over the standard operating + system memory allocator. + +Parsing the Window Geometry + + To parse standard window geometry strings, use XParseGeometry. + + int XParseGeometry(char *parsestring, int *x_return, int + *y_return, unsigned int *width_return, unsigned int + *height_return); + + parsestring + + Specifies the string you want to parse. + + x_return + + y_return + + Return the x and y offsets. + + width_return + + height_return + + Return the width and height determined. + + By convention, X applications use a standard string to indicate + window size and placement. XParseGeometry makes it easier to + conform to this standard because it allows you to parse the + standard window geometry. Specifically, this function lets you + parse strings of the form: + +[=][{xX}][{+-}{+-}] + + The fields map into the arguments associated with this + function. (Items enclosed in <> are integers, items in [] are + optional, and items enclosed in {} indicate ``choose one of.'' + Note that the brackets should not appear in the actual string.) + If the string is not in the Host Portable Character Encoding, + the result is implementation-dependent. + + The XParseGeometry function returns a bitmask that indicates + which of the four values (width, height, xoffset, and yoffset) + were actually found in the string and whether the x and y + values are negative. By convention, -0 is not equal to +0, + because the user needs to be able to say ``position the window + relative to the right or bottom edge.'' For each value found, + the corresponding argument is updated. For each value not + found, the argument is left unchanged. The bits are represented + by XValue, YValue, WidthValue, HeightValue, XNegative, or + YNegative and are defined in . They will be set + whenever one of the values is defined or one of the signs is + set. + + If the function returns either the XValue or YValue flag, you + should place the window at the requested position. + + To construct a window's geometry information, use XWMGeometry. + + int XWMGeometry(Display *display, int screen, char *user_geom, + char *def_geom, unsigned int bwidth, XSizeHints *hints, int + *x_return, int *y_return, int *width_return, int + *height_return, int *gravity_return); + + display + + Specifies the connection to the X server. + + screen + + Specifies the screen. + + user_geom + + Specifies the user-specified geometry or NULL. + + def_geom + + Specifies the application's default geometry or NULL. + + bwidth + + Specifies the border width. + + hints + + Specifies the size hints for the window in its normal state. + + x_return + + y_return + + Return the x and y offsets. + + width_return + + height_return + + Return the width and height determined. + + gravity_return + + Returns the window gravity. + + The XWMGeometry function combines any geometry information + (given in the format used by XParseGeometry) specified by the + user and by the calling program with size hints (usually the + ones to be stored in WM_NORMAL_HINTS) and returns the position, + size, and gravity (NorthWestGravity, NorthEastGravity, + SouthEastGravity, or SouthWestGravity) that describe the + window. If the base size is not set in the XSizeHints + structure, the minimum size is used if set. Otherwise, a base + size of zero is assumed. If no minimum size is set in the hints + structure, the base size is used. A mask (in the form returned + by XParseGeometry) that describes which values came from the + user specification and whether or not the position coordinates + are relative to the right and bottom edges is returned. Note + that these coordinates will have already been accounted for in + the x_return and y_return values. + + Note that invalid geometry specifications can cause a width or + height of zero to be returned. The caller may pass the address + of the hints win_gravity field as gravity_return to update the + hints directly. + +Manipulating Regions + + Regions are arbitrary sets of pixel locations. Xlib provides + functions for manipulating regions. The opaque type Region is + defined in . Xlib provides functions that you can + use to manipulate regions. This section discusses how to: + * Create, copy, or destroy regions + * Move or shrink regions + * Compute with regions + * Determine if regions are empty or equal + * Locate a point or rectangle in a region + +Creating, Copying, or Destroying Regions + + To create a new empty region, use XCreateRegion. + + Region XCreateRegion(void); + + To generate a region from a polygon, use XPolygonRegion. + + Region XPolygonRegion(XPoint points[], int n, int fill_rule); + + points + + Specifies an array of points. + + n + + Specifies the number of points in the polygon. + + fill_rule + + Specifies the fill-rule you want to set for the specified GC. + You can pass EvenOddRule or WindingRule. + + The XPolygonRegion function returns a region for the polygon + defined by the points array. For an explanation of fill_rule, + see XCreateGC. + + To set the clip-mask of a GC to a region, use XSetRegion. + + XSetRegion(Display *display, GC gc, Region r); + + display + + Specifies the connection to the X server. + + gc + + Specifies the GC. + + r + + Specifies the region. + + The XSetRegion function sets the clip-mask in the GC to the + specified region. The region is specified relative to the + drawable's origin. The resulting GC clip origin is + implementation-dependent. Once it is set in the GC, the region + can be destroyed. + + To deallocate the storage associated with a specified region, + use XDestroyRegion. + + XDestroyRegion(Region r); + + r + + Specifies the region. + +Moving or Shrinking Regions + + To move a region by a specified amount, use XOffsetRegion. + + XOffsetRegion(Region r, int dx, int dy); + + r + + Specifies the region. + + dx + + dy + + Specify the x and y coordinates, which define the amount you + want to move the specified region. + + To reduce a region by a specified amount, use XShrinkRegion. + + XShrinkRegion(Region r, int dx, int dy); + + r + + Specifies the region. + + dx + + dy + + Specify the x and y coordinates, which define the amount you + want to shrink the specified region. + + Positive values shrink the size of the region, and negative + values expand the region. + +Computing with Regions + + To generate the smallest rectangle enclosing a region, use + XClipBox. + + XClipBox(Region r, XRectangle *rect_return); + + r + + Specifies the region. + + rect_return + + Returns the smallest enclosing rectangle. + + The XClipBox function returns the smallest rectangle enclosing + the specified region. + + To compute the intersection of two regions, use + XIntersectRegion. + + XIntersectRegion(Region sra, Region srb, Region dr_return); + + sra + + srb + + Specify the two regions with which you want to perform the + computation. + + dr_return + + Returns the result of the computation. + + To compute the union of two regions, use XUnionRegion. + + XUnionRegion(Region sra, Region srb, Region dr_return); + + sra + + srb + + Specify the two regions with which you want to perform the + computation. + + dr_return + + Returns the result of the computation. + + To create a union of a source region and a rectangle, use + XUnionRectWithRegion. + + XUnionRectWithRegion(XRectangle *rectangle, Region src_region, + Region dest_region_return); + + rectangle + + Specifies the rectangle. + + src_region + + Specifies the source region to be used. + + dest_region_return + + Returns the destination region. + + The XUnionRectWithRegion function updates the destination + region from a union of the specified rectangle and the + specified source region. + + To subtract two regions, use XSubtractRegion. + + XSubtractRegion(Region sra, Region srb, Region dr_return); + + sra + + srb + + Specify the two regions with which you want to perform the + computation. + + dr_return + + Returns the result of the computation. + + The XSubtractRegion function subtracts srb from sra and stores + the results in dr_return. + + To calculate the difference between the union and intersection + of two regions, use XXorRegion. + + XXorRegion(Region sra, Region srb, Region dr_return); + + sra + + srb + + Specify the two regions with which you want to perform the + computation. + + dr_return + + Returns the result of the computation. + +Determining if Regions Are Empty or Equal + + To determine if the specified region is empty, use + XEmptyRegion. + + Bool XEmptyRegion(Region r); + + r + + Specifies the region. + + The XEmptyRegion function returns True if the region is empty. + + To determine if two regions have the same offset, size, and + shape, use XEqualRegion. + + Bool XEqualRegion(Region r1, Region r2); + + r1 + + r2 + + Specify the two regions. + + The XEqualRegion function returns True if the two regions have + the same offset, size, and shape. + +Locating a Point or a Rectangle in a Region + + To determine if a specified point resides in a specified + region, use XPointInRegion. + + Bool XPointInRegion(Region r, int x, int y); + + r + + Specifies the region. + + x + + y + + Specify the x and y coordinates, which define the point. + + The XPointInRegion function returns True if the point (x, y) is + contained in the region r. + + To determine if a specified rectangle is inside a region, use + XRectInRegion. + + int XRectInRegion(Region r, int x, int y, unsigned int width, + unsigned int height); + + r + + Specifies the region. + + x + + y + + Specify the x and y coordinates, which define the coordinates + of the upper-left corner of the rectangle. + + width + + height + + Specify the width and height, which define the rectangle. + + The XRectInRegion function returns RectangleIn if the rectangle + is entirely in the specified region, RectangleOut if the + rectangle is entirely out of the specified region, and + RectanglePart if the rectangle is partially in the specified + region. + +Using Cut Buffers + + Xlib provides functions to manipulate cut buffers, a very + simple form of cut-and-paste inter-client communication. + Selections are a much more powerful and useful mechanism for + interchanging data between client (see section 4.5) and + generally should be used instead of cut buffers. + + Cut buffers are implemented as properties on the first root + window of the display. The buffers can only contain text, in + the STRING encoding. The text encoding is not changed by Xlib + when fetching or storing. Eight buffers are provided and can be + accessed as a ring or as explicit buffers (numbered 0 through + 7). + + To store data in cut buffer 0, use XStoreBytes. + + XStoreBytes(Display *display, char *bytes, int nbytes); + + display + + Specifies the connection to the X server. + + bytes + + Specifies the bytes, which are not necessarily ASCII or + null-terminated. + + nbytes + + Specifies the number of bytes to be stored. + + The data can have embedded null characters and need not be + null-terminated. The cut buffer's contents can be retrieved + later by any client calling XFetchBytes. + + XStoreBytes can generate a BadAlloc error. + + To store data in a specified cut buffer, use XStoreBuffer. + + XStoreBuffer(Display *display, char *bytes, int nbytes, int + buffer); + + display + + Specifies the connection to the X server. + + bytes + + Specifies the bytes, which are not necessarily ASCII or + null-terminated. + + nbytes + + Specifies the number of bytes to be stored. + + buffer + + Specifies the buffer in which you want to store the bytes. + + If an invalid buffer is specified, the call has no effect. The + data can have embedded null characters and need not be + null-terminated. + + XStoreBuffer can generate a BadAlloc error. + + To return data from cut buffer 0, use XFetchBytes. + + char *XFetchBytes(Display *display, int *nbytes_return); + + display + + Specifies the connection to the X server. + + nbytes_return + + Returns the number of bytes in the buffer. + + The XFetchBytes function returns the number of bytes in the + nbytes_return argument, if the buffer contains data. Otherwise, + the function returns NULL and sets nbytes to 0. The appropriate + amount of storage is allocated and the pointer returned. The + client must free this storage when finished with it by calling + XFree. + + To return data from a specified cut buffer, use XFetchBuffer. + + char *XFetchBuffer(Display *display, int *nbytes_return, int + buffer); + + display + + Specifies the connection to the X server. + + nbytes_return + + Returns the number of bytes in the buffer. + + buffer + + Specifies the buffer from which you want the stored data + returned. + + The XFetchBuffer function returns zero to the nbytes_return + argument if there is no data in the buffer or if an invalid + buffer is specified. + + To rotate the cut buffers, use XRotateBuffers. + + XRotateBuffers(Display *display, int rotate); + + display + + Specifies the connection to the X server. + + rotate + + Specifies how much to rotate the cut buffers. + + The XRotateBuffers function rotates the cut buffers, such that + buffer 0 becomes buffer n, buffer 1 becomes n + 1 mod 8, and so + on. This cut buffer numbering is global to the display. Note + that XRotateBuffers generates BadMatch errors if any of the + eight buffers have not been created. + +Determining the Appropriate Visual Type + + A single display can support multiple screens. Each screen can + have several different visual types supported at different + depths. You can use the functions described in this section to + determine which visual to use for your application. + + The functions in this section use the visual information masks + and the XVisualInfo structure, which is defined in + and contains: + +/* Visual information mask bits */ + + +#define VisualNoMask 0x0 +#define VisualIDMask 0x1 +#define VisualScreenMask 0x2 +#define VisualDepthMask 0x4 +#define VisualClassMask 0x8 +#define VisualRedMaskMask 0x10 +#define VisualGreenMaskMask 0x20 +#define VisualBlueMaskMask 0x40 +#define VisualColormapSizeMask 0x80 +#define VisualBitsPerRGBMask 0x100 +#define VisualAllMask 0x1FF + + + + +/* Values */ + +typedef struct { + Visual *visual; + VisualID visualid; + int screen; + unsigned int depth; + int class; + unsigned long red_mask; + unsigned long green_mask; + unsigned long blue_mask; + int colormap_size; + int bits_per_rgb; +} XVisualInfo; + + To obtain a list of visual information structures that match a + specified template, use XGetVisualInfo. + + XVisualInfo *XGetVisualInfo(Display *display, long vinfo_mask, + XVisualInfo *vinfo_template, int *nitems_return); + + display + + Specifies the connection to the X server. + + vinfo_mask + + Specifies the visual mask value. + + vinfo_template + + Specifies the visual attributes that are to be used in matching + the visual structures. + + nitems_return + + Returns the number of matching visual structures. + + The XGetVisualInfo function returns a list of visual structures + that have attributes equal to the attributes specified by + vinfo_template. If no visual structures match the template + using the specified vinfo_mask, XGetVisualInfo returns a NULL. + To free the data returned by this function, use XFree. + + To obtain the visual information that matches the specified + depth and class of the screen, use XMatchVisualInfo. + + Status XMatchVisualInfo(Display *display, int screen, int + depth, int class, XVisualInfo *vinfo_return); + + display + + Specifies the connection to the X server. + + screen + + Specifies the screen. + + depth + + Specifies the depth of the screen. + + class + + Specifies the class of the screen. + + vinfo_return + + Returns the matched visual information. + + The XMatchVisualInfo function returns the visual information + for a visual that matches the specified depth and class for a + screen. Because multiple visuals that match the specified depth + and class can exist, the exact visual chosen is undefined. If a + visual is found, XMatchVisualInfo returns nonzero and the + information on the visual to vinfo_return. Otherwise, when a + visual is not found, XMatchVisualInfo returns zero. + +Manipulating Images + + Xlib provides several functions that perform basic operations + on images. All operations on images are defined using an XImage + structure, as defined in . Because the number of + different types of image formats can be very large, this hides + details of image storage properly from applications. + + This section describes the functions for generic operations on + images. Manufacturers can provide very fast implementations of + these for the formats frequently encountered on their hardware. + These functions are neither sufficient nor desirable to use for + general image processing. Rather, they are here to provide + minimal functions on screen format images. The basic operations + for getting and putting images are XGetImage and XPutImage. + + Note that no functions have been defined, as yet, to read and + write images to and from disk files. + + The XImage structure describes an image as it exists in the + client's memory. The user can request that some of the members + such as height, width, and xoffset be changed when the image is + sent to the server. Note that bytes_per_line in concert with + offset can be used to extract a subset of the image. Other + members (for example, byte order, bitmap_unit, and so forth) + are characteristics of both the image and the server. If these + members differ between the image and the server, XPutImage + makes the appropriate conversions. The first byte of the first + line of plane n must be located at the address (data + (n * + height * bytes_per_line)). For a description of the XImage + structure, see section 8.7. + + To allocate an XImage structure and initialize it with image + format values from a display, use XCreateImage. + + XImage *XCreateImage(Display *display, Visual *visual, unsigned + int depth, int format, int offset, char *data, unsigned int + width, unsigned int height, int bitmap_pad, int + bytes_per_line); + + display + + Specifies the connection to the X server. + + visual + + Specifies the Visual structure. + + depth + + Specifies the depth of the image. + + format + + Specifies the format for the image. You can pass XYBitmap, + XYPixmap, or ZPixmap. + + offset + + Specifies the number of pixels to ignore at the beginning of + the scanline. + + data + + Specifies the image data. + + width + + Specifies the width of the image, in pixels. + + height + + Specifies the height of the image, in pixels. + + bitmap_pad + + Specifies the quantum of a scanline (8, 16, or 32). In other + words, the start of one scanline is separated in client memory + from the start of the next scanline by an integer multiple of + this many bits. + + bytes_per_line + + Specifies the number of bytes in the client image between the + start of one scanline and the start of the next. + + The XCreateImage function allocates the memory needed for an + XImage structure for the specified display but does not + allocate space for the image itself. Rather, it initializes the + structure byte-order, bit-order, and bitmap-unit values from + the display and returns a pointer to the XImage structure. The + red, green, and blue mask values are defined for Z format + images only and are derived from the Visual structure passed + in. Other values also are passed in. The offset permits the + rapid displaying of the image without requiring each scanline + to be shifted into position. If you pass a zero value in + bytes_per_line, Xlib assumes that the scanlines are contiguous + in memory and calculates the value of bytes_per_line itself. + + Note that when the image is created using XCreateImage, + XGetImage, or XSubImage, the destroy procedure that the + XDestroyImage function calls frees both the image structure and + the data pointed to by the image structure. + + The basic functions used to get a pixel, set a pixel, create a + subimage, and add a constant value to an image are defined in + the image object. The functions in this section are really + macro invocations of the functions in the image object and are + defined in . + + To obtain a pixel value in an image, use XGetPixel. + + unsigned long XGetPixel(XImage *ximage, int x, int y); + + ximage + + Specifies the image. + + x + + y + + Specify the x and y coordinates. + + The XGetPixel function returns the specified pixel from the + named image. The pixel value is returned in normalized format + (that is, the least significant byte of the long is the least + significant byte of the pixel). The image must contain the x + and y coordinates. + + To set a pixel value in an image, use XPutPixel. + + XPutPixel(XImage *ximage, int x, int y, unsigned long pixel); + + ximage + + Specifies the image. + + x + + y + + Specify the x and y coordinates. + + pixel + + Specifies the new pixel value. + + The XPutPixel function overwrites the pixel in the named image + with the specified pixel value. The input pixel value must be + in normalized format (that is, the least significant byte of + the long is the least significant byte of the pixel). The image + must contain the x and y coordinates. + + To create a subimage, use XSubImage. + + XImage *XSubImage(XImage *ximage, int x, int y, unsigned int + subimage_width, unsigned int subimage_height); + + ximage + + Specifies the image. + + x + + y + + Specify the x and y coordinates. + + subimage_width + + Specifies the width of the new subimage, in pixels. + + subimage_height + + Specifies the height of the new subimage, in pixels. + + The XSubImage function creates a new image that is a subsection + of an existing one. It allocates the memory necessary for the + new XImage structure and returns a pointer to the new image. + The data is copied from the source image, and the image must + contain the rectangle defined by x, y, subimage_width, and + subimage_height. + + To increment each pixel in an image by a constant value, use + XAddPixel. + + XAddPixel(XImage *ximage, long value); + + ximage + + Specifies the image. + + value + + Specifies the constant value that is to be added. + + The XAddPixel function adds a constant value to every pixel in + an image. It is useful when you have a base pixel value from + allocating color resources and need to manipulate the image to + that form. + + To deallocate the memory allocated in a previous call to + XCreateImage, use XDestroyImage. + + XDestroyImage(XImage *ximage); + + ximage + + Specifies the image. + + The XDestroyImage function deallocates the memory associated + with the XImage structure. + + Note that when the image is created using XCreateImage, + XGetImage, or XSubImage, the destroy procedure that this macro + calls frees both the image structure and the data pointed to by + the image structure. + +Manipulating Bitmaps + + Xlib provides functions that you can use to read a bitmap from + a file, save a bitmap to a file, or create a bitmap. This + section describes those functions that transfer bitmaps to and + from the client's file system, thus allowing their reuse in a + later connection (for example, from an entirely different + client or to a different display or server). + + The X version 11 bitmap file format is: + +#define name_width width +#define name_height height +#define name_x_hot x +#define name_y_hot y +static unsigned char name_bits[] = { 0xNN,... } + + The lines for the variables ending with _x_hot and _y_hot + suffixes are optional because they are present only if a + hotspot has been defined for this bitmap. The lines for the + other variables are required. The word ``unsigned'' is + optional; that is, the type of the _bits array can be ``char'' + or ``unsigned char''. The _bits array must be large enough to + contain the size bitmap. The bitmap unit is 8. + + To read a bitmap from a file and store it in a pixmap, use + XReadBitmapFile. + + int XReadBitmapFile(Display *display, Drawable d, char + *filename, unsigned int *width_return, unsigned int + *height_return, Pixmap *bitmap_return, int *x_hot_return, int + *y_hot_return); + + display + + Specifies the connection to the X server. + + d + + Specifies the drawable that indicates the screen. + + filename + + Specifies the file name to use. The format of the file name is + operating-system dependent. + + width_return + + height_return + + Return the width and height values of the read in bitmap file. + + bitmap_return + + Returns the bitmap that is created. + + x_hot_return + + y_hot_return + + Return the hotspot coordinates. + + The XReadBitmapFile function reads in a file containing a + bitmap. The file is parsed in the encoding of the current + locale. The ability to read other than the standard format is + implementation-dependent. If the file cannot be opened, + XReadBitmapFile returns BitmapOpenFailed. If the file can be + opened but does not contain valid bitmap data, it returns + BitmapFileInvalid. If insufficient working storage is + allocated, it returns BitmapNoMemory. If the file is readable + and valid, it returns BitmapSuccess. + + XReadBitmapFile returns the bitmap's height and width, as read + from the file, to width_return and height_return. It then + creates a pixmap of the appropriate size, reads the bitmap data + from the file into the pixmap, and assigns the pixmap to the + caller's variable bitmap. The caller must free the bitmap using + XFreePixmap when finished. If name_x_hot and name_y_hot exist, + XReadBitmapFile returns them to x_hot_return and y_hot_return; + otherwise, it returns -1,-1. + + XReadBitmapFile can generate BadAlloc, BadDrawable, and BadGC + errors. + + To read a bitmap from a file and return it as data, use + XReadBitmapFileData. + + int XReadBitmapFileData(char *filename, unsigned int + *width_return, unsigned int *height_return, unsignedchar + *data_return, int *x_hot_return, int *y_hot_return); + + filename + + Specifies the file name to use. The format of the file name is + operating-system dependent. + + width_return + + height_return + + Return the width and height values of the read in bitmap file. + + data_return + + Returns the bitmap data. + + x_hot_return + + y_hot_return + + Return the hotspot coordinates. + + The XReadBitmapFileData function reads in a file containing a + bitmap, in the same manner as XReadBitmapFile, but returns the + data directly rather than creating a pixmap in the server. The + bitmap data is returned in data_return; the client must free + this storage when finished with it by calling XFree. The status + and other return values are the same as for XReadBitmapFile. + + To write out a bitmap from a pixmap to a file, use + XWriteBitmapFile. + + int XWriteBitmapFile(Display *display, char *filename, Pixmap + bitmap, unsigned int width, unsigned int height, int x_hot, int + y_hot); + + display + + Specifies the connection to the X server. + + filename + + Specifies the file name to use. The format of the file name is + operating-system dependent. + + bitmap + + Specifies the bitmap. + + width + + height + + Specify the width and height. + + x_hot + + y_hot + + Specify where to place the hotspot coordinates (or -1,-1 if + none are present) in the file. + + The XWriteBitmapFile function writes a bitmap out to a file in + the X Version 11 format. The name used in the output file is + derived from the file name by deleting the directory prefix. + The file is written in the encoding of the current locale. If + the file cannot be opened for writing, it returns + BitmapOpenFailed. If insufficient memory is allocated, + XWriteBitmapFile returns BitmapNoMemory; otherwise, on no + error, it returns BitmapSuccess. If x_hot and y_hot are not -1, + -1, XWriteBitmapFile writes them out as the hotspot coordinates + for the bitmap. + + XWriteBitmapFile can generate BadDrawable and BadMatch errors. + + To create a pixmap and then store bitmap-format data into it, + use XCreatePixmapFromBitmapData. + + Pixmap XCreatePixmapFromBitmapData(Display *display, Drawable + d, char *data, unsigned int width, unsigned int height, + unsigned long fg, unsigned long bg, unsigned int depth); + + display + + Specifies the connection to the X server. + + d + + Specifies the drawable that indicates the screen. + + data + + Specifies the data in bitmap format. + + width + + height + + Specify the width and height. + + fg + + bg + + Specify the foreground and background pixel values to use. + + depth + + Specifies the depth of the pixmap. + + The XCreatePixmapFromBitmapData function creates a pixmap of + the given depth and then does a bitmap-format XPutImage of the + data into it. The depth must be supported by the screen of the + specified drawable, or a BadMatch error results. + + XCreatePixmapFromBitmapData can generate BadAlloc, BadDrawable, + BadGC, and BadValue errors. + + To include a bitmap written out by XWriteBitmapFile in a + program directly, as opposed to reading it in every time at run + time, use XCreateBitmapFromData. + + Pixmap XCreateBitmapFromData(Display *display, Drawable d, char + *data, unsigned int width, unsigned int height); + + display + + Specifies the connection to the X server. + + d + + Specifies the drawable that indicates the screen. + + data + + Specifies the location of the bitmap data. + + width + + height + + Specify the width and height. + + The XCreateBitmapFromData function allows you to include in + your C program (using #include) a bitmap file that was written + out by XWriteBitmapFile (X version 11 format only) without + reading in the bitmap file. The following example creates a + gray bitmap: + +#include "gray.bitmap" + +Pixmap bitmap; +bitmap = XCreateBitmapFromData(display, window, gray_bits, gray_width, g +ray_height); + + If insufficient working storage was allocated, + XCreateBitmapFromData returns None. It is your responsibility + to free the bitmap using XFreePixmap when finished. + + XCreateBitmapFromData can generate BadAlloc and BadGC errors. + +Using the Context Manager + + The context manager provides a way of associating data with an + X resource ID (mostly typically a window) in your program. Note + that this is local to your program; the data is not stored in + the server on a property list. Any amount of data in any number + of pieces can be associated with a resource ID, and each piece + of data has a type associated with it. The context manager + requires knowledge of the resource ID and type to store or + retrieve data. + + Essentially, the context manager can be viewed as a + two-dimensional, sparse array: one dimension is subscripted by + the X resource ID and the other by a context type field. Each + entry in the array contains a pointer to the data. Xlib + provides context management functions with which you can save + data values, get data values, delete entries, and create a + unique context type. The symbols used are in . + + To save a data value that corresponds to a resource ID and + context type, use XSaveContext. + + int XSaveContext(Display *display, XID rid, XContext context, + XPointer data); + + display + + Specifies the connection to the X server. + + rid + + Specifies the resource ID with which the data is associated. + + context + + Specifies the context type to which the data belongs. + + data + + Specifies the data to be associated with the window and type. + + If an entry with the specified resource ID and type already + exists, XSaveContext overrides it with the specified context. + The XSaveContext function returns a nonzero error code if an + error has occurred and zero otherwise. Possible errors are + XCNOMEM (out of memory). + + To get the data associated with a resource ID and type, use + XFindContext. + + int XFindContext(Display *display, XID rid, XContext context, + XPointer *data_return); + + display + + Specifies the connection to the X server. + + rid + + Specifies the resource ID with which the data is associated. + + context + + Specifies the context type to which the data belongs. + + data_return + + Returns the data. + + Because it is a return value, the data is a pointer. The + XFindContext function returns a nonzero error code if an error + has occurred and zero otherwise. Possible errors are XCNOENT + (context-not-found). + + To delete an entry for a given resource ID and type, use + XDeleteContext. + + int XDeleteContext(Display *display, XID rid, XContext + context); + + display + + Specifies the connection to the X server. + + rid + + Specifies the resource ID with which the data is associated. + + context + + Specifies the context type to which the data belongs. + + The XDeleteContext function deletes the entry for the given + resource ID and type from the data structure. This function + returns the same error codes that XFindContext returns if + called with the same arguments. XDeleteContext does not free + the data whose address was saved. + + To create a unique context type that may be used in subsequent + calls to XSaveContext and XFindContext, use XUniqueContext. + + XContext XUniqueContext(void); + +Appendix A. Xlib Functions and Protocol Requests + + This appendix provides two tables that relate to Xlib functions + and the X protocol. The following table lists each Xlib + function (in alphabetical order) and the corresponding protocol + request that it generates. + + Table A.1. Protocol requests made by each Xlib function + Xlib Function Protocol Request + XActivateScreenSaver ForceScreenSaver + XAddHost ChangeHosts + XAddHosts ChangeHosts + XAddToSaveSet ChangeSaveSet + XAllocColor AllocColor + XAllocColorCells AllocColorCells + XAllocColorPlanes AllocColorPlanes + XAllocNamedColor AllocNamedColor + XAllowEvents AllowEvents + XAutoRepeatOff ChangeKeyboardControl + XAutoRepeatOn ChangeKeyboardControl + XBell Bell + XChangeActivePointerGrab ChangeActivePointerGrab + XChangeGC ChangeGC + XChangeKeyboardControl ChangeKeyboardControl + XChangeKeyboardMapping ChangeKeyboardMapping + XChangePointerControl ChangePointerControl + XChangeProperty ChangeProperty + XChangeSaveSet ChangeSaveSet + XChangeWindowAttributes ChangeWindowAttributes + XCirculateSubwindows CirculateWindow + XCirculateSubwindowsDown CirculateWindow + XCirculateSubwindowsUp CirculateWindow + XClearArea ClearArea + XClearWindow ClearArea + XConfigureWindow ConfigureWindow + XConvertSelection ConvertSelection + XCopyArea CopyArea + XCopyColormapAndFree CopyColormapAndFree + XCopyGC CopyGC + XCopyPlane CopyPlane + XCreateBitmapFromData CreateGC + CreatePixmap + FreeGC + PutImage + XCreateColormap CreateColormap + XCreateFontCursor CreateGlyphCursor + XCreateGC CreateGC + XCreateGlyphCursor CreateGlyphCursor + XCreatePixmap CreatePixmap + XCreatePixmapCursor CreateCursor + XCreatePixmapFromData CreateGC + CreatePixmap + FreeGC + PutImage + XCreateSimpleWindow CreateWindow + XCreateWindow CreateWindow + XDefineCursor ChangeWindowAttributes + XDeleteProperty DeleteProperty + XDestroySubwindows DestroySubwindows + XDestroyWindow DestroyWindow + XDisableAccessControl SetAccessControl + XDrawArc PolyArc + XDrawArcs PolyArc + XDrawImageString ImageText8 + XDrawImageString16 ImageText16 + XDrawLine PolySegment + XDrawLines PolyLine + XDrawPoint PolyPoint + XDrawPoints PolyPoint + XDrawRectangle PolyRectangle + XDrawRectangles PolyRectangle + XDrawSegments PolySegment + XDrawString PolyText8 + XDrawString16 PolyText16 + XDrawText PolyText8 + XDrawText16 PolyText16 + XEnableAccessControl SetAccessControl + XFetchBytes GetProperty + XFetchName GetProperty + XFillArc PolyFillArc + XFillArcs PolyFillArc + XFillPolygon FillPoly + XFillRectangle PolyFillRectangle + XFillRectangles PolyFillRectangle + XForceScreenSaver ForceScreenSaver + XFreeColormap FreeColormap + XFreeColors FreeColors + XFreeCursor FreeCursor + XFreeFont CloseFont + XFreeGC FreeGC + XFreePixmap FreePixmap + XGetAtomName GetAtomName + XGetClassHint GetProperty + XGetFontPath GetFontPath + XGetGeometry GetGeometry + XGetIconName GetProperty + XGetIconSizes GetProperty + XGetImage GetImage + XGetInputFocus GetInputFocus + XGetKeyboardControl GetKeyboardControl + XGetKeyboardMapping GetKeyboardMapping + XGetModifierMapping GetModifierMapping + GetMotionEvents + XGetNormalHints GetProperty + XGetPointerControl GetPointerControl + XGetPointerMapping GetPointerMapping + XGetRGBColormaps GetProperty + XGetScreenSaver GetScreenSaver + XGetSelectionOwner GetSelectionOwner + XGetSizeHints GetProperty + XGetTextProperty GetProperty + XGetTransientForHint GetProperty + XGetWMClientMachine GetProperty + XGetWMColormapWindows GetProperty + InternAtom + XGetWMHints GetProperty + XGetWMIconName GetProperty + XGetWMName GetProperty + XGetWMNormalHints GetProperty + XGetWMProtocols GetProperty + InternAtom + XGetWMSizeHints GetProperty + XGetWindowAttributes GetWindowAttributes + GetGeometry + XGetWindowProperty GetProperty + XGetZoomHints GetProperty + XGrabButton GrabButton + XGrabKey GrabKey + XGrabKeyboard GrabKeyboard + XGrabPointer GrabPointer + XGrabServer GrabServer + XIconifyWindow InternAtom + SendEvent + XInitExtension QueryExtension + XInstallColormap InstallColormap + XInternAtom InternAtom + XKillClient KillClient + XListExtensions ListExtensions + XListFonts ListFonts + XListFontsWithInfo ListFontsWithInfo + XListHosts ListHosts + XListInstalledColormaps ListInstalledColormaps + XListProperties ListProperties + XLoadFont OpenFont + XLoadQueryFont OpenFont + QueryFont + XLookupColor LookupColor + XLowerWindow ConfigureWindow + XMapRaised ConfigureWindow + MapWindow + XMapSubwindows MapSubwindows + XMapWindow MapWindow + XMoveResizeWindow ConfigureWindow + XMoveWindow ConfigureWindow + XNoOp NoOperation + XOpenDisplay CreateGC + XParseColor LookupColor + XPutImage PutImage + XQueryBestCursor QueryBestSize + XQueryBestSize QueryBestSize + XQueryBestStipple QueryBestSize + XQueryBestTile QueryBestSize + XQueryColor QueryColors + XQueryColors QueryColors + XQueryExtension QueryExtension + XQueryFont QueryFont + XQueryKeymap QueryKeymap + XQueryPointer QueryPointer + XQueryTextExtents QueryTextExtents + XQueryTextExtents16 QueryTextExtents + XQueryTree QueryTree + XRaiseWindow ConfigureWindow + XReadBitmapFile CreateGC + CreatePixmap + FreeGC + PutImage + XRecolorCursor RecolorCursor + XReconfigureWMWindow ConfigureWindow + SendEvent + XRemoveFromSaveSet ChangeSaveSet + XRemoveHost ChangeHosts + XRemoveHosts ChangeHosts + XReparentWindow ReparentWindow + XResetScreenSaver ForceScreenSaver + XResizeWindow ConfigureWindow + XRestackWindows ConfigureWindow + XRotateBuffers RotateProperties + XRotateWindowProperties RotateProperties + XSelectInput ChangeWindowAttributes + XSendEvent SendEvent + XSetAccessControl SetAccessControl + XSetArcMode ChangeGC + XSetBackground ChangeGC + XSetClassHint ChangeProperty + XSetClipMask ChangeGC + XSetClipOrigin ChangeGC + XSetClipRectangles SetClipRectangles + XSetCloseDownMode SetCloseDownMode + XSetCommand ChangeProperty + XSetDashes SetDashes + XSetFillRule ChangeGC + XSetFillStyle ChangeGC + XSetFont ChangeGC + XSetFontPath SetFontPath + XSetForeground ChangeGC + XSetFunction ChangeGC + XSetGraphicsExposures ChangeGC + XSetIconName ChangeProperty + XSetIconSizes ChangeProperty + XSetInputFocus SetInputFocus + XSetLineAttributes ChangeGC + XSetModifierMapping SetModifierMapping + XSetNormalHints ChangeProperty + XSetPlaneMask ChangeGC + XSetPointerMapping SetPointerMapping + XSetRGBColormaps ChangeProperty + XSetScreenSaver SetScreenSaver + XSetSelectionOwner SetSelectionOwner + XSetSizeHints ChangeProperty + XSetStandardProperties ChangeProperty + XSetState ChangeGC + XSetStipple ChangeGC + XSetSubwindowMode ChangeGC + XSetTextProperty ChangeProperty + XSetTile ChangeGC + XSetTransientForHint ChangeProperty + XSetTSOrigin ChangeGC + XSetWMClientMachine ChangeProperty + XSetWMColormapWindows ChangeProperty + InternAtom + XSetWMHints ChangeProperty + XSetWMIconName ChangeProperty + XSetWMName ChangeProperty + XSetWMNormalHints ChangeProperty + XSetWMProperties ChangeProperty + XSetWMProtocols ChangeProperty + InternAtom + XSetWMSizeHints ChangeProperty + XSetWindowBackground ChangeWindowAttributes + XSetWindowBackgroundPixmap ChangeWindowAttributes + XSetWindowBorder ChangeWindowAttributes + XSetWindowBorderPixmap ChangeWindowAttributes + XSetWindowBorderWidth ConfigureWindow + XSetWindowColormap ChangeWindowAttributes + XSetZoomHints ChangeProperty + XStoreBuffer ChangeProperty + XStoreBytes ChangeProperty + XStoreColor StoreColors + XStoreColors StoreColors + XStoreName ChangeProperty + XStoreNamedColor StoreNamedColor + XSync GetInputFocus + XSynchronize GetInputFocus + XTranslateCoordinates TranslateCoordinates + XUndefineCursor ChangeWindowAttributes + XUngrabButton UngrabButton + XUngrabKey UngrabKey + XUngrabKeyboard UngrabKeyboard + XUngrabPointer UngrabPointer + XUngrabServer UngrabServer + XUninstallColormap UninstallColormap + XUnloadFont CloseFont + XUnmapSubwindows UnmapSubwindows + XUnmapWindow UnmapWindow + XWarpPointer WarpPointer + XWithdrawWindow SendEvent + UnmapWindow + + The following table lists each X protocol request (in + alphabetical order) and the Xlib functions that reference it. + + Table A.2. Xlib functions which use each Protocol Request + Protocol Request Xlib Function + AllocColor XAllocColor + AllocColorCells XAllocColorCells + AllocColorPlanes XAllocColorPlanes + AllocNamedColor XAllocNamedColor + AllowEvents XAllowEvents + Bell XBell + ChangeActivePointerGrab XChangeActivePointerGrab + ChangeGC XChangeGC + XSetArcMode + XSetBackground + XSetClipMask + XSetClipOrigin + XSetFillRule + XSetFillStyle + XSetFont + XSetForeground + XSetFunction + XSetGraphicsExposures + XSetLineAttributes + XSetPlaneMask + XSetState + XSetStipple + XSetSubwindowMode + XSetTile + XSetTSOrigin + ChangeHosts XAddHost + XAddHosts + XRemoveHost + XRemoveHosts + ChangeKeyboardControl XAutoRepeatOff + XAutoRepeatOn + XChangeKeyboardControl + ChangeKeyboardMapping XChangeKeyboardMapping + ChangePointerControl XChangePointerControl + ChangeProperty XChangeProperty + XSetClassHint + XSetCommand + XSetIconName + XSetIconSizes + XSetNormalHints + XSetRGBColormaps + XSetSizeHints + XSetStandardProperties + XSetTextProperty + XSetTransientForHint + XSetWMClientMachine + XSetWMColormapWindows + XSetWMHints + XSetWMIconName + XSetWMName + XSetWMNormalHints + XSetWMProperties + XSetWMProtocols + XSetWMSizeHints + XSetZoomHints + XStoreBuffer + XStoreBytes + XStoreName + ChangeSaveSet XAddToSaveSet + XChangeSaveSet + XRemoveFromSaveSet + ChangeWindowAttributes XChangeWindowAttributes + XDefineCursor + XSelectInput + XSetWindowBackground + XSetWindowBackgroundPixmap + XSetWindowBorder + XSetWindowBorderPixmap + XSetWindowColormap + XUndefineCursor + CirculateWindow XCirculateSubwindowsDown + XCirculateSubwindowsUp + XCirculateSubwindows + ClearArea XClearArea + XClearWindow + CloseFont XFreeFont + XUnloadFont + ConfigureWindow XConfigureWindow + XLowerWindow + XMapRaised + XMoveResizeWindow + XMoveWindow + XRaiseWindow + XReconfigureWMWindow + XResizeWindow + XRestackWindows + XSetWindowBorderWidth + ConvertSelection XConvertSelection + CopyArea XCopyArea + CopyColormapAndFree XCopyColormapAndFree + CopyGC XCopyGC + CopyPlane XCopyPlane + CreateColormap XCreateColormap + CreateCursor XCreatePixmapCursor + CreateGC XCreateGC + XCreateBitmapFromData + XCreatePixmapFromData + XOpenDisplay + XReadBitmapFile + CreateGlyphCursor XCreateFontCursor + XCreateGlyphCursor + CreatePixmap XCreatePixmap + XCreateBitmapFromData + XCreatePixmapFromData + XReadBitmapFile + CreateWindow XCreateSimpleWindow + XCreateWindow + DeleteProperty XDeleteProperty + DestroySubwindows XDestroySubwindows + DestroyWindow XDestroyWindow + FillPoly XFillPolygon + ForceScreenSaver XActivateScreenSaver + XForceScreenSaver + XResetScreenSaver + FreeColormap XFreeColormap + FreeColors XFreeColors + FreeCursor XFreeCursor + FreeGC XFreeGC + XCreateBitmapFromData + XCreatePixmapFromData + XReadBitmapFile + FreePixmap XFreePixmap + GetAtomName XGetAtomName + GetFontPath XGetFontPath + GetGeometry XGetGeometry + XGetWindowAttributes + GetImage XGetImage + GetInputFocus XGetInputFocus + XSync + XSynchronize + GetKeyboardControl XGetKeyboardControl + GetKeyboardMapping XGetKeyboardMapping + GetModifierMapping XGetModifierMapping + GetMotionEvents + GetPointerControl XGetPointerControl + GetPointerMapping XGetPointerMapping + GetProperty XFetchBytes + XFetchName + XGetClassHint + XGetIconName + XGetIconSizes + XGetNormalHints + XGetRGBColormaps + XGetSizeHints + XGetTextProperty + XGetTransientForHint + XGetWMClientMachine + XGetWMColormapWindows + XGetWMHints + XGetWMIconName + XGetWMName + XGetWMNormalHints + XGetWMProtocols + XGetWMSizeHints + XGetWindowProperty + XGetZoomHints + GetSelectionOwner XGetSelectionOwner + GetWindowAttributes XGetWindowAttributes + GrabButton XGrabButton + GrabKey XGrabKey + GrabKeyboard XGrabKeyboard + GrabPointer XGrabPointer + GrabServer XGrabServer + ImageText8 XDrawImageString + ImageText16 XDrawImageString16 + InstallColormap XInstallColormap + InternAtom XGetWMColormapWindows + XGetWMProtocols + XIconifyWindow + XInternAtom + XSetWMColormapWindows + XSetWMProtocols + KillClient XKillClient + ListExtensions XListExtensions + ListFonts XListFonts + ListFontsWithInfo XListFontsWithInfo + ListHosts XListHosts + ListInstalledColormaps XListInstalledColormaps + ListProperties XListProperties + LookupColor XLookupColor + XParseColor + MapSubwindows XMapSubwindows + MapWindow XMapRaised + XMapWindow + NoOperation XNoOp + OpenFont XLoadFont + XLoadQueryFont + PolyArc XDrawArc + XDrawArcs + PolyFillArc XFillArc + XFillArcs + PolyFillRectangle XFillRectangle + XFillRectangles + PolyLine XDrawLines + PolyPoint XDrawPoint + XDrawPoints + PolyRectangle XDrawRectangle + XDrawRectangles + PolySegment XDrawLine + XDrawSegments + PolyText8 XDrawString + XDrawText + PolyText16 XDrawString16 + XDrawText16 + PutImage XPutImage + XCreateBitmapFromData + XCreatePixmapFromData + XReadBitmapFile + QueryBestSize XQueryBestCursor + XQueryBestSize + XQueryBestStipple + XQueryBestTile + QueryColors XQueryColor + XQueryColors + QueryExtension XInitExtension + XQueryExtension + QueryFont XLoadQueryFont + XQueryFont + QueryKeymap XQueryKeymap + QueryPointer XQueryPointer + QueryTextExtents XQueryTextExtents + XQueryTextExtents16 + QueryTree XQueryTree + RecolorCursor XRecolorCursor + ReparentWindow XReparentWindow + RotateProperties XRotateBuffers + XRotateWindowProperties + SendEvent XIconifyWindow + XReconfigureWMWindow + XSendEvent + XWithdrawWindow + SetAccessControl XDisableAccessControl + XEnableAccessControl + XSetAccessControl + SetClipRectangles XSetClipRectangles + SetCloseDownMode XSetCloseDownMode + SetDashes XSetDashes + SetFontPath XSetFontPath + SetInputFocus XSetInputFocus + SetModifierMapping XSetModifierMapping + SetPointerMapping XSetPointerMapping + SetScreenSaver XGetScreenSaver + XSetScreenSaver + SetSelectionOwner XSetSelectionOwner + StoreColors XStoreColor + XStoreColors + StoreNamedColor XStoreNamedColor + TranslateCoordinates XTranslateCoordinates + UngrabButton XUngrabButton + UngrabKey XUngrabKey + UngrabKeyboard XUngrabKeyboard + UngrabPointer XUngrabPointer + UngrabServer XUngrabServer + UninstallColormap XUninstallColormap + UnmapSubwindows XUnmapSubWindows + UnmapWindow XUnmapWindow + XWithdrawWindow + WarpPointer XWarpPointer + +Appendix B. X Font Cursors + + The following are the available cursors that can be used with + XCreateFontCursor. +#define XC_X_cursor 0 #define XC_ll_angle 76 +#define XC_arrow 2 #define XC_lr_angle 78 +#define XC_based_arrow_down 4 #define XC_man 80 +#define XC_based_arrow_up 6 #define XC_middlebutton 82 +#define XC_boat 8 #define XC_mouse 84 +#define XC_bogosity 10 #define XC_pencil 86 +#define XC_bottom_left_corner 12 #define XC_pirate 88 +#define XC_bottom_right_corner 14 #define XC_plus 90 +#define XC_bottom_side 16 #define XC_question_arrow 92 +#define XC_bottom_tee 18 #define XC_right_ptr 94 +#define XC_box_spiral 20 #define XC_right_side 96 +#define XC_center_ptr 22 #define XC_right_tee 98 +#define XC_circle 24 #define XC_rightbutton 100 +#define XC_clock 26 #define XC_rtl_logo 102 +#define XC_coffee_mug 28 #define XC_sailboat 104 +#define XC_cross 30 #define XC_sb_down_arrow 106 +#define XC_cross_reverse 32 #define XC_sb_h_double_arrow 1 +08 +#define XC_crosshair 34 #define XC_sb_left_arrow 110 +#define XC_diamond_cross 36 #define XC_sb_right_arrow 112 +#define XC_dot 38 #define XC_sb_up_arrow 114 +#define XC_dot_box_mask 40 #define XC_sb_v_double_arrow 1 +16 +#define XC_double_arrow 42 #define XC_shuttle 118 +#define XC_draft_large 44 #define XC_sizing 120 +#define XC_draft_small 46 #define XC_spider 122 +#define XC_draped_box 48 #define XC_spraycan 124 +#define XC_exchange 50 #define XC_star 126 +#define XC_fleur 52 #define XC_target 128 +#define XC_gobbler 54 #define XC_tcross 130 +#define XC_gumby 56 #define XC_top_left_arrow 132 +#define XC_hand1 58 #define XC_top_left_corner 134 +#define XC_hand2 60 #define XC_top_right_corner 13 +6 +#define XC_heart 62 #define XC_top_side 138 +#define XC_icon 64 #define XC_top_tee 140 +#define XC_iron_cross 66 #define XC_trek 142 +#define XC_left_ptr 68 #define XC_ul_angle 144 +#define XC_left_side 70 #define XC_umbrella 146 +#define XC_left_tee 72 #define XC_ur_angle 148 +#define XC_leftbutton 74 #define XC_watch 150 + #define XC_xterm 152 + +Appendix C. Extensions + + Table of Contents + + Basic Protocol Support Routines + Hooking into Xlib + + Hooks into the Library + Hooks onto Xlib Data Structures + + GC Caching + Graphics Batching + Writing Extension Stubs + + Requests, Replies, and Xproto.h + Request Format + Starting to Write a Stub Procedure + Locking Data Structures + Sending the Protocol Request and Arguments + Variable Length Arguments + Replies + Synchronous Calling + Allocating and Deallocating Memory + Portability Considerations + Deriving the Correct Extension Opcode + + Because X can evolve by extensions to the core protocol, it is + important that extensions not be perceived as second-class + citizens. At some point, your favorite extensions may be + adopted as additional parts of the X Standard. + + Therefore, there should be little to distinguish the use of an + extension from that of the core protocol. To avoid having to + initialize extensions explicitly in application programs, it is + also important that extensions perform lazy evaluations, + automatically initializing themselves when called for the first + time. + + This appendix describes techniques for writing extensions to + Xlib that will run at essentially the same performance as the + core protocol requests. + +Note + + It is expected that a given extension to X consists of multiple + requests. Defining 10 new features as 10 separate extensions is + a bad practice. Rather, they should be packaged into a single + extension and should use minor opcodes to distinguish the + requests. + + The symbols and macros used for writing stubs to Xlib are + listed in . + +Basic Protocol Support Routines + + The basic protocol requests for extensions are XQueryExtension + and XListExtensions. + + Bool XQueryExtension(Display *display, char *name, int + *major_opcode_return, int *first_event_return, int + *first_error_return); + + display + + Specifies the connection to the X server. + + name + + Specifies the extension name. + + major_opcode_return + + Returns the major opcode. + + first_event_return + + Returns the first event code, if any. + + first_error_return + + Returns the first error code, if any. + + The XQueryExtension function determines if the named extension + is present. If the extension is not present, XQueryExtension + returns False; otherwise, it returns True. If the extension is + present, XQueryExtension returns the major opcode for the + extension to major_opcode_return; otherwise, it returns zero. + Any minor opcode and the request formats are specific to the + extension. If the extension involves additional event types, + XQueryExtension returns the base event type code to + first_event_return; otherwise, it returns zero. The format of + the events is specific to the extension. If the extension + involves additional error codes, XQueryExtension returns the + base error code to first_error_return; otherwise, it returns + zero. The format of additional data in the errors is specific + to the extension. + + If the extension name is not in the Host Portable Character + Encoding the result is implementation-dependent. Uppercase and + lowercase matter; the strings ``thing'', ``Thing'', and + ``thinG'' are all considered different names. + + char **XListExtensions(Display *display, int + *nextensions_return); + + display + + Specifies the connection to the X server. + + nextensions_return + + Returns the number of extensions listed. + + The XListExtensions function returns a list of all extensions + supported by the server. If the data returned by the server is + in the Latin Portable Character Encoding, then the returned + strings are in the Host Portable Character Encoding. Otherwise, + the result is implementation-dependent. + + XFreeExtensionList(char **list); + + list + + Specifies the list of extension names. + + The XFreeExtensionList function frees the memory allocated by + XListExtensions. + +Hooking into Xlib + + These functions allow you to hook into the library. They are + not normally used by application programmers but are used by + people who need to extend the core X protocol and the X library + interface. The functions, which generate protocol requests for + X, are typically called stubs. + + In extensions, stubs first should check to see if they have + initialized themselves on a connection. If they have not, they + then should call XInitExtension to attempt to initialize + themselves on the connection. + + If the extension needs to be informed of GC/font allocation or + deallocation or if the extension defines new event types, the + functions described here allow the extension to be called when + these events occur. + + The XExtCodes structure returns the information from + XInitExtension and is defined in : + +typedef struct _XExtCodes { /* public to extension, cannot be change +d */ + int extension; /* extension number */ + int major_opcode; /* major op-code assigned by server */ + int first_event; /* first event number for the extension +*/ + int first_error; /* first error number for the extension +*/ +} XExtCodes; + + XExtCodes *XInitExtension(Display *display, char *name); + + display + + Specifies the connection to the X server. + + name + + Specifies the extension name. + + The XInitExtension function determines if the named extension + exists. Then, it allocates storage for maintaining the + information about the extension on the connection, chains this + onto the extension list for the connection, and returns the + information the stub implementor will need to access the + extension. If the extension does not exist, XInitExtension + returns NULL. + + If the extension name is not in the Host Portable Character + Encoding, the result is implementation-dependent. Uppercase and + lowercase matter; the strings ``thing'', ``Thing'', and + ``thinG'' are all considered different names. + + The extension number in the XExtCodes structure is needed in + the other calls that follow. This extension number is unique + only to a single connection. + + XExtCodes *XAddExtension(Display *display); + + display + + Specifies the connection to the X server. + + For local Xlib extensions, the XAddExtension function allocates + the XExtCodes structure, bumps the extension number count, and + chains the extension onto the extension list. (This permits + extensions to Xlib without requiring server extensions.) + +Hooks into the Library + + These functions allow you to define procedures that are to be + called when various circumstances occur. The procedures include + the creation of a new GC for a connection, the copying of a GC, + the freeing of a GC, the creating and freeing of fonts, the + conversion of events defined by extensions to and from wire + format, and the handling of errors. + + All of these functions return the previous procedure defined + for this extension. + + int XESetCloseDisplay(Display *display, int extension, int + (*proc)()); + + display + + Specifies the connection to the X server. + + extension + + Specifies the extension number. + + proc + + Specifies the procedure to call when the display is closed. + + The XESetCloseDisplay function defines a procedure to be called + whenever XCloseDisplay is called. It returns any previously + defined procedure, usually NULL. + + When XCloseDisplay is called, your procedure is called with + these arguments: + + int (*proc)(Display *display, XExtCodes *codes); + + int *XESetCreateGC(Display *display, int extension, int + (*proc)()); + + display + + Specifies the connection to the X server. + + extension + + Specifies the extension number. + + proc + + Specifies the procedure to call when a GC is closed. + + The XESetCreateGC function defines a procedure to be called + whenever a new GC is created. It returns any previously defined + procedure, usually NULL. + + When a GC is created, your procedure is called with these + arguments: + + int (*proc)(Display *display, GC gc, XExtCodes *codes); + + int *XESetCopyGC(Display *display, int extension, int + (*proc)()); + + display + + Specifies the connection to the X server. + + extension + + Specifies the extension number. + + proc + + Specifies the procedure to call when GC components are copied. + + The XESetCopyGC function defines a procedure to be called + whenever a GC is copied. It returns any previously defined + procedure, usually NULL. + + When a GC is copied, your procedure is called with these + arguments: + + int (*proc)(Display *display, GC gc, XExtCodes *codes); + + int *XESetFreeGC(Display *display, int extension, int + (*proc)()); + + display + + Specifies the connection to the X server. + + extension + + Specifies the extension number. + + proc + + Specifies the procedure to call when a GC is freed. + + The XESetFreeGC function defines a procedure to be called + whenever a GC is freed. It returns any previously defined + procedure, usually NULL. + + When a GC is freed, your procedure is called with these + arguments: + + int (*proc)(Display *display, GC gc, XExtCodes *codes); + + int *XESetCreateFont(Display *display, int extension, int + (*proc)()); + + display + + Specifies the connection to the X server. + + extension + + Specifies the extension number. + + proc + + Specifies the procedure to call when a font is created. + + The XESetCreateFont function defines a procedure to be called + whenever XLoadQueryFont and XQueryFont are called. It returns + any previously defined procedure, usually NULL. + + When XLoadQueryFont or XQueryFont is called, your procedure is + called with these arguments: + + int (*proc)(Display *display, XFontStruct *fs, XExtCodes + *codes); + + int *XESetFreeFont(Display *display, int extension, int + (*proc)()); + + display + + Specifies the connection to the X server. + + extension + + Specifies the extension number. + + proc + + Specifies the procedure to call when a font is freed. + + The XESetFreeFont function defines a procedure to be called + whenever XFreeFont is called. It returns any previously defined + procedure, usually NULL. + + When XFreeFont is called, your procedure is called with these + arguments: + + int (*proc)(Display *display, XFontStruct *fs, XExtCodes + *codes); + + The XESetWireToEvent and XESetEventToWire functions allow you + to define new events to the library. An XEvent structure always + has a type code (type int) as the first component. This + uniquely identifies what kind of event it is. The second + component is always the serial number (type unsigned long) of + the last request processed by the server. The third component + is always a Boolean (type Bool) indicating whether the event + came from a SendEvent protocol request. The fourth component is + always a pointer to the display the event was read from. The + fifth component is always a resource ID of one kind or another, + usually a window, carefully selected to be useful to toolkit + dispatchers. The fifth component should always exist, even if + the event does not have a natural destination; if there is no + value from the protocol to put in this component, initialize it + to zero. There is an implementation limit such that your host + event structure size cannot be bigger than the size of the + XEvent union of structures. There also is no way to guarantee + that more than 24 elements or 96 characters in the structure + will be fully portable between machines. + + int *XESetWireToEvent(Display *display, int event_number, + Status (*proc)()); + + display + + Specifies the connection to the X server. + + event_number + + Specifies the event code. + + proc + + Specifies the procedure to call when converting an event. + + The XESetWireToEvent function defines a procedure to be called + when an event needs to be converted from wire format (xEvent) + to host format (XEvent). The event number defines which + protocol event number to install a conversion procedure for. + XESetWireToEvent returns any previously defined procedure. You + can replace a core event conversion function with one of your + own, although this is not encouraged. It would, however, allow + you to intercept a core event and modify it before being placed + in the queue or otherwise examined. When Xlib needs to convert + an event from wire format to host format, your procedure is + called with these arguments: + + int (*proc)(Display *display, XEvent *re, xEvent *event); + + Your procedure must return status to indicate if the conversion + succeeded. The re argument is a pointer to where the host + format event should be stored, and the event argument is the + 32-byte wire event structure. In the XEvent structure you are + creating, you must fill in the five required members of the + event structure. You should fill in the type member with the + type specified for the xEvent structure. You should copy all + other members from the xEvent structure (wire format) to the + XEvent structure (host format). Your conversion procedure + should return True if the event should be placed in the queue + or False if it should not be placed in the queue. + + To initialize the serial number component of the event, call + _XSetLastRequestRead with the event and use the return value. + + unsigned long_XSetLastRequestRead(Display *display, + xGenericReply *rep); + + display + + Specifies the connection to the X server. + + rep + + Specifies the wire event structure. + + The _XSetLastRequestRead function computes and returns a + complete serial number from the partial serial number in the + event. + + Status *XESetEventToWire(Display *display, int event_number, + int (*proc)()); + + display + + Specifies the connection to the X server. + + event_number + + Specifies the event code. + + proc + + Specifies the procedure to call when converting an event. + + The XESetEventToWire function defines a procedure to be called + when an event needs to be converted from host format (XEvent) + to wire format (xEvent) form. The event number defines which + protocol event number to install a conversion procedure for. + XESetEventToWire returns any previously defined procedure. It + returns zero if the conversion fails or nonzero otherwise. You + can replace a core event conversion function with one of your + own, although this is not encouraged. It would, however, allow + you to intercept a core event and modify it before being sent + to another client. When Xlib needs to convert an event from + host format to wire format, your procedure is called with these + arguments: + + int (*proc)(Display *display, XEvent *re, xEvent *event); + + The re argument is a pointer to the host format event, and the + event argument is a pointer to where the 32-byte wire event + structure should be stored. You should fill in the type with + the type from the XEvent structure. All other members then + should be copied from the host format to the xEvent structure. + + Bool *XESetWireToError(Display *display, int error_number, Bool + (*proc)()); + + display + + Specifies the connection to the X server. + + error_number + + Specifies the error code. + + proc + + Specifies the procedure to call when an error is received. + + The XESetWireToError function defines a procedure to be called + when an extension error needs to be converted from wire format + to host format. The error number defines which protocol error + code to install the conversion procedure for. XESetWireToError + returns any previously defined procedure. + + Use this function for extension errors that contain additional + error values beyond those in a core X error, when multiple wire + errors must be combined into a single Xlib error, or when it is + necessary to intercept an X error before it is otherwise + examined. + + When Xlib needs to convert an error from wire format to host + format, the procedure is called with these arguments: + + int (*proc)(Display *display, XErrorEvent *he, xError *we); + + The he argument is a pointer to where the host format error + should be stored. The structure pointed at by he is guaranteed + to be as large as an XEvent structure and so can be cast to a + type larger than an XErrorEvent to store additional values. If + the error is to be completely ignored by Xlib (for example, + several protocol error structures will be combined into one + Xlib error), then the function should return False; otherwise, + it should return True. + + int *XESetError(Display *display, int extension, int + (*proc)()); + + display + + Specifies the connection to the X server. + + extension + + Specifies the extension number. + + proc + + Specifies the procedure to call when an error is received. + + Inside Xlib, there are times that you may want to suppress the + calling of the external error handling when an error occurs. + This allows status to be returned on a call at the cost of the + call being synchronous (though most such functions are query + operations, in any case, and are typically programmed to be + synchronous). + + When Xlib detects a protocol error in _XReply, it calls your + procedure with these arguments: + + int (*proc)(Display *display, xError *err, XExtCodes *codes, + int *ret_code); + + The err argument is a pointer to the 32-byte wire format error. + The codes argument is a pointer to the extension codes + structure. The ret_code argument is the return code you may + want _XReply returned to. + + If your procedure returns a zero value, the error is not + suppressed, and the client's error handler is called. (For + further information, see section 11.8.2.) If your procedure + returns nonzero, the error is suppressed, and _XReply returns + the value of ret_code. + + char *XESetErrorString(Display *display, int extension, char + *(*proc)()); + + display + + Specifies the connection to the X server. + + extension + + Specifies the extension number. + + proc + + Specifies the procedure to call to obtain an error string. + + The XGetErrorText function returns a string to the user for an + error. XESetErrorString allows you to define a procedure to be + called that should return a pointer to the error message. The + following is an example. + + int (*proc)(Display *display, int code, XExtCodes *codes, char + *buffer, int nbytes); + + Your procedure is called with the error code for every error + detected. You should copy nbytes of a null-terminated string + containing the error message into buffer. + + void *XESetPrintErrorValues(Display *display, int extension, + void (*proc)()); + + display + + Specifies the connection to the X server. + + extension + + Specifies the extension number. + + proc + + Specifies the procedure to call when an error is printed. + + The XESetPrintErrorValues function defines a procedure to be + called when an extension error is printed, to print the error + values. Use this function for extension errors that contain + additional error values beyond those in a core X error. It + returns any previously defined procedure. + + When Xlib needs to print an error, the procedure is called with + these arguments: + + void (*proc)(Display *display, XErrorEvent *ev, void *fp); + + The structure pointed at by ev is guaranteed to be as large as + an XEvent structure and so can be cast to a type larger than an + XErrorEvent to obtain additional values set by using + XESetWireToError. The underlying type of the fp argument is + system dependent; on a POSIX-compliant system, fp should be + cast to type FILE*. + + int *XESetFlushGC(Display *display, int extension, int + *(*proc)()); + + display + + Specifies the connection to the X server. + + extension + + Specifies the extension number. + + proc + + Specifies the procedure to call when a GC is flushed. + + The procedure set by the XESetFlushGC function has the same + interface as the procedure set by the XESetCopyGC function, but + is called when a GC cache needs to be updated in the server. + + int *XESetCopyGC(Display *display, int extension, int + *(*proc)()); + + display + + Specifies the connection to the X server. + + extension + + Specifies the extension number. + + proc + + Specifies the procedure to call when a buffer is flushed. + + The XESetBeforeFlush function defines a procedure to be called + when data is about to be sent to the server. When data is about + to be sent, your procedure is called one or more times with + these arguments: + + void (*proc)(Display *display, XExtCodes *codes, char *data, + long len); + + The data argument specifies a portion of the outgoing data + buffer, and its length in bytes is specified by the len + argument. Your procedure must not alter the contents of the + data and must not do additional protocol requests to the same + display. + +Hooks onto Xlib Data Structures + + Various Xlib data structures have provisions for extension + procedures to chain extension supplied data onto a list. These + structures are GC, Visual, Screen, ScreenFormat, Display, and + XFontStruct. Because the list pointer is always the first + member in the structure, a single set of procedures can be used + to manipulate the data on these lists. + + The following structure is used in the functions in this + section and is defined in + +typedef struct _XExtData { + int number; /* number returned by XInitExtension */ + struct _XExtData *next; /* next item on list of data for structu +re */ + int (*free_private)(); /* if defined, called to free private * +/ + XPointer private_data; /* data private to this extension. */ +} XExtData; + + When any of the data structures listed above are freed, the + list is walked, and the structure's free procedure (if any) is + called. If free is NULL, then the library frees both the data + pointed to by the private_data member and the structure itself. + +union { Display *display; + GC gc; + Visual *visual; + Screen *screen; + ScreenFormat *pixmap_format; + XFontStruct *font } XEDataObject; + + XExtData **XEHeadOfExtensionList(XEDataObject object); + + object + + Specifies the object. + + The XEHeadOfExtensionList function returns a pointer to the + list of extension structures attached to the specified object. + In concert with XAddToExtensionList, XEHeadOfExtensionList + allows an extension to attach arbitrary data to any of the + structures of types contained in XEDataObject. + + XAddToExtensionList(XExtData **structure, XExtData *ext_data); + + structure + + Specifies the extension list. + + ext_data + + Specifies the extension data structure to add. + + The structure argument is a pointer to one of the data + structures enumerated above. You must initialize + ext_data->number with the extension number before calling this + function. + + XExtData *XFindOnExtensionList(struct_XExtData **structure, int + number); + + structure + + Specifies the extension list. + + number + + Specifies the extension number from XInitExtension. + + The XFindOnExtensionList function returns the first extension + data structure for the extension numbered number. It is + expected that an extension will add at most one extension data + structure to any single data structure's extension data list. + There is no way to find additional structures. + + The XAllocID macro, which allocates and returns a resource ID, + is defined in . + + XAllocID(Display *display); + + display + + Specifies the connection to the X server. + + This macro is a call through the Display structure to an + internal resource ID allocator. It returns a resource ID that + you can use when creating new resources. + + The XAllocIDs macro allocates and returns an array of resource + ID. + + XAllocIDs(Display *display, XID *ids_return, int count); + + display + + Specifies the connection to the X server. + + ids_return + + Returns the resource IDs. + + rep + + Specifies the number of resource IDs requested. + + This macro is a call through the Display structure to an + internal resource ID allocator. It returns resource IDs to the + array supplied by the caller. To correctly handle automatic + reuse of resource IDs, you must call XAllocIDs when requesting + multiple resource IDs. This call might generate protocol + requests. + +GC Caching + + GCs are cached by the library to allow merging of independent + change requests to the same GC into single protocol requests. + This is typically called a write-back cache. Any extension + procedure whose behavior depends on the contents of a GC must + flush the GC cache to make sure the server has up-to-date + contents in its GC. + + The FlushGC macro checks the dirty bits in the library's GC + structure and calls _XFlushGCCache if any elements have + changed. The FlushGC macro is defined as follows: + + FlushGC(Display *display, GC gc); + + display + + Specifies the connection to the X server. + + gc + + Specifies the GC. + + Note that if you extend the GC to add additional resource ID + components, you should ensure that the library stub sends the + change request immediately. This is because a client can free a + resource immediately after using it, so if you only stored the + value in the cache without forcing a protocol request, the + resource might be destroyed before being set into the GC. You + can use the _XFlushGCCache procedure to force the cache to be + flushed. The _XFlushGCCache procedure is defined as follows: + + _XFlushGCCache(Display *display, GC gc); + + display + + Specifies the connection to the X server. + + gc + + Specifies the GC. + +Graphics Batching + + If you extend X to add more poly graphics primitives, you may + be able to take advantage of facilities in the library to allow + back-to-back single calls to be transformed into poly requests. + This may dramatically improve performance of programs that are + not written using poly requests. A pointer to an xReq, called + last_req in the display structure, is the last request being + processed. By checking that the last request type, drawable, + gc, and other options are the same as the new one and that + there is enough space left in the buffer, you may be able to + just extend the previous graphics request by extending the + length field of the request and appending the data to the + buffer. This can improve performance by five times or more in + naive programs. For example, here is the source for the + XDrawPoint stub. (Writing extension stubs is discussed in the + next section.) +#include + +/* precompute the maximum size of batching request allowed */ + +static int size = sizeof(xPolyPointReq) + EPERBATCH * sizeof(xPoint); + +XDrawPoint(dpy, d, gc, x, y) + register Display *dpy; + Drawable d; + GC gc; + int x, y; /* INT16 */ +{ + xPoint *point; + LockDisplay(dpy); + FlushGC(dpy, gc); + { + register xPolyPointReq *req = (xPolyPointReq *) dpy->last_req; + /* if same as previous request, with same drawable, batch requests * +/ + if ( + (req->reqType == X_PolyPoint) + && (req->drawable == d) + && (req->gc == gc->gid) + && (req->coordMode == CoordModeOrigin) + && ((dpy->bufptr + sizeof (xPoint)) <= dpy->bufmax) + && (((char *)dpy->bufptr - (char *)req) < size) ) { + point = (xPoint *) dpy->bufptr; + req->length += sizeof (xPoint) >> 2; + dpy->bufptr += sizeof (xPoint); + } + + else { + GetReqExtra(PolyPoint, 4, req); /* 1 point = 4 bytes */ + req->drawable = d; + req->gc = gc->gid; + req->coordMode = CoordModeOrigin; + point = (xPoint *) (req + 1); + } + point->x = x; + point->y = y; + } + UnlockDisplay(dpy); + SyncHandle(); +} + + To keep clients from generating very long requests that may + monopolize the server, there is a symbol defined in + of EPERBATCH on the number of requests batched. + Most of the performance benefit occurs in the first few merged + requests. Note that FlushGC is called before picking up the + value of last_req, because it may modify this field. + +Writing Extension Stubs + + All X requests always contain the length of the request, + expressed as a 16-bit quantity of 32 bit words. This means that + a single request can be no more than 256K bytes in length. Some + servers may not support single requests of such a length. The + value of dpy->max_request_size contains the maximum length as + defined by the server implementation. For further information, + see X Window System Protocol. + +Requests, Replies, and Xproto.h + + The file contains three sets of definitions that + are of interest to the stub implementor: request names, request + structures, and reply structures. + + You need to generate a file equivalent to for + your extension and need to include it in your stub procedure. + Each stub procedure also must include . + + The identifiers are deliberately chosen in such a way that, if + the request is called X_DoSomething, then its request structure + is xDoSomethingReq, and its reply is xDoSomethingReply. The + GetReq family of macros, defined in , takes + advantage of this naming scheme. + + For each X request, there is a definition in + that looks similar to this: + +#define X_DoSomething 42 + + In your extension header file, this will be a minor opcode, + instead of a major opcode. + +Request Format + + Every request contains an 8-bit major opcode and a 16-bit + length field expressed in units of 4 bytes. Every request + consists of 4 bytes of header (containing the major opcode, the + length field, and a data byte) followed by zero or more + additional bytes of data. The length field defines the total + length of the request, including the header. The length field + in a request must equal the minimum length required to contain + the request. If the specified length is smaller or larger than + the required length, the server should generate a BadLength + error. Unused bytes in a request are not required to be zero. + Extensions should be designed in such a way that long protocol + requests can be split up into smaller requests, if it is + possible to exceed the maximum request size of the server. The + protocol guarantees the maximum request size to be no smaller + than 4096 units (16384 bytes). + + Major opcodes 128 through 255 are reserved for extensions. + Extensions are intended to contain multiple requests, so + extension requests typically have an additional minor opcode + encoded in the second data byte in the request header, but the + placement and interpretation of this minor opcode as well as + all other fields in extension requests are not defined by the + core protocol. Every request is implicitly assigned a sequence + number (starting with one) used in replies, errors, and events. + + Most protocol requests have a corresponding structure typedef + in , which looks like: + +typedef struct _DoSomethingReq { + CARD8 reqType; /* X_DoSomething */ + CARD8 someDatum; /* used differently in different request +s */ + CARD16 length; /* total # of bytes in request, divided +by 4 */ + ... + /* request-specific data */ + ... +} xDoSomethingReq; + + If a core protocol request has a single 32-bit argument, you + need not declare a request structure in your extension header + file. Instead, such requests use the xResourceReq structure in + . This structure is used for any request whose + single argument is a Window, Pixmap, Drawable, GContext, Font, + Cursor, Colormap, Atom, or VisualID. + +typedef struct _ResourceReq { + CARD8 reqType; /* the request type, e.g. X_DoSomething */ + BYTE pad; /* not used */ + CARD16 length; /* 2 (= total # of bytes in request, divided by +4) */ + CARD32 id; /* the Window, Drawable, Font, GContext, etc. */ +} xResourceReq; + + If convenient, you can do something similar in your extension + header file. + + In both of these structures, the reqType field identifies the + type of the request (for example, X_MapWindow or + X_CreatePixmap). The length field tells how long the request is + in units of 4-byte longwords. This length includes both the + request structure itself and any variable-length data, such as + strings or lists, that follow the request structure. Request + structures come in different sizes, but all requests are padded + to be multiples of four bytes long. + + A few protocol requests take no arguments at all. Instead, they + use the xReq structure in , which contains only a + reqType and a length (and a pad byte). + + If the protocol request requires a reply, then + also contains a reply structure typedef: + +typedef struct _DoSomethingReply { + BYTE type; /* always X_Reply */ + BYTE someDatum; /* used differently in different requests */ + CARD16 sequenceNumber; /* # of requests sent so far */ + CARD32 length; /* # of additional bytes, divided by 4 */ + ... + /* request-specific data */ + ... +} xDoSomethingReply; + + Most of these reply structures are 32 bytes long. If there are + not that many reply values, then they contain a sufficient + number of pad fields to bring them up to 32 bytes. The length + field is the total number of bytes in the request minus 32, + divided by 4. This length will be nonzero only if: + * The reply structure is followed by variable-length data, + such as a list or string. + * The reply structure is longer than 32 bytes. + + Only GetWindowAttributesl, QueryFont, QueryKeymap, and + GetKeyboardControl have reply structures longer than 32 bytes + in the core protocol. + + A few protocol requests return replies that contain no data. + does not define reply structures for these. + Instead, they use the xGenericReply structure, which contains + only a type, length, and sequence number (and sufficient + padding to make it 32 bytes long). + +Starting to Write a Stub Procedure + + An Xlib stub procedure should start like this: + +#include " + +XDoSomething (arguments, ... ) +/* argument declarations */ +{ + +register XDoSomethingReq *req; +... + + If the protocol request has a reply, then the variable + declarations should include the reply structure for the + request. The following is an example: + +xDoSomethingReply rep; + +Locking Data Structures + + To lock the display structure for systems that want to support + multithreaded access to a single display connection, each stub + will need to lock its critical section. Generally, this section + is the point from just before the appropriate GetReq call until + all arguments to the call have been stored into the buffer. The + precise instructions needed for this locking depend upon the + machine architecture. Two calls, which are generally + implemented as macros, have been provided. + + LockDisplay(Display *display); + + UnlockDisplay(Display *display); + + display + + Specifies the connection to the X server. + +Sending the Protocol Request and Arguments + + After the variable declarations, a stub procedure should call + one of four macros defined in : GetReq, + GetReqExtra, GetResReq, or GetEmptyReq. All of these macros + take, as their first argument, the name of the protocol request + as declared in except with X_ removed. Each one + declares a Display structure pointer, called dpy, and a pointer + to a request structure, called req, which is of the appropriate + type. The macro then appends the request structure to the + output buffer, fills in its type and length field, and sets req + to point to it. + + If the protocol request has no arguments (for instance, + X_GrabServer), then use GetEmptyReq. + +GetEmptyReq (DoSomething, req); + + If the protocol request has a single 32-bit argument (such as a + Pixmap, Window, Drawable, Atom, and so on), then use GetResReq. + The second argument to the macro is the 32-bit object. + X_MapWindow is a good example. + +GetResReq (DoSomething, rid, req); + + The rid argument is the Pixmap, Window, or other resource ID. + + If the protocol request takes any other argument list, then + call GetReq. After the GetReq, you need to set all the other + fields in the request structure, usually from arguments to the + stub procedure. + +GetReq (DoSomething, req); +/* fill in arguments here */ +req->arg1 = arg1; +req->arg2 = arg2; +... + + A few stub procedures (such as XCreateGC and XCreatePixmap) + return a resource ID to the caller but pass a resource ID as an + argument to the protocol request. Such procedures use the macro + XAllocID to allocate a resource ID from the range of IDs that + were assigned to this client when it opened the connection. + +rid = req->rid = XAllocID(); +... +return (rid); + + Finally, some stub procedures transmit a fixed amount of + variable-length data after the request. Typically, these + procedures (such as XMoveWindow and XSetBackground) are special + cases of more general functions like XMoveResizeWindow and + XChangeGC. These procedures use GetReqExtra, which is the same + as GetReq except that it takes an additional argument (the + number of extra bytes to allocate in the output buffer after + the request structure). This number should always be a multiple + of four. Note that it is possible for req to be set to NULL as + a defensive measure if the requested length exceeds the Xlib's + buffer size (normally 16K). + +Variable Length Arguments + + Some protocol requests take additional variable-length data + that follow the xDoSomethingReq structure. The format of this + data varies from request to request. Some requests require a + sequence of 8-bit bytes, others a sequence of 16-bit or 32-bit + entities, and still others a sequence of structures. + + It is necessary to add the length of any variable-length data + to the length field of the request structure. That length field + is in units of 32-bit longwords. If the data is a string or + other sequence of 8-bit bytes, then you must round the length + up and shift it before adding: + +req->length += (nbytes+3)>>2; + + To transmit variable-length data, use the Data macros. If the + data fits into the output buffer, then this macro copies it to + the buffer. If it does not fit, however, the Data macro calls + _XSend, which transmits first the contents of the buffer and + then your data. The Data macros take three arguments: the + display, a pointer to the beginning of the data, and the number + of bytes to be sent. + + Data(display, (char *) data, nbytes); + + Data16(display, (short *) data, nbytes); + + Data32(display, (long *) data, nbytes); + + Data, Data16, and Data32 are macros that may use their last + argument more than once, so that argument should be a variable + rather than an expression such as ``nitems*sizeof(item)''. You + should do that kind of computation in a separate statement + before calling them. Use the appropriate macro when sending + byte, short, or long data. + + If the protocol request requires a reply, then call the + procedure _XSend instead of the Data macro. _XSend takes the + same arguments, but because it sends your data immediately + instead of copying it into the output buffer (which would later + be flushed anyway by the following call on _XReply), it is + faster. + +Replies + + If the protocol request has a reply, then call _XReply after + you have finished dealing with all the fixed-length and + variable-length arguments. _XReply flushes the output buffer + and waits for an xReply packet to arrive. If any events arrive + in the meantime, _XReply places them in the queue for later + use. + + Status _XReply(Display *display, xReply *rep, int extra, Bool + discard); + + display + + Specifies the connection to the X server. + + rep + + Specifies the reply structure. + + extra + + Specifies the number of 32-bit words expected after the replay. + + discard + + Specifies if any data beyond that specified in the extra + argument should be discarded. + + The _XReply function waits for a reply packet and copies its + contents into the specified rep. _XReply handles error and + event packets that occur before the reply is received. _XReply + takes four arguments: + * A Display * structure + * A pointer to a reply structure (which must be cast to an + xReply *) + * The number of additional 32-bit words (beyond sizeof( + xReply) = 32 bytes) in the reply structure + * A Boolean that indicates whether _XReply is to discard any + additional bytes beyond those it was told to read + + Because most reply structures are 32 bytes long, the third + argument is usually 0. The only core protocol exceptions are + the replies to GetWindowAttributesl, QueryFont, QueryKeymap, + and GetKeyboardControl, which have longer replies. + + The last argument should be False if the reply structure is + followed by additional variable-length data (such as a list or + string). It should be True if there is not any variable-length + data. This last argument is provided for upward-compatibility + reasons to allow a client to communicate properly with a + hypothetical later version of the server that sends more data + than the client expected. For example, some later version of + GetWindowAttributesl might use a larger, but compatible, + xGetWindowAttributesReply that contains additional attribute + data at the end. _XReply returns True if it received a reply + successfully or False if it received any sort of error. + + For a request with a reply that is not followed by + variable-length data, you write something like: + +_XReply(display, (xReply *)&rep, 0, True); +*ret1 = rep.ret1; +*ret2 = rep.ret2; +*ret3 = rep.ret3; +... +UnlockDisplay(dpy); +SyncHandle(); +return (rep.ret4); +} + + If there is variable-length data after the reply, change the + True to False, and use the appropriate _XRead function to read + the variable-length data. + + _XRead(Display *display, char *data_return, long nbytes); + + display + + Specifies the connection to the X server. + + data_return + + Specifies the buffer. + + nbytes + + Specifies the number of bytes required. + + The _XRead function reads the specified number of bytes into + data_return. + + _XRead16(Display *display, short *data_return, long nbytes); + + display + + Specifies the connection to the X server. + + data_return + + Specifies the buffer. + + nbytes + + Specifies the number of bytes required. + + The _XRead16 function reads the specified number of bytes, + unpacking them as 16-bit quantities, into the specified array + as shorts. + + _XRead32(Display *display, long *data_return, long nbytes); + + display + + Specifies the connection to the X server. + + data_return + + Specifies the buffer. + + nbytes + + Specifies the number of bytes required. + + The _XRead32 function reads the specified number of bytes, + unpacking them as 32-bit quantities, into the specified array + as longs. + + _XRead16Pad(Display *display, short *data_return, long nbytes); + + display + + Specifies the connection to the X server. + + data_return + + Specifies the buffer. + + nbytes + + Specifies the number of bytes required. + + The _XRead16Pad function reads the specified number of bytes, + unpacking them as 16-bit quantities, into the specified array + as shorts. If the number of bytes is not a multiple of four, + _XRead16Pad reads and discards up to two additional pad bytes. + + _XReadPad(Display *display, char *data_return, long nbytes); + + display + + Specifies the connection to the X server. + + data_return + + Specifies the buffer. + + nbytes + + Specifies the number of bytes required. + + The _XReadPad function reads the specified number of bytes into + data_return. If the number of bytes is not a multiple of four, + _XReadPad reads and discards up to three additional pad bytes. + + Each protocol request is a little different. For further + information, see the Xlib sources for examples. + +Synchronous Calling + + Each procedure should have a call, just before returning to the + user, to a macro called SyncHandle. If synchronous mode is + enabled (see XSynchronize), the request is sent immediately. + The library, however, waits until any error the procedure could + generate at the server has been handled. + +Allocating and Deallocating Memory + + To support the possible reentry of these procedures, you must + observe several conventions when allocating and deallocating + memory, most often done when returning data to the user from + the window system of a size the caller could not know in + advance (for example, a list of fonts or a list of extensions). + The standard C library functions on many systems are not + protected against signals or other multithreaded uses. The + following analogies to standard I/O library functions have been + defined: + + These should be used in place of any calls you would make to + the normal C library functions. + + If you need a single scratch buffer inside a critical section + (for example, to pack and unpack data to and from the wire + protocol), the general memory allocators may be too expensive + to use (particularly in output functions, which are performance + critical). The following function returns a scratch buffer for + use within a critical section: + + char *_XAllocScratch(Display *display, unsigned long nbytes); + + display + + Specifies the connection to the X server. + + nbytes + + Specifies the number of bytes required. + + This storage must only be used inside of a critical section of + your stub. The returned pointer cannot be assumed valid after + any call that might permit another thread to execute inside + Xlib. For example, the pointer cannot be assumed valid after + any use of the GetReq or Data families of macros, after any use + of _XReply, or after any use of the _XSend or _XRead families + of functions. + + The following function returns a scratch buffer for use across + critical sections: + + char *_XAllocTemp(Display *display, unsigned long nbytes); + + display + + Specifies the connection to the X server. + + nbytes + + Specifies the number of bytes required. + + This storage can be used across calls that might permit another + thread to execute inside Xlib. The storage must be explicitly + returned to Xlib. The following function returns the storage: + + void _XFreeTemp(Display *display, char *buf, unsigned long + nbytes); + + display + + Specifies the connection to the X server. + + buf + + Specifies the buffer to return. + + nbytes + + Specifies the size of the buffer. + + You must pass back the same pointer and size that were returned + by _XAllocTemp. + +Portability Considerations + + Many machine architectures do not correctly or efficiently + access data at unaligned locations; their compilers pad out + structures to preserve this characteristic. Many other machines + capable of unaligned references pad inside of structures as + well to preserve alignment, because accessing aligned data is + usually much faster. Because the library and the server use + structures to access data at arbitrary points in a byte stream, + all data in request and reply packets must be naturally + aligned; that is, 16-bit data starts on 16-bit boundaries in + the request and 32-bit data on 32-bit boundaries. All requests + must be a multiple of 32 bits in length to preserve the natural + alignment in the data stream. You must pad structures out to + 32-bit boundaries. Pad information does not have to be zeroed + unless you want to preserve such fields for future use in your + protocol requests, but it is recommended to zero it to avoid + inadvertant data leakage and improve compressability. Floating + point varies radically between machines and should be avoided + completely if at all possible. + + This code may run on machines with 16-bit ints. So, if any + integer argument, variable, or return value either can take + only nonnegative values or is declared as a CARD16 in the + protocol, be sure to declare it as unsigned int and not as int. + (This, of course, does not apply to Booleans or enumerations.) + + Similarly, if any integer argument or return value is declared + CARD32 in the protocol, declare it as an unsigned long and not + as int or long. This also goes for any internal variables that + may take on values larger than the maximum 16-bit unsigned int. + + The library has always assumed that a char is 8 bits, a short + is 16 bits, an int is 16 or 32 bits, and a long is 32 bits. + Unfortunately, this assumption remains on machines where a long + can hold 64-bits, and many functions and structures require + unnecessarily large fields to avoid breaking compatibility with + existing code. Special care must be taken with arrays of values + that are transmitted in the protocol as CARD32 or INT32 but + have to be converted to arrays of 64-bit long when passed to or + from client applications. + + The PackData macro is a half-hearted attempt to deal with the + possibility of 32 bit shorts. However, much more work is needed + to make this work properly. + +Deriving the Correct Extension Opcode + + The remaining problem a writer of an extension stub procedure + faces that the core protocol does not face is to map from the + call to the proper major and minor opcodes. While there are a + number of strategies, the simplest and fastest is outlined + below. + * Declare an array of pointers, _NFILE long (this is normally + found in and is the number of file descriptors + supported on the system) of type XExtCodes. Make sure these + are all initialized to NULL. + * When your stub is entered, your initialization test is just + to use the display pointer passed in to access the file + descriptor and an index into the array. If the entry is + NULL, then this is the first time you are entering the + procedure for this display. Call your initialization + procedure and pass to it the display pointer. + * Once in your initialization procedure, call XInitExtension; + if it succeeds, store the pointer returned into this array. + Make sure to establish a close display handler to allow you + to zero the entry. Do whatever other initialization your + extension requires. (For example, install event handlers + and so on.) Your initialization procedure would normally + return a pointer to the XExtCodes structure for this + extension, which is what would normally be found in your + array of pointers. + * After returning from your initialization procedure, the + stub can now continue normally, because it has its major + opcode safely in its hand in the XExtCodes structure. + +Appendix D. Compatibility Functions + + Table of Contents + + X Version 11 Compatibility Functions + + Setting Standard Properties + Setting and Getting Window Sizing Hints + Getting and Setting an XStandardColormap Structure + Parsing Window Geometry + Getting the X Environment Defaults + + X Version 10 Compatibility Functions + + Drawing and Filling Polygons and Curves + Associating User Data with a Value + + The X Version 11 and X Version 10 functions discussed in this + appendix are obsolete, have been superseded by newer X Version + 11 functions, and are maintained for compatibility reasons + only. + +X Version 11 Compatibility Functions + + You can use the X Version 11 compatibility functions to: + * Set standard properties + * Set and get window sizing hints + * Set and get an XStandardColormap structure + * Parse window geometry + * Get X environment defaults + +Setting Standard Properties + + To specify a minimum set of properties describing the simplest + application, use XSetStandardProperties. This function has been + superseded by XSetWMProperties and sets all or portions of the + WM_NAME, WM_ICON_NAME, WM_HINTS, WM_COMMAND, and + WM_NORMAL_HINTS properties. + + XSetStandardProperties(Display *display, Window w, char + *window_name, char *icon_name, Pixmap icon_pixmap, char **argv, + int argc, XSizeHints *hints); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + window_name + + Specifies the window name, which should be a null-terminated + string. + + icon_name + + Specifies the icon name, which should be a null-terminated + string. + + icon_pixmap + + Specifies the bitmap that is to be used for the icon or None. + + argv + + Specifies the application's argument list. + + argc + + Specifies the number of arguments. + + hints + + Specifies a pointer to the size hints for the window in its + normal state. + + The XSetStandardProperties function provides a means by which + simple applications set the most essential properties with a + single call. XSetStandardProperties should be used to give a + window manager some information about your program's + preferences. It should not be used by applications that need to + communicate more information than is possible with + XSetStandardProperties. (Typically, argv is the argv array of + your main program.) If the strings are not in the Host Portable + Character Encoding, the result is implementation-dependent. + + XSetStandardProperties can generate BadAlloc and BadWindow + errors. + +Setting and Getting Window Sizing Hints + + Xlib provides functions that you can use to set or get window + sizing hints. The functions discussed in this section use the + flags and the XSizeHints structure, as defined in the + header file and use the WM_NORMAL_HINTS property. + + To set the size hints for a given window in its normal state, + use XSetNormalHints. This function has been superseded by + XSetWMNormalHints. + + XSetNormalHints(Display *display, Window w, XSizeHints *hints); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + hints + + Specifies a pointer to the size hints for the window in its + normal state. + + The XSetNormalHints function sets the size hints structure for + the specified window. Applications use XSetNormalHints to + inform the window manager of the size or position desirable for + that window. In addition, an application that wants to move or + resize itself should call XSetNormalHints and specify its new + desired location and size as well as making direct Xlib calls + to move or resize. This is because window managers may ignore + redirected configure requests, but they pay attention to + property changes. + + To set size hints, an application not only must assign values + to the appropriate members in the hints structure but also must + set the flags member of the structure to indicate which + information is present and where it came from. A call to + XSetNormalHints is meaningless, unless the flags member is set + to indicate which members of the structure have been assigned + values. + + XSetNormalHints can generate BadAlloc and BadWindow errors. + + To return the size hints for a window in its normal state, use + XGetNormalHints. This function has been superseded by + XGetWMNormalHints. + + Status XGetNormalHints(Display *display, Window w, XSizeHints + *hints_return); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + hints_return + + Returns the size hints for the window in its normal state. + + The XGetNormalHints function returns the size hints for a + window in its normal state. It returns a nonzero status if it + succeeds or zero if the application specified no normal size + hints for this window. + + XGetNormalHints can generate a BadWindow error. + + The next two functions set and read the WM_ZOOM_HINTS property. + + To set the zoom hints for a window, use XSetZoomHints. This + function is no longer supported by the Inter-Client + Communication Conventions Manual. + + XSetZoomHints(Display *display, Window w, XSizeHints *zhints); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + zhints + + Specifies a pointer to the zoom hints. + + Many window managers think of windows in one of three states: + iconic, normal, or zoomed. The XSetZoomHints function provides + the window manager with information for the window in the + zoomed state. + + XSetZoomHints can generate BadAlloc and BadWindow errors. + + To read the zoom hints for a window, use XGetZoomHints. This + function is no longer supported by the Inter-Client + Communication Conventions Manual. + + Status XGetZoomHints(Display *display, Window w, XSizeHints + *zhints_return); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + zhints_return + + Returns the zoom hints. + + The XGetZoomHints function returns the size hints for a window + in its zoomed state. It returns a nonzero status if it succeeds + or zero if the application specified no zoom size hints for + this window. + + XGetZoomHints can generate a BadWindow error. + + To set the value of any property of type WM_SIZE_HINTS, use + XSetSizeHints. This function has been superseded by + XSetWMSizeHints. + + XSetSizeHints(Display *display, Window w, XSizeHints *hints, + Atom property); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + hints + + Specifies a pointer to the size hints. + + property + + Specifies the property name. + + The XSetSizeHints function sets the XSizeHints structure for + the named property and the specified window. This is used by + XSetNormalHints and XSetZoomHints and can be used to set the + value of any property of type WM_SIZE_HINTS. Thus, it may be + useful if other properties of that type get defined. + + XSetSizeHints can generate BadAlloc, BadAtom, and BadWindow + errors. + + To read the value of any property of type WM_SIZE_HINTS, use + XGetSizeHints. This function has been superseded by + XGetWMSizeHints. + + Status XGetSizeHints(Display *display, Window w, XSizeHints + *hints_return, Atom property); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + hints_return + + Returns the size hints. + + property + + Specifies the property name. + + The XGetSizeHints function returns the XSizeHints structure for + the named property and the specified window. This is used by + XGetNormalHints and XGetZoomHints. It also can be used to + retrieve the value of any property of type WM_SIZE_HINTS. Thus, + it may be useful if other properties of that type get defined. + XGetSizeHints returns a nonzero status if a size hint was + defined or zero otherwise. + + XGetSizeHints can generate BadAtom and BadWindow errors. + +Getting and Setting an XStandardColormap Structure + + To get the XStandardColormap structure associated with one of + the described atoms, use XGetStandardColormap. This function + has been superseded by XGetRGBColormaps. + + Status XGetStandardColormap(Display *display, Window w, + XStandardColormap *colormap_return, Atom property); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + colormap_return + + Returns the colormap associated with the specified atom. + + property + + Specifies the property name. + + The XGetStandardColormap function returns the colormap + definition associated with the atom supplied as the property + argument. XGetStandardColormap returns a nonzero status if + successful and zero otherwise. For example, to fetch the + standard GrayScale colormap for a display, you use + XGetStandardColormap with the following syntax: +XGetStandardColormap(dpy, DefaultRootWindow(dpy), &cmap, XA_RGB_GRAY_MAP +); + + See section 14.3 for the semantics of standard colormaps. + + XGetStandardColormap can generate BadAtom and BadWindow errors. + + To set a standard colormap, use XSetStandardColormap. This + function has been superseded by XSetRGBColormaps. + + XSetStandardColormap(Display *display, Window w, + XStandardColormap *colormap, Atom property); + + display + + Specifies the connection to the X server. + + w + + Specifies the window. + + colormap + + Specifies the colormap. + + property + + Specifies the property name. + + The XSetStandardColormap function usually is only used by + window or session managers. + + XSetStandardColormap can generate BadAlloc, BadAtom, + BadDrawable, and BadWindow errors. + +Parsing Window Geometry + + To parse window geometry given a user-specified position and a + default position, use XGeometry. This function has been + superseded by XWMGeometry. + + int XGeometry(Display *display, int screen, char *position, + char *default_position, unsigned int bwidth, unsigned int + fwidth, unsigned int fheight, int xadder, int yadder, int + *x_return, int *y_return, int *width_return, int + *height_return); + + display + + Specifies the connection to the X server. + + screen + + Specifies the screen. + + position + + default_position + + Specify the geometry specifications. + + bwidth + + Specifies the border width. + + fheight + + fwidth + + Specify the font height and width in pixels (increment size). + + xadder + + yadder + + Specify additional interior padding needed in the window. + + x_return + + y_return + + Return the x and y offsets. + + width_return + + height_return + + Return the width and height determined. + + You pass in the border width (bwidth), size of the increments + fwidth and fheight (typically font width and height), and any + additional interior space (xadder and yadder) to make it easy + to compute the resulting size. The XGeometry function returns + the position the window should be placed given a position and a + default position. XGeometry determines the placement of a + window using a geometry specification as specified by + XParseGeometry and the additional information about the window. + Given a fully qualified default geometry specification and an + incomplete geometry specification, XParseGeometry returns a + bitmask value as defined above in the XParseGeometry call, by + using the position argument. + + The returned width and height will be the width and height + specified by default_position as overridden by any + user-specified position. They are not affected by fwidth, + fheight, xadder, or yadder. The x and y coordinates are + computed by using the border width, the screen width and + height, padding as specified by xadder and yadder, and the + fheight and fwidth times the width and height from the geometry + specifications. + +Getting the X Environment Defaults + + The XGetDefault function provides a primitive interface to the + resource manager facilities discussed in chapter 15. It is only + useful in very simple applications. + + char *XGetDefault(Display *display, char *program, char + *option); + + display + + Specifies the connection to the X server. + + program + + Specifies the program name for the Xlib defaults (usually + argv[0] of the main program). + + option + + Specifies the option name. + + The XGetDefault function returns the value of the resource + prog.option, where prog is the program argument with the + directory prefix removed and option must be a single component. + Note that multilevel resources cannot be used with XGetDefault. + The class "Program.Name" is always used for the resource + lookup. If the specified option name does not exist for this + program, XGetDefault returns NULL. The strings returned by + XGetDefault are owned by Xlib and should not be modified or + freed by the client. + + If a database has been set with XrmSetDatabase, that database + is used for the lookup. Otherwise, a database is created and is + set in the display (as if by calling XrmSetDatabase). The + database is created in the current locale. To create a + database, XGetDefault uses resources from the RESOURCE_MANAGER + property on the root window of screen zero. If no such property + exists, a resource file in the user's home directory is used. + On a POSIX-conformant system, this file is "$HOME/.Xdefaults". + After loading these defaults, XGetDefault merges additional + defaults specified by the XENVIRONMENT environment variable. If + XENVIRONMENT is defined, it contains a full path name for the + additional resource file. If XENVIRONMENT is not defined, + XGetDefault looks for "$HOME/.Xdefaults-name" , where name + specifies the name of the machine on which the application is + running. + +X Version 10 Compatibility Functions + + You can use the X Version 10 compatibility functions to: + * Draw and fill polygons and curves + * Associate user data with a value + +Drawing and Filling Polygons and Curves + + Xlib provides functions that you can use to draw or fill + arbitrary polygons or curves. These functions are provided + mainly for compatibility with X Version 10 and have no server + support. That is, they call other Xlib functions, not the + server directly. Thus, if you just have straight lines to draw, + using XDrawLines or XDrawSegments is much faster. + + The functions discussed here provide all the functionality of + the X Version 10 functions XDraw, XDrawFilled, XDrawPatterned, + XDrawDashed, and XDrawTiled. They are as compatible as possible + given X Version 11's new line-drawing functions. One thing to + note, however, is that VertexDrawLastPoint is no longer + supported. Also, the error status returned is the opposite of + what it was under X Version 10 (this is the X Version 11 + standard error status). XAppendVertex and XClearVertexFlag from + X Version 10 also are not supported. + + Just how the graphics context you use is set up actually + determines whether you get dashes or not, and so on. Lines are + properly joined if they connect and include the closing of a + closed figure (see XDrawLines). The functions discussed here + fail (return zero) only if they run out of memory or are passed + a Vertex list that has a Vertex with VertexStartClosed set that + is not followed by a Vertex with VertexEndClosed set. + + To achieve the effects of the X Version 10 XDraw, XDrawDashed, + and XDrawPatterned, use XDraw. + + #include + + Status XDraw(Display *display, Drawable d, GC gc, Vertex + *vlist, int vcount); + + display + + Specifies the connection to the X server. + + d + + Specifies the drawable. + + gc + + Specifies the GC. + + vlist + + Specifies a pointer to the list of vertices that indicate what + to draw. + + vcount + + Specifies how many vertices are in vlist. + + The XDraw function draws an arbitrary polygon or curve. The + figure drawn is defined by the specified list of vertices + (vlist). The points are connected by lines as specified in the + flags in the vertex structure. + + Each Vertex, as defined in , is a structure with the + following members: +typedef struct _Vertex { + short x,y; + unsigned short flags; +} Vertex; + + The x and y members are the coordinates of the vertex that are + relative to either the upper left inside corner of the drawable + (if VertexRelative is zero) or the previous vertex (if + VertexRelative is one). + + The flags, as defined in , are as follows: +VertexRelative 0x0001 /* else absolute */ +VertexDontDraw 0x0002 /* else draw */ +VertexCurved 0x0004 /* else straight */ +VertexStartClosed 0x0008 /* else not */ +VertexEndClosed 0x0010 /* else not */ + + * If VertexRelative is not set, the coordinates are absolute + (that is, relative to the drawable's origin). The first + vertex must be an absolute vertex. + * If VertexDontDraw is one, no line or curve is drawn from + the previous vertex to this one. This is analogous to + picking up the pen and moving to another place before + drawing another line. + * If VertexCurved is one, a spline algorithm is used to draw + a smooth curve from the previous vertex through this one to + the next vertex. Otherwise, a straight line is drawn from + the previous vertex to this one. It makes sense to set + VertexCurved to one only if a previous and next vertex are + both defined (either explicitly in the array or through the + definition of a closed curve). + * It is permissible for VertexDontDraw bits and VertexCurved + bits both to be one. This is useful if you want to define + the previous point for the smooth curve but do not want an + actual curve drawing to start until this point. + * If VertexStartClosed is one, then this point marks the + beginning of a closed curve. This vertex must be followed + later in the array by another vertex whose effective + coordinates are identical and that has a VertexEndClosed + bit of one. The points in between form a cycle to determine + predecessor and successor vertices for the spline + algorithm. + + This function uses these GC components: function, plane-mask, + line-width, line-style, cap-style, join-style, fill-style, + subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. It + also uses these GC mode-dependent components: foreground, + background, tile, stipple, tile-stipple-x-origin, + tile-stipple-y-origin, dash-offset, and dash-list. + + To achieve the effects of the X Version 10 XDrawTiled and + XDrawFilled, use XDrawFilled. + + #include + + Status XDrawFilled(Display *display, Drawable d, GC gc, Vertex + *vlist, int vcount); + + display + + Specifies the connection to the X server. + + d + + Specifies the drawable. + + gc + + Specifies the GC. + + vlist + + Specifies a pointer to the list of vertices that indicate what + to draw. + + vcount + + Specifies how many vertices are in vlist. + + The XDrawFilled function draws arbitrary polygons or curves and + then fills them. + + This function uses these GC components: function, plane-mask, + line-width, line-style, cap-style, join-style, fill-style, + subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. It + also uses these GC mode-dependent components: foreground, + background, tile, stipple, tile-stipple-x-origin, + tile-stipple-y-origin, dash-offset, dash-list, fill-style, and + fill-rule. + +Associating User Data with a Value + + These functions have been superseded by the context management + functions (see section 16.10). It is often necessary to + associate arbitrary information with resource IDs. Xlib + provides the XAssocTable functions that you can use to make + such an association. Application programs often need to be able + to easily refer to their own data structures when an event + arrives. The XAssocTable system provides users of the X library + with a method for associating their own data structures with X + resources (Pixmaps, Fonts, Windows, and so on). + + An XAssocTable can be used to type X resources. For example, + the user may want to have three or four types of windows, each + with different properties. This can be accomplished by + associating each X window ID with a pointer to a window + property data structure defined by the user. A generic type has + been defined in the X library for resource IDs. It is called an + XID. + + There are a few guidelines that should be observed when using + an XAssocTable : + * All XIDs are relative to the specified display. + * Because of the hashing scheme used by the association + mechanism, the following rules for determining the size of + a XAssocTable should be followed. Associations will be made + and looked up more efficiently if the table size (number of + buckets in the hashing system) is a power of two and if + there are not more than 8 XIDs per bucket. + + To return a pointer to a new XAssocTable, use + XCreateAssocTable. + + XAssocTable *XCreateAssocTable(int size); + + size + + Specifies the number of buckets in the hash system of + XAssocTable. + + The size argument specifies the number of buckets in the hash + system of XAssocTable. For reasons of efficiency the number of + buckets should be a power of two. Some size suggestions might + be: use 32 buckets per 100 objects, and a reasonable maximum + number of objects per buckets is 8. If an error allocating + memory for the XAssocTable occurs, a NULL pointer is returned. + + To create an entry in a given XAssocTable, use XMakeAssoc. + + XMakeAssoc(Display *display, XAssocTable *table, XID x_id, char + *data); + + display + + Specifies the connection to the X server. + + table + + Specifies the assoc table. + + x_id + + Specifies the X resource ID. + + data + + Specifies the data to be associated with the X resource ID. + + The XMakeAssoc function inserts data into an XAssocTable keyed + on an XID. Data is inserted into the table only once. Redundant + inserts are ignored. The queue in each association bucket is + sorted from the lowest XID to the highest XID. + + To obtain data from a given XAssocTable, use XLookUpAssoc. + + char *XLookUpAssoc(Display *display, XAssocTable *table, XID + x_id); + + display + + Specifies the connection to the X server. + + table + + Specifies the assoc table. + + x_id + + Specifies the X resource ID. + + The XLookUpAssoc function retrieves the data stored in an + XAssocTable by its XID. If an appropriately matching XID can be + found in the table, XLookUpAssoc returns the data associated + with it. If the x_id cannot be found in the table, it returns + NULL. + + To delete an entry from a given XAssocTable, use XDeleteAssoc. + + XDeleteAssoc(Display *display, XAssocTable *table, XID x_id); + + display + + Specifies the connection to the X server. + + table + + Specifies the assoc table. + + x_id + + Specifies the X resource ID. + + The XDeleteAssoc function deletes an association in an + XAssocTable keyed on its XID. Redundant deletes (and deletes of + nonexistent XIDs) are ignored. Deleting associations in no way + impairs the performance of an XAssocTable. + + To free the memory associated with a given XAssocTable, use + XDestroyAssocTable. + + XDestroyAssocTable(XAssocTable *table); + + table + + Specifies the assoc table. + +Glossary + + Access control list + X maintains a list of hosts from which client programs + can be run. By default, only programs on the local host + and hosts specified in an initial list read by the + server can use the display. This access control list can + be changed by clients on the local host. Some server + implementations can also implement other authorization + mechanisms in addition to or in place of this mechanism. + The action of this mechanism can be conditional based on + the authorization protocol name and data received by the + server at connection setup. + + Active grab + A grab is active when the pointer or keyboard is + actually owned by the single grabbing client. + + Ancestors + If W is an inferior of A, then A is an ancestor of W. + + Atom + An atom is a unique ID corresponding to a string name. + Atoms are used to identify properties, types, and + selections. + + Background + An InputOutput window can have a background, which is + defined as a pixmap. When regions of the window have + their contents lost or invalidated, the server + automatically tiles those regions with the background. + + Backing store + When a server maintains the contents of a window, the + pixels saved off-screen are known as a backing store. + + Base font name + A font name used to select a family of fonts whose + members may be encoded in various charsets. The + CharSetRegistry and CharSetEncoding fields of an XLFD + name identify the charset of the font. A base font name + may be a full XLFD name, with all fourteen '-' + delimiters, or an abbreviated XLFD name containing only + the first 12 fields of an XLFD name, up to but not + including CharSetRegistry, with or without the + thirteenth '-', or a non-XLFD name. Any XLFD fields may + contain wild cards. + + When creating an XFontSet, Xlib accepts from the client + a list of one or more base font names which select one + or more font families. They are combined with charset + names obtained from the encoding of the locale to load + the fonts required to render text. + + Bit gravity + When a window is resized, the contents of the window are + not necessarily discarded. It is possible to request + that the server relocate the previous contents to some + region of the window (though no guarantees are made). + This attraction of window contents for some location of + a window is known as bit gravity. + + Bit plane + When a pixmap or window is thought of as a stack of + bitmaps, each bitmap is called a bit plane or plane. + + Bitmap + A bitmap is a pixmap of depth one. + + Border + An InputOutput window can have a border of equal + thickness on all four sides of the window. The contents + of the border are defined by a pixmap, and the server + automatically maintains the contents of the border. + Exposure events are never generated for border regions. + + Button grabbing + Buttons on the pointer can be passively grabbed by a + client. When the button is pressed, the pointer is then + actively grabbed by the client. + + Byte order + For image (pixmap/bitmap) data, the server defines the + byte order, and clients with different native byte + ordering must swap bytes as necessary. For all other + parts of the protocol, the client defines the byte + order, and the server swaps bytes as necessary. + + Character + A member of a set of elements used for the organization, + control, or representation of text (ISO2022, as adapted + by XPG3). Note that in ISO2022 terms, a character is not + bound to a coded value until it is identified as part of + a coded character set. + + Character glyph + The abstract graphical symbol for a character. Character + glyphs may or may not map one-to-one to font glyphs, and + may be context-dependent, varying with the adjacent + characters. Multiple characters may map to a single + character glyph. + + Character set + A collection of characters. + + Charset + An encoding with a uniform, state-independent mapping + from characters to codepoints. A coded character set. + + For display in X, there can be a direct mapping from a + charset to one font, if the width of all characters in + the charset is either one or two bytes. A text string + encoded in an encoding such as Shift-JIS cannot be + passed directly to the X server, because the text + imaging requests accept only single-width charsets + (either 8 or 16 bits). Charsets which meet these + restrictions can serve as ``font charsets''. Font + charsets strictly speaking map font indices to font + glyphs, not characters to character glyphs. + + Note that a single font charset is sometimes used as the + encoding of a locale, for example, ISO8859-1. + + Children + The children of a window are its first-level subwindows. + + Class + Windows can be of different classes or types. See the + entries for InputOnly and InputOutput windows for + further information about valid window types. + + Client + An application program connects to the window system + server by some interprocess communication (IPC) path, + such as a TCP connection or a shared memory buffer. This + program is referred to as a client of the window system + server. More precisely, the client is the IPC path + itself. A program with multiple paths open to the server + is viewed as multiple clients by the protocol. Resource + lifetimes are controlled by connection lifetimes, not by + program lifetimes. + + Clipping region + In a graphics context, a bitmap or list of rectangles + can be specified to restrict output to a particular + region of the window. The image defined by the bitmap or + rectangles is called a clipping region. + + Coded character + A character bound to a codepoint. + + Coded character set + A set of unambiguous rules that establishes a character + set and the one-to-one relationship between each + character of the set and its bit representation. + (ISO2022, as adapted by XPG3) A definition of a + one-to-one mapping of a set of characters to a set of + codepoints. + + Codepoint + The coded representation of a single character in a + coded character set. + + Colormap + A colormap consists of a set of entries defining color + values. The colormap associated with a window is used to + display the contents of the window; each pixel value + indexes the colormap to produce an RGB value that drives + the guns of a monitor. Depending on hardware + limitations, one or more colormaps can be installed at + one time so that windows associated with those maps + display with true colors. + + Connection + The IPC path between the server and client program is + known as a connection. A client program typically (but + not necessarily) has one connection to the server over + which requests and events are sent. + + Containment + A window contains the pointer if the window is viewable + and the hotspot of the cursor is within a visible region + of the window or a visible region of one of its + inferiors. The border of the window is included as part + of the window for containment. The pointer is in a + window if the window contains the pointer but no + inferior contains the pointer. + + Coordinate system + The coordinate system has X horizontal and Y vertical, + with the origin [0, 0] at the upper left. Coordinates + are integral 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. + + Cursor + A cursor is the visible shape of the pointer on a + screen. It consists of a hotspot, a source bitmap, a + shape bitmap, and a pair of colors. The cursor defined + for a window controls the visible appearance when the + pointer is in that window. + + Depth + The depth of a window or pixmap is the number of bits + per pixel it has. The depth of a graphics context is the + depth of the drawables it can be used in conjunction + with graphics output. + + Device + Keyboards, mice, tablets, track-balls, button boxes, and + so on are all collectively known as input devices. + Pointers can have one or more buttons (the most common + number is three). The core protocol only deals with two + devices: the keyboard and the pointer. + + DirectColor + DirectColor is a class of colormap in which a pixel + value is decomposed into three separate subfields for + indexing. The first subfield indexes an array to produce + red intensity values. The second subfield indexes a + second array to produce blue intensity values. The third + subfield indexes a third array to produce green + intensity values. The RGB (red, green, and blue) values + in the colormap entry can be changed dynamically. + + Display + A server, together with its screens and input devices, + is called a display. The Xlib Display structure contains + all information about the particular display and its + screens as well as the state that Xlib needs to + communicate with the display over a particular + connection. + + Drawable + Both windows and pixmaps can be used as sources and + destinations in graphics operations. These windows and + pixmaps are collectively known as drawables. However, an + InputOnly window cannot be used as a source or + destination in a graphics operation. + + Encoding + A set of unambiguous rules that establishes a character + set and a relationship between the characters and their + representations. The character set does not have to be + fixed to a finite pre-defined set of characters. The + representations do not have to be of uniform length. + Examples are an ISO2022 graphic set, a state-independent + or state-dependent combination of graphic sets, possibly + including control sets, and the X Compound Text + encoding. + + In X, encodings are identified by a string which appears + as: the CharSetRegistry and CharSetEncoding components + of an XLFD name; the name of a charset of the locale for + which a font could not be found; or an atom which + identifies the encoding of a text property or which + names an encoding for a text selection target type. + Encoding names should be composed of characters from the + X Portable Character Set. + + Escapement + The escapement of a string is the distance in pixels in + the primary draw direction from the drawing origin to + the origin of the next character (that is, the one + following the given string) to be drawn. + + Event + Clients are informed of information asynchronously by + means of events. These events can be either + asynchronously generated from devices or generated as + side effects of client requests. Events are grouped into + types. The server never sends an event to a client + unless the client has specifically asked to be informed + of that type of event. However, clients can force events + to be sent to other clients. Events are typically + reported relative to a window. + + Event mask + Events are requested relative to a window. The set of + event types a client requests relative to a window is + described by using an event mask. + + Event propagation + Device-related events propagate from the source window + to ancestor windows until some client has expressed + interest in handling that type of event or until the + event is discarded explicitly. + + Event source + The deepest viewable window that the pointer is in is + called the source of a device-related event. + + Event synchronization + There are certain race conditions possible when + demultiplexing device events to clients (in particular, + deciding where pointer and keyboard events should be + sent when in the middle of window management + operations). The event synchronization mechanism allows + synchronous processing of device events. + + Exposure event + Servers do not guarantee to preserve the contents of + windows when windows are obscured or reconfigured. + Exposure events are sent to clients to inform them when + contents of regions of windows have been lost. + + Extension + Named extensions to the core protocol can be defined to + extend the system. Extensions to output requests, + resources, and event types are all possible and + expected. + + Font + A font is an array of glyphs (typically characters). The + protocol does no translation or interpretation of + character sets. The client simply indicates values used + to index the glyph array. A font contains additional + metric information to determine interglyph and interline + spacing. + + Font glyph + The abstract graphical symbol for an index into a font. + + Frozen events + Clients can freeze event processing during keyboard and + pointer grabs. + + GC + GC is an abbreviation for graphics context. See Graphics + context. + + Glyph + An identified abstract graphical symbol independent of + any actual image. (ISO/IEC/DIS 9541-1) An abstract + visual representation of a graphic character, not bound + to a codepoint. + + Glyph image + An image of a glyph, as obtained from a glyph + representation displayed on a presentation surface. + (ISO/IEC/DIS 9541-1) + + Grab + Keyboard keys, the keyboard, pointer buttons, the + pointer, and the server can be grabbed for exclusive use + by a client. In general, these facilities are not + intended to be used by normal applications but are + intended for various input and window managers to + implement various styles of user interfaces. + + Graphics context + Various information for graphics output is stored in a + graphics context (GC), such as foreground pixel, + background pixel, line width, clipping region, and so + on. A graphics context can only be used with drawables + that have the same root and the same depth as the + graphics context. + + Gravity + The contents of windows and windows themselves have a + gravity, which determines how the contents move when a + window is resized. See Bit gravity and Window gravity. + + GrayScale + GrayScale can be viewed as a degenerate case of + PseudoColor, in which the red, green, and blue values in + any given colormap entry are equal and thus, produce + shades of gray. The gray values can be changed + dynamically. + + Host Portable Character Encoding + The encoding of the X Portable Character Set on the + host. The encoding itself is not defined by this + standard, but the encoding must be the same in all + locales supported by Xlib on the host. If a string is + said to be in the Host Portable Character Encoding, then + it only contains characters from the X Portable + Character Set, in the host encoding. + + Hotspot + A cursor has an associated hotspot, which defines the + point in the cursor corresponding to the coordinates + reported for the pointer. + + Identifier + An identifier is a unique value associated with a + resource that clients use to name that resource. The + identifier can be used over any connection to name the + resource. + + Inferiors + The inferiors of a window are all of the subwindows + nested below it: the children, the children's children, + and so on. + + Input focus + The input focus is usually a window defining the scope + for processing of keyboard input. If a generated + keyboard event usually would be reported to this window + or one of its inferiors, the event is reported as usual. + Otherwise, the event is reported with respect to the + focus window. The input focus also can be set such that + all keyboard events are discarded and such that the + focus window is dynamically taken to be the root window + of whatever screen the pointer is on at each keyboard + event. + + Input manager + Control over keyboard input is typically provided by an + input manager client, which usually is part of a window + manager. + + InputOnly window + An InputOnly window is a window that cannot be used for + graphics requests. InputOnly windows are invisible and + are used to control such things as cursors, input event + generation, and grabbing. InputOnly windows cannot have + InputOutput windows as inferiors. + + InputOutput window + An InputOutput window is the normal kind of window that + is used for both input and output. InputOutput windows + can have both InputOutput and InputOnly windows as + inferiors. + + Internationalization + The process of making software adaptable to the + requirements of different native languages, local + customs, and character string encodings. Making a + computer program adaptable to different locales without + program source modifications or recompilation. + + ISO2022 + ISO standard for code extension techniques for 7-bit and + 8-bit coded character sets. + + Key grabbing + Keys on the keyboard can be passively grabbed by a + client. When the key is pressed, the keyboard is then + actively grabbed by the client. + + Keyboard grabbing + A client can actively grab control of the keyboard, and + key events will be sent to that client rather than the + client the events would normally have been sent to. + + Keysym + An encoding of a symbol on a keycap on a keyboard. + + Latin-1 + The coded character set defined by the ISO8859-1 + standard. + + 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. + + Locale + The international environment of a computer program + defining the ``localized'' behavior of that program at + run-time. This information can be established from one + or more sets of localization data. ANSI C defines + locale-specific processing by C system library calls. + See ANSI C and the X/Open Portability Guide + specifications for more details. In this specification, + on implementations that conform to the ANSI C library, + the ``current locale'' is the current setting of the + LC_CTYPE setlocale category. Associated with each locale + is a text encoding. When text is processed in the + context of a locale, the text must be in the encoding of + the locale. The current locale affects Xlib in its: + + + Encoding and processing of input method text + + Encoding of resource files and values + + Encoding and imaging of text strings + + Encoding and decoding for inter-client text + communication + + Locale name + The identifier used to select the desired locale for the + host C library and X library functions. On ANSI C + library compliant systems, the locale argument to the + setlocale function. + + Localization + The process of establishing information within a + computer system specific to the operation of particular + native languages, local customs and coded character + sets. (XPG3) + + Mapped + A window is said to be mapped if a map call has been + performed on it. Unmapped windows and their inferiors + are never viewable or visible. + + Modifier keys + Shift, Control, Meta, Super, Hyper, Alt, Compose, Apple, + CapsLock, ShiftLock, and similar keys are called + modifier keys. + + Monochrome + Monochrome is a special case of StaticGray in which + there are only two colormap entries. + + Multibyte + A character whose codepoint is stored in more than one + byte; any encoding which can contain multibyte + characters; text in a multibyte encoding. The ``char *'' + null-terminated string datatype in ANSI C. Note that + references in this document to multibyte strings imply + only that the strings may contain multibyte characters. + + Obscure + A window is obscured if some other window obscures it. A + window can be partially obscured and so still have + visible regions. Window A obscures window B if both are + viewable InputOutput windows, if A is higher in the + global stacking order, and if the rectangle defined by + the outside edges of A intersects the rectangle defined + by the outside edges of B. Note the distinction between + obscures and occludes. Also note that window borders are + included in the calculation. + + Occlude + A window is occluded if some other window occludes it. + Window A occludes window B if both are mapped, if A is + higher in the global stacking order, and if the + rectangle defined by the outside edges of A intersects + the rectangle defined by the outside edges of B. Note + the distinction between occludes and obscures. Also note + that window borders are included in the calculation and + that InputOnly windows never obscure other windows but + can occlude other windows. + + Padding + Some padding bytes are inserted in the data stream to + maintain alignment of the protocol requests on natural + boundaries. This increases ease of portability to some + machine architectures. + + Parent window + If C is a child of P, then P is the parent of C. + + Passive grab + Grabbing a key or button is a passive grab. The grab + activates when the key or button is actually pressed. + + Pixel value + A pixel is an N-bit value, where N is the number of bit + planes used in a particular window or pixmap (that is, + is the depth of the window or pixmap). A pixel in a + window indexes a colormap to derive an actual color to + be displayed. + + Pixmap + A pixmap is a three-dimensional array of bits. A pixmap + is normally thought of as a two-dimensional array of + pixels, where each pixel can be a value from 0 to 2^N-1, + and where N is the depth (z axis) of the pixmap. A + pixmap can also be thought of as a stack of N bitmaps. A + pixmap can only be used on the screen that it was + created in. + + Plane + When a pixmap or window is thought of as a stack of + bitmaps, each bitmap is called a plane or bit plane. + + Plane mask + Graphics operations can be restricted to only affect a + subset of bit planes of a destination. A plane mask is a + bit mask describing which planes are to be modified. The + plane mask is stored in a graphics context. + + Pointer + The pointer is the pointing device currently attached to + the cursor and tracked on the screens. + + Pointer grabbing + A client can actively grab control of the pointer. Then + button and motion events will be sent to that client + rather than the client the events would normally have + been sent to. + + Pointing device + A pointing device is typically a mouse, tablet, or some + other device with effective dimensional motion. The core + protocol defines only one visible cursor, which tracks + whatever pointing device is attached as the pointer. + + POSIX + Portable Operating System Interface, ISO/IEC 9945-1 + (IEEE Std 1003.1). + + 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 ._- + + Property + Windows can have associated properties that consist of a + name, a type, a data format, and some data. The protocol + places no interpretation on properties. They are + intended as a general-purpose naming mechanism for + clients. For example, clients might use properties to + share information such as resize hints, program names, + and icon formats with a window manager. + + Property list + The property list of a window is the list of properties + that have been defined for the window. + + PseudoColor + PseudoColor is a class of colormap in which a pixel + value indexes the colormap entry to produce an + independent RGB value; that is, the colormap is viewed + as an array of triples (RGB values). The RGB values can + be changed dynamically. + + Rectangle + A rectangle specified by [x,y,w,h] has an infinitely + thin outline path with corners at [x,y], [x+w,y], + [x+w,y+h], and [x, y+h]. When a rectangle is filled, the + lower-right edges are not drawn. For example, if w=h=0, + nothing would be drawn. For w=h=1, a single pixel would + be drawn. + + Redirecting control + Window managers (or client programs) may enforce window + layout policy in various ways. When a client attempts to + change the size or position of a window, the operation + may be redirected to a specified client rather than the + operation actually being performed. + + Reply + Information requested by a client program using the X + protocol is sent back to the client with a reply. Both + events and replies are multiplexed on the same + connection. Most requests do not generate replies, but + some requests generate multiple replies. + + Request + A command to the server is called a request. It is a + single block of data sent over a connection. + + Resource + Windows, pixmaps, cursors, fonts, graphics contexts, and + colormaps are known as resources. They all have unique + identifiers associated with them for naming purposes. + The lifetime of a resource usually is bounded by the + lifetime of the connection over which the resource was + created. + + RGB values + RGB values are the red, green, and blue intensity values + that are used to define a color. These values are always + represented as 16-bit, unsigned numbers, with 0 the + minimum intensity and 65535 the maximum intensity. The X + server scales these values to match the display + hardware. + + Root + The root of a pixmap or graphics context is the same as + the root of whatever drawable was used when the pixmap + or GC was created. The root of a window is the root + window under which the window was created. + + Root window + Each screen has a root window covering it. The root + window cannot be reconfigured or unmapped, but otherwise + it acts as a full-fledged window. A root window has no + parent. + + Save set + The save set of a client is a list of other clients' + windows that, if they are inferiors of one of the + client's windows at connection close, should not be + destroyed and that should be remapped if currently + unmapped. Save sets are typically used by window + managers to avoid lost windows if the manager should + terminate abnormally. + + Scanline + A scanline is a list of pixel or bit values viewed as a + horizontal row (all values having the same y coordinate) + of an image, with the values ordered by increasing the x + coordinate. + + Scanline order + An image represented in scanline order contains + scanlines ordered by increasing the y coordinate. + + Screen + A server can provide several independent screens, which + typically have physically independent monitors. This + would be the expected configuration when there is only a + single keyboard and pointer shared among the screens. A + Screen structure contains the information about that + screen and is linked to the Display structure. + + Selection + A selection can be thought of as an indirect property + with dynamic type. That is, rather than having the + property stored in the X server, it is maintained by + some client (the owner). A selection is global and is + thought of as belonging to the user and being maintained + by clients, rather than being private to a particular + window subhierarchy or a particular set of clients. When + a client asks for the contents of a selection, it + specifies a selection target type, which can be used to + control the transmitted representation of the contents. + For example, if the selection is ``the last thing the + user clicked on,'' and that is currently an image, then + the target type might specify whether the contents of + the image should be sent in XY format or Z format. + + The target type can also be used to control the class of + contents transmitted; for example, asking for the + ``looks'' (fonts, line spacing, indentation, and so + forth) of a paragraph selection, rather than the text of + the paragraph. The target type can also be used for + other purposes. The protocol does not constrain the + semantics. + + Server + The server, which is also referred to as the X server, + provides the basic windowing mechanism. It handles IPC + connections from clients, multiplexes graphics requests + onto the screens, and demultiplexes input back to the + appropriate clients. + + Server grabbing + The server can be grabbed by a single client for + exclusive use. This prevents processing of any requests + from other client connections until the grab is + completed. This is typically only a transient state for + such things as rubber-banding, pop-up menus, or + executing requests indivisibly. + + Shift sequence + ISO2022 defines control characters and escape sequences + which temporarily (single shift) or permanently (locking + shift) cause a different character set to be in effect + (``invoking'' a character set). + + Sibling + Children of the same parent window are known as sibling + windows. + + Stacking order + Sibling windows, similar to sheets of paper on a desk, + can stack on top of each other. Windows above both + obscure and occlude lower windows. The relationship + between sibling windows is known as the stacking order. + + State-dependent encoding + An encoding in which an invocation of a charset can + apply to multiple characters in sequence. A + state-dependent encoding begins in an ``initial state'' + and enters other ``shift states'' when specific ``shift + sequences'' are encountered in the byte sequence. In + ISO2022 terms, this means use of locking shifts, not + single shifts. + + State-independent encoding + Any encoding in which the invocations of the charsets + are fixed, or span only a single character. In ISO2022 + terms, this means use of at most single shifts, not + locking shifts. + + StaticColor + StaticColor can be viewed as a degenerate case of + PseudoColor in which the RGB values are predefined and + read-only. + + StaticGray + StaticGray can be viewed as a degenerate case of + GrayScale in which the gray values are predefined and + read-only. The values are typically linear or + near-linear increasing ramps. + + Status + Many Xlib functions return a success status. If the + function does not succeed, however, its arguments are + not disturbed. + + Stipple + A stipple pattern is a bitmap that is used to tile a + region to serve as an additional clip mask for a fill + operation with the foreground color. + + STRING encoding + Latin-1, plus tab and newline. + + String Equivalence + Two ISO Latin-1 STRING8 values are considered equal if + they are the same length and if corresponding bytes are + either equal or are equivalent as follows: decimal + values 65 to 90 inclusive (characters ``A'' to ``Z'') + are pairwise equivalent to decimal values 97 to 122 + inclusive (characters ``a'' to ``z''), decimal values + 192 to 214 inclusive (characters ``A grave'' to ``O + diaeresis'') are pairwise equivalent to decimal values + 224 to 246 inclusive (characters ``a grave'' to ``o + diaeresis''), and decimal values 216 to 222 inclusive + (characters ``O oblique'' to ``THORN'') are pairwise + equivalent to decimal values 246 to 254 inclusive + (characters ``o oblique'' to ``thorn''). + + Tile + A pixmap can be replicated in two dimensions to tile a + region. The pixmap itself is also known as a tile. + + Timestamp + A timestamp is a time value expressed in milliseconds. + It is typically the time since the last server reset. + Timestamp values wrap around (after about 49.7 days). + The server, given its current time is represented by + timestamp T, always interprets timestamps from clients + by treating half of the timestamp space as being earlier + in time than T and half of the timestamp space as being + later in time than T. One timestamp value, represented + by the constant CurrentTime, is never generated by the + server. This value is reserved for use in requests to + represent the current server time. + + TrueColor + TrueColor can be viewed as a degenerate case of + DirectColor in which the subfields in the pixel value + directly encode the corresponding RGB values. That is, + the colormap has predefined read-only RGB values. The + values are typically linear or near-linear increasing + ramps. + + Type + A type is an arbitrary atom used to identify the + interpretation of property data. Types are completely + uninterpreted by the server. They are solely for the + benefit of clients. X predefines type atoms for many + frequently used types, and clients also can define new + types. + + Viewable + A window is viewable if it and all of its ancestors are + mapped. This does not imply that any portion of the + window is actually visible. Graphics requests can be + performed on a window when it is not viewable, but + output will not be retained unless the server is + maintaining backing store. + + Visible + A region of a window is visible if someone looking at + the screen can actually see it; that is, the window is + viewable and the region is not occluded by any other + window. + + Whitespace + Any spacing character. On implementations that conform + to the ANSI C library, whitespace is any character for + which isspace returns true. + + Window gravity + When windows are resized, subwindows may be repositioned + automatically relative to some position in the window. + This attraction of a subwindow to some part of its + parent is known as window gravity. + + Window manager + Manipulation of windows on the screen and much of the + user interface (policy) is typically provided by a + window manager client. + + X Portable Character Set + A basic set of 97 characters which are assumed to exist + in all locales supported by Xlib. This set contains the + following characters: + + a..z A..Z 0..9 + !"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~ + , , and + + + This is the left/lower half (also called the G0 set) of + the graphic character set of ISO8859-1 plus , + , and . It is also the set of graphic + characters in 7-bit ASCII plus the same three control + characters. The actual encoding of these characters on + the host is system dependent; see the Host Portable + Character Encoding. + + XLFD + The X Logical Font Description Conventions that define a + standard syntax for structured font names. + + XY format + The data for a pixmap is said to be in XY format if it + is organized as a set of bitmaps representing individual + bit planes with the planes appearing from + most-significant to least-significant bit order. + + Z format + The data for a pixmap is said to be in Z format if it is + organized as a set of pixel values in scanline order. + +Index + +Symbols + + _XAllocScratch, Allocating and Deallocating Memory + _XAllocTemp, Allocating and Deallocating Memory + _Xdebug, Enabling or Disabling Synchronization + _XFlushGCCache, GC Caching + _XFreeTemp, Allocating and Deallocating Memory + _XReply, Replies + _XSetLastRequestRead, Hooks into the Library + +A + + Access control list, Controlling Host Access, Glossary + Active grab, Pointer Grabbing, Glossary + Allocation, Allocating and Freeing Color Cells, Allocating and + Freeing Color Cells, Allocating and Freeing Color Cells, + Allocating and Freeing Color Cells, Allocating and + Freeing Color Cells, Allocating and Freeing Color Cells, + Allocating and Freeing Color Cells + + colormap, Allocating and Freeing Color Cells + read-only colormap cells, Allocating and Freeing Color + Cells, Allocating and Freeing Color Cells, + Allocating and Freeing Color Cells, Allocating and + Freeing Color Cells + + read/write colormap cells, Allocating and Freeing Color + Cells + + read/write colormap planes, Allocating and Freeing Color + Cells + + AllPlanes, Display Macros + Ancestors, Glossary + Arcs, Drawing Single and Multiple Arcs, Filling Single and + Multiple Arcs + + drawing, Drawing Single and Multiple Arcs + filling, Filling Single and Multiple Arcs + + Areas, Clearing Areas, Copying Areas + + clearing, Clearing Areas + copying, Copying Areas + + Atom, Properties and Atoms, Properties and Atoms, Properties + and Atoms, Properties and Atoms, Properties and Atoms, + Properties and Atoms, Properties and Atoms, Glossary + + getting name, Properties and Atoms, Properties and Atoms + interning, Properties and Atoms, Properties and Atoms + predefined, Properties and Atoms + + Authentication, Controlling Host Access + +B + + Background, Glossary + Backing store, Glossary + BadAccess, Using the Default Error Handlers + BadAlloc, Using the Default Error Handlers + BadAtom, Using the Default Error Handlers + BadColor, Using the Default Error Handlers + BadCursor, Using the Default Error Handlers + BadDrawable, Using the Default Error Handlers + BadFont, Using the Default Error Handlers + BadGC, Using the Default Error Handlers + BadIDChoice, Using the Default Error Handlers + BadImplementation, Using the Default Error Handlers + BadLength, Using the Default Error Handlers + BadMatch, Using the Default Error Handlers + BadName, Using the Default Error Handlers + BadPixmap, Using the Default Error Handlers + BadRequest, Using the Default Error Handlers + BadValue, Using the Default Error Handlers + BadWindow, Using the Default Error Handlers + Base font name, Glossary + Bit, Glossary, Glossary + + gravity, Glossary + plane, Glossary + + Bitmap, Overview of the X Window System, Glossary + BitmapBitOrder, Image Format Functions and Macros + BitmapPad, Image Format Functions and Macros + BitmapUnit, Image Format Functions and Macros + BlackPixel, Display Macros + BlackPixelOfScreen, Screen Information Macros + Bool, Generic Values and Types + Border, Glossary + Button, Pointer Grabbing, Pointer Grabbing, Glossary + + grabbing, Pointer Grabbing, Glossary + ungrabbing, Pointer Grabbing + + ButtonPress, Keyboard and Pointer Events + ButtonRelease, Keyboard and Pointer Events + Byte, Glossary + + order, Glossary + +C + + CallbackPrototype, Input Method Callback Semantics + CCC, Color Conversion Contexts and Gamut Mapping, Color + Conversion Contexts and Gamut Mapping, Color Conversion + Contexts and Gamut Mapping, Color Conversion Context + Functions, Color Conversion Context Functions, Getting + and Setting the Color Conversion Context of a Colormap, + Getting and Setting the Color Conversion Context of a + Colormap, Obtaining the Default Color Conversion + Context, Obtaining the Default Color Conversion Context, + Creating and Freeing a Color Conversion Context, + Creating and Freeing a Color Conversion Context + + creation, Creating and Freeing a Color Conversion Context + default, Color Conversion Contexts and Gamut Mapping, + Color Conversion Context Functions, Obtaining the + Default Color Conversion Context, Obtaining the + Default Color Conversion Context + + freeing, Creating and Freeing a Color Conversion Context + of colormap, Color Conversion Contexts and Gamut Mapping, + Color Conversion Context Functions, Getting and + Setting the Color Conversion Context of a + Colormap, Getting and Setting the Color Conversion + Context of a Colormap + + CellsOfScreen, Screen Information Macros + Changing, Pointer Grabbing + + pointer grab, Pointer Grabbing + + Character, Glossary + Character glyph, Glossary + Character set, Glossary + Charset, Glossary + Child window, Overview of the X Window System + Child Window, Obtaining Window Information + Children, Glossary + Chroma, TekHVC Queries, TekHVC Queries, TekHVC Queries, TekHVC + Queries, TekHVC Queries, TekHVC Queries + + maximum, TekHVC Queries, TekHVC Queries, TekHVC Queries + + CIE metric lightness, CIELab Queries, CIELab Queries, CIELab + Queries, CIELab Queries, CIELab Queries, CIELab Queries, + CIELab Queries, CIELuv Queries, CIELuv Queries, CIELuv + Queries, CIELuv Queries, CIELuv Queries, CIELuv Queries, + CIELuv Queries + + maximum, CIELab Queries, CIELab Queries, CIELuv Queries, + CIELuv Queries + + minimum, CIELab Queries, CIELuv Queries + + CirculateNotify, CirculateNotify Events + CirculateRequest, CirculateRequest Events + Class, Glossary + Clearing, Clearing Areas, Clearing Areas + + areas, Clearing Areas + windows, Clearing Areas + + Client, Glossary + Client White Point, Color Conversion Contexts and Gamut + Mapping, Modifying Attributes of a Color Conversion + Context + + of Color Conversion Context, Modifying Attributes of a + Color Conversion Context + + ClientMessage, ClientMessage Events + ClientWhitePointOfCCC, Color Conversion Context Macros + Clipping region, Glossary + Coded character, Glossary + Coded character set, Glossary + Codepoint, Glossary + Color, Color Structures, Mapping Color Names to Values, Mapping + Color Names to Values, Mapping Color Names to Values, + Allocating and Freeing Color Cells, Allocating and + Freeing Color Cells, Allocating and Freeing Color Cells, + Allocating and Freeing Color Cells, Allocating and + Freeing Color Cells, Allocating and Freeing Color Cells, + Allocating and Freeing Color Cells, Allocating and + Freeing Color Cells, Allocating and Freeing Color Cells, + Allocating and Freeing Color Cells, Modifying and + Querying Colormap Cells, Modifying and Querying Colormap + Cells, Modifying and Querying Colormap Cells, Modifying + and Querying Colormap Cells, Modifying and Querying + Colormap Cells, Modifying and Querying Colormap Cells, + Modifying and Querying Colormap Cells, Modifying and + Querying Colormap Cells, Modifying and Querying Colormap + Cells, Modifying and Querying Colormap Cells, Converting + between Color Spaces + + allocation, Allocating and Freeing Color Cells, Allocating + and Freeing Color Cells, Allocating and Freeing + Color Cells, Allocating and Freeing Color Cells, + Allocating and Freeing Color Cells, Allocating and + Freeing Color Cells, Allocating and Freeing Color + Cells + + conversion, Converting between Color Spaces + deallocation, Allocating and Freeing Color Cells + naming, Mapping Color Names to Values, Mapping Color Names + to Values, Mapping Color Names to Values, + Allocating and Freeing Color Cells, Allocating and + Freeing Color Cells, Modifying and Querying + Colormap Cells + + querying, Modifying and Querying Colormap Cells, Modifying + and Querying Colormap Cells, Modifying and + Querying Colormap Cells, Modifying and Querying + Colormap Cells + + storing, Modifying and Querying Colormap Cells, Modifying + and Querying Colormap Cells, Modifying and + Querying Colormap Cells, Modifying and Querying + Colormap Cells, Modifying and Querying Colormap + Cells + + Color Characterization Data, Creating Additional Function Sets + Color conversion, Converting between Color Spaces + Color Conversion Context, Color Conversion Contexts and Gamut + Mapping, Color Conversion Contexts and Gamut Mapping, + Color Conversion Contexts and Gamut Mapping, Color + Conversion Contexts and Gamut Mapping, Color Conversion + Context Functions, Color Conversion Context Functions, + Color Conversion Context Functions, Getting and Setting + the Color Conversion Context of a Colormap, Getting and + Setting the Color Conversion Context of a Colormap, + Obtaining the Default Color Conversion Context, + Obtaining the Default Color Conversion Context, Creating + and Freeing a Color Conversion Context, Creating and + Freeing a Color Conversion Context + + creation, Color Conversion Contexts and Gamut Mapping, + Color Conversion Context Functions, Creating and + Freeing a Color Conversion Context + + default, Color Conversion Contexts and Gamut Mapping, + Color Conversion Context Functions, Obtaining the + Default Color Conversion Context, Obtaining the + Default Color Conversion Context + + freeing, Creating and Freeing a Color Conversion Context + of colormap, Color Conversion Contexts and Gamut Mapping, + Color Conversion Context Functions, Getting and + Setting the Color Conversion Context of a + Colormap, Getting and Setting the Color Conversion + Context of a Colormap + + Color map, Color Management Functions, Allocating and Freeing + Color Cells + + Colormap, Getting and Setting the Color Conversion Context of a + Colormap, Getting and Setting the Color Conversion + Context of a Colormap, Glossary + + CCC of, Getting and Setting the Color Conversion Context + of a Colormap, Getting and Setting the Color + Conversion Context of a Colormap + + ColormapNotify, Colormap State Change Events + Colormaps, Standard Colormap Properties and Atoms + + standard, Standard Colormap Properties and Atoms + + ConfigureNotify, ConfigureNotify Events + ConfigureRequest, ConfigureRequest Events + Connection, Glossary + ConnectionNumber, Display Macros + Containment, Glossary + Coordinate system, Glossary + Copying, Copying Areas, Copying Areas + + areas, Copying Areas + planes, Copying Areas + + CreateNotify, CreateNotify Events + CurrentTime, Event Processing Overview, Pointer Grabbing + Cursor, Creating Windows, Creating, Recoloring, and Freeing + Cursors, Glossary + + Initial State, Creating Windows + limitations, Creating, Recoloring, and Freeing Cursors + + Cut Buffers, Using Cut Buffers + +D + + Debugging, Enabling or Disabling Synchronization, Using the + Default Error Handlers, Using the Default Error + Handlers, Using the Default Error Handlers, Using the + Default Error Handlers + + error event, Using the Default Error Handlers + error handlers, Using the Default Error Handlers + error message strings, Using the Default Error Handlers + error numbers, Using the Default Error Handlers + synchronous mode, Enabling or Disabling Synchronization + + Default Protection, Controlling Host Access + DefaultColormap, Display Macros + DefaultColormapOfScreen, Screen Information Macros + DefaultDepth, Display Macros + DefaultDepthOfScreen, Screen Information Macros + DefaultGC, Display Macros + DefaultGCOfScreen, Screen Information Macros + DefaultRootWindow, Display Macros + DefaultScreen, Display Macros + DefaultScreenOfDisplay, Display Macros + DefaultVisual, Display Macros + DefaultVisualOfScreen, Screen Information Macros + Depth, Glossary + Destination, Manipulating Graphics Context/State + DestroyCallback, Destroy Callback, Destroy Callback + DestroyNotify, DestroyNotify Events + Device, Glossary + Device Color Characterization, Function Sets + Device profile, Color Conversion Contexts and Gamut Mapping, + Creating Additional Function Sets + + DirectColor, Glossary + Display, Opening the Display, Obtaining Information about the + Display, Image Formats, or Screens, Glossary, Glossary, + Glossary + + data structure, Obtaining Information about the Display, + Image Formats, or Screens + + structure, Glossary, Glossary + + Display Functions, Manipulating Graphics Context/State + DisplayCells, Display Macros + DisplayHeight, Image Format Functions and Macros + DisplayHeightMM, Image Format Functions and Macros + DisplayOfCCC, Color Conversion Context Macros + DisplayOfScreen, Screen Information Macros + DisplayPlanes, Display Macros + DisplayString, Display Macros + DisplayWidth, Image Format Functions and Macros + DisplayWidthMM, Image Format Functions and Macros + DoesBackingStore, Screen Information Macros + DoesSaveUnders, Screen Information Macros + Drawable, Overview of the X Window System, Glossary + Drawing, Drawing Single and Multiple Points, Drawing Single and + Multiple Lines, Drawing Single and Multiple Lines, + Drawing Single and Multiple Rectangles, Drawing Single + and Multiple Arcs, Drawing Complex Text, Drawing Text + Characters, Drawing Image Text Characters + + arcs, Drawing Single and Multiple Arcs + image text, Drawing Image Text Characters + lines, Drawing Single and Multiple Lines + points, Drawing Single and Multiple Points + polygons, Drawing Single and Multiple Lines + rectangles, Drawing Single and Multiple Rectangles + strings, Drawing Text Characters + text items, Drawing Complex Text + +E + + Encoding, Glossary + EnterNotify, Window Entry/Exit Events + Environment, Opening the Display + + DISPLAY, Opening the Display + + Error, Errors, Using the Default Error Handlers, Using the + Default Error Handlers + + codes, Using the Default Error Handlers + handlers, Using the Default Error Handlers + handling, Errors + + Escapement, Glossary + Event, Overview of the X Window System, Event Types, Event + Types, Event Types, Selecting Events, Glossary, + Glossary, Glossary, Glossary, Glossary, Glossary + + categories, Event Types + Exposure, Glossary + mask, Glossary + propagation, Selecting Events, Glossary + source, Glossary + synchronization, Glossary + types, Event Types + + Event mask, Event Masks + EventMaskOfScreen, Screen Information Macros + Events, Keyboard and Pointer Events, Keyboard and Pointer + Events, Keyboard and Pointer Events, Keyboard and + Pointer Events, Keyboard and Pointer Events, Window + Entry/Exit Events, Window Entry/Exit Events, Input Focus + Events, Input Focus Events, Key Map State Notification + Events, Expose Events, GraphicsExpose and NoExpose + Events, GraphicsExpose and NoExpose Events, + CirculateNotify Events, ConfigureNotify Events, + CreateNotify Events, DestroyNotify Events, GravityNotify + Events, MapNotify Events, MappingNotify Events, + ReparentNotify Events, UnmapNotify Events, + VisibilityNotify Events, CirculateRequest Events, + ConfigureRequest Events, MapRequest Events, + ResizeRequest Events, Colormap State Change Events, + ClientMessage Events, PropertyNotify Events, + SelectionClear Events, SelectionRequest Events, + SelectionNotify Events + + ButtonPress, Keyboard and Pointer Events + ButtonRelease, Keyboard and Pointer Events + CirculateNotify, CirculateNotify Events + CirculateRequest, CirculateRequest Events + ClientMessage, ClientMessage Events + ColormapNotify, Colormap State Change Events + ConfigureNotify, ConfigureNotify Events + ConfigureRequest, ConfigureRequest Events + CreateNotify, CreateNotify Events + DestroyNotify, DestroyNotify Events + EnterNotify, Window Entry/Exit Events + Expose, Expose Events + FocusIn, Input Focus Events + FocusOut, Input Focus Events + GraphicsExpose, GraphicsExpose and NoExpose Events + GravityNotify, GravityNotify Events + KeymapNotify, Key Map State Notification Events + KeyPress, Keyboard and Pointer Events + KeyRelease, Keyboard and Pointer Events + LeaveNotify, Window Entry/Exit Events + MapNotify, MapNotify Events + MappingNotify, MappingNotify Events + MapRequest, MapRequest Events + MotionNotify, Keyboard and Pointer Events + NoExpose, GraphicsExpose and NoExpose Events + PropertyNotify, PropertyNotify Events + ReparentNotify, ReparentNotify Events + ResizeRequest, ResizeRequest Events + SelectionClear, SelectionClear Events + SelectionNotify, SelectionNotify Events + SelectionRequest, SelectionRequest Events + UnmapNotify, UnmapNotify Events + VisibilityNotify, VisibilityNotify Events + + Expose, Expose Events + Extension, Glossary + +F + + False, Generic Values and Types + Files, Overview of the X Window System, Standard Header Files, + Standard Header Files, Standard Header Files, Standard + Header Files, Standard Header Files, Standard Header + Files, Standard Header Files, Standard Header Files, + Standard Header Files, Standard Header Files, Standard + Header Files, Standard Header Files, Standard Header + Files, Opening the Display, Properties and Atoms, Color + Management Functions, Color Management Functions, + Manipulating Graphics Context/State, Loading and Freeing + Fonts, Controlling Host Access, Event Types, Event + Structures, Event Masks, GraphicsExpose and NoExpose + Events, Manipulating the Keyboard Encoding, Manipulating + the Keyboard Encoding, Setting and Reading the WM_HINTS + Property, Setting and Reading the WM_NORMAL_HINTS + Property, Setting and Reading the WM_CLASS Property, + Setting and Reading the WM_ICON_SIZE Property, Standard + Colormap Properties and Atoms, Resource Manager + Functions, Using Keyboard Utility Functions, Parsing the + Window Geometry, Manipulating Regions, Determining the + Appropriate Visual Type, Manipulating Images, + Manipulating Images, Using the Context Manager, Setting + and Getting Window Sizing Hints, Getting the X + Environment Defaults, Drawing and Filling Polygons and + Curves, Drawing and Filling Polygons and Curves + + $HOME/.Xdefaults, Getting the X Environment Defaults + /etc/X?.hosts, Controlling Host Access + , Standard Header Files + , Standard Header Files, Manipulating the + Keyboard Encoding + + , Standard Header Files, Manipulating the + Keyboard Encoding, Using Keyboard Utility + Functions + + , Overview of the X Window System, Standard + Header Files, Manipulating Graphics Context/State, + Event Types, Event Masks + + , Standard Header Files, Drawing and Filling + Polygons and Curves, Drawing and Filling Polygons + and Curves + + , Standard Header Files, Properties and + Atoms, Loading and Freeing Fonts, Standard + Colormap Properties and Atoms + + , Standard Header Files, Color Management + Functions + + , Standard Header Files, Opening the Display, + Color Management Functions, Event Structures, + Manipulating Images + + , Standard Header Files + , Standard Header Files, GraphicsExpose and + NoExpose Events + + , Standard Header Files + , Standard Header Files, Resource Manager + Functions + + , Standard Header Files, Setting and Reading + the WM_HINTS Property, Setting and Reading the + WM_NORMAL_HINTS Property, Setting and Reading the + WM_CLASS Property, Setting and Reading the + WM_ICON_SIZE Property, Parsing the Window + Geometry, Manipulating Regions, Determining the + Appropriate Visual Type, Manipulating Images, + Using the Context Manager, Setting and Getting + Window Sizing Hints + + Filling, Filling Single and Multiple Rectangles, Filling a + Single Polygon, Filling Single and Multiple Arcs + + arcs, Filling Single and Multiple Arcs + polygon, Filling a Single Polygon + rectangles, Filling Single and Multiple Rectangles + + FlushGC, GC Caching + FocusIn, Input Focus Events + FocusOut, Input Focus Events + Font, Font Metrics, Glossary + Font glyph, Glossary + Fonts, Loading and Freeing Fonts, Loading and Freeing Fonts, + Loading and Freeing Fonts + + freeing font information, Loading and Freeing Fonts + getting information, Loading and Freeing Fonts + unloading, Loading and Freeing Fonts + + Freeing, Window Attributes, Changing Window Attributes, + Changing Window Attributes, Allocating and Freeing Color + Cells + + colors, Allocating and Freeing Color Cells + resources, Window Attributes, Changing Window Attributes, + Changing Window Attributes + + Frozen events, Glossary + Function set, Function Sets, Function Sets + + LINEAR_RGB, Function Sets + +G + + Gamut compression, Color Conversion Contexts and Gamut Mapping, + Modifying Attributes of a Color Conversion Context, + Modifying Attributes of a Color Conversion Context, + Modifying Attributes of a Color Conversion Context + + client data, Modifying Attributes of a Color Conversion + Context + + procedure, Modifying Attributes of a Color Conversion + Context + + setting in Color Conversion Context, Modifying Attributes + of a Color Conversion Context + + Gamut handling, Color Conversion Contexts and Gamut Mapping + Gamut querying, Gamut Querying Functions + GC, Glossary + GeometryCallback, Geometry Callback + Glyph, Glossary + Glyph image, Glossary + Grab, Glossary + Grabbing, Grabbing the Server, Pointer Grabbing, Pointer + Grabbing, Keyboard Grabbing, Keyboard Grabbing + + buttons, Pointer Grabbing + keyboard, Keyboard Grabbing + keys, Keyboard Grabbing + pointer, Pointer Grabbing + server, Grabbing the Server + + Graphics context, Manipulating Graphics Context/State, Glossary + + initializing, Manipulating Graphics Context/State + + GraphicsExpose, GraphicsExpose and NoExpose Events + Gravity, Glossary + GravityNotify, GravityNotify Events + GrayScale, Glossary + +H + + Hash Lookup, Associating User Data with a Value + Headers, Overview of the X Window System, Standard Header + Files, Standard Header Files, Standard Header Files, + Standard Header Files, Standard Header Files, Standard + Header Files, Standard Header Files, Standard Header + Files, Standard Header Files, Standard Header Files, + Standard Header Files, Standard Header Files, Standard + Header Files, Standard Header Files, Opening the + Display, Properties and Atoms, Color Management + Functions, Color Management Functions, Manipulating + Graphics Context/State, Loading and Freeing Fonts, Event + Types, Event Structures, Event Masks, GraphicsExpose and + NoExpose Events, Manipulating the Keyboard Encoding, + Manipulating the Keyboard Encoding, Setting and Reading + the WM_HINTS Property, Setting and Reading the + WM_NORMAL_HINTS Property, Setting and Reading the + WM_CLASS Property, Setting and Reading the WM_ICON_SIZE + Property, Standard Colormap Properties and Atoms, + Resource Manager Functions, Using Keyboard Utility + Functions, Parsing the Window Geometry, Manipulating + Regions, Determining the Appropriate Visual Type, + Manipulating Images, Manipulating Images, Using the + Context Manager, Setting and Getting Window Sizing + Hints, Drawing and Filling Polygons and Curves, Drawing + and Filling Polygons and Curves + + , Standard Header Files + , Standard Header Files, Manipulating the + Keyboard Encoding + + , Standard Header Files, Manipulating the + Keyboard Encoding, Using Keyboard Utility + Functions + + , Overview of the X Window System, Standard + Header Files, Manipulating Graphics Context/State, + Event Types, Event Masks + + , Standard Header Files, Drawing and Filling + Polygons and Curves, Drawing and Filling Polygons + and Curves + + , Standard Header Files, Properties and + Atoms, Loading and Freeing Fonts, Standard + Colormap Properties and Atoms + + , Standard Header Files, Color Management + Functions + + , Standard Header Files, Opening the Display, + Color Management Functions, Event Structures, + Manipulating Images + + , Standard Header Files + , Standard Header Files, GraphicsExpose and + NoExpose Events + + , Standard Header Files + , Standard Header Files, Resource Manager + Functions + + , Standard Header Files, Setting and Reading + the WM_HINTS Property, Setting and Reading the + WM_NORMAL_HINTS Property, Setting and Reading the + WM_CLASS Property, Setting and Reading the + WM_ICON_SIZE Property, Parsing the Window + Geometry, Manipulating Regions, Determining the + Appropriate Visual Type, Manipulating Images, + Using the Context Manager, Setting and Getting + Window Sizing Hints + + HeightMMOfScreen, Screen Information Macros + HeightOfScreen, Screen Information Macros + Host Portable Character Encoding, Glossary + Hotspot, Glossary + +I + + Identifier, Glossary + Image text, Drawing Image Text Characters + + drawing, Drawing Image Text Characters + + ImageByteOrder, Image Format Functions and Macros + IMInstantiateCallback, Input Method Functions + Inferiors, Glossary + Input, Glossary, Glossary + + focus, Glossary + manager, Glossary + + Input Control, Event Types + Internationalization, Glossary + IsCursorKey, KeySym Classification Macros + IsFunctionKey, KeySym Classification Macros + IsKeypadKey, KeySym Classification Macros + IsMiscFunctionKey, KeySym Classification Macros + IsModifierKey, KeySym Classification Macros + ISO2022, Glossary + IsPFKey, KeySym Classification Macros + IsPrivateKeypadKey, KeySym Classification Macros + +K + + Key, Keyboard Grabbing, Keyboard Grabbing, Glossary + + grabbing, Keyboard Grabbing, Glossary + ungrabbing, Keyboard Grabbing + + Keyboard, Keyboard Grabbing, Keyboard Grabbing, Manipulating + the Keyboard and Pointer Settings, Manipulating the + Keyboard and Pointer Settings, Manipulating the Keyboard + and Pointer Settings, Glossary + + bell volume, Manipulating the Keyboard and Pointer + Settings + + bit vector, Manipulating the Keyboard and Pointer Settings + grabbing, Keyboard Grabbing, Glossary + keyclick volume, Manipulating the Keyboard and Pointer + Settings + + ungrabbing, Keyboard Grabbing + + KeymapNotify, Key Map State Notification Events + KeyPress, Keyboard and Pointer Events + KeyRelease, Keyboard and Pointer Events + Keysym, Glossary + +L + + LastKnownRequestProcessed, Display Macros + Latin Portable Character Encoding, Glossary + Latin-1, Glossary + LeaveNotify, Window Entry/Exit Events + Lines, Drawing Single and Multiple Lines + + drawing, Drawing Single and Multiple Lines + + Locale, Glossary + Locale name, Glossary + Localization, Glossary + LockDisplay, Locking Data Structures + +M + + MapNotify, MapNotify Events + Mapped window, Glossary + MappingNotify, MappingNotify Events + MapRequest, MapRequest Events + MaxCmapsOfScreen, Screen Information Macros + Menus, Grabbing the Server + MinCmapsOfScreen, Screen Information Macros + Modifier keys, Glossary + Monochrome, Glossary + MotionNotify, Keyboard and Pointer Events + Mouse, Manipulating the Keyboard and Pointer Settings + + programming, Manipulating the Keyboard and Pointer + Settings + + Multibyte, Glossary + +N + + NextRequest, Display Macros + NoExpose, GraphicsExpose and NoExpose Events + None, Generic Values and Types + +O + + Obscure, Glossary + Occlude, Glossary + Output Control, Event Types + +P + + Padding, Glossary + Parent Window, Overview of the X Window System, Obtaining + Window Information + + Passive grab, Pointer Grabbing, Glossary + Pixel value, Manipulating Graphics Context/State, Glossary + Pixmap, Overview of the X Window System, Glossary + Plane, Manipulating Graphics Context/State, Copying Areas, + Glossary, Glossary + + copying, Copying Areas + mask, Manipulating Graphics Context/State, Glossary + + PlanesOfScreen, Screen Information Macros + Pointer, Pointer Grabbing, Pointer Grabbing, Pointer Grabbing, + Glossary, Glossary + + grabbing, Pointer Grabbing, Pointer Grabbing, Glossary + ungrabbing, Pointer Grabbing + + Pointing device, Glossary + Points, Drawing Single and Multiple Points + + drawing, Drawing Single and Multiple Points + + Polygons, Drawing Single and Multiple Lines, Filling a Single + Polygon + + drawing, Drawing Single and Multiple Lines + filling, Filling a Single Polygon + + POSIX, Glossary + POSIX Portable Filename Character Set, Glossary + POSIX System Call, Display Macros + + fork, Display Macros + + PreeditCaretCallback, Preedit Caret Callback + PreeditDoneCallback, Preedit State Callbacks + PreeditDrawCallback, Preedit Draw Callback + PreeditStartCallback, Preedit State Callbacks + PreeditStateNotifyCallback, Preedit State Notify Callback + Property, Obtaining and Changing Window Properties, Obtaining + and Changing Window Properties, Obtaining and Changing + Window Properties, Obtaining and Changing Window + Properties, Obtaining and Changing Window Properties, + Obtaining and Changing Window Properties, Obtaining and + Changing Window Properties, Obtaining and Changing + Window Properties, Obtaining and Changing Window + Properties, Glossary + + appending, Obtaining and Changing Window Properties + changing, Obtaining and Changing Window Properties + deleting, Obtaining and Changing Window Properties + format, Obtaining and Changing Window Properties + getting, Obtaining and Changing Window Properties + listing, Obtaining and Changing Window Properties + prepending, Obtaining and Changing Window Properties + replacing, Obtaining and Changing Window Properties + type, Obtaining and Changing Window Properties + + Property list, Glossary + PropertyNotify, PropertyNotify Events + Protocol, Opening the Display, Opening the Display + + DECnet, Opening the Display + TCP, Opening the Display + + ProtocolRevision, Display Macros + ProtocolVersion, Display Macros + PseudoColor, Glossary + Psychometric Chroma, CIELab Queries, CIELab Queries, CIELab + Queries, CIELab Queries, CIELuv Queries, CIELuv Queries, + CIELuv Queries, CIELuv Queries + + maximum, CIELab Queries, CIELab Queries, CIELuv Queries, + CIELuv Queries + + Psychometric Hue Angle, CIELab Queries, CIELab Queries, CIELab + Queries, CIELab Queries, CIELuv Queries, CIELuv Queries, + CIELuv Queries, CIELuv Queries + +Q + + QLength, Display Macros + +R + + Read-only colormap cells, Allocating and Freeing Color Cells, + Allocating and Freeing Color Cells, Allocating and + Freeing Color Cells, Allocating and Freeing Color Cells, + Allocating and Freeing Color Cells + + allocating, Allocating and Freeing Color Cells, Allocating + and Freeing Color Cells, Allocating and Freeing + Color Cells, Allocating and Freeing Color Cells + + read-only colormap cells, Allocating and Freeing Color Cells + Read/write colormap cells, Allocating and Freeing Color Cells, + Allocating and Freeing Color Cells + + allocating, Allocating and Freeing Color Cells + + Read/write colormap planes, Allocating and Freeing Color Cells + + allocating, Allocating and Freeing Color Cells + + Rectangle, Filling Single and Multiple Rectangles, Glossary + + filling, Filling Single and Multiple Rectangles + + Rectangles, Drawing Single and Multiple Rectangles + + drawing, Drawing Single and Multiple Rectangles + + Redirecting control, Glossary + ReparentNotify, ReparentNotify Events + Reply, Glossary + Request, Glossary + ResizeRequest, ResizeRequest Events + Resource, Glossary + Resource IDs, Overview of the X Window System, Overview of the + X Window System, Overview of the X Window System, + Overview of the X Window System, Overview of the X + Window System, Overview of the X Window System, Overview + of the X Window System, Closing the Display, Window + Attributes, Changing Window Attributes, Changing Window + Attributes, Associating User Data with a Value + + Colormap, Overview of the X Window System + Cursor, Overview of the X Window System + Font, Overview of the X Window System + freeing, Window Attributes, Changing Window Attributes, + Changing Window Attributes + + GContext, Overview of the X Window System + Pixmap, Overview of the X Window System + Window, Overview of the X Window System + + RGB values, Glossary + Root, Glossary + RootWindow, Display Macros + RootWindowOfScreen, Screen Information Macros + +S + + Save set, Glossary + Save Unders, Save Under Flag + Scanline, Glossary, Glossary + + order, Glossary + + Screen, Overview of the X Window System, Opening the Display, + Glossary, Glossary + + structure, Glossary + + Screen White Point, Gamut Querying Functions + ScreenCount, Display Macros + ScreenNumberOfCCC, Color Conversion Context Macros + ScreenOfDisplay, Display Macros + ScreenWhitePointOfCCC, Color Conversion Context Macros + Selection, Selections, Selections, Selections, Selections, + Glossary + + converting, Selections + getting the owner, Selections + setting the owner, Selections + + SelectionClear, SelectionClear Events + SelectionNotify, SelectionNotify Events + SelectionRequest, SelectionRequest Events + Serial Number, Using the Default Error Handlers + Server, Grabbing the Server, Glossary, Glossary + + grabbing, Grabbing the Server, Glossary + + ServerVendor, Display Macros + Shift sequence, Glossary + Sibling, Glossary + Source, Manipulating Graphics Context/State + Stacking order, Overview of the X Window System, Glossary + Standard Colormaps, Standard Colormap Properties and Atoms + State-dependent encoding, Glossary + State-independent encoding, Glossary + StaticColor, Glossary + StaticGray, Glossary + Status, Errors, Glossary + StatusDoneCallback, Status Callbacks + StatusDrawCallback, Status Callbacks + StatusStartCallback, Status Callbacks + Stipple, Glossary + String Equivalence, Glossary + StringConversionCallback, String Conversion Callback + Strings, Drawing Text Characters + + drawing, Drawing Text Characters + +T + + Text, Drawing Complex Text + + drawing, Drawing Complex Text + + Tile, Overview of the X Window System, Window Attributes, + Window Attributes, Glossary + + mode, Window Attributes + pixmaps, Window Attributes + + Time, Pointer Grabbing + Timestamp, Glossary + True, Generic Values and Types + TrueColor, Glossary + Type, Glossary + +U + + Ungrabbing, Pointer Grabbing, Pointer Grabbing, Keyboard + Grabbing, Keyboard Grabbing + + buttons, Pointer Grabbing + keyboard, Keyboard Grabbing + keys, Keyboard Grabbing + pointer, Pointer Grabbing + + UnlockDisplay, Locking Data Structures + UnmapNotify, UnmapNotify Events + UnmapNotify Event, Unmapping Windows, Unmapping Windows + +V + + Value, TekHVC Queries, TekHVC Queries, TekHVC Queries, TekHVC + Queries, TekHVC Queries, TekHVC Queries, TekHVC Queries, + TekHVC Queries + + maximum, TekHVC Queries, TekHVC Queries, TekHVC Queries + minimum, TekHVC Queries + + VendorRelease, Display Macros + Vertex, Drawing and Filling Polygons and Curves + VertexCurved, Drawing and Filling Polygons and Curves + VertexDontDraw, Drawing and Filling Polygons and Curves + VertexEndClosed, Drawing and Filling Polygons and Curves + VertexRelative, Drawing and Filling Polygons and Curves + VertexStartClosed, Drawing and Filling Polygons and Curves + Viewable, Glossary + VisibilityNotify, VisibilityNotify Events + Visible, Glossary + Visual, Visual Types + Visual Classes, Visual Types, Visual Types, Visual Types, + Visual Types, Visual Types, Visual Types + + GrayScale, Visual Types + PseudoColor, Visual Types + StaticColor, Visual Types, Visual Types + StaticGray, Visual Types + TrueColor, Visual Types + + Visual Type, Visual Types + VisualOfCCC, Color Conversion Context Macros + +W + + White point, Color Conversion Contexts and Gamut Mapping + White point adjustment, Color Conversion Contexts and Gamut + Mapping, Modifying Attributes of a Color Conversion + Context, Modifying Attributes of a Color Conversion + Context, Modifying Attributes of a Color Conversion + Context + + client data, Modifying Attributes of a Color Conversion + Context + + procedure, Modifying Attributes of a Color Conversion + Context + + setting in Color Conversion Context, Modifying Attributes + of a Color Conversion Context + + WhitePixel, Display Macros + WhitePixelOfScreen, Screen Information Macros + Whitespace, Glossary + WidthMMOfScreen, Screen Information Macros + WidthOfScreen, Screen Information Macros + Window, Overview of the X Window System, Display Macros, + Display Macros, Window Attributes, Window Attributes, + Window Attributes, Creating Windows, Changing Window + Attributes, Changing Window Attributes, Changing Window + Attributes, Clearing Areas, Grabbing the Server, Setting + and Reading the WM_NAME Property, Setting and Reading + the WM_ICON_NAME Property, Parsing the Window Geometry, + Parsing Window Geometry, Associating User Data with a + Value, Glossary, Glossary, Glossary, Glossary, Glossary, + Glossary + + attributes, Window Attributes + background, Changing Window Attributes + clearing, Clearing Areas + defining the cursor, Changing Window Attributes + determining location, Parsing the Window Geometry, Parsing + Window Geometry + + gravity, Glossary + icon name, Setting and Reading the WM_ICON_NAME Property + IDs, Associating User Data with a Value + InputOnly, Creating Windows, Glossary + InputOutput, Glossary + manager, Glossary + managers, Grabbing the Server + mapping, Window Attributes + name, Setting and Reading the WM_NAME Property + parent, Glossary + root, Glossary + RootWindow, Display Macros + undefining the cursor, Changing Window Attributes + XRootWindow, Display Macros + +X + + X Portable Character Set, Glossary + X10 compatibility, Drawing and Filling Polygons and Curves, + Drawing and Filling Polygons and Curves, Drawing and + Filling Polygons and Curves, Drawing and Filling + Polygons and Curves, Drawing and Filling Polygons and + Curves, Drawing and Filling Polygons and Curves, Drawing + and Filling Polygons and Curves, Drawing and Filling + Polygons and Curves, Drawing and Filling Polygons and + Curves, Drawing and Filling Polygons and Curves + + XDraw, Drawing and Filling Polygons and Curves, Drawing + and Filling Polygons and Curves + + XDrawDashed, Drawing and Filling Polygons and Curves, + Drawing and Filling Polygons and Curves + + XDrawFilled, Drawing and Filling Polygons and Curves, + Drawing and Filling Polygons and Curves + + XDrawPatterned, Drawing and Filling Polygons and Curves, + Drawing and Filling Polygons and Curves + + XDrawTiled, Drawing and Filling Polygons and Curves, + Drawing and Filling Polygons and Curves + + X11/cursorfont.h, Standard Header Files + X11/keysym.h, Standard Header Files, Manipulating the Keyboard + Encoding + + X11/keysymdef.h, Standard Header Files, Manipulating the + Keyboard Encoding, Using Keyboard Utility Functions + + X11/X.h, Overview of the X Window System, Standard Header + Files, Manipulating Graphics Context/State, Event Types, + Event Masks + + X11/X10.h, Standard Header Files, Drawing and Filling Polygons + and Curves, Drawing and Filling Polygons and Curves + + X11/Xatom.h, Standard Header Files, Properties and Atoms, + Loading and Freeing Fonts, Standard Colormap Properties + and Atoms + + X11/Xcms.h, Standard Header Files, Color Management Functions + X11/Xlib.h, Standard Header Files, Opening the Display, Color + Management Functions, Event Structures, Manipulating + Images + + X11/Xlibint.h, Standard Header Files + X11/Xproto.h, Standard Header Files, GraphicsExpose and + NoExpose Events + + X11/Xprotostr.h, Standard Header Files + X11/Xresource.h, Standard Header Files, Resource Manager + Functions + + X11/Xutil.h, Standard Header Files, Setting and Reading the + WM_HINTS Property, Setting and Reading the + WM_NORMAL_HINTS Property, Setting and Reading the + WM_CLASS Property, Setting and Reading the WM_ICON_SIZE + Property, Parsing the Window Geometry, Manipulating + Regions, Determining the Appropriate Visual Type, + Manipulating Images, Using the Context Manager, Setting + and Getting Window Sizing Hints + + XActivateScreenSaver, Controlling the Screen Saver + XAddExtension, Hooking into Xlib + XAddHost, Adding, Getting, or Removing Hosts + XAddHosts, Adding, Getting, or Removing Hosts + XAddPixel, Manipulating Images + XAddToExtensionList, Hooks onto Xlib Data Structures + XAddToSaveSet, Controlling the Lifetime of a Window + XAllocClassHint, Setting and Reading the WM_CLASS Property + XAllocColor, Allocating and Freeing Color Cells, Allocating and + Freeing Color Cells + + XAllocColorCells, Allocating and Freeing Color Cells, + Allocating and Freeing Color Cells + + XAllocColorPlanes, Allocating and Freeing Color Cells, + Allocating and Freeing Color Cells + + XAllocID, Hooks onto Xlib Data Structures + XAllocIDs, Hooks onto Xlib Data Structures + XAllocNamedColor, Allocating and Freeing Color Cells, + Allocating and Freeing Color Cells + + XAllowEvents, Resuming Event Processing + XAllPlanes, Display Macros + XAnyEvent, Event Structures + XArc, Drawing Points, Lines, Rectangles, and Arcs + XAutoRepeatOff, Manipulating the Keyboard and Pointer Settings + XAutoRepeatOn, Manipulating the Keyboard and Pointer Settings + XBaseFontNameListOfFontSet, Creating and Freeing a Font Set + XBell, Manipulating the Keyboard and Pointer Settings + XBitmapBitOrder, Image Format Functions and Macros + XBitmapPad, Image Format Functions and Macros + XBitmapUnit, Image Format Functions and Macros + XBlackPixel, Display Macros + XBlackPixelOfScreen, Screen Information Macros + XCellsOfScreen, Screen Information Macros + XChangeActivePointerGrab, Pointer Grabbing + XChangeGC, Manipulating Graphics Context/State + XChangeKeyboardControl, Manipulating the Keyboard and Pointer + Settings + + XChangeKeyboardMapping, Manipulating the Keyboard Encoding + XChangePointerControl, Manipulating the Keyboard and Pointer + Settings + + XChangeProperty, Obtaining and Changing Window Properties + XChangeSaveSet, Controlling the Lifetime of a Window + XChangeWindowAttributes, Changing Window Attributes + XChar2b, Font Metrics + XCharStruct, Font Metrics + XCheckIfEvent, Selecting Events Using a Predicate Procedure + XCheckMaskEvent, Selecting Events Using a Window or Event Mask + XCheckTypedEvent, Selecting Events Using a Window or Event Mask + XCheckTypedWindowEvent, Selecting Events Using a Window or + Event Mask + + XCheckWindowEvent, Selecting Events Using a Window or Event + Mask, Selecting Events Using a Window or Event Mask + + XCirculateEvent, CirculateNotify Events + XCirculateRequestEvent, CirculateRequest Events + XCirculateSubwindows, Changing Window Stacking Order + XCirculateSubwindowsDown, Changing Window Stacking Order + XCirculateSubwindowsUp, Changing Window Stacking Order + XClassHint, Setting and Reading the WM_CLASS Property + XClearArea, Clearing Areas + XClearWindow, Clearing Areas + XClientMessageEvent, ClientMessage Events + XClipBox, Computing with Regions + XCloseDisplay, Closing the Display, Closing the Display + XCloseIM, Input Method Functions + XCloseOM, Output Method Functions + XcmsAddColorSpace, Adding Device-Independent Color Spaces + XcmsAddFunctionSet, Adding Function Sets + XcmsAllocColor, Allocating and Freeing Color Cells + XcmsAllocNamedColor, Allocating and Freeing Color Cells + XcmsCCCOfColormap, Getting and Setting the Color Conversion + Context of a Colormap + + XcmsCIELab, Color Structures + XcmsCIELabQueryMaxC, CIELab Queries + XcmsCIELabQueryMaxL, CIELab Queries + XcmsCIELabQueryMaxLC, CIELab Queries + XcmsCIELabQueryMinL, CIELab Queries + XcmsCIELuv, Color Structures + XcmsCIELuvQueryMaxC, CIELuv Queries + XcmsCIELuvQueryMaxL, CIELuv Queries + XcmsCIELuvQueryMaxLC, CIELuv Queries + XcmsCIELuvQueryMinL, CIELuv Queries + XcmsCIEuvY, Color Structures + XcmsCIExyY, Color Structures + XcmsCIEXYZ, Color Structures + XcmsClientWhitePointOfCCC, Color Conversion Context Macros + XcmsColor, Color Structures + XcmsCompressionProc, Prototype Gamut Compression Procedure + XcmsConvertColors, Converting between Color Spaces + XcmsCreateCCC, Creating and Freeing a Color Conversion Context + XcmsDefaultCCC, Obtaining the Default Color Conversion Context + XcmsDisplayOfCCC, Color Conversion Context Macros + XcmsFormatOfPrefix, Querying Color Space Format and Prefix + XcmsFreeCCC, Creating and Freeing a Color Conversion Context + XcmsLookupColor, Mapping Color Names to Values + XcmsPad, Color Structures + XcmsParseStringProc, Parse String Callback + XcmsPrefixOfFormat, Querying Color Space Format and Prefix + XcmsQueryBlack, Red, Green, and Blue Queries + XcmsQueryBlue, Red, Green, and Blue Queries + XcmsQueryColor, Modifying and Querying Colormap Cells + XcmsQueryColors, Modifying and Querying Colormap Cells + XcmsQueryGreen, Red, Green, and Blue Queries + XcmsQueryRed, Red, Green, and Blue Queries + XcmsQueryWhite, Red, Green, and Blue Queries + XcmsRGB, Color Structures + XcmsRGBi, Color Structures + XcmsScreenInitProc, Creating Additional Function Sets + XcmsScreenNumberOfCCC, Color Conversion Context Macros + XcmsScreenWhitePointOfCCC, Color Conversion Context Macros + XcmsSetCCCOfColormap, Getting and Setting the Color Conversion + Context of a Colormap + + XcmsSetCompressionProc, Modifying Attributes of a Color + Conversion Context + + XcmsSetWhiteAdjustProc, Modifying Attributes of a Color + Conversion Context + + XcmsSetWhitePoint, Modifying Attributes of a Color Conversion + Context + + XcmsStoreColor, Modifying and Querying Colormap Cells + XcmsStoreColors, Modifying and Querying Colormap Cells + XcmsTekHVC, Color Structures + XcmsTekHVCQueryMaxC, TekHVC Queries + XcmsTekHVCQueryMaxV, TekHVC Queries + XcmsTekHVCQueryMaxVC, TekHVC Queries + XcmsTekHVCQueryMaxVSamples, TekHVC Queries + XcmsTekHVCQueryMinV, TekHVC Queries + XcmsVisualOfCCC, Color Conversion Context Macros + XcmsWhiteAdjustProc, Prototype White Point Adjustment Procedure + XColor, Color Structures + XColormapEvent, Colormap State Change Events + XConfigureEvent, ConfigureNotify Events + XConfigureRequestEvent, ConfigureRequest Events + XConfigureWindow, Configuring Windows + XConnectionNumber, Display Macros + XContextDependentDrawing, Obtaining Font Set Metrics + XContextualDrawing, Obtaining Font Set Metrics + XConvertCase, Using Keyboard Utility Functions + XConvertSelection, Selections + XCopyArea, Copying Areas + XCopyColormapAndFree, Creating, Copying, and Destroying + Colormaps + + XCopyGC, Manipulating Graphics Context/State + XCopyPlane, Copying Areas + XCreateAssocTable, Associating User Data with a Value + XCreateBitmapFromData, Manipulating Bitmaps + XCreateColormap, Creating, Copying, and Destroying Colormaps + XCreateFontCursor, Creating, Recoloring, and Freeing Cursors + XCreateFontSet, Creating and Freeing a Font Set + XCreateGC, Manipulating Graphics Context/State + XCreateGlyphCursor, Creating, Recoloring, and Freeing Cursors + XCreateIC, Input Context Functions + XCreateImage, Manipulating Images + XCreateOC, Output Context Functions + XCreatePixmap, Creating and Freeing Pixmaps + XCreatePixmapCursor, Creating, Recoloring, and Freeing Cursors + XCreatePixmapFromBitmapData, Manipulating Bitmaps + XCreateSimpleWindow, Creating Windows + XCreateWindow, Creating Windows + XCreateWindowEvent, CreateNotify Events + XCrossingEvent, Window Entry/Exit Events + XDefaultColormap, Display Macros + XDefaultColormapOfScreen, Screen Information Macros + XDefaultDepth, Display Macros + XDefaultDepthOfScreen, Screen Information Macros + XDefaultGC, Display Macros + XDefaultGCOfScreen, Screen Information Macros + XDefaultRootWindow, Display Macros + XDefaultScreen, Display Macros + XDefaultScreenOfDisplay, Display Macros + XDefaultVisual, Display Macros + XDefaultVisualOfScreen, Screen Information Macros + XDefineCursor, Creating Windows, Changing Window Attributes + XDeleteAssoc, Associating User Data with a Value + XDeleteContext, Using the Context Manager + XDeleteModifiermapEntry, Manipulating the Keyboard Encoding + XDeleteProperty, Obtaining and Changing Window Properties + XDestroyAssocTable, Associating User Data with a Value + XDestroyIC, Input Context Functions + XDestroyImage, Manipulating Images + XDestroyOC, Output Context Functions + XDestroyRegion, Creating, Copying, or Destroying Regions + XDestroySubwindows, Destroying Windows + XDestroyWindow, Destroying Windows + XDestroyWindowEvent, DestroyNotify Events + XDirectionalDependentDrawing, Obtaining Font Set Metrics + XDisableAccessControl, Changing, Enabling, or Disabling Access + Control + + XDisplayCells, Display Macros + XDisplayHeight, Image Format Functions and Macros + XDisplayHeightMM, Image Format Functions and Macros + XDisplayKeycodes, Manipulating the Keyboard Encoding + XDisplayMotionBufferSize, Getting Pointer Motion History + XDisplayName, Using the Default Error Handlers + XDisplayOfIM, Input Method Functions + XDisplayOfOM, Output Method Functions + XDisplayOfScreen, Screen Information Macros + XDisplayPlanes, Display Macros + XDisplayString, Display Macros + XDisplayWidth, Image Format Functions and Macros + XDisplayWidthMM, Image Format Functions and Macros + XDoesBackingStore, Screen Information Macros + XDoesSaveUnders, Screen Information Macros + xDoSomethingReply, Request Format + xDoSomethingReq, Request Format + XDrawArc, Drawing Single and Multiple Arcs, Drawing Single and + Multiple Arcs + + XDrawArcs, Drawing Single and Multiple Arcs, Drawing Single and + Multiple Arcs + + XDrawImageString, Drawing Image Text Characters, Drawing Image + Text Characters + + XDrawImageString16, Drawing Image Text Characters, Drawing + Image Text Characters + + XDrawLine, Drawing Single and Multiple Lines, Drawing Single + and Multiple Lines + + XDrawLines, Drawing Single and Multiple Lines, Drawing Single + and Multiple Lines, Drawing and Filling Polygons and + Curves + + XDrawPoint, Drawing Single and Multiple Points, Drawing Single + and Multiple Points + + XDrawPoints, Drawing Single and Multiple Points, Drawing Single + and Multiple Points + + XDrawRectangle, Drawing Single and Multiple Rectangles, Drawing + Single and Multiple Rectangles + + XDrawRectangles, Drawing Single and Multiple Rectangles, + Drawing Single and Multiple Rectangles + + XDrawSegments, Drawing Single and Multiple Lines, Drawing + Single and Multiple Lines, Drawing and Filling Polygons + and Curves + + XDrawString, Drawing Text Characters + XDrawString16, Drawing Text Characters + XDrawText, Drawing Complex Text + XDrawText16, Drawing Complex Text + XEHeadOfExtensionList, Hooks onto Xlib Data Structures + XEmptyRegion, Determining if Regions Are Empty or Equal + XEnableAccessControl, Changing, Enabling, or Disabling Access + Control + + XEnterWindowEvent, Window Entry/Exit Events + XEqualRegion, Determining if Regions Are Empty or Equal + XErrorEvent, Using the Default Error Handlers + XESetBeforeFlush, Hooks into the Library + XESetCloseDisplay, Hooks into the Library + XESetCopyGC, Hooks into the Library + XESetCreateFont, Hooks into the Library + XESetCreateGC, Hooks into the Library + XESetError, Hooks into the Library + XESetErrorString, Hooks into the Library + XESetEventToWire, Hooks into the Library + XESetFlushGC, Hooks into the Library + XESetFreeFont, Hooks into the Library + XESetPrintErrorValues, Hooks into the Library + XESetWireToError, Hooks into the Library + XESetWireToEvent, Hooks into the Library + XEvent, Event Structures + XEventMaskOfScreen, Screen Information Macros + XEventsQueued, Event Queue Management + XExposeEvent, Expose Events + XExtCodes, Hooking into Xlib + XExtData, Hooks onto Xlib Data Structures + XExtendedMaxRequestSize, Display Macros + XExtentsOfFontSet, Obtaining Font Set Metrics + XFetchBuffer, Using Cut Buffers + XFetchBytes, Using Cut Buffers + XFetchName, Setting and Reading the WM_NAME Property + XFillArc, Filling Single and Multiple Arcs, Filling Single and + Multiple Arcs + + XFillArcs, Filling Single and Multiple Arcs + XFillPolygon, Filling a Single Polygon + XFillRectangle, Filling Single and Multiple Rectangles, Filling + Single and Multiple Rectangles + + XFillRectangles, Filling Single and Multiple Rectangles, + Filling Single and Multiple Rectangles + + XFilterEvent, Event Filtering + XFindContext, Using the Context Manager + XFindOnExtensionList, Hooks onto Xlib Data Structures + XFlush, Handling the Output Buffer + XFlushGC, Manipulating Graphics Context/State + XFocusChangeEvent, Input Focus Events + XFocusInEvent, Input Focus Events + XFocusOutEvent, Input Focus Events + XFontProp, Font Metrics + XFontSetExtents, Obtaining Font Set Metrics + XFontsOfFontSet, Creating and Freeing a Font Set + XFontStruct, Font Metrics + XForceScreenSaver, Controlling the Screen Saver + XFree, Freeing Client-Created Data + XFreeColormap, Creating, Copying, and Destroying Colormaps + XFreeColors, Allocating and Freeing Color Cells + XFreeCursor, Creating, Recoloring, and Freeing Cursors + XFreeExtensionList, Basic Protocol Support Routines + XFreeFont, Loading and Freeing Fonts + XFreeFontInfo, Obtaining and Freeing Font Names and Information + XFreeFontNames, Obtaining and Freeing Font Names and + Information + + XFreeFontPath, Setting and Retrieving the Font Search Path + XFreeFontSet, Creating and Freeing a Font Set + XFreeGC, Manipulating Graphics Context/State + XFreeModifiermap, Manipulating the Keyboard Encoding + XFreePixmap, Creating and Freeing Pixmaps + XFreeStringList, Converting String Lists + XGContextFromGC, Manipulating Graphics Context/State + XGeometry, Parsing Window Geometry + XGetAtomName, Properties and Atoms + XGetAtomNames, Properties and Atoms + XGetClassHint, Setting and Reading the WM_CLASS Property + XGetCommand, Setting and Reading the WM_COMMAND Property + XGetDefault, Getting the X Environment Defaults + XGetErrorDatabaseText, Using the Default Error Handlers + XGetErrorText, Using the Default Error Handlers + XGetFontPath, Setting and Retrieving the Font Search Path + XGetFontProperty, Loading and Freeing Fonts + XGetGCValues, Manipulating Graphics Context/State + XGetGeometry, Obtaining Window Information + XGetIconName, Setting and Reading the WM_ICON_NAME Property + XGetIconSizes, Setting and Reading the WM_ICON_SIZE Property + XGetICValues, Input Context Functions + XGetImage, Transferring Images between Client and Server + XGetIMValues, Input Method Functions + XGetInputFocus, Controlling Input Focus + XGetKeyboardControl, Manipulating the Keyboard and Pointer + Settings, Manipulating the Keyboard and Pointer Settings + + XGetKeyboardMapping, Manipulating the Keyboard Encoding + XGetModifierMapping, Manipulating the Keyboard Encoding + XGetMotionEvents, Getting Pointer Motion History + XGetNormalHints, Setting and Getting Window Sizing Hints + XGetOCValues, Output Context Functions + XGetOMValues, Output Method Functions + XGetPixel, Manipulating Images + XGetPointerControl, Manipulating the Keyboard and Pointer + Settings + + XGetPointerMapping, Manipulating the Keyboard and Pointer + Settings + + XGetRGBColormaps, Setting and Obtaining Standard Colormaps + XGetScreenSaver, Controlling the Screen Saver + XGetSelectionOwner, Selections + XGetSizeHints, Setting and Getting Window Sizing Hints + XGetStandardColormap, Getting and Setting an XStandardColormap + Structure + + XGetSubImage, Transferring Images between Client and Server + XGetTextProperty, Setting and Reading Text Properties + XGetTransientForHint, Setting and Reading the WM_TRANSIENT_FOR + Property + + XGetVisualInfo, Determining the Appropriate Visual Type + XGetWindowAttributes, Obtaining Window Information + XGetWindowProperty, Obtaining and Changing Window Properties + XGetWMClientMachine, Setting and Reading the WM_CLIENT_MACHINE + Property + + XGetWMColormapWindows, Setting and Reading the + WM_COLORMAP_WINDOWS Property + + XGetWMHints, Setting and Reading the WM_HINTS Property + XGetWMIconName, Setting and Reading the WM_ICON_NAME Property + XGetWMName, Setting and Reading the WM_NAME Property + XGetWMNormalHints, Setting and Reading the WM_NORMAL_HINTS + Property + + XGetWMProtocols, Setting and Reading the WM_PROTOCOLS Property + XGetWMSizeHints, Setting and Reading the WM_NORMAL_HINTS + Property + + XGetZoomHints, Setting and Getting Window Sizing Hints + XGrabButton, Pointer Grabbing + XGrabKey, Keyboard Grabbing + XGrabKeyboard, Keyboard Grabbing + XGrabPointer, Pointer Grabbing + XGrabServer, Grabbing the Server + XGraphicsExposeEvent, GraphicsExpose and NoExpose Events + XGravityEvent, GravityNotify Events + XHeightMMOfScreen, Screen Information Macros + XHeightOfScreen, Screen Information Macros + XHostAddress, Adding, Getting, or Removing Hosts + XIconifyWindow, Manipulating Top-Level Windows + XIconSize, Setting and Reading the WM_ICON_SIZE Property, + Setting and Reading the WM_ICON_SIZE Property + + XID, Generic Values and Types + XIfEvent, Selecting Events Using a Predicate Procedure + XIMAbsolutePosition, Preedit Caret Callback + XImage, Transferring Images between Client and Server + XImageByteOrder, Image Format Functions and Macros + XIMBackwardChar, Preedit Caret Callback + XIMBackwardWord, Preedit Caret Callback + XIMCallback, Preedit and Status Callbacks + XIMCaretDirection, Preedit Caret Callback + XIMCaretDown, Preedit Caret Callback + XIMCaretStyle, Preedit Caret Callback + XIMCaretUp, Preedit Caret Callback + XIMDontChange, Preedit Caret Callback + XIMForwardChar, Preedit Caret Callback + XIMForwardWord, Preedit Caret Callback + XIMHighlight, Preedit Draw Callback + XIMInitialState, Reset State + XIMLineEnd, Preedit Caret Callback + XIMLineStart, Preedit Caret Callback + XIMNextLine, Preedit Caret Callback + XIMOfIC, Input Context Functions + XIMPreeditArea, Query Input Style, Query Input Style + XIMPreeditCallbacks, Query Input Style, Query Input Style + XIMPreeditCaretCallbackStruct, Preedit Caret Callback + XIMPreeditDisable, Preedit State + XIMPreeditDrawCallbackStruct, Preedit Draw Callback + XIMPreeditEnable, Preedit State + XIMPreeditNone, Query Input Style, Query Input Style + XIMPreeditNothing, Query Input Style, Query Input Style + XIMPreeditPosition, Query Input Style, Query Input Style + XIMPreeditStateNotifyCallbackStruct, Preedit State Notify + Callback + + XIMPreeditUnknown, Preedit State + XIMPreviousLine, Preedit Caret Callback + XIMPrimary, Preedit Draw Callback + XIMProc, Preedit and Status Callbacks + XIMReverse, Preedit Draw Callback + XIMSecondary, Preedit Draw Callback + XIMStatusArea, Query Input Style, Query Input Style + XIMStatusCallbacks, Query Input Style, Query Input Style + XIMStatusDataType, Status Callbacks + XIMStatusDrawCallbackStruct, Status Callbacks + XIMStatusNone, Query Input Style, Query Input Style + XIMStatusNothing, Query Input Style, Query Input Style + XIMStringConversionCallbackStruct, String Conversion Callback + XIMStyle, Query Input Style + XIMStyles, Query Input Style + XIMTertiary, Preedit Draw Callback + XIMText, Preedit Draw Callback + XIMUnderline, Preedit Draw Callback + XIMVisibleToBackward, Preedit Draw Callback + XIMVisibleToCenter, Preedit Draw Callback + XIMVisibleToForward, Preedit Draw Callback + XInitExtension, Hooking into Xlib + XInitImage, Transferring Images between Client and Server + XInitThreads, Using Xlib with Threads + XINPreserveState, Reset State + XInsertModifiermapEntry, Manipulating the Keyboard Encoding + XInstallColormap, Managing Installed Colormaps + XInternalConnectionNumbers, Using Internal Connections + XInternAtom, Properties and Atoms + XInternAtoms, Properties and Atoms + XIntersectRegion, Computing with Regions + XKeyboardState, Manipulating the Keyboard and Pointer Settings + XKeycodeToKeysym, Using Keyboard Utility Functions + XKeymapEvent, Key Map State Notification Events + XKeysymToKeycode, Using Keyboard Utility Functions + XKeysymToString, Using Keyboard Utility Functions + XKillClient, Killing Clients + XLastKnownRequestProcessed, Display Macros + XLeaveWindowEvent, Window Entry/Exit Events + XLFD, Glossary + XlibSpecificationRelease, Standard Header Files + XListDepths, Display Macros + XListExtensions, Basic Protocol Support Routines + XListFonts, Obtaining and Freeing Font Names and Information + XListFontsWithInfo, Obtaining and Freeing Font Names and + Information + + XListHosts, Adding, Getting, or Removing Hosts + XListInstalledColormaps, Managing Installed Colormaps + XListPixmapFormats, Image Format Functions and Macros + XListProperties, Obtaining and Changing Window Properties + XLoadFont, Loading and Freeing Fonts + XLoadQueryFont, Loading and Freeing Fonts + XLocaleOfFontSet, Creating and Freeing a Font Set + XLocaleOfIM, Input Method Functions + XLocaleOfOM, Output Method Functions + XLockDisplay, Using Xlib with Threads + XLookUpAssoc, Associating User Data with a Value + XLookupColor, Mapping Color Names to Values + XLookupKeysym, Using Keyboard Utility Functions + XLookupString, Using Latin-1 Keyboard Event Functions + XLowerWindow, Changing Window Stacking Order + XMakeAssoc, Associating User Data with a Value + XMapEvent, MapNotify Events + XMappingEvent, MappingNotify Events + XMapRaised, Mapping Windows + XMapRequestEvent, MapRequest Events + XMapSubwindows, Mapping Windows, Mapping Windows + XMapWindow, Window Attributes, Mapping Windows, Mapping Windows + XMaskEvent, Selecting Events Using a Window or Event Mask + XMatchVisualInfo, Determining the Appropriate Visual Type + XMaxCmapsOfScreen, Screen Information Macros + XMaxRequestSize, Display Macros + XmbDrawImageString, Drawing Text Using Font Sets + XmbDrawString, Drawing Text Using Font Sets + XmbDrawText, Drawing Text Using Font Sets + XmbLookupString, Getting Keyboard Input + XmbResetIC, Input Context Functions + XmbSetWMProperties, Using Window Manager Convenience Functions + XmbTextEscapement, Obtaining Font Set Metrics + XmbTextExtents, Obtaining Font Set Metrics + XmbTextItem, Drawing Text Using Font Sets + XmbTextListToTextProperty, Converting String Lists + XmbTextPerCharExtents, Obtaining Font Set Metrics + XmbTextPropertyToTextList, Converting String Lists + XMinCmapsOfScreen, Screen Information Macros + XModifierKeymap, Manipulating the Keyboard Encoding + XMoveResizeWindow, Configuring Windows + XMoveWindow, Configuring Windows + XNArea, Area + XNAreaNeeded, Area Needed + XNBackground, Foreground and Background + XNClientWindow, Client Window + XNColormap, Colormap + XNCursor, Cursor + XNewModifiermap, Manipulating the Keyboard Encoding + XNextEvent, Handling the Output Buffer, Returning the Next + Event + + XNextRequest, Display Macros + XNFilterEvents, Filter Events + XNFocusWindow, Focus Window + XNFontSet, Font Set + XNForeground, Foreground and Background + XNGeometryCallback, Geometry Callback + XNoExposeEvent, GraphicsExpose and NoExpose Events + XNoOp, Generating a NoOperation Protocol Request + XNPreeditAttributes, Preedit and Status Attributes + XNPreeditCaretCallback, Preedit and Status Callbacks + XNPreeditDoneCallback, Preedit and Status Callbacks + XNPreeditDrawCallback, Preedit and Status Callbacks + XNPreeditStartCallback, Preedit and Status Callbacks + XNResourceClass, Resource Name and Class + XNResourceName, Resource Name and Class + XNSpotLocation, Spot Location + XNStatusAttributes, Preedit and Status Attributes + XNStatusDoneCallback, Preedit and Status Callbacks + XNStatusDrawCallback, Preedit and Status Callbacks + XNStatusStartCallback, Preedit and Status Callbacks + XNStdColormap, Colormap + XOffsetRegion, Moving or Shrinking Regions + XOMCharSetList, Required Char Set + XOMOfOC, Output Context Functions + XOpenDisplay, Opening the Display + XOpenIM, Input Method Functions + XOpenOM, Output Method Functions + XParseColor, Mapping Color Names to Values + XParseGeometry, Parsing the Window Geometry + XPeekEvent, Returning the Next Event + XPeekIfEvent, Selecting Events Using a Predicate Procedure + XPending, Handling the Output Buffer, Event Queue Management + Xpermalloc, Allocating Permanent Storage + XPixmapFormatValues, Image Format Functions and Macros + XPlanesOfScreen, Screen Information Macros + XPoint, Drawing Points, Lines, Rectangles, and Arcs + XPointer, Generic Values and Types + XPointInRegion, Locating a Point or a Rectangle in a Region + XPolygonRegion, Creating, Copying, or Destroying Regions + XProcessInternalConnection, Using Internal Connections + XPropertyEvent, PropertyNotify Events + XProtocolRevision, Display Macros + XProtocolVersion, Display Macros + XPutBackEvent, Putting an Event Back into the Queue + XPutImage, Transferring Images between Client and Server + XPutPixel, Manipulating Images + XQLength, Display Macros + XQueryBestCursor, Creating, Recoloring, and Freeing Cursors, + Creating, Recoloring, and Freeing Cursors + + XQueryBestSize, Setting the Fill Tile and Stipple + XQueryBestStipple, Setting the Fill Tile and Stipple + XQueryBestTile, Setting the Fill Tile and Stipple + XQueryColor, Modifying and Querying Colormap Cells + XQueryColors, Modifying and Querying Colormap Cells + XQueryExtension, Basic Protocol Support Routines + XQueryFont, Loading and Freeing Fonts + XQueryKeymap, Manipulating the Keyboard and Pointer Settings + XQueryPointer, Translating Screen Coordinates + XQueryTextExtents, Querying Character String Sizes + XQueryTextExtents16, Querying Character String Sizes + XQueryTree, Obtaining Window Information + XRaiseWindow, Changing Window Stacking Order + XReadBitmapFile, Manipulating Bitmaps + XReadBitmapFileData, Manipulating Bitmaps + XRebindKeysym, Using Latin-1 Keyboard Event Functions + XRecolorCursor, Creating, Recoloring, and Freeing Cursors + XReconfigureWMWindow, Manipulating Top-Level Windows + XRectangle, Drawing Points, Lines, Rectangles, and Arcs + XRectInRegion, Locating a Point or a Rectangle in a Region + XRefreshKeyboardMapping, Using Keyboard Utility Functions + XRegisterIMInstantiateCallback, Input Method Functions + XRemoveConnectionWatch, Using Internal Connections + XRemoveFromSaveSet, Controlling the Lifetime of a Window + XRemoveHost, Adding, Getting, or Removing Hosts + XRemoveHosts, Adding, Getting, or Removing Hosts + XReparentEvent, ReparentNotify Events + XReparentWindow, Changing the Parent of a Window + XResetScreenSaver, Controlling the Screen Saver + XResizeRequestEvent, ResizeRequest Events + XResizeWindow, Configuring Windows + XResourceManagerString, Creating and Storing Databases + xResourceReq, Request Format + XRestackWindows, Changing Window Stacking Order + XrmCombineDatabase, Merging Resource Databases + XrmCombineFileDatabase, Merging Resource Databases + XrmDatabase, Creating and Storing Databases + XrmDestroyDatabase, Creating and Storing Databases + XrmEnumerateDatabase, Enumerating Database Entries + XrmGetDatabase, Creating and Storing Databases + XrmGetFileDatabase, Creating and Storing Databases + XrmGetResource, Looking Up Resources + XrmGetStringDatabase, Creating and Storing Databases + XrmInitialize, Creating and Storing Databases + XrmLocaleOfDatabase, Creating and Storing Databases + XrmMergeDatabases, Merging Resource Databases + XrmOptionDescRec, Parsing Command Line Options + XrmOptionKind, Parsing Command Line Options + XrmParseCommand, Parsing Command Line Options + XrmPermStringToQuark, Quarks + XrmPutFileDatabase, Creating and Storing Databases + XrmPutLineResource, Storing into a Resource Database + XrmPutResource, Storing into a Resource Database + XrmPutStringResource, Storing into a Resource Database + XrmQGetResource, Looking Up Resources + XrmQGetSearchList, Looking Up Resources + XrmQGetSearchResource, Looking Up Resources + XrmQPutResource, Storing into a Resource Database + XrmQPutStringResource, Storing into a Resource Database + XrmQuarkToString, Quarks + XrmSetDatabase, Creating and Storing Databases + XrmStringToBindingQuarkList, Quarks + XrmStringToQuark, Quarks + XrmStringToQuarkList, Quarks + XrmUniqueQuark, Quarks + XrmValue, Creating and Storing Databases + XRootWindow, Display Macros + XRootWindowOfScreen, Screen Information Macros + XRotateBuffers, Using Cut Buffers + XRotateWindowProperties, Obtaining and Changing Window + Properties + + XSaveContext, Using the Context Manager + XScreenCount, Display Macros + XScreenNumberOfScreen, Screen Information Macros + XScreenOfDisplay, Display Macros + XScreenResourceString, Creating and Storing Databases + XSegment, Drawing Points, Lines, Rectangles, and Arcs + XSelectInput, Selecting Events + XSelectionClearEvent, SelectionClear Events + XSelectionEvent, SelectionNotify Events + XSelectionRequestEvent, SelectionRequest Events + XSendEvent, Sending Events to Other Applications, Sending + Events to Other Applications + + XServerInterpretedAddress, Adding, Getting, or Removing Hosts + XServerVendor, Display Macros + XSetAccessControl, Changing, Enabling, or Disabling Access + Control + + XSetAfterFunction, Enabling or Disabling Synchronization + XSetArcMode, Setting the Arc Mode, Subwindow Mode, and Graphics + Exposure + + XSetBackground, Setting the Foreground, Background, Function, + or Plane Mask + + XSetClassHint, Setting and Reading the WM_CLASS Property + XSetClipMask, Setting the Clip Region + XSetClipOrigin, Setting the Clip Region + XSetClipRectangles, Setting the Clip Region + XSetCloseDownMode, Closing the Display + XSetCommand, Setting and Reading the WM_COMMAND Property + XSetDashes, Setting the Line Attributes and Dashes + XSetErrorHandler, Using the Default Error Handlers + XSetFillRule, Setting the Fill Style and Fill Rule + XSetFillStyle, Setting the Fill Style and Fill Rule + XSetFont, Setting the Current Font + XSetFontPath, Setting and Retrieving the Font Search Path + XSetForeground, Setting the Foreground, Background, Function, + or Plane Mask + + XSetFunction, Setting the Foreground, Background, Function, or + Plane Mask + + XSetGraphicsExposures, Setting the Arc Mode, Subwindow Mode, + and Graphics Exposure + + XSetICFocus, Input Context Functions + XSetIconName, Setting and Reading the WM_ICON_NAME Property + XSetIconSizes, Setting and Reading the WM_ICON_SIZE Property + XSetICValues, Input Context Functions + XSetIMValues, Input Method Functions + XSetInputFocus, Controlling Input Focus + XSetIOErrorHandler, Using the Default Error Handlers + XSetLineAttributes, Setting the Line Attributes and Dashes + XSetLocaleModifiers, X Locale Management + XSetModifierMapping, Manipulating the Keyboard Encoding + XSetNormalHints, Setting and Getting Window Sizing Hints + XSetOCValues, Output Context Functions + XSetOMValues, Output Method Functions + XSetPlaneMask, Setting the Foreground, Background, Function, or + Plane Mask + + XSetPointerMapping, Manipulating the Keyboard and Pointer + Settings + + XSetRegion, Creating, Copying, or Destroying Regions + XSetRGBColormaps, Setting and Obtaining Standard Colormaps + XSetScreenSaver, Controlling the Screen Saver + XSetSelectionOwner, Selections + XSetSizeHints, Setting and Getting Window Sizing Hints + XSetStandardColormap, Getting and Setting an XStandardColormap + Structure + + XSetStandardProperties, Setting Standard Properties + XSetState, Setting the Foreground, Background, Function, or + Plane Mask + + XSetStipple, Setting the Fill Tile and Stipple + XSetSubwindowMode, Setting the Arc Mode, Subwindow Mode, and + Graphics Exposure + + XSetTextProperty, Setting and Reading Text Properties + XSetTile, Setting the Fill Tile and Stipple + XSetTransientForHint, Setting and Reading the WM_TRANSIENT_FOR + Property + + XSetTSOrigin, Setting the Fill Tile and Stipple + XSetWindowAttributes, Window Attributes + XSetWindowBackground, Changing Window Attributes + XSetWindowBackgroundPixmap, Changing Window Attributes + XSetWindowBorder, Changing Window Attributes + XSetWindowBorderPixmap, Changing Window Attributes + XSetWindowBorderWidth, Configuring Windows + XSetWindowColormap, Changing Window Attributes + XSetWMClientMachine, Setting and Reading the WM_CLIENT_MACHINE + Property + + XSetWMColormapWindows, Setting and Reading the + WM_COLORMAP_WINDOWS Property + + XSetWMHints, Setting and Reading the WM_HINTS Property + XSetWMIconName, Setting and Reading the WM_ICON_NAME Property + XSetWMName, Setting and Reading the WM_NAME Property + XSetWMNormalHints, Setting and Reading the WM_NORMAL_HINTS + Property + + XSetWMProperties, Using Window Manager Convenience Functions + XSetWMProtocols, Setting and Reading the WM_PROTOCOLS Property + XSetWMSizeHints, Setting and Reading the WM_NORMAL_HINTS + Property + + XSetZoomHints, Setting and Getting Window Sizing Hints + XShrinkRegion, Moving or Shrinking Regions + XStoreBuffer, Using Cut Buffers + XStoreBytes, Using Cut Buffers + XStoreColor, Modifying and Querying Colormap Cells + XStoreColors, Modifying and Querying Colormap Cells + XStoreName, Setting and Reading the WM_NAME Property + XStoreNamedColor, Modifying and Querying Colormap Cells + XStringListToTextProperty, Converting String Lists + XStringToKeysym, Using Keyboard Utility Functions + XSubImage, Manipulating Images + XSubtractRegion, Computing with Regions + XSync, Overview of the X Window System, Overview of the X + Window System, Handling the Output Buffer + + XSynchronize, Enabling or Disabling Synchronization + XTextExtents, Computing Logical Extents + XTextExtents16, Computing Logical Extents + XTextItem, Drawing Text + XTextItem16, Drawing Text + XTextProperty, Converting String Lists + XTextPropertyToStringList, Converting String Lists + XTextWidth, Computing Character String Sizes, Computing + Character String Sizes + + XTextWidth16, Computing Character String Sizes, Computing + Character String Sizes + + XTimeCoord, Getting Pointer Motion History + XTranslateCoordinates, Translating Screen Coordinates + XUndefineCursor, Changing Window Attributes + XUngrabButton, Pointer Grabbing + XUngrabKey, Keyboard Grabbing + XUngrabKeyboard, Keyboard Grabbing + XUngrabPointer, Pointer Grabbing + XUngrabServer, Grabbing the Server + XUninstallColormap, Managing Installed Colormaps + XUnionRectWithRegion, Computing with Regions + XUnionRegion, Computing with Regions + XUnloadFont, Loading and Freeing Fonts + XUnlockDisplay, Using Xlib with Threads + XUnmapEvent, UnmapNotify Events + XUnmapSubwindows, Unmapping Windows + XUnmapWindow, Unmapping Windows, Unmapping Windows + XUnregisterIMInstantiateCallback, Input Method Functions + XUnsetICFocus, Input Context Functions + XVaCreateNestedList, Variable Argument Lists + XVendorRelease, Display Macros + XVisibilityEvent, VisibilityNotify Events + XVisualIDFromVisual, Visual Types + XWarpPointer, Moving the Pointer + XwcDrawImageString, Drawing Text Using Font Sets + XwcDrawString, Drawing Text Using Font Sets + XwcDrawText, Drawing Text Using Font Sets + XwcFreeStringList, Converting String Lists + XwcLookupString, Getting Keyboard Input + XwcResetIC, Input Context Functions + XwcTextEscapement, Obtaining Font Set Metrics + XwcTextExtents, Obtaining Font Set Metrics + XwcTextItem, Drawing Text Using Font Sets + XwcTextListToTextProperty, Converting String Lists + XwcTextPerCharExtents, Obtaining Font Set Metrics + XwcTextPropertyToTextList, Converting String Lists + XWhitePixel, Display Macros + XWhitePixelOfScreen, Screen Information Macros + XWidthMMOfScreen, Screen Information Macros + XWidthOfScreen, Screen Information Macros + XWindowAttributes, Obtaining Window Information + XWindowChanges, Configuring Windows + XWindowEvent, Handling the Output Buffer, Selecting Events + Using a Window or Event Mask + + XWithdrawWindow, Manipulating Top-Level Windows + XWMGeometry, Parsing the Window Geometry + XWriteBitmapFile, Manipulating Bitmaps, Manipulating Bitmaps + XXorRegion, Computing with Regions + XY format, Glossary + +Z + + Z format, Glossary -- cgit 1.4.1-21-gabe81