Change organization and massively refactor v001

1 files changed, 33445 insertions, 0 deletions

@@ -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 <X11/X.h>. These resources are
+   created by requests and are destroyed (or freed) by requests or
+   when connections are closed. Most of these resources are
+   potentially sharable between applications, and in fact, windows
+   are manipulated explicitly by window manager programs. Fonts
+   and cursors are shared automatically across multiple screens.
+   Fonts are loaded and unloaded as needed and are shared by
+   multiple clients. Fonts are often cached in the server. Xlib
+   provides no support for sharing graphics contexts between
+   applications.
+
+   Client programs are informed of events. Events may either be
+   side effects of a request (for example, restacking windows
+   generates Expose events) or completely asynchronous (for
+   example, from the keyboard). A client program asks to be
+   informed of events. Because other applications can send events
+   to your application, programs must be prepared to handle (or
+   ignore) events of all types.
+
+   Input events (for example, a key pressed or the pointer moved)
+   arrive asynchronously from the server and are queued until they
+   are requested by an explicit call (for example, XNextEvent or
+   XWindowEvent). In addition, some library functions (for
+   example, XRaiseWindow) generate Expose and ConfigureRequest
+   events. These events also arrive asynchronously, but the client
+   may wish to explicitly wait for them by calling XSync after
+   calling a function that can cause the server to generate
+   events.
+
+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:
+
+   <X11/Xlib.h>
+
+   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.)
+
+   <X11/X.h>
+
+   This file declares types and constants for the X protocol that
+   are to be used by applications. It is included automatically
+   from <X11/Xlib.h> so application code should never need to
+   reference this file directly.
+
+   <X11/Xcms.h>
+
+   This file contains symbols for much of the color management
+   facilities described in chapter 6. All functions, types, and
+   symbols with the prefix "Xcms", plus the Color Conversion
+   Contexts macros, are declared in this file. <X11/Xlib.h> must
+   be included before including this file.
+
+   <X11/Xutil.h>
+
+   This file declares various functions, types, and symbols used
+   for inter-client communication and application utility
+   functions, which are described in chapters 14 and 16.
+   <X11/Xlib.h> must be included before including this file.
+
+   <X11/Xresource.h>
+
+   This file declares all functions, types, and symbols for the
+   resource manager facilities, which are described in chapter 15.
+   <X11/Xlib.h> must be included before including this file.
+
+   <X11/Xatom.h>
+
+   This file declares all predefined atoms, which are symbols with
+   the prefix "XA_".
+
+   <X11/cursorfont.h>
+
+   This file declares the cursor symbols for the standard cursor
+   font, which are listed in Appendix B. All cursor symbols have
+   the prefix "XC_".
+
+   <X11/keysymdef.h>
+
+   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.
+
+   <X11/keysym.h>
+
+   This file defines the preprocessor symbols XK_MISCELLANY,
+   XK_XKB_KEYS, XK_LATIN1, XK_LATIN2, XK_LATIN3, XK_LATIN4, and
+   XK_GREEK and then includes <X11/keysymdef.h>.
+
+   <X11/Xlibint.h>
+
+   This file declares all the functions, types, and symbols used
+   for extensions, which are described in Appendix C. This file
+   automatically includes <X11/Xlib.h>.
+
+   <X11/Xproto.h>
+
+   This file declares types and symbols for the basic X protocol,
+   for use in implementing extensions. It is included
+   automatically from <X11/Xlibint.h>, so application and
+   extension code should never need to reference this file
+   directly.
+
+   <X11/Xprotostr.h>
+
+   This file declares types and symbols for the basic X protocol,
+   for use in implementing extensions. It is included
+   automatically from <X11/Xproto.h>, so application and extension
+   code should never need to reference this file directly.
+
+   <X11/X10.h>
+
+   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 !"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~ <space>, <tab>
+   , and <newline>
+
+   This set is the left/lower half of the graphic character set of
+   ISO8859-1 plus space, tab, and newline. It is also the set of
+   graphic characters in 7-bit ASCII plus the same three control
+   characters. The actual encoding of these characters on the host
+   is system dependent.
+
+   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 <X11/Xlib.h>. If XOpenDisplay
+   does not succeed, it returns NULL. After a successful call to
+   XOpenDisplay, all of the screens in the display can be used by
+   the client. The screen number specified in the display_name
+   argument is returned by the DefaultScreen macro (or the
+   XDefaultScreen function). You can access elements of the
+   Display and Screen structures only by using the information
+   macros or functions. For information about using macros and
+   functions to obtain information from the Display structure, see
+   section 2.2.1.
+
+   X servers may implement various types of access control
+   mechanisms (see section 9.8).
+
+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 <X11/Xatom.h>. To avoid name clashes with user
+   symbols, the #define name for each atom has the XA_ prefix. For
+   an explanation of the functions that let you get and set much
+   of the information stored in these predefined properties, see
+   chapter 14.
+
+   The core protocol imposes no semantics on these property names,
+   but semantics are specified in other X Consortium standards,
+   such as the Inter-Client Communication Conventions Manual and
+   the X Logical Font Description Conventions.
+
+   You can use properties to communicate other information between
+   applications. The functions described in this section let you
+   define new properties and get the unique atom IDs in your
+   applications.
+
+   Although any particular atom can have some client
+   interpretation within each of the name spaces, atoms occur in
+   five distinct name spaces within the protocol:
+     * 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 <X11/cursorfont.h>
+
+   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 <X11/Xcms.h>. The remaining
+   functions and types are defined in <X11/Xlib.h>.
+
+   Functions in this chapter manipulate the representation of
+   color on the screen. For each possible value that a pixel can
+   take in a window, there is a color cell in the colormap. For
+   example, if a window is 4 bits deep, pixel values 0 through 15
+   are defined. A colormap is a collection of color cells. A color
+   cell consists of a triple of red, green, and blue (RGB) values.
+   The hardware imposes limits on the number of significant bits
+   in these values. As each pixel is read out of display memory,
+   the pixel is looked up in a colormap. The RGB value of the cell
+   determines what color is displayed on the screen. On a
+   grayscale display with a black-and-white monitor, the values
+   are combined to determine the brightness on the screen.
+
+   Typically, an application allocates color cells or sets of
+   color cells to obtain the desired colors. The client can
+   allocate read-only cells. In which case, the pixel values for
+   these colors can be shared among multiple applications, and the
+   RGB value of the cell cannot be changed. If the client
+   allocates read/write cells, they are exclusively owned by the
+   client, and the color associated with the pixel value can be
+   changed at will. Cells must be allocated (and, if read/write,
+   initialized with an RGB value) by a client to obtain desired
+   colors. The use of pixel value for an unallocated cell results
+   in an undefined color.
+
+   Because colormaps are associated with windows, X supports
+   displays with multiple colormaps and, indeed, different types
+   of colormaps. If there are insufficient colormap resources in
+   the display, some windows will display in their true colors,
+   and others will display with incorrect colors. A window manager
+   usually controls which windows are displayed in their true
+   colors if more than one colormap is required for the color
+   resources the applications are using. At any time, there is a
+   set of installed colormaps for a screen. Windows using one of
+   the installed colormaps display with true colors, and windows
+   using other colormaps generally display with incorrect colors.
+   You can control the set of installed colormaps by using
+   XInstallColormap and XUninstallColormap.
+
+   Colormaps are local to a particular screen. Screens always have
+   a default colormap, and programs typically allocate cells out
+   of this colormap. Generally, you should not write applications
+   that monopolize color resources. Although some hardware
+   supports multiple colormaps installed at one time, many of the
+   hardware displays built today support only a single installed
+   colormap, so the primitives are written to encourage sharing of
+   colormap entries between applications.
+
+   The DefaultColormap macro returns the default colormap. The
+   DefaultVisual macro returns the default visual type for the
+   specified screen. Possible visual types are StaticGray,
+   GrayScale, StaticColor, PseudoColor, TrueColor, or DirectColor
+   (see section 3.1).
+
+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:
+
+<color_space_name>:<value>/.../<value>
+
+   The following are examples of valid color strings.
+
+"CIEXYZ:0.3227/0.28133/0.2493"
+"RGBi:1.0/0.0/0.0"
+"rgb:00/ff/00"
+"CIELuv:50.0/0.0/0.0"
+
+   The syntax and semantics of numerical specifications are given
+   for each standard color space in the following sections.
+
+RGB Device String Specification
+
+   An RGB Device specification is identified by the prefix
+   ``rgb:'' and conforms to the following syntax:
+
+rgb:<red>/<green>/<blue>
+
+    <red>, <green>, <blue> := h | hh | hhh | hhhh
+    h := single hexadecimal digits (case insignificant)
+
+   Note that h indicates the value scaled in 4 bits, hh the value
+   scaled in 8 bits, hhh the value scaled in 12 bits, and hhhh the
+   value scaled in 16 bits, respectively.
+
+   Typical examples are the strings ``rgb:ea/75/52'' and
+   ``rgb:ccc/320/320'', but mixed numbers of hexadecimal digit
+   strings (``rgb:ff/a5/0'' and ``rgb:ccc/32/0'') are also
+   allowed.
+
+   For backward compatibility, an older syntax for RGB Device is
+   supported, but its continued use is not encouraged. The syntax
+   is an initial sharp sign character followed by a numeric
+   specification, in one of the following formats:
+
+
+
+#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:<red>/<green>/<blue>
+
+   Note that red, green, and blue are floating-point values
+   between 0.0 and 1.0, inclusive. The input format for these
+   values is an optional sign, a string of numbers possibly
+   containing a decimal point, and an optional exponent field
+   containing an E or e followed by a possibly signed integer
+   string.
+
+Device-Independent String Specifications
+
+   The standard device-independent string specifications have the
+   following syntax:
+
+CIEXYZ:<X>/<Y>/<Z>
+CIEuvY:<u>/<v>/<Y>
+CIExyY:<x>/<y>/<Y>
+CIELab:<L>/<a>/<b>
+CIELuv:<L>/<u>/<v>
+TekHVC:<H>/<V>/<C>
+
+   All of the values (C, H, V, X, Y, Z, a, b, u, v, y, x) are
+   floating-point values. The syntax for these values is an
+   optional plus or minus sign, a string of digits possibly
+   containing a decimal point, and an optional exponent field
+   consisting of an ``E'' or ``e'' followed by an optional plus or
+   minus followed by a string of digits.
+
+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:
+
+Xcms<color_space>QueryMax<dimensions>
+
+Xcms<color_space>QueryMin<dimensions>
+
+   The <dimensions> 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               <implementation dependent>
+   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 <X11/X.h>, 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
+   <X11/Xatom.h>. 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 <X11/X.h>, 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
+   <X11/Xlib.h>. 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 <X11/X.h>. 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 <X11/Xproto.h>. 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
+   <X11/Xproto.h>. 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 <X11/keysymdef.h>.
+   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
+   <X11/keysym.h>, 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
+   <X11/Xlib.h>. 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 <X11/Xatom.h>
+   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
+   <X11/Xutil.h> 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
+   <X11/Xutil.h> 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 <X11/Xutil.h>
+   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 <X11/Xutil.h>
+   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
+   <X11/Xatom.h> 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
+   <X11/Xresource.h>.
+
+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 | <empty lin
+e>
+Comment     =     "!" {<any character except null or newline>}
+IncludeFile     =     "#" WhiteSpace "include" WhiteSpace FileName White
+Space
+FileName     =     <valid filename for operating system>
+ResourceSpec     =     WhiteSpace ResourceName WhiteSpace ":" WhiteSpace
+ Value
+ResourceName     =     [Binding] {Component Binding} ComponentName
+Binding     =     "." | "*"
+WhiteSpace     =     {<space> | <horizontal tab>}
+Component     =     "?" | ComponentName
+ComponentName     =     NameChar {NameChar}
+NameChar     =     "a"-"z" | "A"-"Z" | "0"-"9" | "_" | "-"
+Value     =     {<any character except null or unescaped newline>}
+
+   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 <X11/keysymdef.h> 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:
+
+[=][<width>{xX}<height>][{+-}<xoffset>{+-}<yoffset>]
+
+   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 <X11/Xutil.h>. 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 <X11/Xutil.h>. 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
+   <X11/Xutil.h> 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 <X11/Xlib.h>. 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 <X11/Xutil.h>.
+
+   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 <X11/Xutil.h>.
+
+   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 <X11/Xlibint.h>.
+
+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 <X11/Xlib.h>:
+
+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 <X11/Xlib.h>
+
+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 <X11/Xlib.h>.
+
+   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 <X11/Xlibint.h>
+
+/* 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
+   <X11/Xlibint.h> 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 <X11/Xproto.h> 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 <X11/Xproto.h> for
+   your extension and need to include it in your stub procedure.
+   Each stub procedure also must include <X11/Xlibint.h>.
+
+   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 <X11/Xlibint.h>, takes
+   advantage of this naming scheme.
+
+   For each X request, there is a definition in <X11/Xproto.h>
+   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 <X11/Xproto.h>, 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
+   <X11/Xproto.h>. 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 <X11/Xproto.h>, which contains only a
+   reqType and a length (and a pad byte).
+
+   If the protocol request requires a reply, then <X11/Xproto.h>
+   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.
+   <X11/Xproto.h> 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 "<X11/Xlibint.h>
+
+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 <X11/Xlibint.h>: GetReq,
+   GetReqExtra, GetResReq, or GetEmptyReq. All of these macros
+   take, as their first argument, the name of the protocol request
+   as declared in <X11/Xproto.h> 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 <stdio.h> 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
+   <X11/Xutil.h> 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 <X11/X10.h>
+
+   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 <X11/X10.h>, 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 <X11/X10.h>, 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 <X11/X10.h>
+
+   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
+          !"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~
+          <space>, <tab>, and <newline>
+
+
+          This is the left/lower half (also called the G0 set) 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; 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
+        <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
+
+   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
+
+        <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
+
+   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