From 95ddeb52fce369af6ad910bd7593681dcc83c4d9 Mon Sep 17 00:00:00 2001 From: Case Duckworth Date: Wed, 17 Jan 2024 22:50:58 -0600 Subject: ignore binary and reference --- ref/libX11.txt | 33445 ------------------------------------------------------- 1 file changed, 33445 deletions(-) delete mode 100644 ref/libX11.txt (limited to 'ref') diff --git a/ref/libX11.txt b/ref/libX11.txt deleted file mode 100644 index 5540d62..0000000 --- a/ref/libX11.txt +++ /dev/null @@ -1,33445 +0,0 @@ -Xlib - C Language X Interface - -X Consortium Standard - -James Gettys - - Digital Equipment Corporation - Cambridge Research Laboratory - -Robert W. Scheifler - - Massachusetts Institute of Technology - Laboratory for Computer Science - -Chuck Adams - - Tektronix, Inc. - -Vania Joloboff - - Open Software Foundation - -Hideki Hiura - - Sun Microsystems, Inc. - -Bill McMahon - - Hewlett-Packard Company - -Ron Newman - - Massachusetts Institute of Technology - -Al Tabayoyon - - Tektronix, Inc. - -Glenn Widener - - Tektronix, Inc. - -Shigeru Yamada - - Fujitsu OSSI - - X Version 11, Release 7.7 - - Copyright © 1985, 1986, 1987, 1988, 1989, 1991, 1994, 1996, - 2002 The Open Group - - Permission is hereby granted, free of charge, to any person - obtaining a copy of this software and associated documentation - files (the "Software"), to deal in the Software without - restriction, including without limitation the rights to use, - copy, modify, merge, publish, distribute, sublicense, and/or - sell copies of the Software, and to permit persons to whom the - Software is furnished to do so, subject to the following - conditions: - - The above copyright notice and this permission notice shall be - included in all copies or substantial portions of the Software. - - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, - EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES - OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND - NONINFRINGEMENT. IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR - ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF - CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN - CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN - THE SOFTWARE. - - Except as contained in this notice, the name of The Open Group - shall not be used in advertising or otherwise to promote the - sale, use or other dealings in this Software without prior - written authorization from The Open Group. - - Copyright © 1985, 1986, 1987, 1988, 1989, 1991 Digital - Equipment Corporation - - Permission to use, copy, modify and distribute this - documentation for any purpose and without fee is hereby - granted, provided that the above copyright notice appears in - all copies and that both that copyright notice and this - permission notice appear in supporting documentation, and that - the names of Digital and Tetronix not be used in in advertising - or publicity pertaining to distribution of the software without - specific, written prior permission. Digital and Tetronix make - no representations about the suitability of the software - described herein for any purpose. It is provided "as is" - without express or implied warranty. - - TekHVC is a trademark of Tektronix, Inc. - __________________________________________________________ - - Table of Contents - - Acknowledgments - 1. Introduction to Xlib - - Overview of the X Window System - Errors - Standard Header Files - Generic Values and Types - Naming and Argument Conventions within Xlib - Programming Considerations - Character Sets and Encodings - Formatting Conventions - - 2. Display Functions - - Opening the Display - Obtaining Information about the Display, Image Formats, or - Screens - - Display Macros - Image Format Functions and Macros - Screen Information Macros - - Generating a NoOperation Protocol Request - Freeing Client-Created Data - Closing the Display - Using X Server Connection Close Operations - Using Xlib with Threads - Using Internal Connections - - 3. Window Functions - - Visual Types - Window Attributes - - Background Attribute - Border Attribute - Gravity Attributes - Backing Store Attribute - Save Under Flag - Backing Planes and Backing Pixel Attributes - Event Mask and Do Not Propagate Mask Attributes - Override Redirect Flag - Colormap Attribute - Cursor Attribute - - Creating Windows - Destroying Windows - Mapping Windows - Unmapping Windows - Configuring Windows - Changing Window Stacking Order - Changing Window Attributes - - 4. Window Information Functions - - Obtaining Window Information - Translating Screen Coordinates - Properties and Atoms - Obtaining and Changing Window Properties - Selections - - 5. Pixmap and Cursor Functions - - Creating and Freeing Pixmaps - Creating, Recoloring, and Freeing Cursors - - 6. Color Management Functions - - Color Structures - Color Strings - - RGB Device String Specification - RGB Intensity String Specification - Device-Independent String Specifications - - Color Conversion Contexts and Gamut Mapping - Creating, Copying, and Destroying Colormaps - Mapping Color Names to Values - Allocating and Freeing Color Cells - Modifying and Querying Colormap Cells - Color Conversion Context Functions - - Getting and Setting the Color Conversion Context of - a Colormap - - Obtaining the Default Color Conversion Context - Color Conversion Context Macros - Modifying Attributes of a Color Conversion Context - Creating and Freeing a Color Conversion Context - - Converting between Color Spaces - Callback Functions - - Prototype Gamut Compression Procedure - Supplied Gamut Compression Procedures - Prototype White Point Adjustment Procedure - Supplied White Point Adjustment Procedures - - Gamut Querying Functions - - Red, Green, and Blue Queries - CIELab Queries - CIELuv Queries - TekHVC Queries - - Color Management Extensions - - Color Spaces - Adding Device-Independent Color Spaces - Querying Color Space Format and Prefix - Creating Additional Color Spaces - Parse String Callback - Color Specification Conversion Callback - Function Sets - Adding Function Sets - Creating Additional Function Sets - - 7. Graphics Context Functions - - Manipulating Graphics Context/State - Using Graphics Context Convenience Routines - - Setting the Foreground, Background, Function, or - Plane Mask - - Setting the Line Attributes and Dashes - Setting the Fill Style and Fill Rule - Setting the Fill Tile and Stipple - Setting the Current Font - Setting the Clip Region - Setting the Arc Mode, Subwindow Mode, and Graphics - Exposure - - 8. Graphics Functions - - Clearing Areas - Copying Areas - Drawing Points, Lines, Rectangles, and Arcs - - Drawing Single and Multiple Points - Drawing Single and Multiple Lines - Drawing Single and Multiple Rectangles - Drawing Single and Multiple Arcs - - Filling Areas - - Filling Single and Multiple Rectangles - Filling a Single Polygon - Filling Single and Multiple Arcs - - Font Metrics - - Loading and Freeing Fonts - Obtaining and Freeing Font Names and Information - Computing Character String Sizes - Computing Logical Extents - Querying Character String Sizes - - Drawing Text - - Drawing Complex Text - Drawing Text Characters - Drawing Image Text Characters - - Transferring Images between Client and Server - - 9. Window and Session Manager Functions - - Changing the Parent of a Window - Controlling the Lifetime of a Window - Managing Installed Colormaps - Setting and Retrieving the Font Search Path - Grabbing the Server - Killing Clients - Controlling the Screen Saver - Controlling Host Access - - Adding, Getting, or Removing Hosts - Changing, Enabling, or Disabling Access Control - - 10. Events - - Event Types - Event Structures - Event Masks - Event Processing Overview - Keyboard and Pointer Events - - Pointer Button Events - Keyboard and Pointer Events - - Window Entry/Exit Events - - Normal Entry/Exit Events - Grab and Ungrab Entry/Exit Events - - Input Focus Events - - Normal Focus Events and Focus Events While Grabbed - Focus Events Generated by Grabs - - Key Map State Notification Events - Exposure Events - - Expose Events - GraphicsExpose and NoExpose Events - - Window State Change Events - - CirculateNotify Events - ConfigureNotify Events - CreateNotify Events - DestroyNotify Events - GravityNotify Events - MapNotify Events - MappingNotify Events - ReparentNotify Events - UnmapNotify Events - VisibilityNotify Events - - Structure Control Events - - CirculateRequest Events - ConfigureRequest Events - MapRequest Events - ResizeRequest Events - - Colormap State Change Events - Client Communication Events - - ClientMessage Events - PropertyNotify Events - SelectionClear Events - SelectionRequest Events - SelectionNotify Events - - 11. Event Handling Functions - - Selecting Events - Handling the Output Buffer - Event Queue Management - Manipulating the Event Queue - - Returning the Next Event - Selecting Events Using a Predicate Procedure - Selecting Events Using a Window or Event Mask - - Putting an Event Back into the Queue - Sending Events to Other Applications - Getting Pointer Motion History - Handling Protocol Errors - - Enabling or Disabling Synchronization - Using the Default Error Handlers - - 12. Input Device Functions - - Pointer Grabbing - Keyboard Grabbing - Resuming Event Processing - Moving the Pointer - Controlling Input Focus - Manipulating the Keyboard and Pointer Settings - Manipulating the Keyboard Encoding - - 13. Locales and Internationalized Text Functions - - X Locale Management - Locale and Modifier Dependencies - Variable Argument Lists - Output Methods - - Output Method Overview - Output Method Functions - X Output Method Values - Output Context Functions - Output Context Values - Creating and Freeing a Font Set - Obtaining Font Set Metrics - Drawing Text Using Font Sets - - Input Methods - - Input Method Overview - Input Method Management - Input Method Functions - Input Method Values - Input Context Functions - Input Context Values - Input Method Callback Semantics - Event Filtering - Getting Keyboard Input - Input Method Conventions - - String Constants - - 14. Inter-Client Communication Functions - - Client to Window Manager Communication - - Manipulating Top-Level Windows - Converting String Lists - Setting and Reading Text Properties - Setting and Reading the WM_NAME Property - Setting and Reading the WM_ICON_NAME Property - Setting and Reading the WM_HINTS Property - Setting and Reading the WM_NORMAL_HINTS Property - Setting and Reading the WM_CLASS Property - Setting and Reading the WM_TRANSIENT_FOR Property - Setting and Reading the WM_PROTOCOLS Property - Setting and Reading the WM_COLORMAP_WINDOWS Property - Setting and Reading the WM_ICON_SIZE Property - Using Window Manager Convenience Functions - - Client to Session Manager Communication - - Setting and Reading the WM_COMMAND Property - Setting and Reading the WM_CLIENT_MACHINE Property - - Standard Colormaps - - Standard Colormap Properties and Atoms - Setting and Obtaining Standard Colormaps - - 15. Resource Manager Functions - - Resource File Syntax - Resource Manager Matching Rules - Quarks - Creating and Storing Databases - Merging Resource Databases - Looking Up Resources - Storing into a Resource Database - Enumerating Database Entries - Parsing Command Line Options - - 16. Application Utility Functions - - Using Keyboard Utility Functions - - KeySym Classification Macros - - Using Latin-1 Keyboard Event Functions - Allocating Permanent Storage - Parsing the Window Geometry - Manipulating Regions - - Creating, Copying, or Destroying Regions - Moving or Shrinking Regions - Computing with Regions - Determining if Regions Are Empty or Equal - Locating a Point or a Rectangle in a Region - - Using Cut Buffers - Determining the Appropriate Visual Type - Manipulating Images - Manipulating Bitmaps - Using the Context Manager - - A. Xlib Functions and Protocol Requests - B. X Font Cursors - C. Extensions - - Basic Protocol Support Routines - Hooking into Xlib - - Hooks into the Library - Hooks onto Xlib Data Structures - - GC Caching - Graphics Batching - Writing Extension Stubs - - Requests, Replies, and Xproto.h - Request Format - Starting to Write a Stub Procedure - Locking Data Structures - Sending the Protocol Request and Arguments - Variable Length Arguments - Replies - Synchronous Calling - Allocating and Deallocating Memory - Portability Considerations - Deriving the Correct Extension Opcode - - D. Compatibility Functions - - X Version 11 Compatibility Functions - - Setting Standard Properties - Setting and Getting Window Sizing Hints - Getting and Setting an XStandardColormap Structure - Parsing Window Geometry - Getting the X Environment Defaults - - X Version 10 Compatibility Functions - - Drawing and Filling Polygons and Curves - Associating User Data with a Value - - Glossary - Index - - List of Tables - - A.1. Protocol requests made by each Xlib function - A.2. Xlib functions which use each Protocol Request - -Acknowledgments - - The design and implementation of the first 10 versions of X - were primarily the work of three individuals: Robert Scheifler - of the MIT Laboratory for Computer Science and Jim Gettys of - Digital Equipment Corporation and Ron Newman of MIT, both at - MIT Project Athena. X version 11, however, is the result of the - efforts of dozens of individuals at almost as many locations - and organizations. At the risk of offending some of the players - by exclusion, we would like to acknowledge some of the people - who deserve special credit and recognition for their work on - Xlib. Our apologies to anyone inadvertently overlooked. - -Release 1 - - Our thanks does to Ron Newman (MIT Project Athena), who - contributed substantially to the design and implementation of - the Version 11 Xlib interface. - - Our thanks also goes to Ralph Swick (Project Athena and - Digital) who kept it all together for us during the early - releases. He handled literally thousands of requests from - people everywhere and saved the sanity of at least one of us. - His calm good cheer was a foundation on which we could build. - - Our thanks also goes to Todd Brunhoff (Tektronix) who was - ``loaned'' to Project Athena at exactly the right moment to - provide very capable and much-needed assistance during the - alpha and beta releases. He was responsible for the successful - integration of sources from multiple sites; we would not have - had a release without him. - - Our thanks also goes to Al Mento and Al Wojtas of Digital's - ULTRIX Documentation Group. With good humor and cheer, they - took a rough draft and made it an infinitely better and more - useful document. The work they have done will help many - everywhere. We also would like to thank Hal Murray (Digital - SRC) and Peter George (Digital VMS) who contributed much by - proofreading the early drafts of this document. - - Our thanks also goes to Jeff Dike (Digital UEG), Tom Benson, - Jackie Granfield, and Vince Orgovan (Digital VMS) who helped - with the library utilities implementation; to Hania Gajewska - (Digital UEG-WSL) who, along with Ellis Cohen (CMU and - Siemens), was instrumental in the semantic design of the window - manager properties; and to Dave Rosenthal (Sun Microsystems) - who also contributed to the protocol and provided the sample - generic color frame buffer device-dependent code. - - The alpha and beta test participants deserve special - recognition and thanks as well. It is significant that the bug - reports (and many fixes) during alpha and beta test came almost - exclusively from just a few of the alpha testers, mostly - hardware vendors working on product implementations of X. The - continued public contribution of vendors and universities is - certainly to the benefit of the entire X community. - - Our special thanks must go to Sam Fuller, Vice-President of - Corporate Research at Digital, who has remained committed to - the widest public availability of X and who made it possible to - greatly supplement MIT's resources with the Digital staff in - order to make version 11 a reality. Many of the people - mentioned here are part of the Western Software Laboratory - (Digital UEG-WSL) of the ULTRIX Engineering group and work for - Smokey Wallace, who has been vital to the project's success. - Others not mentioned here worked on the toolkit and are - acknowledged in the X Toolkit documentation. - - Of course, we must particularly thank Paul Asente, formerly of - Stanford University and now of Digital UEG-WSL, who wrote W, - the predecessor to X, and Brian Reid, formerly of Stanford - University and now of Digital WRL, who had much to do with W's - design. - - Finally, our thanks goes to MIT, Digital Equipment Corporation, - and IBM for providing the environment where it could happen. - -Release 4 - - Our thanks go to Jim Fulton (MIT X Consortium) for designing - and specifying the new Xlib functions for Inter-Client - Communication Conventions (ICCCM) support. - - We also thank Al Mento of Digital for his continued effort in - maintaining this document and Jim Fulton and Donna Converse - (MIT X Consortium) for their much-appreciated efforts in - reviewing the changes. - -Release 5 - - The principal authors of the Input Method facilities are Vania - Joloboff (Open Software Foundation) and Bill McMahon - (Hewlett-Packard). The principal author of the rest of the - internationalization facilities is Glenn Widener (Tektronix). - Our thanks to them for keeping their sense of humor through a - long and sometimes difficult design process. Although the words - and much of the design are due to them, many others have - contributed substantially to the design and implementation. Tom - McFarland (HP) and Frank Rojas (IBM) deserve particular - recognition for their contributions. Other contributors were: - Tim Anderson (Motorola), Alka Badshah (OSF), Gabe Beged-Dov - (HP), Chih-Chung Ko (III), Vera Cheng (III), Michael Collins - (Digital), Walt Daniels (IBM), Noritoshi Demizu (OMRON), - Keisuke Fukui (Fujitsu), Hitoshoi Fukumoto (Nihon Sun), Tim - Greenwood (Digital), John Harvey (IBM), Hideki Hiura (Sun), - Fred Horman (AT&T), Norikazu Kaiya (Fujitsu), Yuji Kamata - (IBM), Yutaka Kataoka (Waseda University), Ranee Khubchandani - (Sun), Akira Kon (NEC), Hiroshi Kuribayashi (OMRON), Teruhiko - Kurosaka (Sun), Seiji Kuwari (OMRON), Sandra Martin (OSF), - Narita Masahiko (Fujitsu), Masato Morisaki (NTT), Nelson Ng - (Sun), Takashi Nishimura (NTT America), Makato Nishino (IBM), - Akira Ohsone (Nihon Sun), Chris Peterson (MIT), Sam Shteingart - (AT&T), Manish Sheth (AT&T), Muneiyoshi Suzuki (NTT), Cori - Mehring (Digital), Shoji Sugiyama (IBM), and Eiji Tosa (IBM). - - We are deeply indebted to Tatsuya Kato (NTT), Hiroshi - Kuribayashi (OMRON), Seiji Kuwari (OMRON), Muneiyoshi Suzuki - (NTT), and Li Yuhong (OMRON) for producing one of the first - complete sample implementation of the internationalization - facilities, and Hiromu Inukai (Nihon Sun), Takashi Fujiwara - (Fujitsu), Hideki Hiura (Sun), Yasuhiro Kawai (Oki - Technosystems Laboratory), Kazunori Nishihara (Fuji Xerox), - Masaki Takeuchi (Sony), Katsuhisa Yano (Toshiba), Makoto - Wakamatsu (Sony Corporation) for producing the another complete - sample implementation of the internationalization facilities. - - The principal authors (design and implementation) of the Xcms - color management facilities are Al Tabayoyon (Tektronix) and - Chuck Adams (Tektronix). Joann Taylor (Tektronix), Bob Toole - (Tektronix), and Keith Packard (MIT X Consortium) also - contributed significantly to the design. Others who contributed - are: Harold Boll (Kodak), Ken Bronstein (HP), Nancy Cam (SGI), - Donna Converse (MIT X Consortium), Elias Israel (ISC), Deron - Johnson (Sun), Jim King (Adobe), Ricardo Motta (HP), Chuck Peek - (IBM), Wil Plouffe (IBM), Dave Sternlicht (MIT X Consortium), - Kumar Talluri (AT&T), and Richard Verberg (IBM). - - We also once again thank Al Mento of Digital for his work in - formatting and reformatting text for this manual, and for - producing man pages. Thanks also to Clive Feather (IXI) for - proof-reading and finding a number of small errors. - -Release 6 - - Stephen Gildea (X Consortium) authored the threads support. - Ovais Ashraf (Sun) and Greg Olsen (Sun) contributed - substantially by testing the facilities and reporting bugs in a - timely fashion. - - The principal authors of the internationalization facilities, - including Input and Output Methods, are Hideki Hiura (SunSoft) - and Shigeru Yamada (Fujitsu OSSI). Although the words and much - of the design are due to them, many others have contributed - substantially to the design and implementation. They are: - Takashi Fujiwara (Fujitsu), Yoshio Horiuchi (IBM), Makoto Inada - (Digital), Hiromu Inukai (Nihon SunSoft), Song JaeKyung - (KAIST), Franky Ling (Digital), Tom McFarland (HP), Hiroyuki - Miyamoto (Digital), Masahiko Narita (Fujitsu), Frank Rojas - (IBM), Hidetoshi Tajima (HP), Masaki Takeuchi (Sony), Makoto - Wakamatsu (Sony), Masaki Wakao (IBM), Katsuhisa Yano(Toshiba) - and Jinsoo Yoon (KAIST). - - The principal producers of the sample implementation of the - internationalization facilities are: Jeffrey Bloomfield - (Fujitsu OSSI), Takashi Fujiwara (Fujitsu), Hideki Hiura - (SunSoft), Yoshio Horiuchi (IBM), Makoto Inada (Digital), - Hiromu Inukai (Nihon SunSoft), Song JaeKyung (KAIST), Riki - Kawaguchi (Fujitsu), Franky Ling (Digital), Hiroyuki Miyamoto - (Digital), Hidetoshi Tajima (HP), Toshimitsu Terazono - (Fujitsu), Makoto Wakamatsu (Sony), Masaki Wakao (IBM), Shigeru - Yamada (Fujitsu OSSI) and Katsuhisa Yano (Toshiba). - - The coordinators of the integration, testing, and release of - this implementation of the internationalization facilities are - Nobuyuki Tanaka (Sony) and Makoto Wakamatsu (Sony). - - Others who have contributed to the architectural design or - testing of the sample implementation of the - internationalization facilities are: Hector Chan (Digital), - Michael Kung (IBM), Joseph Kwok (Digital), Hiroyuki Machida - (Sony), Nelson Ng (SunSoft), Frank Rojas (IBM), Yoshiyuki - Segawa (Fujitsu OSSI), Makiko Shimamura (Fujitsu), Shoji - Sugiyama (IBM), Lining Sun (SGI), Masaki Takeuchi (Sony), - Jinsoo Yoon (KAIST) and Akiyasu Zen (HP). - - Jim Gettys - Cambridge Research Laboratory - Digital Equipment Corporation - Robert W. Scheifler - Laboratory for Computer Science - Massachusetts Institute of Technology - -Release 7 - - This document is made available to you in modern formats such - as HTML and PDF thanks to the efforts of Matt Dew, who - converted the original troff sources to DocBook/XML and edited - them into shape; along with Gaetan Nadon and Alan Coopersmith, - who set up the formatting machinery in the libX11 builds and - performed further editing of the DocBook markup. - -Chapter 1. Introduction to Xlib - - Table of Contents - - Overview of the X Window System - Errors - Standard Header Files - Generic Values and Types - Naming and Argument Conventions within Xlib - Programming Considerations - Character Sets and Encodings - Formatting Conventions - - The X Window System is a network-transparent window system that - was designed at MIT. X display servers run on computers with - either monochrome or color bitmap display hardware. The server - distributes user input to and accepts output requests from - various client programs located either on the same machine or - elsewhere in the network. Xlib is a C subroutine library that - application programs (clients) use to interface with the window - system by means of a stream connection. Although a client - usually runs on the same machine as the X server it is talking - to, this need not be the case. - - Xlib - C Language X Interface is a reference guide to the - low-level C language interface to the X Window System protocol. - It is neither a tutorial nor a user's guide to programming the - X Window System. Rather, it provides a detailed description of - each function in the library as well as a discussion of the - related background information. Xlib - C Language X Interface - assumes a basic understanding of a graphics window system and - of the C programming language. Other higher-level abstractions - (for example, those provided by the toolkits for X) are built - on top of the Xlib library. For further information about these - higher-level libraries, see the appropriate toolkit - documentation. The X Window System Protocol provides the - definitive word on the behavior of X. Although additional - information appears here, the protocol document is the ruling - document. - - To provide an introduction to X programming, this chapter - discusses: - * Overview of the X Window System - * Errors - * Standard header files - * Generic values and types - * Naming and argument conventions within Xlib - * Programming considerations - * Character sets and encodings - * Formatting conventions - -Overview of the X Window System - - Some of the terms used in this book are unique to X, and other - terms that are common to other window systems have different - meanings in X. You may find it helpful to refer to the - glossary, which is located at the end of the book. - - The X Window System supports one or more screens containing - overlapping windows or subwindows. A screen is a physical - monitor and hardware that can be color, grayscale, or - monochrome. There can be multiple screens for each display or - workstation. A single X server can provide display services for - any number of screens. A set of screens for a single user with - one keyboard and one pointer (usually a mouse) is called a - display. - - All the windows in an X server are arranged in strict - hierarchies. At the top of each hierarchy is a root window, - which covers each of the display screens. Each root window is - partially or completely covered by child windows. All windows, - except for root windows, have parents. There is usually at - least one window for each application program. Child windows - may in turn have their own children. In this way, an - application program can create an arbitrarily deep tree on each - screen. X provides graphics, text, and raster operations for - windows. - - A child window can be larger than its parent. That is, part or - all of the child window can extend beyond the boundaries of the - parent, but all output to a window is clipped by its parent. If - several children of a window have overlapping locations, one of - the children is considered to be on top of or raised over the - others, thus obscuring them. Output to areas covered by other - windows is suppressed by the window system unless the window - has backing store. If a window is obscured by a second window, - the second window obscures only those ancestors of the second - window that are also ancestors of the first window. - - A window has a border zero or more pixels in width, which can - be any pattern (pixmap) or solid color you like. A window - usually but not always has a background pattern, which will be - repainted by the window system when uncovered. Child windows - obscure their parents, and graphic operations in the parent - window usually are clipped by the children. - - Each window and pixmap has its own coordinate system. The - coordinate system has the X axis horizontal and the Y axis - vertical with the origin [0, 0] at the upper-left corner. - Coordinates are integral, in terms of pixels, and coincide with - pixel centers. For a window, the origin is inside the border at - the inside, upper-left corner. - - X does not guarantee to preserve the contents of windows. When - part or all of a window is hidden and then brought back onto - the screen, its contents may be lost. The server then sends the - client program an Expose event to notify it that part or all of - the window needs to be repainted. Programs must be prepared to - regenerate the contents of windows on demand. - - X also provides off-screen storage of graphics objects, called - pixmaps. Single plane (depth 1) pixmaps are sometimes referred - to as bitmaps. Pixmaps can be used in most graphics functions - interchangeably with windows and are used in various graphics - operations to define patterns or tiles. Windows and pixmaps - together are referred to as drawables. - - Most of the functions in Xlib just add requests to an output - buffer. These requests later execute asynchronously on the X - server. Functions that return values of information stored in - the server do not return (that is, they block) until an - explicit reply is received or an error occurs. You can provide - an error handler, which will be called when the error is - reported. - - If a client does not want a request to execute asynchronously, - it can follow the request with a call to XSync, which blocks - until all previously buffered asynchronous events have been - sent and acted on. As an important side effect, the output - buffer in Xlib is always flushed by a call to any function that - returns a value from the server or waits for input. - - Many Xlib functions will return an integer resource ID, which - allows you to refer to objects stored on the X server. These - can be of type Window, Font, Pixmap, Colormap, Cursor, and - GContext, as defined in the file . These resources are - created by requests and are destroyed (or freed) by requests or - when connections are closed. Most of these resources are - potentially sharable between applications, and in fact, windows - are manipulated explicitly by window manager programs. Fonts - and cursors are shared automatically across multiple screens. - Fonts are loaded and unloaded as needed and are shared by - multiple clients. Fonts are often cached in the server. Xlib - provides no support for sharing graphics contexts between - applications. - - Client programs are informed of events. Events may either be - side effects of a request (for example, restacking windows - generates Expose events) or completely asynchronous (for - example, from the keyboard). A client program asks to be - informed of events. Because other applications can send events - to your application, programs must be prepared to handle (or - ignore) events of all types. - - Input events (for example, a key pressed or the pointer moved) - arrive asynchronously from the server and are queued until they - are requested by an explicit call (for example, XNextEvent or - XWindowEvent). In addition, some library functions (for - example, XRaiseWindow) generate Expose and ConfigureRequest - events. These events also arrive asynchronously, but the client - may wish to explicitly wait for them by calling XSync after - calling a function that can cause the server to generate - events. - -Errors - - Some functions return Status, an integer error indication. If - the function fails, it returns a zero. If the function returns - a status of zero, it has not updated the return arguments. - Because C does not provide multiple return values, many - functions must return their results by writing into - client-passed storage. By default, errors are handled either by - a standard library function or by one that you provide. - Functions that return pointers to strings return NULL pointers - if the string does not exist. - - The X server reports protocol errors at the time that it - detects them. If more than one error could be generated for a - given request, the server can report any of them. - - Because Xlib usually does not transmit requests to the server - immediately (that is, it buffers them), errors can be reported - much later than they actually occur. For debugging purposes, - however, Xlib provides a mechanism for forcing synchronous - behavior (see section 11.8.1). When synchronization is enabled, - errors are reported as they are generated. - - When Xlib detects an error, it calls an error handler, which - your program can provide. If you do not provide an error - handler, the error is printed, and your program terminates. - -Standard Header Files - - The following include files are part of the Xlib standard: - - - - This is the main header file for Xlib. The majority of all Xlib - symbols are declared by including this file. This file also - contains the preprocessor symbol XlibSpecificationRelease. This - symbol is defined to have the 6 in this release of the - standard. (Release 5 of Xlib was the first release to have this - symbol.) - - - - This file declares types and constants for the X protocol that - are to be used by applications. It is included automatically - from so application code should never need to - reference this file directly. - - - - This file contains symbols for much of the color management - facilities described in chapter 6. All functions, types, and - symbols with the prefix "Xcms", plus the Color Conversion - Contexts macros, are declared in this file. must - be included before including this file. - - - - This file declares various functions, types, and symbols used - for inter-client communication and application utility - functions, which are described in chapters 14 and 16. - must be included before including this file. - - - - This file declares all functions, types, and symbols for the - resource manager facilities, which are described in chapter 15. - must be included before including this file. - - - - This file declares all predefined atoms, which are symbols with - the prefix "XA_". - - - - This file declares the cursor symbols for the standard cursor - font, which are listed in Appendix B. All cursor symbols have - the prefix "XC_". - - - - This file declares all standard KeySym values, which are - symbols with the prefix "XK_". The KeySyms are arranged in - groups, and a preprocessor symbol controls inclusion of each - group. The preprocessor symbol must be defined prior to - inclusion of the file to obtain the associated values. The - preprocessor symbols are XK_MISCELLANY, XK_XKB_KEYS, XK_3270, - XK_LATIN1, XK_LATIN2, XK_LATIN3, XK_LATIN4, XK_KATAKANA, - XK_ARABIC, XK_CYRILLIC, XK_GREEK, XK_TECHNICAL, XK_SPECIAL, - XK_PUBLISHING, XK_APL, XK_HEBREW, XK_THAI, and XK_KOREAN. - - - - This file defines the preprocessor symbols XK_MISCELLANY, - XK_XKB_KEYS, XK_LATIN1, XK_LATIN2, XK_LATIN3, XK_LATIN4, and - XK_GREEK and then includes . - - - - This file declares all the functions, types, and symbols used - for extensions, which are described in Appendix C. This file - automatically includes . - - - - This file declares types and symbols for the basic X protocol, - for use in implementing extensions. It is included - automatically from , so application and - extension code should never need to reference this file - directly. - - - - This file declares types and symbols for the basic X protocol, - for use in implementing extensions. It is included - automatically from , so application and extension - code should never need to reference this file directly. - - - - This file declares all the functions, types, and symbols used - for the X10 compatibility functions, which are described in - Appendix D. - -Generic Values and Types - - The following symbols are defined by Xlib and used throughout - the manual: - * Xlib defines the type Bool and the Boolean values True and - False. - * None is the universal null resource ID or atom. - * The type XID is used for generic resource IDs. - * The type XPointer is defined to be char* and is used as a - generic opaque pointer to data. - -Naming and Argument Conventions within Xlib - - Xlib follows a number of conventions for the naming and syntax - of the functions. Given that you remember what information the - function requires, these conventions are intended to make the - syntax of the functions more predictable. - - The major naming conventions are: - * To differentiate the X symbols from the other symbols, the - library uses mixed case for external symbols. It leaves - lowercase for variables and all uppercase for user macros, - as per existing convention. - * All Xlib functions begin with a capital X. - * The beginnings of all function names and symbols are - capitalized. - * All user-visible data structures begin with a capital X. - More generally, anything that a user might dereference - begins with a capital X. - * Macros and other symbols do not begin with a capital X. To - distinguish them from all user symbols, each word in the - macro is capitalized. - * All elements of or variables in a data structure are in - lowercase. Compound words, where needed, are constructed - with underscores (_). - * The display argument, where used, is always first in the - argument list. - * All resource objects, where used, occur at the beginning of - the argument list immediately after the display argument. - * When a graphics context is present together with another - type of resource (most commonly, a drawable), the graphics - context occurs in the argument list after the other - resource. Drawables outrank all other resources. - * Source arguments always precede the destination arguments - in the argument list. - * The x argument always precedes the y argument in the - argument list. - * The width argument always precedes the height argument in - the argument list. - * Where the x, y, width, and height arguments are used - together, the x and y arguments always precede the width - and height arguments. - * Where a mask is accompanied with a structure, the mask - always precedes the pointer to the structure in the - argument list. - -Programming Considerations - - The major programming considerations are: - * Coordinates and sizes in X are actually 16-bit quantities. - This decision was made to minimize the bandwidth required - for a given level of performance. Coordinates usually are - declared as an int in the interface. Values larger than 16 - bits are truncated silently. Sizes (width and height) are - declared as unsigned quantities. - * Keyboards are the greatest variable between different - manufacturers' workstations. If you want your program to be - portable, you should be particularly conservative here. - * Many display systems have limited amounts of off-screen - memory. If you can, you should minimize use of pixmaps and - backing store. - * The user should have control of their screen real estate. - Therefore, you should write your applications to react to - window management rather than presume control of the entire - screen. What you do inside of your top-level window, - however, is up to your application. For further - information, see chapter 14 and the Inter-Client - Communication Conventions Manual. - -Character Sets and Encodings - - Some of the Xlib functions make reference to specific character - sets and character encodings. The following are the most - common: - - X Portable Character Set - - A basic set of 97 characters, which are assumed to exist in all - locales supported by Xlib. This set contains the following - characters: - - a..z A..Z 0..9 !"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~ , - , and - - This set is the left/lower half of the graphic character set of - ISO8859-1 plus space, tab, and newline. It is also the set of - graphic characters in 7-bit ASCII plus the same three control - characters. The actual encoding of these characters on the host - is system dependent. - - Host Portable Character Encoding - - The encoding of the X Portable Character Set on the host. The - encoding itself is not defined by this standard, but the - encoding must be the same in all locales supported by Xlib on - the host. If a string is said to be in the Host Portable - Character Encoding, then it only contains characters from the X - Portable Character Set, in the host encoding. - - Latin-1 - - The coded character set defined by the ISO8859-1 standard. - - Latin Portable Character Encoding - - The encoding of the X Portable Character Set using the Latin-1 - codepoints plus ASCII control characters. If a string is said - to be in the Latin Portable Character Encoding, then it only - contains characters from the X Portable Character Set, not all - of Latin-1. - - STRING Encoding - - Latin-1, plus tab and newline. - - POSIX Portable Filename Character Set - - The set of 65 characters, which can be used in naming files on - a POSIX-compliant host, that are correctly processed in all - locales. The set is: - - a..z A..Z 0..9 ._- - -Formatting Conventions - - Xlib - C Language X Interface uses the following conventions: - * Global symbols are printed in this special font. These can - be either function names, symbols defined in include files, - or structure names. When declared and defined, function - arguments are printed in italics. In the explanatory text - that follows, they usually are printed in regular type. - * Each function is introduced by a general discussion that - distinguishes it from other functions. The function - declaration itself follows, and each argument is - specifically explained. Although ANSI C function prototype - syntax is not used, Xlib header files normally declare - functions using function prototypes in ANSI C environments. - General discussion of the function, if any is required, - follows the arguments. Where applicable, the last paragraph - of the explanation lists the possible Xlib error codes that - the function can generate. For a complete discussion of the - Xlib error codes, see section 11.8.2. - * To eliminate any ambiguity between those arguments that you - pass and those that a function returns to you, the - explanations for all arguments that you pass start with the - word specifies or, in the case of multiple arguments, the - word specify. The explanations for all arguments that are - returned to you start with the word returns or, in the case - of multiple arguments, the word return. The explanations - for all arguments that you can pass and are returned start - with the words specifies and returns. - * Any pointer to a structure that is used to return a value - is designated as such by the _return suffix as part of its - name. All other pointers passed to these functions are used - for reading only. A few arguments use pointers to - structures that are used for both input and output and are - indicated by using the _in_out suffix. - -Chapter 2. Display Functions - - Table of Contents - - Opening the Display - Obtaining Information about the Display, Image Formats, or - Screens - - Display Macros - Image Format Functions and Macros - Screen Information Macros - - Generating a NoOperation Protocol Request - Freeing Client-Created Data - Closing the Display - Using X Server Connection Close Operations - Using Xlib with Threads - Using Internal Connections - - Before your program can use a display, you must establish a - connection to the X server. Once you have established a - connection, you then can use the Xlib macros and functions - discussed in this chapter to return information about the - display. This chapter discusses how to: - * Open (connect to) the display - * Obtain information about the display, image formats, or - screens - * Generate a NoOperation protocol request - * Free client-created data - * Close (disconnect from) a display - * Use X Server connection close operations - * Use Xlib with threads - * Use internal connections - -Opening the Display - - To open a connection to the X server that controls a display, - use XOpenDisplay. - - Display *XOpenDisplay(char *display_name); - - display_name - - Specifies the hardware display name, which determines the - display and communications domain to be used. On a - POSIX-conformant system, if the display_name is NULL, it - defaults to the value of the DISPLAY environment variable. - - The encoding and interpretation of the display name are - implementation-dependent. Strings in the Host Portable - Character Encoding are supported; support for other characters - is implementation-dependent. On POSIX-conformant systems, the - display name or DISPLAY environment variable can be a string in - the format: - - - protocol/hostname:number.screen_number - - protocol - - Specifies a protocol family or an alias for a protocol family. - Supported protocol families are implementation dependent. The - protocol entry is optional. If protocol is not specified, the / - separating protocol and hostname must also not be specified. - - hostname - - Specifies the name of the host machine on which the display is - physically attached. You follow the hostname with either a - single colon (:) or a double colon (::). - - number - - Specifies the number of the display server on that host - machine. You may optionally follow this display number with a - period (.). A single CPU can have more than one display. - Multiple displays are usually numbered starting with zero. - - screen_number - - Specifies the screen to be used on that server. Multiple - screens can be controlled by a single X server. The - screen_number sets an internal variable that can be accessed by - using the DefaultScreen macro or the XDefaultScreen function if - you are using languages other than C (see section 2.2.1). - - For example, the following would specify screen 1 of display 0 - on the machine named ``dual-headed'': - -dual-headed:0.1 - - The XOpenDisplay function returns a Display structure that - serves as the connection to the X server and that contains all - the information about that X server. XOpenDisplay connects your - application to the X server through TCP or DECnet - communications protocols, or through some local inter-process - communication protocol. If the protocol is specified as "tcp", - "inet", or "inet6", or if no protocol is specified and the - hostname is a host machine name and a single colon (:) - separates the hostname and display number, XOpenDisplay - connects using TCP streams. (If the protocol is specified as - "inet", TCP over IPv4 is used. If the protocol is specified as - "inet6", TCP over IPv6 is used. Otherwise, the implementation - determines which IP version is used.) If the hostname and - protocol are both not specified, Xlib uses whatever it believes - is the fastest transport. If the hostname is a host machine - name and a double colon (::) separates the hostname and display - number, XOpenDisplay connects using DECnet. A single X server - can support any or all of these transport mechanisms - simultaneously. A particular Xlib implementation can support - many more of these transport mechanisms. - - If successful, XOpenDisplay returns a pointer to a Display - structure, which is defined in . If XOpenDisplay - does not succeed, it returns NULL. After a successful call to - XOpenDisplay, all of the screens in the display can be used by - the client. The screen number specified in the display_name - argument is returned by the DefaultScreen macro (or the - XDefaultScreen function). You can access elements of the - Display and Screen structures only by using the information - macros or functions. For information about using macros and - functions to obtain information from the Display structure, see - section 2.2.1. - - X servers may implement various types of access control - mechanisms (see section 9.8). - -Obtaining Information about the Display, Image Formats, or Screens - - The Xlib library provides a number of useful macros and - corresponding functions that return data from the Display - structure. The macros are used for C programming, and their - corresponding function equivalents are for other language - bindings. This section discusses the: - * Display macros - * Image format functions and macros - * Screen information macros - - All other members of the Display structure (that is, those for - which no macros are defined) are private to Xlib and must not - be used. Applications must never directly modify or inspect - these private members of the Display structure. The - XDisplayWidth, XDisplayHeight, XDisplayCells, XDisplayPlanes, - XDisplayWidthMM, and XDisplayHeightMM functions in the next - sections are misnamed. These functions really should be named - Screenwhatever and XScreenwhatever, not Displaywhatever or - XDisplaywhatever. Our apologies for the resulting confusion. - -Display Macros - - Applications should not directly modify any part of the Display - and Screen structures. The members should be considered - read-only, although they may change as the result of other - operations on the display. - - The following lists the C language macros, their corresponding - function equivalents that are for other language bindings, and - what data both can return. -AllPlanes - - unsigned long XAllPlanes(void); - - Both return a value with all bits set to 1 suitable for use in - a plane argument to a procedure. - - Both BlackPixel and WhitePixel can be used in implementing a - monochrome application. These pixel values are for permanently - allocated entries in the default colormap. The actual RGB (red, - green, and blue) values are settable on some screens and, in - any case, may not actually be black or white. The names are - intended to convey the expected relative intensity of the - colors. - - BlackPixel(display, screen_number); - - unsigned long XBlackPixel(Display *display, int screen_number); - - display - - Specifies the connection to the X server. - - screen_number - - Specifies the appropriate screen number on the host server. - - Both return the black pixel value for the specified screen. - - WhitePixel(display, screen_number); - - unsigned long XWhitePixel(Display *display, int screen_number); - - display - - Specifies the connection to the X server. - - screen_number - - Specifies the appropriate screen number on the host server. - - Both return the white pixel value for the specified screen. - - ConnectionNumber(display); - - int XConnectionNumber(Display *display); - - display - - Specifies the connection to the X server. - - Both return a connection number for the specified display. On a - POSIX-conformant system, this is the file descriptor of the - connection. - - DefaultColormap(display, screen_number); - - Colormap XDefaultColormap(Display *display, int screen_number); - - display - - Specifies the connection to the X server. - - screen_number - - Specifies the appropriate screen number on the host server. - - Both return the default colormap ID for allocation on the - specified screen. Most routine allocations of color should be - made out of this colormap. - - DefaultDepth(display, screen_number); - - int XDefaultDepth(Display *display, int screen_number); - - display - - Specifies the connection to the X server. - - screen_number - - Specifies the appropriate screen number on the host server. - - Both return the depth (number of planes) of the default root - window for the specified screen. Other depths may also be - supported on this screen (see XMatchVisualInfo). - - To determine the number of depths that are available on a given - screen, use XListDepths. - - int *XListDepths(Display *display, int screen_number, int - *count_return); - - display - - Specifies the connection to the X server. - - screen_number - - Specifies the appropriate screen number on the host server. - - count_return - - Returns the number of depths. - - The XListDepths function returns the array of depths that are - available on the specified screen. If the specified - screen_number is valid and sufficient memory for the array can - be allocated, XListDepths sets count_return to the number of - available depths. Otherwise, it does not set count_return and - returns NULL. To release the memory allocated for the array of - depths, use XFree. - - DefaultGC(display, screen_number); - - GC XDefaultGC(Display *display, int screen_number); - - display - - Specifies the connection to the X server. - - screen_number - - Specifies the appropriate screen number on the host server. - - Both return the default graphics context for the root window of - the specified screen. This GC is created for the convenience of - simple applications and contains the default GC components with - the foreground and background pixel values initialized to the - black and white pixels for the screen, respectively. You can - modify its contents freely because it is not used in any Xlib - function. This GC should never be freed. - - DefaultRootWindow(display); - - Window XDefaultRootWindow(Display *display); - - display - - Specifies the connection to the X server. - - Both return the root window for the default screen. - - DefaultScreenOfDisplay(display); - - Screen *XDefaultScreenOfDisplay(Display *display); - - display - - Specifies the connection to the X server. - - Both return a pointer to the default screen. - - ScreenOfDisplay(display, screen_number); - - Screen *XScreenOfDisplay(Display *display, int screen_number); - - display - - Specifies the connection to the X server. - - screen_number - - Specifies the appropriate screen number on the host server. - - Both return a pointer to the indicated screen. - - DefaultScreen(display); - - int XDefaultScreen(Display *display); - - display - - Specifies the connection to the X server. - - Both return the default screen number referenced by the - XOpenDisplay function. This macro or function should be used to - retrieve the screen number in applications that will use only a - single screen. - - DefaultVisual(display, screen_number); - - Visual *XDefaultVisual(Display *display, int screen_number); - - display - - Specifies the connection to the X server. - - screen_number - - Specifies the appropriate screen number on the host server. - - Both return the default visual type for the specified screen. - For further information about visual types, see section 3.1. - - DisplayCells(display, screen_number); - - int XDisplayCells(Display *display, int screen_number); - - display - - Specifies the connection to the X server. - - screen_number - - Specifies the appropriate screen number on the host server. - - Both return the number of entries in the default colormap. - - DisplayPlanes(display, screen_number); - - int XDisplayPlanes(Display *display, int screen_number); - - display - - Specifies the connection to the X server. - - screen_number - - Specifies the appropriate screen number on the host server. - - Both return the depth of the root window of the specified - screen. For an explanation of depth, see the glossary. - - DisplayString(display); - - char *XDisplayString(Display *display); - - display - - Specifies the connection to the X server. - - Both return the string that was passed to XOpenDisplay when the - current display was opened. On POSIX-conformant systems, if the - passed string was NULL, these return the value of the DISPLAY - environment variable when the current display was opened. These - are useful to applications that invoke the fork system call and - want to open a new connection to the same display from the - child process as well as for printing error messages. - - long XExtendedMaxRequestSize(Display *display); - - display - - Specifies the connection to the X server. - - The XExtendedMaxRequestSize function returns zero if the - specified display does not support an extended-length protocol - encoding; otherwise, it returns the maximum request size (in - 4-byte units) supported by the server using the extended-length - encoding. The Xlib functions XDrawLines, XDrawArcs, - XFillPolygon, XChangeProperty, XSetClipRectangles, and - XSetRegion will use the extended-length encoding as necessary, - if supported by the server. Use of the extended-length encoding - in other Xlib functions (for example, XDrawPoints, - XDrawRectangles, XDrawSegments, XFillArcs, XFillRectangles, - XPutImage) is permitted but not required; an Xlib - implementation may choose to split the data across multiple - smaller requests instead. - - long XMaxRequestSize(Display *display); - - display - - Specifies the connection to the X server. - - The XMaxRequestSize function returns the maximum request size - (in 4-byte units) supported by the server without using an - extended-length protocol encoding. Single protocol requests to - the server can be no larger than this size unless an - extended-length protocol encoding is supported by the server. - The protocol guarantees the size to be no smaller than 4096 - units (16384 bytes). Xlib automatically breaks data up into - multiple protocol requests as necessary for the following - functions: XDrawPoints, XDrawRectangles, XDrawSegments, - XFillArcs, XFillRectangles, and XPutImage. - - LastKnownRequestProcessed(display); - - unsigned long XLastKnownRequestProcessed(Display *display); - - display - - Specifies the connection to the X server. - - Both extract the full serial number of the last request known - by Xlib to have been processed by the X server. Xlib - automatically sets this number when replies, events, and errors - are received. - - NextRequest(display); - - unsigned long XNextRequest(Display *display); - - display - - Specifies the connection to the X server. - - Both extract the full serial number that is to be used for the - next request. Serial numbers are maintained separately for each - display connection. - - ProtocolVersion(display); - - int XProtocolVersion(Display *display); - - display - - Specifies the connection to the X server. - - Both return the major version number (11) of the X protocol - associated with the connected display. - - ProtocolRevision(display); - - int XProtocolRevision(Display *display); - - display - - Specifies the connection to the X server. - - Both return the minor protocol revision number of the X server. - - QLength(display); - - int XQLength(Display *display); - - display - - Specifies the connection to the X server. - - Both return the length of the event queue for the connected - display. Note that there may be more events that have not been - read into the queue yet (see XEventsQueued). - - RootWindow(display, screen_number); - - Window XRootWindow(Display *display, int screen_number); - - display - - Specifies the connection to the X server. - - screen_number - - Specifies the appropriate screen number on the host server. - - Both return the root window. These are useful with functions - that need a drawable of a particular screen and for creating - top-level windows. - - ScreenCount(display); - - int XScreenCount(Display *display); - - display - - Specifies the connection to the X server. - - Both return the number of available screens. - - ServerVendor(display); - - char *XServerVendor(Display *display); - - display - - Specifies the connection to the X server. - - Both return a pointer to a null-terminated string that provides - some identification of the owner of the X server - implementation. If the data returned by the server is in the - Latin Portable Character Encoding, then the string is in the - Host Portable Character Encoding. Otherwise, the contents of - the string are implementation-dependent. - - VendorRelease(display); - - int XVendorRelease(Display *display); - - display - - Specifies the connection to the X server. - - Both return a number related to a vendor's release of the X - server. - -Image Format Functions and Macros - - Applications are required to present data to the X server in a - format that the server demands. To help simplify applications, - most of the work required to convert the data is provided by - Xlib (see sections 8.7 and 16.8). - - The XPixmapFormatValues structure provides an interface to the - pixmap format information that is returned at the time of a - connection setup. It contains: -typedef struct { - int depth; - int bits_per_pixel; - int scanline_pad; -} XPixmapFormatValues; - - To obtain the pixmap format information for a given display, - use XListPixmapFormats. - - XPixmapFormatValues *XListPixmapFormats(Display *display, int - *count_return); - - display - - Specifies the connection to the X server. - - count_return - - Returns the number of pixmap formats that are supported by the - display. - - The XListPixmapFormats function returns an array of - XPixmapFormatValues structures that describe the types of Z - format images supported by the specified display. If - insufficient memory is available, XListPixmapFormats returns - NULL. To free the allocated storage for the XPixmapFormatValues - structures, use XFree. - - The following lists the C language macros, their corresponding - function equivalents that are for other language bindings, and - what data they both return for the specified server and screen. - These are often used by toolkits as well as by simple - applications. - - ImageByteOrder(display); - - int XImageByteOrder(Display *display); - - display - - Specifies the connection to the X server. - - Both specify the required byte order for images for each - scanline unit in XY format (bitmap) or for each pixel value in - Z format. The macro or function can return either LSBFirst or - MSBFirst. - - XBitmapUnit(display); - - int XBitmapUnit(Display *display); - - display - - Specifies the connection to the X server. - - Both return the size of a bitmap's scanline unit in bits. The - scanline is calculated in multiples of this value. - - BitmapBitOrder(display); - - int XBitmapBitOrder(Display *display); - - display - - Specifies the connection to the X server. - - Within each bitmap unit, the left-most bit in the bitmap as - displayed on the screen is either the least significant or most - significant bit in the unit. This macro or function can return - LSBFirst or MSBFirst. - - BitmapPad(display); - - int XBitmapPad(Display *display); - - display - - Specifies the connection to the X server. - - Each scanline must be padded to a multiple of bits returned by - this macro or function. - - DisplayHeight(display, screen_number); - - int XDisplayHeight(Display *display, int screen_number); - - display - - Specifies the connection to the X server. - - screen_number - - Specifies the appropriate screen number on the host server. - - Both return an integer that describes the height of the screen - in pixels. - - DisplayHeightMM(display, screen_number); - - int XDisplayHeightMM(Display *display, int screen_number); - - display - - Specifies the connection to the X server. - - screen_number - - Specifies the appropriate screen number on the host server. - - Both return the height of the specified screen in millimeters. - - DisplayWidth(display, screen_number); - - int XDisplayWidth(Display *display, int screen_number); - - display - - Specifies the connection to the X server. - - screen_number - - Specifies the appropriate screen number on the host server. - - Both return the width of the screen in pixels. - - DisplayWidthMM(display, screen_number); - - int XDisplayWidthMM(Display *display, int screen_number); - - display - - Specifies the connection to the X server. - - screen_number - - Specifies the appropriate screen number on the host server. - - Both return the width of the specified screen in millimeters. - -Screen Information Macros - - The following lists the C language macros, their corresponding - function equivalents that are for other language bindings, and - what data they both can return. These macros or functions all - take a pointer to the appropriate screen structure. - - BlackPixelOfScreen(screen); - - unsigned long XBlackPixelOfScreen(Screen *screen); - - screen - - Specifies the appropriate Screen structure. - - Both return the black pixel value of the specified screen. - - XWhitePixelOfScreen(screen); - - unsigned long XWhitePixelOfScreen(Screen *screen); - - screen - - Specifies the appropriate Screen structure. - - Both return the white pixel value of the specified screen. - - CellsOfScreen(screen); - - int XCellsOfScreen(Screen *screen); - - screen - - Specifies the appropriate Screen structure. - - Both return the number of colormap cells in the default - colormap of the specified screen. - - DefaultColormapOfScreen(screen); - - Colormap XDefaultColormapOfScreen(Screen *screen); - - screen - - Specifies the appropriate Screen structure. - - Both return the default colormap of the specified screen. - - DefaultDepthOfScreen(screen); - - int XDefaultDepthOfScreen(Screen *screen); - - screen - - Specifies the appropriate Screen structure. - - Both return the depth of the root window. - - DefaultGCOfScreen(screen); - - GC XDefaultGCOfScreen(Screen *screen); - - screen - - Specifies the appropriate Screen structure. - - Both return a default graphics context (GC) of the specified - screen, which has the same depth as the root window of the - screen. The GC must never be freed. - - XDefaultVisualOfScreen(screen); - - Visual *XDefaultVisualOfScreen(Screen *screen); - - screen - - Specifies the appropriate Screen structure. - - Both return the default visual of the specified screen. For - information on visual types, see section 3.1. - - DoesBackingStore(screen); - - int XDoesBackingStore(Screen *screen); - - screen - - Specifies the appropriate Screen structure. - - Both return a value indicating whether the screen supports - backing stores. The value returned can be one of WhenMapped, - NotUseful, or Always (see section 3.2.4). - - DoesSaveUnders(screen); - - Bool XDoesSaveUnders(Screen *screen); - - screen - - Specifies the appropriate Screen structure. - - Both return a Boolean value indicating whether the screen - supports save unders. If True, the screen supports save unders. - If False, the screen does not support save unders (see section - 3.2.5). - - DisplayOfScreen(screen); - - Display *XDisplayOfScreen(Screen *screen); - - screen - - Specifies the appropriate Screen structure. - - Both return the display of the specified screen. - - ScreenNumberOfScreen(screen); - - long XScreenNumberOfScreen(Screen *screen); - - screen - - Specifies the appropriate Screen structure. - - The XScreenNumberOfScreen function returns the screen index - number of the specified screen. - - EventMaskOfScreen(screen); - - long XEventMaskOfScreen(Screen *screen); - - screen - - Specifies the appropriate Screen structure. - - Both return the event mask of the root window for the specified - screen at connection setup time. - - WidthOfScreen(screen); - - int XWidthOfScreen(Screen *screen); - - screen - - Specifies the appropriate Screen structure. - - Both return the width of the specified screen in pixels. - - HeightOfScreen(screen); - - int XHeightOfScreen(Screen *screen); - - screen - - Specifies the appropriate Screen structure. - - Both return the height of the specified screen in pixels. - - WidthMMOfScreen(screen); - - int XWidthMMOfScreen(Screen *screen); - - screen - - Specifies the appropriate Screen structure. - - Both return the width of the specified screen in millimeters. - - HeightMMOfScreen(screen); - - int XHeightMMOfScreen(Screen *screen); - - screen - - Specifies the appropriate Screen structure. - - Both return the height of the specified screen in millimeters. - - MaxCmapsOfScreen(screen); - - int XMaxCmapsOfScreen(Screen *screen); - - screen - - Specifies the appropriate Screen structure. - - Both return the maximum number of installed colormaps supported - by the specified screen (see section 9.3). - - MinCmapsOfScreen(screen); - - int XMinCmapsOfScreen(Screen *screen); - - screen - - Specifies the appropriate Screen structure. - - Both return the minimum number of installed colormaps supported - by the specified screen (see section 9.3). - - PlanesOfScreen(screen); - - int XPlanesOfScreen(Screen *screen); - - screen - - Specifies the appropriate Screen structure. - - Both return the depth of the root window. - - RootWindowOfScreen(screen); - - Window XRootWindowOfScreen(Screen *screen); - - screen - - Specifies the appropriate Screen structure. - - Both return the root window of the specified screen. - -Generating a NoOperation Protocol Request - - To execute a NoOperation protocol request, use XNoOp. - - XNoOp(Display *display); - - display - - Specifies the connection to the X server. - - The XNoOp function sends a NoOperation protocol request to the - X server, thereby exercising the connection. - -Freeing Client-Created Data - - To free in-memory data that was created by an Xlib function, - use XFree. - - XFree(void *data); - - data - - Specifies the data that is to be freed. - - The XFree function is a general-purpose Xlib routine that frees - the specified data. You must use it to free any objects that - were allocated by Xlib, unless an alternate function is - explicitly specified for the object. A NULL pointer cannot be - passed to this function. - -Closing the Display - - To close a display or disconnect from the X server, use - XCloseDisplay. - - XCloseDisplay(Display *display); - - display - - Specifies the connection to the X server. - - The XCloseDisplay function closes the connection to the X - server for the display specified in the Display structure and - destroys all windows, resource IDs (Window, Font, Pixmap, - Colormap, Cursor, and GContext), or other resources that the - client has created on this display, unless the close-down mode - of the client has been changed (see XSetCloseDownMode). - Therefore, these windows, resource IDs, and other resources - should never be referenced again or an error will be generated. - Before exiting, you should call XCloseDisplay explicitly so - that any pending errors are reported as XCloseDisplay performs - a final XSync operation. - - XCloseDisplay can generate a BadGC error. - - Xlib provides a function to permit the resources owned by a - client to survive after the client's connection is closed. To - change a client's close-down mode, use XSetCloseDownMode. - - XSetCloseDownMode(Display *display, int close_mode); - - display - - Specifies the connection to the X server. - - close_mode - - Specifies the client close-down mode. You can pass DestroyAll, - RetainPermanent, or RetainTemporary. - - The XSetCloseDownMode function defines what will happen to the - client's resources at connection close. A connection starts in - DestroyAll mode. For information on what happens to the - client's resources when the close_mode argument is - RetainPermanent or RetainTemporary, see section 2.6. - - XSetCloseDownMode can generate a BadValue error. - -Using X Server Connection Close Operations - - When the X server's connection to a client is closed either by - an explicit call to XCloseDisplay or by a process that exits, - the X server performs the following automatic operations: - * It disowns all selections owned by the client (see - XSetSelectionOwner). - * It performs an XUngrabPointer and XUngrabKeyboard if the - client has actively grabbed the pointer or the keyboard. - * It performs an XUngrabServer if the client has grabbed the - server. - * It releases all passive grabs made by the client. - * It marks all resources (including colormap entries) - allocated by the client either as permanent or temporary, - depending on whether the close-down mode is RetainPermanent - or RetainTemporary. However, this does not prevent other - client applications from explicitly destroying the - resources (see XSetCloseDownMode). - - When the close-down mode is DestroyAll, the X server destroys - all of a client's resources as follows: - * It examines each window in the client's save-set to - determine if it is an inferior (subwindow) of a window - created by the client. (The save-set is a list of other - clients' windows that are referred to as save-set windows.) - If so, the X server reparents the save-set window to the - closest ancestor so that the save-set window is not an - inferior of a window created by the client. The reparenting - leaves unchanged the absolute coordinates (with respect to - the root window) of the upper-left outer corner of the - save-set window. - * It performs a MapWindow request on the save-set window if - the save-set window is unmapped. The X server does this - even if the save-set window was not an inferior of a window - created by the client. - * It destroys all windows created by the client. - * It performs the appropriate free request on each nonwindow - resource created by the client in the server (for example, - Font, Pixmap, Cursor, Colormap, and GContext). - * It frees all colors and colormap entries allocated by a - client application. - - Additional processing occurs when the last connection to the X - server closes. An X server goes through a cycle of having no - connections and having some connections. When the last - connection to the X server closes as a result of a connection - closing with the close_mode of DestroyAll, the X server does - the following: - * It resets its state as if it had just been started. The X - server begins by destroying all lingering resources from - clients that have terminated in RetainPermanent or - RetainTemporary mode. - * It deletes all but the predefined atom identifiers. - * It deletes all properties on all root windows (see section - 4.3). - * It resets all device maps and attributes (for example, key - click, bell volume, and acceleration) as well as the access - control list. - * It restores the standard root tiles and cursors. - * It restores the default font path. - * It restores the input focus to state PointerRoot. - - However, the X server does not reset if you close a connection - with a close-down mode set to RetainPermanent or - RetainTemporary. - -Using Xlib with Threads - - On systems that have threads, support may be provided to permit - multiple threads to use Xlib concurrently. - - To initialize support for concurrent threads, use XInitThreads. - - Status XInitThreads(void); - - The XInitThreads function initializes Xlib support for - concurrent threads. This function must be the first Xlib - function a multi-threaded program calls, and it must complete - before any other Xlib call is made. This function returns a - nonzero status if initialization was successful; otherwise, it - returns zero. On systems that do not support threads, this - function always returns zero. - - It is only necessary to call this function if multiple threads - might use Xlib concurrently. If all calls to Xlib functions are - protected by some other access mechanism (for example, a mutual - exclusion lock in a toolkit or through explicit client - programming), Xlib thread initialization is not required. It is - recommended that single-threaded programs not call this - function. - - To lock a display across several Xlib calls, use XLockDisplay. - - XLockDisplay(Display *display); - - display - - Specifies the connection to the X server. - - The XLockDisplay function locks out all other threads from - using the specified display. Other threads attempting to use - the display will block until the display is unlocked by this - thread. Nested calls to XLockDisplay work correctly; the - display will not actually be unlocked until XUnlockDisplay has - been called the same number of times as XLockDisplay. This - function has no effect unless Xlib was successfully initialized - for threads using XInitThreads. - - To unlock a display, use XUnlockDisplay. - - XUnlockDisplay(Display *display); - - display - - Specifies the connection to the X server. - - The XUnlockDisplay function allows other threads to use the - specified display again. Any threads that have blocked on the - display are allowed to continue. Nested locking works - correctly; if XLockDisplay has been called multiple times by a - thread, then XUnlockDisplay must be called an equal number of - times before the display is actually unlocked. This function - has no effect unless Xlib was successfully initialized for - threads using XInitThreads. - -Using Internal Connections - - In addition to the connection to the X server, an Xlib - implementation may require connections to other kinds of - servers (for example, to input method servers as described in - chapter 13). Toolkits and clients that use multiple displays, - or that use displays in combination with other inputs, need to - obtain these additional connections to correctly block until - input is available and need to process that input when it is - available. Simple clients that use a single display and block - for input in an Xlib event function do not need to use these - facilities. - - To track internal connections for a display, use - XAddConnectionWatch. - - typedef void (*XConnectionWatchProc)(Display *display, XPointer - client_data, int fd, Bool opening, XPointer *watch_data); - - Status XAddConnectionWatch(Display *display, - XConnectionWatchProc procedure, XPointer client_data); - - display - - Specifies the connection to the X server. - - procedure - - Specifies the procedure to be called. - - client_data - - Specifies the additional client data. - - The XAddConnectionWatch function registers a procedure to be - called each time Xlib opens or closes an internal connection - for the specified display. The procedure is passed the display, - the specified client_data, the file descriptor for the - connection, a Boolean indicating whether the connection is - being opened or closed, and a pointer to a location for private - watch data. If opening is True, the procedure can store a - pointer to private data in the location pointed to by - watch_data; when the procedure is later called for this same - connection and opening is False, the location pointed to by - watch_data will hold this same private data pointer. - - This function can be called at any time after a display is - opened. If internal connections already exist, the registered - procedure will immediately be called for each of them, before - XAddConnectionWatch returns. XAddConnectionWatch returns a - nonzero status if the procedure is successfully registered; - otherwise, it returns zero. - - The registered procedure should not call any Xlib functions. If - the procedure directly or indirectly causes the state of - internal connections or watch procedures to change, the result - is not defined. If Xlib has been initialized for threads, the - procedure is called with the display locked and the result of a - call by the procedure to any Xlib function that locks the - display is not defined unless the executing thread has - externally locked the display using XLockDisplay. - - To stop tracking internal connections for a display, use - XRemoveConnectionWatch. - - Status XRemoveConnectionWatch(Display *display, - XConnectionWatchProc procedure, XPointer client_data); - - display - - Specifies the connection to the X server. - - procedure - - Specifies the procedure to be called. - - client_data - - Specifies the additional client data. - - The XRemoveConnectionWatch function removes a previously - registered connection watch procedure. The client_data must - match the client_data used when the procedure was initially - registered. - - To process input on an internal connection, use - XProcessInternalConnection. - - void XProcessInternalConnection(Display *display, int fd); - - display - - Specifies the connection to the X server. - - fd - - Specifies the file descriptor. - - The XProcessInternalConnection function processes input - available on an internal connection. This function should be - called for an internal connection only after an operating - system facility (for example, select or poll) has indicated - that input is available; otherwise, the effect is not defined. - - To obtain all of the current internal connections for a - display, use XInternalConnectionNumbers. - - Status XInternalConnectionNumbers(Display *display, int ** fd, - int * count_return); - - display - - Specifies the connection to the X server. - - fd_return - - Returns the file descriptors. - - count_return - - Returns the number of file descriptors. - - The XInternalConnectionNumbers function returns a list of the - file descriptors for all internal connections currently open - for the specified display. When the allocated list is no longer - needed, free it by using XFree. This functions returns a - nonzero status if the list is successfully allocated; - otherwise, it returns zero. - -Chapter 3. Window Functions - - Table of Contents - - Visual Types - Window Attributes - - Background Attribute - Border Attribute - Gravity Attributes - Backing Store Attribute - Save Under Flag - Backing Planes and Backing Pixel Attributes - Event Mask and Do Not Propagate Mask Attributes - Override Redirect Flag - Colormap Attribute - Cursor Attribute - - Creating Windows - Destroying Windows - Mapping Windows - Unmapping Windows - Configuring Windows - Changing Window Stacking Order - Changing Window Attributes - -Visual Types - - On some display hardware, it may be possible to deal with color - resources in more than one way. For example, you may be able to - deal with a screen of either 12-bit depth with arbitrary - mapping of pixel to color (pseudo-color) or 24-bit depth with 8 - bits of the pixel dedicated to each of red, green, and blue. - These different ways of dealing with the visual aspects of the - screen are called visuals. For each screen of the display, - there may be a list of valid visual types supported at - different depths of the screen. Because default windows and - visual types are defined for each screen, most simple - applications need not deal with this complexity. Xlib provides - macros and functions that return the default root window, the - default depth of the default root window, and the default - visual type (see sections 2.2.1 and 16.7). - - Xlib uses an opaque Visual structure that contains information - about the possible color mapping. The visual utility functions - (see section 16.7) use an XVisualInfo structure to return this - information to an application. The members of this structure - pertinent to this discussion are class, red_mask, green_mask, - blue_mask, bits_per_rgb, and colormap_size. The class member - specifies one of the possible visual classes of the screen and - can be StaticGray, StaticColor, TrueColor, GrayScale, - PseudoColor, or DirectColor. - - The following concepts may serve to make the explanation of - visual types clearer. The screen can be color or grayscale, can - have a colormap that is writable or read-only, and can also - have a colormap whose indices are decomposed into separate RGB - pieces, provided one is not on a grayscale screen. This leads - to the following diagram: - Color Gray-Scale - R/O R/W R/O R/W ----------------------------------------------- - Undecomposed Static Pseudo Static Gray - Colormap Color Color Gray Scale - - Decomposed True Direct - Colormap Color Color ----------------------------------------------- - - Conceptually, as each pixel is read out of video memory for - display on the screen, it goes through a look-up stage by - indexing into a colormap. Colormaps can be manipulated - arbitrarily on some hardware, in limited ways on other - hardware, and not at all on other hardware. The visual types - affect the colormap and the RGB values in the following ways: - - * For PseudoColor, a pixel value indexes a colormap to - produce independent RGB values, and the RGB values can be - changed dynamically. - * GrayScale is treated the same way as PseudoColor except - that the primary that drives the screen is undefined. Thus, - the client should always store the same value for red, - green, and blue in the colormaps. - * For DirectColor, a pixel value is decomposed into separate - RGB subfields, and each subfield separately indexes the - colormap for the corresponding value. The RGB values can be - changed dynamically. - * TrueColor is treated the same way as DirectColor except - that the colormap has predefined, read-only RGB values. - These RGB values are server dependent but provide linear or - near-linear ramps in each primary. - * StaticColor is treated the same way as PseudoColor except - that the colormap has predefined, read-only, - server-dependent RGB values. - * StaticGray is treated the same way as StaticColor except - that the RGB values are equal for any single pixel value, - thus resulting in shades of gray. StaticGray with a - two-entry colormap can be thought of as monochrome. - - The red_mask, green_mask, and blue_mask members are only - defined for DirectColor and TrueColor. Each has one contiguous - set of bits with no intersections. The bits_per_rgb member - specifies the log base 2 of the number of distinct color values - (individually) of red, green, and blue. Actual RGB values are - unsigned 16-bit numbers. The colormap_size member defines the - number of available colormap entries in a newly created - colormap. For DirectColor and TrueColor, this is the size of an - individual pixel subfield. - - To obtain the visual ID from a Visual, use XVisualIDFromVisual. - - VisualID XVisualIDFromVisual(Visual *visual); - - visual - - Specifies the visual type. - - The XVisualIDFromVisual function returns the visual ID for the - specified visual type. - -Window Attributes - - All InputOutput windows have a border width of zero or more - pixels, an optional background, an event suppression mask - (which suppresses propagation of events from children), and a - property list (see section 4.3). The window border and - background can be a solid color or a pattern, called a tile. - All windows except the root have a parent and are clipped by - their parent. If a window is stacked on top of another window, - it obscures that other window for the purpose of input. If a - window has a background (almost all do), it obscures the other - window for purposes of output. Attempts to output to the - obscured area do nothing, and no input events (for example, - pointer motion) are generated for the obscured area. - - Windows also have associated property lists (see section 4.3). - - Both InputOutput and InputOnly windows have the following - common attributes, which are the only attributes of an - InputOnly window: - * win-gravity - * event-mask - * do-not-propagate-mask - * override-redirect - * cursor - - If you specify any other attributes for an InputOnly window, a - BadMatch error results. - - InputOnly windows are used for controlling input events in - situations where InputOutput windows are unnecessary. InputOnly - windows are invisible; can only be used to control such things - as cursors, input event generation, and grabbing; and cannot be - used in any graphics requests. Note that InputOnly windows - cannot have InputOutput windows as inferiors. - - Windows have borders of a programmable width and pattern as - well as a background pattern or tile. Pixel values can be used - for solid colors. The background and border pixmaps can be - destroyed immediately after creating the window if no further - explicit references to them are to be made. The pattern can - either be relative to the parent or absolute. If - ParentRelative, the parent's background is used. - - When windows are first created, they are not visible (not - mapped) on the screen. Any output to a window that is not - visible on the screen and that does not have backing store will - be discarded. An application may wish to create a window long - before it is mapped to the screen. When a window is eventually - mapped to the screen (using XMapWindow), the X server generates - an Expose event for the window if backing store has not been - maintained. - - A window manager can override your choice of size, border - width, and position for a top-level window. Your program must - be prepared to use the actual size and position of the top - window. It is not acceptable for a client application to resize - itself unless in direct response to a human command to do so. - Instead, either your program should use the space given to it, - or if the space is too small for any useful work, your program - might ask the user to resize the window. The border of your - top-level window is considered fair game for window managers. - - To set an attribute of a window, set the appropriate member of - the XSetWindowAttributes structure and OR in the corresponding - value bitmask in your subsequent calls to XCreateWindow and - XChangeWindowAttributes, or use one of the other convenience - functions that set the appropriate attribute. The symbols for - the value mask bits and the XSetWindowAttributes structure are: - - /* Window attribute value mask bits */ -/* Window attribute value mask bits */ -#define CWBackPixmap (1L<<0) -#define CWBackPixel (1L<<1) -#define CWBorderPixmap (1L<<2) -#define CWBorderPixel (1L<<3) -#define CWBitGravity (1L<<4) -#define CWWinGravity (1L<<5) -#define CWBackingStore (1L<<6) -#define CWBackingPlanes (1L<<7) -#define CWBackingPixel (1L<<8) -#define CWOverrideRedirect (1L<<9) -#define CWSaveUnder (1L<<10) -#define CWEventMask (1L<<11) -#define CWDontPropagate (1L<<12) -#define CWColormap (1L<<13) -#define CWCursor (1L<<14) - - - -/* Values */ - -typedef struct { - Pixmap background_pixmap; /* background, None, or ParentRelativ -e */ - unsigned long background_pixel; /* background pixel */ - Pixmap border_pixmap; /* border of the window or CopyFromP -arent */ - unsigned long border_pixel; /* border pixel value */ - int bit_gravity; /* one of bit gravity values */ - int win_gravity; /* one of the window gravity values */ - int backing_store; /* NotUseful, WhenMapped, Always */ - unsigned long backing_planes; /* planes to be preserved if poss -ible */ - unsigned long backing_pixel; /* value to use in restoring plane -s */ - Bool save_under; /* should bits under be saved? (popups) */ - long event_mask; /* set of events that should be saved */ - long do_not_propagate_mask; /* set of events that should not pr -opagate */ - Bool override_redirect; /* boolean value for override_redirect -*/ - Colormap colormap; /* color map to be associated with window */ - Cursor cursor; /* cursor to be displayed (or None) */ -} XSetWindowAttributes; - - The following lists the defaults for each window attribute and - indicates whether the attribute is applicable to InputOutput - and InputOnly windows: - Attribute Default InputOutput InputOnly - background-pixmap None Yes No - background-pixel Undefined Yes No - border-pixmap CopyFromParent Yes No - border-pixel Undefined Yes No - bit-gravity ForgetGravity Yes No - win-gravity NorthWestGravity Yes Yes - backing-store NotUseful Yes No - backing-planes All ones Yes No - backing-pixel zero Yes No - save-under False Yes No - event-mask empty set Yes Yes - do-not-propagate-mask empty set Yes Yes - override-redirect False Yes Yes - colormap CopyFromParent Yes No - cursor None Yes Yes - -Background Attribute - - Only InputOutput windows can have a background. You can set the - background of an InputOutput window by using a pixel or a - pixmap. - - The background-pixmap attribute of a window specifies the - pixmap to be used for a window's background. This pixmap can be - of any size, although some sizes may be faster than others. The - background-pixel attribute of a window specifies a pixel value - used to paint a window's background in a single color. - - You can set the background-pixmap to a pixmap, None (default), - or ParentRelative. You can set the background-pixel of a window - to any pixel value (no default). If you specify a - background-pixel, it overrides either the default - background-pixmap or any value you may have set in the - background-pixmap. A pixmap of an undefined size that is filled - with the background-pixel is used for the background. Range - checking is not performed on the background pixel; it simply is - truncated to the appropriate number of bits. - - If you set the background-pixmap, it overrides the default. The - background-pixmap and the window must have the same depth, or a - BadMatch error results. If you set background-pixmap to None, - the window has no defined background. If you set the - background-pixmap to ParentRelative: - * The parent window's background-pixmap is used. The child - window, however, must have the same depth as its parent, or - a BadMatch error results. - * If the parent window has a background-pixmap of None, the - window also has a background-pixmap of None. - * A copy of the parent window's background-pixmap is not - made. The parent's background-pixmap is examined each time - the child window's background-pixmap is required. - * The background tile origin always aligns with the parent - window's background tile origin. If the background-pixmap - is not ParentRelative, the background tile origin is the - child window's origin. - - Setting a new background, whether by setting background-pixmap - or background-pixel, overrides any previous background. The - background-pixmap can be freed immediately if no further - explicit reference is made to it (the X server will keep a copy - to use when needed). If you later draw into the pixmap used for - the background, what happens is undefined because the X - implementation is free to make a copy of the pixmap or to use - the same pixmap. - - When no valid contents are available for regions of a window - and either the regions are visible or the server is maintaining - backing store, the server automatically tiles the regions with - the window's background unless the window has a background of - None. If the background is None, the previous screen contents - from other windows of the same depth as the window are simply - left in place as long as the contents come from the parent of - the window or an inferior of the parent. Otherwise, the initial - contents of the exposed regions are undefined. Expose events - are then generated for the regions, even if the - background-pixmap is None (see section 10.9). - -Border Attribute - - Only InputOutput windows can have a border. You can set the - border of an InputOutput window by using a pixel or a pixmap. - - The border-pixmap attribute of a window specifies the pixmap to - be used for a window's border. The border-pixel attribute of a - window specifies a pixmap of undefined size filled with that - pixel be used for a window's border. Range checking is not - performed on the background pixel; it simply is truncated to - the appropriate number of bits. The border tile origin is - always the same as the background tile origin. - - You can also set the border-pixmap to a pixmap of any size - (some may be faster than others) or to CopyFromParent - (default). You can set the border-pixel to any pixel value (no - default). - - If you set a border-pixmap, it overrides the default. The - border-pixmap and the window must have the same depth, or a - BadMatch error results. If you set the border-pixmap to - CopyFromParent, the parent window's border-pixmap is copied. - Subsequent changes to the parent window's border attribute do - not affect the child window. However, the child window must - have the same depth as the parent window, or a BadMatch error - results. - - The border-pixmap can be freed immediately if no further - explicit reference is made to it. If you later draw into the - pixmap used for the border, what happens is undefined because - the X implementation is free either to make a copy of the - pixmap or to use the same pixmap. If you specify a - border-pixel, it overrides either the default border-pixmap or - any value you may have set in the border-pixmap. All pixels in - the window's border will be set to the border-pixel. Setting a - new border, whether by setting border-pixel or by setting - border-pixmap, overrides any previous border. - - Output to a window is always clipped to the inside of the - window. Therefore, graphics operations never affect the window - border. - -Gravity Attributes - - The bit gravity of a window defines which region of the window - should be retained when an InputOutput window is resized. The - default value for the bit-gravity attribute is ForgetGravity. - The window gravity of a window allows you to define how the - InputOutput or InputOnly window should be repositioned if its - parent is resized. The default value for the win-gravity - attribute is NorthWestGravity. - - If the inside width or height of a window is not changed and if - the window is moved or its border is changed, then the contents - of the window are not lost but move with the window. Changing - the inside width or height of the window causes its contents to - be moved or lost (depending on the bit-gravity of the window) - and causes children to be reconfigured (depending on their - win-gravity). For a change of width and height, the (x, y) - pairs are defined: - - Gravity Direction Coordinates - NorthWestGravity (0, 0) - NorthGravity (Width/2, 0) - NorthEastGravity (Width, 0) - WestGravity (0, Height/2) - CenterGravity (Width/2, Height/2) - EastGravity (Width, Height/2) - SouthWestGravity (0, Height) - SouthGravity (Width/2, Height) - SouthEastGravity (Width, Height) - - When a window with one of these bit-gravity values is resized, - the corresponding pair defines the change in position of each - pixel in the window. When a window with one of these - win-gravities has its parent window resized, the corresponding - pair defines the change in position of the window within the - parent. When a window is so repositioned, a GravityNotify event - is generated (see section 10.10.5). - - A bit-gravity of StaticGravity indicates that the contents or - origin should not move relative to the origin of the root - window. If the change in size of the window is coupled with a - change in position (x, y), then for bit-gravity the change in - position of each pixel is (-x, -y), and for win-gravity the - change in position of a child when its parent is so resized is - (-x, -y). Note that StaticGravity still only takes effect when - the width or height of the window is changed, not when the - window is moved. - - A bit-gravity of ForgetGravity indicates that the window's - contents are always discarded after a size change, even if a - backing store or save under has been requested. The window is - tiled with its background and zero or more Expose events are - generated. If no background is defined, the existing screen - contents are not altered. Some X servers may also ignore the - specified bit-gravity and always generate Expose events. - - The contents and borders of inferiors are not affected by their - parent's bit-gravity. A server is permitted to ignore the - specified bit-gravity and use Forget instead. - - A win-gravity of UnmapGravity is like NorthWestGravity (the - window is not moved), except the child is also unmapped when - the parent is resized, and an UnmapNotify event is generated. - -Backing Store Attribute - - Some implementations of the X server may choose to maintain the - contents of InputOutput windows. If the X server maintains the - contents of a window, the off-screen saved pixels are known as - backing store. The backing store advises the X server on what - to do with the contents of a window. The backing-store - attribute can be set to NotUseful (default), WhenMapped, or - Always. - - A backing-store attribute of NotUseful advises the X server - that maintaining contents is unnecessary, although some X - implementations may still choose to maintain contents and, - therefore, not generate Expose events. A backing-store - attribute of WhenMapped advises the X server that maintaining - contents of obscured regions when the window is mapped would be - beneficial. In this case, the server may generate an Expose - event when the window is created. A backing-store attribute of - Always advises the X server that maintaining contents even when - the window is unmapped would be beneficial. Even if the window - is larger than its parent, this is a request to the X server to - maintain complete contents, not just the region within the - parent window boundaries. While the X server maintains the - window's contents, Expose events normally are not generated, - but the X server may stop maintaining contents at any time. - - When the contents of obscured regions of a window are being - maintained, regions obscured by noninferior windows are - included in the destination of graphics requests (and source, - when the window is the source). However, regions obscured by - inferior windows are not included. - -Save Under Flag - - Some server implementations may preserve contents of - InputOutput windows under other InputOutput windows. This is - not the same as preserving the contents of a window for you. - You may get better visual appeal if transient windows (for - example, pop-up menus) request that the system preserve the - screen contents under them, so the temporarily obscured - applications do not have to repaint. - - You can set the save-under flag to True or False (default). If - save-under is True, the X server is advised that, when this - window is mapped, saving the contents of windows it obscures - would be beneficial. - -Backing Planes and Backing Pixel Attributes - - You can set backing planes to indicate (with bits set to 1) - which bit planes of an InputOutput window hold dynamic data - that must be preserved in backing store and during save unders. - The default value for the backing-planes attribute is all bits - set to 1. You can set backing pixel to specify what bits to use - in planes not covered by backing planes. The default value for - the backing-pixel attribute is all bits set to 0. The X server - is free to save only the specified bit planes in the backing - store or the save under and is free to regenerate the remaining - planes with the specified pixel value. Any extraneous bits in - these values (that is, those bits beyond the specified depth of - the window) may be simply ignored. If you request backing store - or save unders, you should use these members to minimize the - amount of off-screen memory required to store your window. - -Event Mask and Do Not Propagate Mask Attributes - - The event mask defines which events the client is interested in - for this InputOutput or InputOnly window (or, for some event - types, inferiors of this window). The event mask is the bitwise - inclusive OR of zero or more of the valid event mask bits. You - can specify that no maskable events are reported by setting - NoEventMask (default). - - The do-not-propagate-mask attribute defines which events should - not be propagated to ancestor windows when no client has the - event type selected in this InputOutput or InputOnly window. - The do-not-propagate-mask is the bitwise inclusive OR of zero - or more of the following masks: KeyPress, KeyRelease, - ButtonPress, ButtonRelease, PointerMotion, Button1Motion, - Button2Motion, Button3Motion, Button4Motion, Button5Motion, and - ButtonMotion. You can specify that all events are propagated by - setting NoEventMask (default). - -Override Redirect Flag - - To control window placement or to add decoration, a window - manager often needs to intercept (redirect) any map or - configure request. Pop-up windows, however, often need to be - mapped without a window manager getting in the way. To control - whether an InputOutput or InputOnly window is to ignore these - structure control facilities, use the override-redirect flag. - - The override-redirect flag specifies whether map and configure - requests on this window should override a - SubstructureRedirectMask on the parent. You can set the - override-redirect flag to True or False (default). Window - managers use this information to avoid tampering with pop-up - windows (see also chapter 14). - -Colormap Attribute - - The colormap attribute specifies which colormap best reflects - the true colors of the InputOutput window. The colormap must - have the same visual type as the window, or a BadMatch error - results. X servers capable of supporting multiple hardware - colormaps can use this information, and window managers can use - it for calls to XInstallColormap. You can set the colormap - attribute to a colormap or to CopyFromParent (default). - - If you set the colormap to CopyFromParent, the parent window's - colormap is copied and used by its child. However, the child - window must have the same visual type as the parent, or a - BadMatch error results. The parent window must not have a - colormap of None, or a BadMatch error results. The colormap is - copied by sharing the colormap object between the child and - parent, not by making a complete copy of the colormap contents. - Subsequent changes to the parent window's colormap attribute do - not affect the child window. - -Cursor Attribute - - The cursor attribute specifies which cursor is to be used when - the pointer is in the InputOutput or InputOnly window. You can - set the cursor to a cursor or None (default). - - If you set the cursor to None, the parent's cursor is used when - the pointer is in the InputOutput or InputOnly window, and any - change in the parent's cursor will cause an immediate change in - the displayed cursor. By calling XFreeCursor, the cursor can be - freed immediately as long as no further explicit reference to - it is made. - -Creating Windows - - Xlib provides basic ways for creating windows, and toolkits - often supply higher-level functions specifically for creating - and placing top-level windows, which are discussed in the - appropriate toolkit documentation. If you do not use a toolkit, - however, you must provide some standard information or hints - for the window manager by using the Xlib inter-client - communication functions (see chapter 14). - - If you use Xlib to create your own top-level windows (direct - children of the root window), you must observe the following - rules so that all applications interact reasonably across the - different styles of window management: - * You must never fight with the window manager for the size - or placement of your top-level window. - * You must be able to deal with whatever size window you get, - even if this means that your application just prints a - message like ``Please make me bigger'' in its window. - * You should only attempt to resize or move top-level windows - in direct response to a user request. If a request to - change the size of a top-level window fails, you must be - prepared to live with what you get. You are free to resize - or move the children of top-level windows as necessary. - (Toolkits often have facilities for automatic relayout.) - * If you do not use a toolkit that automatically sets - standard window properties, you should set these properties - for top-level windows before mapping them. - - For further information, see chapter 14 and the Inter-Client - Communication Conventions Manual. - - XCreateWindow is the more general function that allows you to - set specific window attributes when you create a window. - XCreateSimpleWindow creates a window that inherits its - attributes from its parent window. - - The X server acts as if InputOnly windows do not exist for the - purposes of graphics requests, exposure processing, and - VisibilityNotify events. An InputOnly window cannot be used as - a drawable (that is, as a source or destination for graphics - requests). InputOnly and InputOutput windows act identically in - other respects (properties, grabs, input control, and so on). - Extension packages can define other classes of windows. - - To create an unmapped window and set its window attributes, use - XCreateWindow. - - Window XCreateWindow(Display *display, Window parent, int x, - int y, unsigned int width, unsigned int height, unsigned int - border_width, int depth, unsigned int class, Visual *visual, - unsigned long valuemask, XSetWindowAttributes *attributes); - - display - - Specifies the connection to the X server. - - parent - - Specifies the parent window. - - x - - y - - Specify the x and y coordinates, which are the top-left outside - corner of the created window's borders and are relative to the - inside of the parent window's borders. - - width - - height - - Specify the width and height, which are the created window's - inside dimensions and do not include the created window's - borders. The dimensions must be nonzero, or a BadValue error - results. - - border_width - - Specifies the width of the created window's border in pixels. - - depth - - Specifies the window's depth. A depth of CopyFromParent means - the depth is taken from the parent. - - class - - Specifies the created window's class. You can pass InputOutput, - InputOnly, or CopyFromParent. A class of CopyFromParent means - the class is taken from the parent. - - visual - - Specifies the visual type. A visual of CopyFromParent means the - visual type is taken from the parent. - - valuemask - - Specifies which window attributes are defined in the attributes - argument. This mask is the bitwise inclusive OR of the valid - attribute mask bits. If valuemask is zero, the attributes are - ignored and are not referenced. - - attributes - - Specifies the structure from which the values (as specified by - the value mask) are to be taken. The value mask should have the - appropriate bits set to indicate which attributes have been set - in the structure. - - The XCreateWindow function creates an unmapped subwindow for a - specified parent window, returns the window ID of the created - window, and causes the X server to generate a CreateNotify - event. The created window is placed on top in the stacking - order with respect to siblings. - - The coordinate system has the X axis horizontal and the Y axis - vertical with the origin [0, 0] at the upper-left corner. - Coordinates are integral, in terms of pixels, and coincide with - pixel centers. Each window and pixmap has its own coordinate - system. For a window, the origin is inside the border at the - inside, upper-left corner. - - The border_width for an InputOnly window must be zero, or a - BadMatch error results. For class InputOutput, the visual type - and depth must be a combination supported for the screen, or a - BadMatch error results. The depth need not be the same as the - parent, but the parent must not be a window of class InputOnly, - or a BadMatch error results. For an InputOnly window, the depth - must be zero, and the visual must be one supported by the - screen. If either condition is not met, a BadMatch error - results. The parent window, however, may have any depth and - class. If you specify any invalid window attribute for a - window, a BadMatch error results. - - The created window is not yet displayed (mapped) on the user's - display. To display the window, call XMapWindow. The new window - initially uses the same cursor as its parent. A new cursor can - be defined for the new window by calling XDefineCursor. The - window will not be visible on the screen unless it and all of - its ancestors are mapped and it is not obscured by any of its - ancestors. - - XCreateWindow can generate BadAlloc, BadColor, BadCursor, - BadMatch, BadPixmap, BadValue, and BadWindow errors. - - To create an unmapped InputOutput subwindow of a given parent - window, use XCreateSimpleWindow. - - Window XCreateSimpleWindow(Display *display, Window parent, int - x, int y, unsigned int width, unsigned int height, unsigned int - border_width, unsigned long border, unsigned long background); - - display - - Specifies the connection to the X server. - - parent - - Specifies the parent window. - - x - - y - - Specify the x and y coordinates, which are the top-left outside - corner of the new window's borders and are relative to the - inside of the parent window's borders. - - width - - height - - Specify the width and height, which are the created window's - inside dimensions and do not include the created window's - borders. The dimensions must be nonzero, or a BadValue error - results. - - border_width - - Specifies the width of the created window's border in pixels. - - border - - Specifies the border pixel value of the window. - - background - - Specifies the background pixel value of the window. - - The XCreateSimpleWindow function creates an unmapped - InputOutput subwindow for a specified parent window, returns - the window ID of the created window, and causes the X server to - generate a CreateNotify event. The created window is placed on - top in the stacking order with respect to siblings. Any part of - the window that extends outside its parent window is clipped. - The border_width for an InputOnly window must be zero, or a - BadMatch error results. XCreateSimpleWindow inherits its depth, - class, and visual from its parent. All other window attributes, - except background and border, have their default values. - - XCreateSimpleWindow can generate BadAlloc, BadMatch, BadValue, - and BadWindow errors. - -Destroying Windows - - Xlib provides functions that you can use to destroy a window or - destroy all subwindows of a window. - - To destroy a window and all of its subwindows, use - XDestroyWindow. - - XDestroyWindow(Display *display, Window w); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - The XDestroyWindow function destroys the specified window as - well as all of its subwindows and causes the X server to - generate a DestroyNotify event for each window. The window - should never be referenced again. If the window specified by - the w argument is mapped, it is unmapped automatically. The - ordering of the DestroyNotify events is such that for any given - window being destroyed, DestroyNotify is generated on any - inferiors of the window before being generated on the window - itself. The ordering among siblings and across subhierarchies - is not otherwise constrained. If the window you specified is a - root window, no windows are destroyed. Destroying a mapped - window will generate Expose events on other windows that were - obscured by the window being destroyed. - - XDestroyWindow can generate a BadWindow error. - - To destroy all subwindows of a specified window, use - XDestroySubwindows. - - XDestroySubwindows(Display *display, Window w); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - The XDestroySubwindows function destroys all inferior windows - of the specified window, in bottom-to-top stacking order. It - causes the X server to generate a DestroyNotify event for each - window. If any mapped subwindows were actually destroyed, - XDestroySubwindows causes the X server to generate Expose - events on the specified window. This is much more efficient - than deleting many windows one at a time because much of the - work need be performed only once for all of the windows, rather - than for each window. The subwindows should never be referenced - again. - - XDestroySubwindows can generate a BadWindow error. - -Mapping Windows - - A window is considered mapped if an XMapWindow call has been - made on it. It may not be visible on the screen for one of the - following reasons: - * It is obscured by another opaque window. - * One of its ancestors is not mapped. - * It is entirely clipped by an ancestor. - - Expose events are generated for the window when part or all of - it becomes visible on the screen. A client receives the Expose - events only if it has asked for them. Windows retain their - position in the stacking order when they are unmapped. - - A window manager may want to control the placement of - subwindows. If SubstructureRedirectMask has been selected by a - window manager on a parent window (usually a root window), a - map request initiated by other clients on a child window is not - performed, and the window manager is sent a MapRequest event. - However, if the override-redirect flag on the child had been - set to True (usually only on pop-up menus), the map request is - performed. - - A tiling window manager might decide to reposition and resize - other clients' windows and then decide to map the window to its - final location. A window manager that wants to provide - decoration might reparent the child into a frame first. For - further information, see sections 3.2.8 and 10.10. Only a - single client at a time can select for - SubstructureRedirectMask. - - Similarly, a single client can select for ResizeRedirectMask on - a parent window. Then, any attempt to resize the window by - another client is suppressed, and the client receives a - ResizeRequest event. - - To map a given window, use XMapWindow. - - XMapWindow(Display *display, Window w); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - The XMapWindow function maps the window and all of its - subwindows that have had map requests. Mapping a window that - has an unmapped ancestor does not display the window but marks - it as eligible for display when the ancestor becomes mapped. - Such a window is called unviewable. When all its ancestors are - mapped, the window becomes viewable and will be visible on the - screen if it is not obscured by another window. This function - has no effect if the window is already mapped. - - If the override-redirect of the window is False and if some - other client has selected SubstructureRedirectMask on the - parent window, then the X server generates a MapRequest event, - and the XMapWindow function does not map the window. Otherwise, - the window is mapped, and the X server generates a MapNotify - event. - - If the window becomes viewable and no earlier contents for it - are remembered, the X server tiles the window with its - background. If the window's background is undefined, the - existing screen contents are not altered, and the X server - generates zero or more Expose events. If backing-store was - maintained while the window was unmapped, no Expose events are - generated. If backing-store will now be maintained, a - full-window exposure is always generated. Otherwise, only - visible regions may be reported. Similar tiling and exposure - take place for any newly viewable inferiors. - - If the window is an InputOutput window, XMapWindow generates - Expose events on each InputOutput window that it causes to be - displayed. If the client maps and paints the window and if the - client begins processing events, the window is painted twice. - To avoid this, first ask for Expose events and then map the - window, so the client processes input events as usual. The - event list will include Expose for each window that has - appeared on the screen. The client's normal response to an - Expose event should be to repaint the window. This method - usually leads to simpler programs and to proper interaction - with window managers. - - XMapWindow can generate a BadWindow error. - - To map and raise a window, use XMapRaised. - - XMapRaised(Display *display, Window w); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - The XMapRaised function essentially is similar to XMapWindow in - that it maps the window and all of its subwindows that have had - map requests. However, it also raises the specified window to - the top of the stack. For additional information, see - XMapWindow. - - XMapRaised can generate multiple BadWindow errors. - - To map all subwindows for a specified window, use - XMapSubwindows. - - XMapSubwindows(Display *display, Window w); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - The XMapSubwindows function maps all subwindows for a specified - window in top-to-bottom stacking order. The X server generates - Expose events on each newly displayed window. This may be much - more efficient than mapping many windows one at a time because - the server needs to perform much of the work only once, for all - of the windows, rather than for each window. - - XMapSubwindows can generate a BadWindow error. - -Unmapping Windows - - Xlib provides functions that you can use to unmap a window or - all subwindows. - - To unmap a window, use XUnmapWindow. - - XUnmapWindow(Display *display, Window w); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - The XUnmapWindow function unmaps the specified window and - causes the X server to generate an UnmapNotify event. If the - specified window is already unmapped, XUnmapWindow has no - effect. Normal exposure processing on formerly obscured windows - is performed. Any child window will no longer be visible until - another map call is made on the parent. In other words, the - subwindows are still mapped but are not visible until the - parent is mapped. Unmapping a window will generate Expose - events on windows that were formerly obscured by it. - - XUnmapWindow can generate a BadWindow error. - - To unmap all subwindows for a specified window, use - XUnmapSubwindows. - - XUnmapSubwindows(Display *display, Window w); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - The XUnmapSubwindows function unmaps all subwindows for the - specified window in bottom-to-top stacking order. It causes the - X server to generate an UnmapNotify event on each subwindow and - Expose events on formerly obscured windows. Using this function - is much more efficient than unmapping multiple windows one at a - time because the server needs to perform much of the work only - once, for all of the windows, rather than for each window. - - XUnmapSubwindows can generate a BadWindow error. - -Configuring Windows - - Xlib provides functions that you can use to move a window, - resize a window, move and resize a window, or change a window's - border width. To change one of these parameters, set the - appropriate member of the XWindowChanges structure and OR in - the corresponding value mask in subsequent calls to - XConfigureWindow. The symbols for the value mask bits and the - XWindowChanges structure are: - -/* Configure window value mask bits */ -#define CWX (1<<0) -#define CWY (1<<1) -#define CWWidth (1<<2) -#define CWHeight (1<<3) -#define CWBorderWidth (1<<4) -#define CWSibling (1<<5) -#define CWStackMode (1<<6) - -/* Values */ - -typedef struct { - int x, y; - int width, height; - int border_width; - Window sibling; - int stack_mode; -} XWindowChanges; - - The x and y members are used to set the window's x and y - coordinates, which are relative to the parent's origin and - indicate the position of the upper-left outer corner of the - window. The width and height members are used to set the inside - size of the window, not including the border, and must be - nonzero, or a BadValue error results. Attempts to configure a - root window have no effect. - - The border_width member is used to set the width of the border - in pixels. Note that setting just the border width leaves the - outer-left corner of the window in a fixed position but moves - the absolute position of the window's origin. If you attempt to - set the border-width attribute of an InputOnly window nonzero, - a BadMatch error results. - - The sibling member is used to set the sibling window for - stacking operations. The stack_mode member is used to set how - the window is to be restacked and can be set to Above, Below, - TopIf, BottomIf, or Opposite. - - If the override-redirect flag of the window is False and if - some other client has selected SubstructureRedirectMask on the - parent, the X server generates a ConfigureRequest event, and no - further processing is performed. Otherwise, if some other - client has selected ResizeRedirectMask on the window and the - inside width or height of the window is being changed, a - ResizeRequest event is generated, and the current inside width - and height are used instead. Note that the override-redirect - flag of the window has no effect on ResizeRedirectMask and that - SubstructureRedirectMask on the parent has precedence over - ResizeRedirectMask on the window. - - When the geometry of the window is changed as specified, the - window is restacked among siblings, and a ConfigureNotify event - is generated if the state of the window actually changes. - GravityNotify events are generated after ConfigureNotify - events. If the inside width or height of the window has - actually changed, children of the window are affected as - specified. - - If a window's size actually changes, the window's subwindows - move according to their window gravity. Depending on the - window's bit gravity, the contents of the window also may be - moved (see section 3.2.3). - - If regions of the window were obscured but now are not, - exposure processing is performed on these formerly obscured - windows, including the window itself and its inferiors. As a - result of increasing the width or height, exposure processing - is also performed on any new regions of the window and any - regions where window contents are lost. - - The restack check (specifically, the computation for BottomIf, - TopIf, and Opposite) is performed with respect to the window's - final size and position (as controlled by the other arguments - of the request), not its initial position. If a sibling is - specified without a stack_mode, a BadMatch error results. - - If a sibling and a stack_mode are specified, the window is - restacked as follows: - Above The window is placed just above the sibling. - Below The window is placed just below the sibling. - TopIf If the sibling occludes the window, the window is placed - at the top of the stack. - BottomIf If the window occludes the sibling, the window is - placed at the bottom of the stack. - Opposite If the sibling occludes the window, the window is - placed at the top of the stack. If the window occludes the - sibling, the window is placed at the bottom of the stack. - - If a stack_mode is specified but no sibling is specified, the - window is restacked as follows: - Above The window is placed at the top of the stack. - Below The window is placed at the bottom of the stack. - TopIf If any sibling occludes the window, the window is placed - at the top of the stack. - BottomIf If the window occludes any sibling, the window is - placed at the bottom of the stack. - Opposite If any sibling occludes the window, the window is - placed at the top of the stack. If the window occludes any - sibling, the window is placed at the bottom of the stack. - - Attempts to configure a root window have no effect. - - To configure a window's size, location, stacking, or border, - use XConfigureWindow. - - XConfigureWindow(Display *display, Window w, unsigned int - value_mask, XWindowChanges *values); - - display - - Specifies the connection to the X server. - - w - - Specifies the window to be reconfigured. - - value_mask - - Specifies which values are to be set using information in the - values structure. This mask is the bitwise inclusive OR of the - valid configure window values bits. - - values - - Specifies the XWindowChanges structure. - - The XConfigureWindow function uses the values specified in the - XWindowChanges structure to reconfigure a window's size, - position, border, and stacking order. Values not specified are - taken from the existing geometry of the window. - - If a sibling is specified without a stack_mode or if the window - is not actually a sibling, a BadMatch error results. Note that - the computations for BottomIf, TopIf, and Opposite are - performed with respect to the window's final geometry (as - controlled by the other arguments passed to XConfigureWindow), - not its initial geometry. Any backing store contents of the - window, its inferiors, and other newly visible windows are - either discarded or changed to reflect the current screen - contents (depending on the implementation). - - XConfigureWindow can generate BadMatch, BadValue, and BadWindow - errors. - - To move a window without changing its size, use XMoveWindow. - - XMoveWindow(Display *display, Window w, int x, int y); - - display - - Specifies the connection to the X server. - - w - - Specifies the window to be moved. - - x - - y - - Specify the x and y coordinates, which define the new location - of the top-left pixel of the window's border or the window - itself if it has no border. - - The XMoveWindow function moves the specified window to the - specified x and y coordinates, but it does not change the - window's size, raise the window, or change the mapping state of - the window. Moving a mapped window may or may not lose the - window's contents depending on if the window is obscured by - nonchildren and if no backing store exists. If the contents of - the window are lost, the X server generates Expose events. - Moving a mapped window generates Expose events on any formerly - obscured windows. - - If the override-redirect flag of the window is False and some - other client has selected SubstructureRedirectMask on the - parent, the X server generates a ConfigureRequest event, and no - further processing is performed. Otherwise, the window is - moved. - - XMoveWindow can generate a BadWindow error. - - To change a window's size without changing the upper-left - coordinate, use XResizeWindow. - - XResizeWindow(Display *display, Window w, unsigned int width, - unsigned int height); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - width - - height - - Specify the width and height, which are the interior dimensions - of the window after the call completes. - - The XResizeWindow function changes the inside dimensions of the - specified window, not including its borders. This function does - not change the window's upper-left coordinate or the origin and - does not restack the window. Changing the size of a mapped - window may lose its contents and generate Expose events. If a - mapped window is made smaller, changing its size generates - Expose events on windows that the mapped window formerly - obscured. - - If the override-redirect flag of the window is False and some - other client has selected SubstructureRedirectMask on the - parent, the X server generates a ConfigureRequest event, and no - further processing is performed. If either width or height is - zero, a BadValue error results. - - XResizeWindow can generate BadValue and BadWindow errors. - - To change the size and location of a window, use - XMoveResizeWindow. - - XMoveResizeWindow(Display *display, Window w, int x, int y, - unsigned int width, unsigned int height); - - display - - Specifies the connection to the X server. - - w - - Specifies the window to be reconfigured. - - x - - y - - Specify the x and y coordinates, which define the new position - of the window relative to its parent. - - width - - height - - Specify the width and height, which define the interior size of - the window. - - The XMoveResizeWindow function changes the size and location of - the specified window without raising it. Moving and resizing a - mapped window may generate an Expose event on the window. - Depending on the new size and location parameters, moving and - resizing a window may generate Expose events on windows that - the window formerly obscured. - - If the override-redirect flag of the window is False and some - other client has selected SubstructureRedirectMask on the - parent, the X server generates a ConfigureRequest event, and no - further processing is performed. Otherwise, the window size and - location are changed. - - XMoveResizeWindow can generate BadValue and BadWindow errors. - - To change the border width of a given window, use - XSetWindowBorderWidth. - - XSetWindowBorderWidth(Display *display, Window w, unsigned int - width); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - width - - Specifies the width of the window border. - - The XSetWindowBorderWidth function sets the specified window's - border width to the specified width. - - XSetWindowBorderWidth can generate a BadWindow error. - -Changing Window Stacking Order - - Xlib provides functions that you can use to raise, lower, - circulate, or restack windows. - - To raise a window so that no sibling window obscures it, use - XRaiseWindow. - - XRaiseWindow(Display *display, Window w); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - The XRaiseWindow function raises the specified window to the - top of the stack so that no sibling window obscures it. If the - windows are regarded as overlapping sheets of paper stacked on - a desk, then raising a window is analogous to moving the sheet - to the top of the stack but leaving its x and y location on the - desk constant. Raising a mapped window may generate Expose - events for the window and any mapped subwindows that were - formerly obscured. - - If the override-redirect attribute of the window is False and - some other client has selected SubstructureRedirectMask on the - parent, the X server generates a ConfigureRequest event, and no - processing is performed. Otherwise, the window is raised. - - XRaiseWindow can generate a BadWindow error. - - To lower a window so that it does not obscure any sibling - windows, use XLowerWindow. - - XLowerWindow(Display *display, Window w); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - The XLowerWindow function lowers the specified window to the - bottom of the stack so that it does not obscure any sibling - windows. If the windows are regarded as overlapping sheets of - paper stacked on a desk, then lowering a window is analogous to - moving the sheet to the bottom of the stack but leaving its x - and y location on the desk constant. Lowering a mapped window - will generate Expose events on any windows it formerly - obscured. - - If the override-redirect attribute of the window is False and - some other client has selected SubstructureRedirectMask on the - parent, the X server generates a ConfigureRequest event, and no - processing is performed. Otherwise, the window is lowered to - the bottom of the stack. - - XLowerWindow can generate a BadWindow error. - - To circulate a subwindow up or down, use XCirculateSubwindows. - - XCirculateSubwindows(Display *display, Window w, int - direction); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - direction - - Specifies the direction (up or down) that you want to circulate - the window. You can pass RaiseLowest or LowerHighest. - - The XCirculateSubwindows function circulates children of the - specified window in the specified direction. If you specify - RaiseLowest, XCirculateSubwindows raises the lowest mapped - child (if any) that is occluded by another child to the top of - the stack. If you specify LowerHighest, XCirculateSubwindows - lowers the highest mapped child (if any) that occludes another - child to the bottom of the stack. Exposure processing is then - performed on formerly obscured windows. If some other client - has selected SubstructureRedirectMask on the window, the X - server generates a CirculateRequest event, and no further - processing is performed. If a child is actually restacked, the - X server generates a CirculateNotify event. - - XCirculateSubwindows can generate BadValue and BadWindow - errors. - - To raise the lowest mapped child of a window that is partially - or completely occluded by another child, use - XCirculateSubwindowsUp. - - XCirculateSubwindowsUp(Display *display, Window w); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - The XCirculateSubwindowsUp function raises the lowest mapped - child of the specified window that is partially or completely - occluded by another child. Completely unobscured children are - not affected. This is a convenience function equivalent to - XCirculateSubwindows with RaiseLowest specified. - - XCirculateSubwindowsUp can generate a BadWindow error. - - To lower the highest mapped child of a window that partially or - completely occludes another child, use - XCirculateSubwindowsDown. - - XCirculateSubwindowsDown(Display *display, Window w); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - The XCirculateSubwindowsDown function lowers the highest mapped - child of the specified window that partially or completely - occludes another child. Completely unobscured children are not - affected. This is a convenience function equivalent to - XCirculateSubwindows with LowerHighest specified. - - XCirculateSubwindowsDown can generate a BadWindow error. - - To restack a set of windows from top to bottom, use - XRestackWindows. - - XRestackWindows(Display *display, Window windows[], int - nwindows); - - display - - Specifies the connection to the X server. - - windows - - Specifies an array containing the windows to be restacked. - - nwindows - - Specifies the number of windows to be restacked. - - The XRestackWindows function restacks the windows in the order - specified, from top to bottom. The stacking order of the first - window in the windows array is unaffected, but the other - windows in the array are stacked underneath the first window, - in the order of the array. The stacking order of the other - windows is not affected. For each window in the window array - that is not a child of the specified window, a BadMatch error - results. - - If the override-redirect attribute of a window is False and - some other client has selected SubstructureRedirectMask on the - parent, the X server generates ConfigureRequest events for each - window whose override-redirect flag is not set, and no further - processing is performed. Otherwise, the windows will be - restacked in top-to-bottom order. - - XRestackWindows can generate a BadWindow error. - -Changing Window Attributes - - Xlib provides functions that you can use to set window - attributes. XChangeWindowAttributes is the more general - function that allows you to set one or more window attributes - provided by the XSetWindowAttributes structure. The other - functions described in this section allow you to set one - specific window attribute, such as a window's background. - - To change one or more attributes for a given window, use - XChangeWindowAttributes. - - XChangeWindowAttributes(Display *display, Window w, unsigned - long valuemask, XSetWindowAttributes *attributes); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - valuemask - - Specifies which window attributes are defined in the attributes - argument. This mask is the bitwise inclusive OR of the valid - attribute mask bits. If valuemask is zero, the attributes are - ignored and are not referenced. The values and restrictions are - the same as for XCreateWindow. - - attributes - - Specifies the structure from which the values (as specified by - the value mask) are to be taken. The value mask should have the - appropriate bits set to indicate which attributes have been set - in the structure (see section 3.2). - - Depending on the valuemask, the XChangeWindowAttributes - function uses the window attributes in the XSetWindowAttributes - structure to change the specified window attributes. Changing - the background does not cause the window contents to be - changed. To repaint the window and its background, use - XClearWindow. Setting the border or changing the background - such that the border tile origin changes causes the border to - be repainted. Changing the background of a root window to None - or ParentRelative restores the default background pixmap. - Changing the border of a root window to CopyFromParent restores - the default border pixmap. Changing the win-gravity does not - affect the current position of the window. Changing the - backing-store of an obscured window to WhenMapped or Always, or - changing the backing-planes, backing-pixel, or save-under of a - mapped window may have no immediate effect. Changing the - colormap of a window (that is, defining a new map, not changing - the contents of the existing map) generates a ColormapNotify - event. Changing the colormap of a visible window may have no - immediate effect on the screen because the map may not be - installed (see XInstallColormap). Changing the cursor of a root - window to None restores the default cursor. Whenever possible, - you are encouraged to share colormaps. - - Multiple clients can select input on the same window. Their - event masks are maintained separately. When an event is - generated, it is reported to all interested clients. However, - only one client at a time can select for - SubstructureRedirectMask, ResizeRedirectMask, and - ButtonPressMask. If a client attempts to select any of these - event masks and some other client has already selected one, a - BadAccess error results. There is only one - do-not-propagate-mask for a window, not one per client. - - XChangeWindowAttributes can generate BadAccess, BadColor, - BadCursor, BadMatch, BadPixmap, BadValue, and BadWindow errors. - - To set the background of a window to a given pixel, use - XSetWindowBackground. - - XSetWindowBackground(Display *display, Window w, unsigned long - background_pixel); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - background_pixel - - Specifies the pixel that is to be used for the background. - - The XSetWindowBackground function sets the background of the - window to the specified pixel value. Changing the background - does not cause the window contents to be changed. - XSetWindowBackground uses a pixmap of undefined size filled - with the pixel value you passed. If you try to change the - background of an InputOnly window, a BadMatch error results. - - XSetWindowBackground can generate BadMatch and BadWindow - errors. - - To set the background of a window to a given pixmap, use - XSetWindowBackgroundPixmap. - - XSetWindowBackgroundPixmap(Display *display, Window w, Pixmap - background_pixmap); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - background_pixmap - - Specifies the background pixmap, ParentRelative, or None. - - The XSetWindowBackgroundPixmap function sets the background - pixmap of the window to the specified pixmap. The background - pixmap can immediately be freed if no further explicit - references to it are to be made. If ParentRelative is - specified, the background pixmap of the window's parent is - used, or on the root window, the default background is - restored. If you try to change the background of an InputOnly - window, a BadMatch error results. If the background is set to - None, the window has no defined background. - - XSetWindowBackgroundPixmap can generate BadMatch, BadPixmap, - and BadWindow errors. XSetWindowBackground and - XSetWindowBackgroundPixmap do not change the current contents - of the window. - - To change and repaint a window's border to a given pixel, use - XSetWindowBorder. - - XSetWindowBorder(Display *display, Window w, unsigned long - border_pixel); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - border_pixel - - Specifies the entry in the colormap. - - The XSetWindowBorder function sets the border of the window to - the pixel value you specify. If you attempt to perform this on - an InputOnly window, a BadMatch error results. - - XSetWindowBorder can generate BadMatch and BadWindow errors. - - To change and repaint the border tile of a given window, use - XSetWindowBorderPixmap. - - XSetWindowBorderPixmap(Display *display, Window w, Pixmap - border_pixmap); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - border_pixmap - - Specifies the border pixmap or CopyFromParent. - - The XSetWindowBorderPixmap function sets the border pixmap of - the window to the pixmap you specify. The border pixmap can be - freed immediately if no further explicit references to it are - to be made. If you specify CopyFromParent, a copy of the parent - window's border pixmap is used. If you attempt to perform this - on an InputOnly window, a BadMatch error results. - - XSetWindowBorderPixmap can generate BadMatch, BadPixmap, and - BadWindow errors. - - To set the colormap of a given window, use XSetWindowColormap. - - XSetWindowColormap(Display *display, Window w, Colormap - colormap); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - colormap - - Specifies the colormap. - - The XSetWindowColormap function sets the specified colormap of - the specified window. The colormap must have the same visual - type as the window, or a BadMatch error results. - - XSetWindowColormap can generate BadColor, BadMatch, and - BadWindow errors. - - To define which cursor will be used in a window, use - XDefineCursor. - - XDefineCursor(Display *display, Window w, Cursor cursor); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - cursor - - Specifies the cursor that is to be displayed or None. - - If a cursor is set, it will be used when the pointer is in the - window. If the cursor is None, it is equivalent to - XUndefineCursor. - - XDefineCursor can generate BadCursor and BadWindow errors. - - To undefine the cursor in a given window, use XUndefineCursor. - - XUndefineCursor(Display *display, Window w); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - The XUndefineCursor function undoes the effect of a previous - XDefineCursor for this window. When the pointer is in the - window, the parent's cursor will now be used. On the root - window, the default cursor is restored. - - XUndefineCursor can generate a BadWindow error. - -Chapter 4. Window Information Functions - - Table of Contents - - Obtaining Window Information - Translating Screen Coordinates - Properties and Atoms - Obtaining and Changing Window Properties - Selections - - After you connect the display to the X server and create a - window, you can use the Xlib window information functions to: - * Obtain information about a window - * Translate screen coordinates - * Manipulate property lists - * Obtain and change window properties - * Manipulate selections - -Obtaining Window Information - - Xlib provides functions that you can use to obtain information - about the window tree, the window's current attributes, the - window's current geometry, or the current pointer coordinates. - Because they are most frequently used by window managers, these - functions all return a status to indicate whether the window - still exists. - - To obtain the parent, a list of children, and number of - children for a given window, use XQueryTree. - - Status XQueryTree(Display *display, Window w, Window - *root_return, Window *parent_return, Window **children_return, - unsigned int *nchildren_return); - - display - - Specifies the connection to the X server. - - w - - Specifies the window whose list of children, root, parent, and - number of children you want to obtain. - - root_return - - Returns the root window. - - parent_return - - Returns the parent window. - - children_return - - Returns the list of children. - - nchildren_return - - Returns the number of children. - - The XQueryTree function returns the root ID, the parent window - ID, a pointer to the list of children windows (NULL when there - are no children), and the number of children in the list for - the specified window. The children are listed in current - stacking order, from bottom-most (first) to top-most (last). - XQueryTree returns zero if it fails and nonzero if it succeeds. - To free a non-NULL children list when it is no longer needed, - use XFree. - - XQueryTree can generate a BadWindow error. - - To obtain the current attributes of a given window, use - XGetWindowAttributes. - - Status XGetWindowAttributes(Display *display, Window w, - XWindowAttributes *window_attributes_return); - - display - - Specifies the connection to the X server. - - w - - Specifies the window whose current attributes you want to - obtain. - - window_attributes_return - - Returns the specified window's attributes in the - XWindowAttributes structure. - - The XGetWindowAttributes function returns the current - attributes for the specified window to an XWindowAttributes - structure. - - - -typedef struct { - int x, y; /* location of window */ - int width, height; /* width and height of window */ - int border_width; /* border width of window */ - int depth; /* depth of window */ - Visual *visual; /* the associated visual structure */ - Window root; /* root of screen containing window * -/ - int class; /* InputOutput, InputOnly*/ - int bit_gravity; /* one of the bit gravity values */ - int win_gravity; /* one of the window gravity values * -/ - int backing_store; /* NotUseful, WhenMapped, Always */ - unsigned long backing_planes; /* planes to be preserved if possible - */ - unsigned long backing_pixel; /* value to be used when restoring pl -anes */ - Bool save_under; /* boolean, should bits under be save -d? */ - Colormap colormap; /* color map to be associated with wi -ndow */ - Bool map_installed; /* boolean, is color map currently in -stalled*/ - int map_state; /* IsUnmapped, IsUnviewable, IsViewab -le */ - long all_event_masks; /* set of events all people have inte -rest in*/ - long your_event_mask; /* my event mask */ - long do_not_propagate_mask; /* set of events that should not prop -agate */ - Bool override_redirect; /* boolean value for override-redirec -t */ - Screen *screen; /* back pointer to correct screen */ -} XWindowAttributes; - - The x and y members are set to the upper-left outer corner - relative to the parent window's origin. The width and height - members are set to the inside size of the window, not including - the border. The border_width member is set to the window's - border width in pixels. The depth member is set to the depth of - the window (that is, bits per pixel for the object). The visual - member is a pointer to the screen's associated Visual - structure. The root member is set to the root window of the - screen containing the window. The class member is set to the - window's class and can be either InputOutput or InputOnly. - - The bit_gravity member is set to the window's bit gravity and - can be one of the following: - ForgetGravity EastGravity - NorthWestGravity SouthWestGravity - NorthGravity SouthGravity - NorthEastGravity SouthEastGravity - WestGravity StaticGravity - - The win_gravity member is set to the window's window gravity - and can be one of the following: - UnmapGravity SouthWestGravity - NorthWestGravity SouthGravity - NorthGravity SouthEastGravity - NorthEastGravity StaticGravity - WestGravity CenterGravity - EastGravity - - For additional information on gravity, see section 3.2.3. - - The backing_store member is set to indicate how the X server - should maintain the contents of a window and can be WhenMapped, - Always, or NotUseful. The backing_planes member is set to - indicate (with bits set to 1) which bit planes of the window - hold dynamic data that must be preserved in backing_stores and - during save_unders. The backing_pixel member is set to indicate - what values to use for planes not set in backing_planes. - - The save_under member is set to True or False. The colormap - member is set to the colormap for the specified window and can - be a colormap ID or None. The map_installed member is set to - indicate whether the colormap is currently installed and can be - True or False. The map_state member is set to indicate the - state of the window and can be IsUnmapped, IsUnviewable, or - IsViewable. IsUnviewable is used if the window is mapped but - some ancestor is unmapped. - - The all_event_masks member is set to the bitwise inclusive OR - of all event masks selected on the window by all clients. The - your_event_mask member is set to the bitwise inclusive OR of - all event masks selected by the querying client. The - do_not_propagate_mask member is set to the bitwise inclusive OR - of the set of events that should not propagate. - - The override_redirect member is set to indicate whether this - window overrides structure control facilities and can be True - or False. Window manager clients should ignore the window if - this member is True. - - The screen member is set to a screen pointer that gives you a - back pointer to the correct screen. This makes it easier to - obtain the screen information without having to loop over the - root window fields to see which field matches. - - XGetWindowAttributes can generate BadDrawable and BadWindow - errors. - - To obtain the current geometry of a given drawable, use - XGetGeometry. - - Status XGetGeometry(Display *display, Drawable d, Window - *root_return, int *x_return, int *y_return, unsigned int - *width_return, unsigned int *height_return, unsigned int - *border_width_return, unsigned int *depth_return); - - display - - Specifies the connection to the X server. - - d - - Specifies the drawable, which can be a window or a pixmap. - - root_return - - Returns the root window. - - x_return - - y_return - - Return the x and y coordinates that define the location of the - drawable. For a window, these coordinates specify the - upper-left outer corner relative to its parent's origin. For - pixmaps, these coordinates are always zero. - - width_return - - height_return - - Return the drawable's dimensions (width and height). For a - window, these dimensions specify the inside size, not including - the border. - - border_width_return - - Returns the border width in pixels. If the drawable is a - pixmap, it returns zero. - - depth_return - - Returns the depth of the drawable (bits per pixel for the - object). - - The XGetGeometry function returns the root window and the - current geometry of the drawable. The geometry of the drawable - includes the x and y coordinates, width and height, border - width, and depth. These are described in the argument list. It - is legal to pass to this function a window whose class is - InputOnly. - - XGetGeometry can generate a BadDrawable error. - -Translating Screen Coordinates - - Applications sometimes need to perform a coordinate - transformation from the coordinate space of one window to - another window or need to determine which window the pointing - device is in. XTranslateCoordinates and XQueryPointer fulfill - these needs (and avoid any race conditions) by asking the X - server to perform these operations. - - To translate a coordinate in one window to the coordinate space - of another window, use XTranslateCoordinates. - - Bool XTranslateCoordinates(Display *display, Window src_w, - Window dest_w, int src_x, int src_y, int *dest_x_return, int - *dest_y_return, Window *child_return); - - display - - Specifies the connection to the X server. - - src_w - - Specifies the source window. - - dest_w - - Specifies the destination window. - - src_x - - src_y - - Specify the x and y coordinates within the source window. - - dest_x_return - - dest_y_return - - Return the x and y coordinates within the destination window. - - child_return - - Returns the child if the coordinates are contained in a mapped - child of the destination window. - - If XTranslateCoordinates returns True, it takes the src_x and - src_y coordinates relative to the source window's origin and - returns these coordinates to dest_x_return and dest_y_return - relative to the destination window's origin. If - XTranslateCoordinates returns False, src_w and dest_w are on - different screens, and dest_x_return and dest_y_return are - zero. If the coordinates are contained in a mapped child of - dest_w, that child is returned to child_return. Otherwise, - child_return is set to None. - - XTranslateCoordinates can generate a BadWindow error. - - To obtain the screen coordinates of the pointer or to determine - the pointer coordinates relative to a specified window, use - XQueryPointer. - - Bool XQueryPointer(Display *display, Window w, Window - *root_return, Window *child_return, int *root_x_return, int - *root_y_return, int *win_x_return, int *win_y_return, unsigned - int *mask_return); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - root_return - - Returns the root window that the pointer is in. - - child_return - - Returns the child window that the pointer is located in, if - any. - - root_x_return - - root_y_return - - Return the pointer coordinates relative to the root window's - origin. - - win_x_return - - win_y_return - - Return the pointer coordinates relative to the specified - window. - - mask_return - - Returns the current state of the modifier keys and pointer - buttons. - - The XQueryPointer function returns the root window the pointer - is logically on and the pointer coordinates relative to the - root window's origin. If XQueryPointer returns False, the - pointer is not on the same screen as the specified window, and - XQueryPointer returns None to child_return and zero to - win_x_return and win_y_return. If XQueryPointer returns True, - the pointer coordinates returned to win_x_return and - win_y_return are relative to the origin of the specified - window. In this case, XQueryPointer returns the child that - contains the pointer, if any, or else None to child_return. - - XQueryPointer returns the current logical state of the keyboard - buttons and the modifier keys in mask_return. It sets - mask_return to the bitwise inclusive OR of one or more of the - button or modifier key bitmasks to match the current state of - the mouse buttons and the modifier keys. - - Note that the logical state of a device (as seen through Xlib) - may lag the physical state if device event processing is frozen - (see section 12.1). - - XQueryPointer can generate a BadWindow error. - -Properties and Atoms - - A property is a collection of named, typed data. The window - system has a set of predefined properties (for example, the - name of a window, size hints, and so on), and users can define - any other arbitrary information and associate it with windows. - Each property has a name, which is an ISO Latin-1 string. For - each named property, a unique identifier (atom) is associated - with it. A property also has a type, for example, string or - integer. These types are also indicated using atoms, so - arbitrary new types can be defined. Data of only one type may - be associated with a single property name. Clients can store - and retrieve properties associated with windows. For efficiency - reasons, an atom is used rather than a character string. - XInternAtom can be used to obtain the atom for property names. - - A property is also stored in one of several possible formats. - The X server can store the information as 8-bit quantities, - 16-bit quantities, or 32-bit quantities. This permits the X - server to present the data in the byte order that the client - expects. If you define further properties of complex type, you - must encode and decode them yourself. These functions must be - carefully written if they are to be portable. For further - information about how to write a library extension, see - appendix C. The type of a property is defined by an atom, which - allows for arbitrary extension in this type scheme. - - Certain property names are predefined in the server for - commonly used functions. The atoms for these properties are - defined in . To avoid name clashes with user - symbols, the #define name for each atom has the XA_ prefix. For - an explanation of the functions that let you get and set much - of the information stored in these predefined properties, see - chapter 14. - - The core protocol imposes no semantics on these property names, - but semantics are specified in other X Consortium standards, - such as the Inter-Client Communication Conventions Manual and - the X Logical Font Description Conventions. - - You can use properties to communicate other information between - applications. The functions described in this section let you - define new properties and get the unique atom IDs in your - applications. - - Although any particular atom can have some client - interpretation within each of the name spaces, atoms occur in - five distinct name spaces within the protocol: - * Selections - * Property names - * Property types - * Font properties - * Type of a ClientMessage event (none are built into the X - server) - - The built-in selection property names are: - PRIMARY SECONDARY - - The built-in property names are: - CUT_BUFFER0 RESOURCE_MANAGER - CUT_BUFFER1 WM_CLASS - CUT_BUFFER2 WM_CLIENT_MACHINE - CUT_BUFFER3 WM_COLORMAP_WINDOWS - CUT_BUFFER4 WM_COMMAND - CUT_BUFFER5 WM_HINTS - CUT_BUFFER6 WM_ICON_NAME - CUT_BUFFER7 WM_ICON_SIZE - RGB_BEST_MAP WM_NAME - RGB_BLUE_MAP WM_NORMAL_HINTS - RGB_DEFAULT_MAP WM_PROTOCOLS - RGB_GRAY_MAP WM_STATE - RGB_GREEN_MAP WM_TRANSIENT_FOR - RGB_RED_MAP WM_ZOOM_HINTS - - The built-in property types are: - ARC PIXMAP - ATOM POINT - BITMAP RGB_COLOR_MAP - CARDINAL RECTANGLE - COLORMAP STRING - CURSOR VISUALID - DRAWABLE WINDOW - FONT WM_HINTS - INTEGER WM_SIZE_HINTS - - The built-in font property names are: - MIN_SPACE STRIKEOUT_DESCENT - NORM_SPACE STRIKEOUT_ASCENT - MAX_SPACE ITALIC_ANGLE - END_SPACE X_HEIGHT - SUPERSCRIPT_X QUAD_WIDTH - SUPERSCRIPT_Y WEIGHT - SUBSCRIPT_X POINT_SIZE - SUBSCRIPT_Y RESOLUTION - UNDERLINE_POSITION COPYRIGHT - UNDERLINE_THICKNESS NOTICE - FONT_NAME FAMILY_NAME - FULL_NAME CAP_HEIGHT - - For further information about font properties, see section 8.5. - - To return an atom for a given name, use XInternAtom. - - Atom XInternAtom(Display *display, char *atom_name, Bool - only_if_exists); - - display - - Specifies the connection to the X server. - - atom_name - - Specifies the name associated with the atom you want returned. - - only_if_exists - - Specifies a Boolean value that indicates whether the atom must - be created. - - The XInternAtom function returns the atom identifier associated - with the specified atom_name string. If only_if_exists is - False, the atom is created if it does not exist. Therefore, - XInternAtom can return None. If the atom name is not in the - Host Portable Character Encoding, the result is - implementation-dependent. Uppercase and lowercase matter; the - strings ``thing'', ``Thing'', and ``thinG'' all designate - different atoms. The atom will remain defined even after the - client's connection closes. It will become undefined only when - the last connection to the X server closes. - - XInternAtom can generate BadAlloc and BadValue errors. - - To return atoms for an array of names, use XInternAtoms. - - Status XInternAtoms(Display *display, char **names, int count, - Bool only_if_exists, Atom *atoms_return); - - display - - Specifies the connection to the X server. - - names - - Specifies the array of atom names. - - count - - Specifies the number of atom names in the array. - - only_if_exists - - Specifies a Boolean value that indicates whether the atom must - be created. - - atoms_return - - Returns the atoms. - - The XInternAtoms function returns the atom identifiers - associated with the specified names. The atoms are stored in - the atoms_return array supplied by the caller. Calling this - function is equivalent to calling XInternAtom for each of the - names in turn with the specified value of only_if_exists, but - this function minimizes the number of round-trip protocol - exchanges between the client and the X server. - - This function returns a nonzero status if atoms are returned - for all of the names; otherwise, it returns zero. - - XInternAtoms can generate BadAlloc and BadValue errors. - - To return a name for a given atom identifier, use XGetAtomName. - - char *XGetAtomName(Display *display, Atom atom); - - display - - Specifies the connection to the X server. - - atom - - Specifies the atom for the property name you want returned. - - The XGetAtomName function returns the name associated with the - specified atom. If the data returned by the server is in the - Latin Portable Character Encoding, then the returned string is - in the Host Portable Character Encoding. Otherwise, the result - is implementation-dependent. To free the resulting string, call - XFree. - - XGetAtomName can generate a BadAtom error. - - To return the names for an array of atom identifiers, use - XGetAtomNames. - - Status XGetAtomNames(Display *display, Atom *atoms, int count, - char **names_return); - - display - - Specifies the connection to the X server. - - atoms - - Specifies the array of atoms. - - count - - Specifies the number of atoms in the array. - - names_return - - Returns the atom names. - - The XGetAtomNames function returns the names associated with - the specified atoms. The names are stored in the names_return - array supplied by the caller. Calling this function is - equivalent to calling XGetAtomName for each of the atoms in - turn, but this function minimizes the number of round-trip - protocol exchanges between the client and the X server. - - This function returns a nonzero status if names are returned - for all of the atoms; otherwise, it returns zero. - - XGetAtomNames can generate a BadAtom error. - -Obtaining and Changing Window Properties - - You can attach a property list to every window. Each property - has a name, a type, and a value (see section 4.3). The value is - an array of 8-bit, 16-bit, or 32-bit quantities, whose - interpretation is left to the clients. The type char is used to - represent 8-bit quantities, the type short is used to represent - 16-bit quantities, and the type long is used to represent - 32-bit quantities. - - Xlib provides functions that you can use to obtain, change, - update, or interchange window properties. In addition, Xlib - provides other utility functions for inter-client communication - (see chapter 14). - - To obtain the type, format, and value of a property of a given - window, use XGetWindowProperty. - - int XGetWindowProperty(Display *display, Window w, Atom - property, long long_offset, long long_length, Bool delete, Atom - req_type, Atom *actual_type_return, int *actual_format_return, - unsigned long *nitems_return, unsigned long - *bytes_after_return, unsigned char **prop_return); - - display - - Specifies the connection to the X server. - - w - - Specifies the window whose property you want to obtain. - - property - - Specifies the property name. - - long_offset - - Specifies the offset in the specified property (in 32-bit - quantities) where the data is to be retrieved. - - long_length - - Specifies the length in 32-bit multiples of the data to be - retrieved. - - delete - - Specifies a Boolean value that determines whether the property - is deleted. - - req_type - - Specifies the atom identifier associated with the property type - or AnyPropertyType. - - actual_type_return - - Returns the atom identifier that defines the actual type of the - property. - - actual_format_return - - Returns the actual format of the property. - - nitems_return - - Returns the actual number of 8-bit, 16-bit, or 32-bit items - stored in the prop_return data. - - bytes_after_return - - Returns the number of bytes remaining to be read in the - property if a partial read was performed. - - prop_return - - Returns the data in the specified format. - - The XGetWindowProperty function returns the actual type of the - property; the actual format of the property; the number of - 8-bit, 16-bit, or 32-bit items transferred; the number of bytes - remaining to be read in the property; and a pointer to the data - actually returned. XGetWindowProperty sets the return arguments - as follows: - * If the specified property does not exist for the specified - window, XGetWindowProperty returns None to - actual_type_return and the value zero to - actual_format_return and bytes_after_return. The - nitems_return argument is empty. In this case, the delete - argument is ignored. - * If the specified property exists but its type does not - match the specified type, XGetWindowProperty returns the - actual property type to actual_type_return, the actual - property format (never zero) to actual_format_return, and - the property length in bytes (even if the - actual_format_return is 16 or 32) to bytes_after_return. It - also ignores the delete argument. The nitems_return - argument is empty. - * If the specified property exists and either you assign - AnyPropertyType to the req_type argument or the specified - type matches the actual property type, XGetWindowProperty - returns the actual property type to actual_type_return and - the actual property format (never zero) to - actual_format_return. It also returns a value to - bytes_after_return and nitems_return, by defining the - following values: - * N = actual length of the stored property in bytes (even if - the format is 16 or 32) I = 4 * long_offset T = N - I L = - MINIMUM(T, 4 * long_length) A = N - (I + L) - * The returned value starts at byte index I in the property - (indexing from zero), and its length in bytes is L. If the - value for long_offset causes L to be negative, a BadValue - error results. The value of bytes_after_return is A, giving - the number of trailing unread bytes in the stored property. - - If the returned format is 8, the returned data is represented - as a char array. If the returned format is 16, the returned - data is represented as a short array and should be cast to that - type to obtain the elements. If the returned format is 32, the - returned data is represented as a long array and should be cast - to that type to obtain the elements. - - XGetWindowProperty always allocates one extra byte in - prop_return (even if the property is zero length) and sets it - to zero so that simple properties consisting of characters do - not have to be copied into yet another string before use. - - If delete is True and bytes_after_return is zero, - XGetWindowProperty deletes the property from the window and - generates a PropertyNotify event on the window. - - The function returns Success if it executes successfully. To - free the resulting data, use XFree. - - XGetWindowProperty can generate BadAtom, BadValue, and - BadWindow errors. - - To obtain a given window's property list, use XListProperties. - - Atom *XListProperties(Display *display, Window w, int - *num_prop_return); - - display - - Specifies the connection to the X server. - - w - - Specifies the window whose property list you want to obtain. - - num_prop_return - - Returns the length of the properties array. - - The XListProperties function returns a pointer to an array of - atom properties that are defined for the specified window or - returns NULL if no properties were found. To free the memory - allocated by this function, use XFree. - - XListProperties can generate a BadWindow error. - - To change a property of a given window, use XChangeProperty. - - XChangeProperty(Display *display, Window w, Atom property, Atom - type, int format, int mode, unsignedchar *data, int nelements); - - display - - Specifies the connection to the X server. - - w - - Specifies the window whose property you want to change. - - property - - Specifies the property name. - - type - - Specifies the type of the property. The X server does not - interpret the type but simply passes it back to an application - that later calls XGetWindowProperty. - - format - - Specifies whether the data should be viewed as a list of 8-bit, - 16-bit, or 32-bit quantities. Possible values are 8, 16, and - 32. This information allows the X server to correctly perform - byte-swap operations as necessary. If the format is 16-bit or - 32-bit, you must explicitly cast your data pointer to an - (unsigned char *) in the call to XChangeProperty. - - mode - - Specifies the mode of the operation. You can pass - PropModeReplace, PropModePrepend, or PropModeAppend. - - data - - Specifies the property data. - - nelements - - Specifies the number of elements of the specified data format. - - The XChangeProperty function alters the property for the - specified window and causes the X server to generate a - PropertyNotify event on that window. XChangeProperty performs - the following: - * If mode is PropModeReplace, XChangeProperty discards the - previous property value and stores the new data. - * If mode is PropModePrepend or PropModeAppend, - XChangeProperty inserts the specified data before the - beginning of the existing data or onto the end of the - existing data, respectively. The type and format must match - the existing property value, or a BadMatch error results. - If the property is undefined, it is treated as defined with - the correct type and format with zero-length data. - - If the specified format is 8, the property data must be a char - array. If the specified format is 16, the property data must be - a short array. If the specified format is 32, the property data - must be a long array. - - The lifetime of a property is not tied to the storing client. - Properties remain until explicitly deleted, until the window is - destroyed, or until the server resets. For a discussion of what - happens when the connection to the X server is closed, see - section 2.6. The maximum size of a property is server dependent - and can vary dynamically depending on the amount of memory the - server has available. (If there is insufficient space, a - BadAlloc error results.) - - XChangeProperty can generate BadAlloc, BadAtom, BadMatch, - BadValue, and BadWindow errors. - - To rotate a window's property list, use - XRotateWindowProperties. - - XRotateWindowProperties(Display *display, Window w, Atom - properties[], int num_prop, int npositions); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - properties - - Specifies the array of properties that are to be rotated. - - num_prop - - Specifies the length of the properties array. - - npositions - - Specifies the rotation amount. - - The XRotateWindowProperties function allows you to rotate - properties on a window and causes the X server to generate - PropertyNotify events. If the property names in the properties - array are viewed as being numbered starting from zero and if - there are num_prop property names in the list, then the value - associated with property name I becomes the value associated - with property name (I + npositions) mod N for all I from zero - to N - 1. The effect is to rotate the states by npositions - places around the virtual ring of property names (right for - positive npositions, left for negative npositions). If - npositions mod N is nonzero, the X server generates a - PropertyNotify event for each property in the order that they - are listed in the array. If an atom occurs more than once in - the list or no property with that name is defined for the - window, a BadMatch error results. If a BadAtom or BadMatch - error results, no properties are changed. - - XRotateWindowProperties can generate BadAtom, BadMatch, and - BadWindow errors. - - To delete a property on a given window, use XDeleteProperty. - - XDeleteProperty(Display *display, Window w, Atom property); - - display - - Specifies the connection to the X server. - - w - - Specifies the window whose property you want to delete. - - property - - Specifies the property name. - - The XDeleteProperty function deletes the specified property - only if the property was defined on the specified window and - causes the X server to generate a PropertyNotify event on the - window unless the property does not exist. - - XDeleteProperty can generate BadAtom and BadWindow errors. - -Selections - - Selections are one method used by applications to exchange - data. By using the property mechanism, applications can - exchange data of arbitrary types and can negotiate the type of - the data. A selection can be thought of as an indirect property - with a dynamic type. That is, rather than having the property - stored in the X server, the property is maintained by some - client (the owner). A selection is global in nature (considered - to belong to the user but be maintained by clients) rather than - being private to a particular window subhierarchy or a - particular set of clients. - - Xlib provides functions that you can use to set, get, or - request conversion of selections. This allows applications to - implement the notion of current selection, which requires that - notification be sent to applications when they no longer own - the selection. Applications that support selection often - highlight the current selection and so must be informed when - another application has acquired the selection so that they can - unhighlight the selection. - - When a client asks for the contents of a selection, it - specifies a selection target type. This target type can be used - to control the transmitted representation of the contents. For - example, if the selection is ``the last thing the user clicked - on'' and that is currently an image, then the target type might - specify whether the contents of the image should be sent in XY - format or Z format. - - The target type can also be used to control the class of - contents transmitted, for example, asking for the ``looks'' - (fonts, line spacing, indentation, and so forth) of a paragraph - selection, not the text of the paragraph. The target type can - also be used for other purposes. The protocol does not - constrain the semantics. - - To set the selection owner, use XSetSelectionOwner. - - XSetSelectionOwner(Display *display, Atom selection, Window - owner, Time time); - - display - - Specifies the connection to the X server. - - selection - - Specifies the selection atom. - - owner - - Specifies the owner of the specified selection atom. You can - pass a window or None. - - time - - Specifies the time. You can pass either a timestamp or - CurrentTime. - - The XSetSelectionOwner function changes the owner and - last-change time for the specified selection and has no effect - if the specified time is earlier than the current last-change - time of the specified selection or is later than the current X - server time. Otherwise, the last-change time is set to the - specified time, with CurrentTime replaced by the current server - time. If the owner window is specified as None, then the owner - of the selection becomes None (that is, no owner). Otherwise, - the owner of the selection becomes the client executing the - request. - - If the new owner (whether a client or None) is not the same as - the current owner of the selection and the current owner is not - None, the current owner is sent a SelectionClear event. If the - client that is the owner of a selection is later terminated - (that is, its connection is closed) or if the owner window it - has specified in the request is later destroyed, the owner of - the selection automatically reverts to None, but the - last-change time is not affected. The selection atom is - uninterpreted by the X server. XGetSelectionOwner returns the - owner window, which is reported in SelectionRequest and - SelectionClear events. Selections are global to the X server. - - XSetSelectionOwner can generate BadAtom and BadWindow errors. - - To return the selection owner, use XGetSelectionOwner. - - Window XGetSelectionOwner(Display *display, Atom selection); - - display - - Specifies the connection to the X server. - - selection - - Specifies the selection atom whose owner you want returned. - - The XGetSelectionOwner function returns the window ID - associated with the window that currently owns the specified - selection. If no selection was specified, the function returns - the constant None. If None is returned, there is no owner for - the selection. - - XGetSelectionOwner can generate a BadAtom error. - - To request conversion of a selection, use XConvertSelection. - - XConvertSelection(Display *display, Atom selection, Atom - target, Atom property, Window requestor, Time time); - - display - - Specifies the connection to the X server. - - selection - - Specifies the selection atom. - - target - - Specifies the target atom. - - property - - Specifies the property name. You also can pass None. - - requestor - - Specifies the requestor. - - time - - Specifies the time. You can pass either a timestamp or - CurrentTime. - - XConvertSelection requests that the specified selection be - converted to the specified target type: - * If the specified selection has an owner, the X server sends - a SelectionRequest event to that owner. - * If no owner for the specified selection exists, the X - server generates a SelectionNotify event to the requestor - with property None. - - The arguments are passed on unchanged in either of the events. - There are two predefined selection atoms: PRIMARY and - SECONDARY. - - XConvertSelection can generate BadAtom and BadWindow errors. - -Chapter 5. Pixmap and Cursor Functions - - Table of Contents - - Creating and Freeing Pixmaps - Creating, Recoloring, and Freeing Cursors - -Creating and Freeing Pixmaps - - Pixmaps can only be used on the screen on which they were - created. Pixmaps are off-screen resources that are used for - various operations, such as defining cursors as tiling patterns - or as the source for certain raster operations. Most graphics - requests can operate either on a window or on a pixmap. A - bitmap is a single bit-plane pixmap. - - To create a pixmap of a given size, use XCreatePixmap. - - Pixmap XCreatePixmap(Display *display, Drawable d, unsigned int - width, unsigned int height, unsigned int depth); - - display - - Specifies the connection to the X server. - - d - - Specifies which screen the pixmap is created on. - - width - - height - - Specify the width and height, which define the dimensions of - the pixmap. - - depth - - Specifies the depth of the pixmap. - - The XCreatePixmap function creates a pixmap of the width, - height, and depth you specified and returns a pixmap ID that - identifies it. It is valid to pass an InputOnly window to the - drawable argument. The width and height arguments must be - nonzero, or a BadValue error results. The depth argument must - be one of the depths supported by the screen of the specified - drawable, or a BadValue error results. - - The server uses the specified drawable to determine on which - screen to create the pixmap. The pixmap can be used only on - this screen and only with other drawables of the same depth - (see XCopyPlane for an exception to this rule). The initial - contents of the pixmap are undefined. - - XCreatePixmap can generate BadAlloc, BadDrawable, and BadValue - errors. - - To free all storage associated with a specified pixmap, use - XFreePixmap. - - XFreePixmap(Display *display, Pixmap pixmap); - - display - - Specifies the connection to the X server. - - pixmap - - Specifies the pixmap. - - The XFreePixmap function first deletes the association between - the pixmap ID and the pixmap. Then, the X server frees the - pixmap storage when there are no references to it. The pixmap - should never be referenced again. - - XFreePixmap can generate a BadPixmap error. - -Creating, Recoloring, and Freeing Cursors - - Each window can have a different cursor defined for it. - Whenever the pointer is in a visible window, it is set to the - cursor defined for that window. If no cursor was defined for - that window, the cursor is the one defined for the parent - window. - - From X's perspective, a cursor consists of a cursor source, - mask, colors, and a hotspot. The mask pixmap determines the - shape of the cursor and must be a depth of one. The source - pixmap must have a depth of one, and the colors determine the - colors of the source. The hotspot defines the point on the - cursor that is reported when a pointer event occurs. There may - be limitations imposed by the hardware on cursors as to size - and whether a mask is implemented. XQueryBestCursor can be used - to find out what sizes are possible. There is a standard font - for creating cursors, but Xlib provides functions that you can - use to create cursors from an arbitrary font or from bitmaps. - - To create a cursor from the standard cursor font, use - XCreateFontCursor. - - #include - - Cursor XCreateFontCursor(Display *display, unsigned int shape); - - display - - Specifies the connection to the X server. - - shape - - Specifies the shape of the cursor. - - X provides a set of standard cursor shapes in a special font - named cursor. Applications are encouraged to use this interface - for their cursors because the font can be customized for the - individual display type. The shape argument specifies which - glyph of the standard fonts to use. - - The hotspot comes from the information stored in the cursor - font. The initial colors of a cursor are a black foreground and - a white background (see XRecolorCursor). For further - information about cursor shapes, see appendix B. - - XCreateFontCursor can generate BadAlloc and BadValue errors. - - To create a cursor from font glyphs, use XCreateGlyphCursor. - - Cursor XCreateGlyphCursor(Display *display, Font source_font, - Font mask_font, unsigned int source_char, unsigned int - mask_char, XColor *foreground_color, XColor *background_color); - - display - - Specifies the connection to the X server. - - source_font - - Specifies the font for the source glyph. - - mask_font - - Specifies the font for the mask glyph or None. - - source_char - - Specifies the character glyph for the source. - - mask_char - - Specifies the glyph character for the mask. - - foreground_color - - Specifies the RGB values for the foreground of the source. - - background_color - - Specifies the RGB values for the background of the source. - - The XCreateGlyphCursor function is similar to - XCreatePixmapCursor except that the source and mask bitmaps are - obtained from the specified font glyphs. The source_char must - be a defined glyph in source_font, or a BadValue error results. - If mask_font is given, mask_char must be a defined glyph in - mask_font, or a BadValue error results. The mask_font and - character are optional. The origins of the source_char and - mask_char (if defined) glyphs are positioned coincidently and - define the hotspot. The source_char and mask_char need not have - the same bounding box metrics, and there is no restriction on - the placement of the hotspot relative to the bounding boxes. If - no mask_char is given, all pixels of the source are displayed. - You can free the fonts immediately by calling XFreeFont if no - further explicit references to them are to be made. - - For 2-byte matrix fonts, the 16-bit value should be formed with - the byte1 member in the most significant byte and the byte2 - member in the least significant byte. - - XCreateGlyphCursor can generate BadAlloc, BadFont, and BadValue - errors. - - To create a cursor from two bitmaps, use XCreatePixmapCursor. - - Cursor XCreatePixmapCursor(Display *display, Pixmap source, - Pixmap mask, XColor *foreground_color, XColor - *background_color, unsigned int x, unsigned int y); - - display - - Specifies the connection to the X server. - - source - - Specifies the shape of the source cursor. - - mask - - Specifies the cursor's source bits to be displayed or None. - - foreground_color - - Specifies the RGB values for the foreground of the source. - - background_color - - Specifies the RGB values for the background of the source. - - x - - y - - Specify the x and y coordinates, which indicate the hotspot - relative to the source's origin. - - The XCreatePixmapCursor function creates a cursor and returns - the cursor ID associated with it. The foreground and background - RGB values must be specified using foreground_color and - background_color, even if the X server only has a StaticGray or - GrayScale screen. The foreground color is used for the pixels - set to 1 in the source, and the background color is used for - the pixels set to 0. Both source and mask, if specified, must - have depth one (or a BadMatch error results) but can have any - root. The mask argument defines the shape of the cursor. The - pixels set to 1 in the mask define which source pixels are - displayed, and the pixels set to 0 define which pixels are - ignored. If no mask is given, all pixels of the source are - displayed. The mask, if present, must be the same size as the - pixmap defined by the source argument, or a BadMatch error - results. The hotspot must be a point within the source, or a - BadMatch error results. - - The components of the cursor can be transformed arbitrarily to - meet display limitations. The pixmaps can be freed immediately - if no further explicit references to them are to be made. - Subsequent drawing in the source or mask pixmap has an - undefined effect on the cursor. The X server might or might not - make a copy of the pixmap. - - XCreatePixmapCursor can generate BadAlloc and BadPixmap errors. - - To determine useful cursor sizes, use XQueryBestCursor. - - Status XQueryBestCursor(Display *display, Drawable d, unsigned - int width, unsigned int height, unsigned int *width_return, - unsigned int *height_return); - - display - - Specifies the connection to the X server. - - d - - Specifies the drawable, which indicates the screen. - - width - - height - - Specify the width and height of the cursor that you want the - size information for. - - width_return - - height_return - - Return the best width and height that is closest to the - specified width and height. - - Some displays allow larger cursors than other displays. The - XQueryBestCursor function provides a way to find out what size - cursors are actually possible on the display. It returns the - largest size that can be displayed. Applications should be - prepared to use smaller cursors on displays that cannot support - large ones. - - XQueryBestCursor can generate a BadDrawable error. - - To change the color of a given cursor, use XRecolorCursor. - - XRecolorCursor(Display *display, Cursor cursor, XColor - *foreground_color, XColor *background_color); - - display - - Specifies the connection to the X server. - - cursor - - Specifies the cursor. - - foreground_color - - Specifies the RGB values for the foreground of the source. - - background_color - - Specifies the RGB values for the background of the source. - - The XRecolorCursor function changes the color of the specified - cursor, and if the cursor is being displayed on a screen, the - change is visible immediately. The pixel members of the XColor - structures are ignored; only the RGB values are used. - - XRecolorCursor can generate a BadCursor error. - - To free (destroy) a given cursor, use XFreeCursor. - - XFreeCursor(Display *display, Cursor cursor); - - display - - Specifies the connection to the X server. - - cursor - - Specifies the cursor. - - The XFreeCursor function deletes the association between the - cursor resource ID and the specified cursor. The cursor storage - is freed when no other resource references it. The specified - cursor ID should not be referred to again. - - XFreeCursor can generate a BadCursor error. - -Chapter 6. Color Management Functions - - Table of Contents - - Color Structures - Color Strings - - RGB Device String Specification - RGB Intensity String Specification - Device-Independent String Specifications - - Color Conversion Contexts and Gamut Mapping - Creating, Copying, and Destroying Colormaps - Mapping Color Names to Values - Allocating and Freeing Color Cells - Modifying and Querying Colormap Cells - Color Conversion Context Functions - - Getting and Setting the Color Conversion Context of a - Colormap - - Obtaining the Default Color Conversion Context - Color Conversion Context Macros - Modifying Attributes of a Color Conversion Context - Creating and Freeing a Color Conversion Context - - Converting between Color Spaces - Callback Functions - - Prototype Gamut Compression Procedure - Supplied Gamut Compression Procedures - Prototype White Point Adjustment Procedure - Supplied White Point Adjustment Procedures - - Gamut Querying Functions - - Red, Green, and Blue Queries - CIELab Queries - CIELuv Queries - TekHVC Queries - - Color Management Extensions - - Color Spaces - Adding Device-Independent Color Spaces - Querying Color Space Format and Prefix - Creating Additional Color Spaces - Parse String Callback - Color Specification Conversion Callback - Function Sets - Adding Function Sets - Creating Additional Function Sets - - Each X window always has an associated colormap that provides a - level of indirection between pixel values and colors displayed - on the screen. Xlib provides functions that you can use to - manipulate a colormap. The X protocol defines colors using - values in the RGB color space. The RGB color space is device - dependent; rendering an RGB value on differing output devices - typically results in different colors. Xlib also provides a - means for clients to specify color using device-independent - color spaces for consistent results across devices. Xlib - supports device-independent color spaces derivable from the CIE - XYZ color space. This includes the CIE XYZ, xyY, L*u*v*, and - L*a*b* color spaces as well as the TekHVC color space. - - This chapter discusses how to: - * Create, copy, and destroy a colormap - * Specify colors by name or value - * Allocate, modify, and free color cells - * Read entries in a colormap - * Convert between color spaces - * Control aspects of color conversion - * Query the color gamut of a screen - * Add new color spaces - - All functions, types, and symbols in this chapter with the - prefix ``Xcms'' are defined in . The remaining - functions and types are defined in . - - Functions in this chapter manipulate the representation of - color on the screen. For each possible value that a pixel can - take in a window, there is a color cell in the colormap. For - example, if a window is 4 bits deep, pixel values 0 through 15 - are defined. A colormap is a collection of color cells. A color - cell consists of a triple of red, green, and blue (RGB) values. - The hardware imposes limits on the number of significant bits - in these values. As each pixel is read out of display memory, - the pixel is looked up in a colormap. The RGB value of the cell - determines what color is displayed on the screen. On a - grayscale display with a black-and-white monitor, the values - are combined to determine the brightness on the screen. - - Typically, an application allocates color cells or sets of - color cells to obtain the desired colors. The client can - allocate read-only cells. In which case, the pixel values for - these colors can be shared among multiple applications, and the - RGB value of the cell cannot be changed. If the client - allocates read/write cells, they are exclusively owned by the - client, and the color associated with the pixel value can be - changed at will. Cells must be allocated (and, if read/write, - initialized with an RGB value) by a client to obtain desired - colors. The use of pixel value for an unallocated cell results - in an undefined color. - - Because colormaps are associated with windows, X supports - displays with multiple colormaps and, indeed, different types - of colormaps. If there are insufficient colormap resources in - the display, some windows will display in their true colors, - and others will display with incorrect colors. A window manager - usually controls which windows are displayed in their true - colors if more than one colormap is required for the color - resources the applications are using. At any time, there is a - set of installed colormaps for a screen. Windows using one of - the installed colormaps display with true colors, and windows - using other colormaps generally display with incorrect colors. - You can control the set of installed colormaps by using - XInstallColormap and XUninstallColormap. - - Colormaps are local to a particular screen. Screens always have - a default colormap, and programs typically allocate cells out - of this colormap. Generally, you should not write applications - that monopolize color resources. Although some hardware - supports multiple colormaps installed at one time, many of the - hardware displays built today support only a single installed - colormap, so the primitives are written to encourage sharing of - colormap entries between applications. - - The DefaultColormap macro returns the default colormap. The - DefaultVisual macro returns the default visual type for the - specified screen. Possible visual types are StaticGray, - GrayScale, StaticColor, PseudoColor, TrueColor, or DirectColor - (see section 3.1). - -Color Structures - - Functions that operate only on RGB color space values use an - XColor structure, which contains: - - - -typedef struct { - unsigned long pixel; /* pixel value */ - unsigned short red, green, blue; /* rgb values */ - char flags; /* DoRed, DoGreen, DoBlue */ - char pad; -} XColor; - - The red, green, and blue values are always in the range 0 to - 65535 inclusive, independent of the number of bits actually - used in the display hardware. The server scales these values - down to the range used by the hardware. Black is represented by - (0,0,0), and white is represented by (65535,65535,65535). In - some functions, the flags member controls which of the red, - green, and blue members is used and can be the inclusive OR of - zero or more of DoRed, DoGreen, and DoBlue. - - Functions that operate on all color space values use an - XcmsColor structure. This structure contains a union of - substructures, each supporting color specification encoding for - a particular color space. Like the XColor structure, the - XcmsColor structure contains pixel and color specification - information (the spec member in the XcmsColor structure). - - - -typedef unsigned long XcmsColorFormat; /* Color Specifi -cation Format */ - -typedef struct { - union { - XcmsRGB RGB; - XcmsRGBi RGBi; - XcmsCIEXYZ CIEXYZ; - XcmsCIEuvY CIEuvY; - XcmsCIExyY CIExyY; - XcmsCIELab CIELab; - XcmsCIELuv CIELuv; - XcmsTekHVC TekHVC; - XcmsPad Pad; - } spec; - unsigned long pixel; - XcmsColorFormat format; -} XcmsColor; /* Xcms Color Structure */ - - Because the color specification can be encoded for the various - color spaces, encoding for the spec member is identified by the - format member, which is of type XcmsColorFormat. The following - macros define standard formats. -#define XcmsUndefinedFormat 0x00000000 -#define XcmsCIEXYZFormat 0x00000001 /* CIE XYZ */ -#define XcmsCIEuvYFormat 0x00000002 /* CIE u'v'Y */ -#define XcmsCIExyYFormat 0x00000003 /* CIE xyY */ -#define XcmsCIELabFormat 0x00000004 /* CIE L*a*b* */ -#define XcmsCIELuvFormat 0x00000005 /* CIE L*u*v* */ -#define XcmsTekHVCFormat 0x00000006 /* TekHVC */ -#define XcmsRGBFormat 0x80000000 /* RGB Device */ -#define XcmsRGBiFormat 0x80000001 /* RGB Intensity */ - - Formats for device-independent color spaces are distinguishable - from those for device-dependent spaces by the 32nd bit. If this - bit is set, it indicates that the color specification is in a - device-dependent form; otherwise, it is in a device-independent - form. If the 31st bit is set, this indicates that the color - space has been added to Xlib at run time (see section 6.12.4). - The format value for a color space added at run time may be - different each time the program is executed. If references to - such a color space must be made outside the client (for - example, storing a color specification in a file), then - reference should be made by color space string prefix (see - XcmsFormatOfPrefix and XcmsPrefixOfFormat). - - Data types that describe the color specification encoding for - the various color spaces are defined as follows: - - - -typedef double XcmsFloat; - -typedef struct { - unsigned short red; /* 0x0000 to 0xffff */ - unsigned short green; /* 0x0000 to 0xffff */ - unsigned short blue; /* 0x0000 to 0xffff */ -} XcmsRGB; /* RGB Device */ - - - -typedef struct { - XcmsFloat red; /* 0.0 to 1.0 */ - XcmsFloat green; /* 0.0 to 1.0 */ - XcmsFloat blue; /* 0.0 to 1.0 */ -} XcmsRGBi; /* RGB Intensity */ - - - -typedef struct { - XcmsFloat X; - XcmsFloat Y; /* 0.0 to 1.0 */ - XcmsFloat Z; -} XcmsCIEXYZ; /* CIE XYZ */ - - - -typedef struct { - XcmsFloat u_prime; /* 0.0 to ~0.6 */ - XcmsFloat v_prime; /* 0.0 to ~0.6 */ - XcmsFloat Y; /* 0.0 to 1.0 */ -} XcmsCIEuvY; /* CIE u'v'Y */ - - - -typedef struct { - XcmsFloat x; /* 0.0 to ~.75 */ - XcmsFloat y; /* 0.0 to ~.85 */ - XcmsFloat Y; /* 0.0 to 1.0 */ -} XcmsCIExyY; /* CIE xyY */ - - - -typedef struct { - XcmsFloat L_star; /* 0.0 to 100.0 */ - XcmsFloat a_star; - XcmsFloat b_star; -} XcmsCIELab; /* CIE L*a*b* */ - - - -typedef struct { - XcmsFloat L_star; /* 0.0 to 100.0 */ - XcmsFloat u_star; - XcmsFloat v_star; -} XcmsCIELuv; /* CIE L*u*v* */ - - - -typedef struct { - XcmsFloat H; /* 0.0 to 360.0 */ - XcmsFloat V; /* 0.0 to 100.0 */ - XcmsFloat C; /* 0.0 to 100.0 */ -} XcmsTekHVC; /* TekHVC */ - - - -typedef struct { - XcmsFloat pad0; - XcmsFloat pad1; - XcmsFloat pad2; - XcmsFloat pad3; -} XcmsPad; /* four doubles */ - - The device-dependent formats provided allow color specification - in: - * RGB Intensity (XcmsRGBi) - * Red, green, and blue linear intensity values, - floating-point values from 0.0 to 1.0, where 1.0 indicates - full intensity, 0.5 half intensity, and so on. - * RGB Device (XcmsRGB) - * Red, green, and blue values appropriate for the specified - output device. XcmsRGB values are of type unsigned short, - scaled from 0 to 65535 inclusive, and are interchangeable - with the red, green, and blue values in an XColor - structure. - - It is important to note that RGB Intensity values are not gamma - corrected values. In contrast, RGB Device values generated as a - result of converting color specifications are always gamma - corrected, and RGB Device values acquired as a result of - querying a colormap or passed in by the client are assumed by - Xlib to be gamma corrected. The term RGB value in this manual - always refers to an RGB Device value. - -Color Strings - - Xlib provides a mechanism for using string names for colors. A - color string may either contain an abstract color name or a - numerical color specification. Color strings are - case-insensitive. - - Color strings are used in the following functions: - * XAllocNamedColor - * XcmsAllocNamedColor - * XLookupColor - * XcmsLookupColor - * XParseColor - * XStoreNamedColor - - Xlib supports the use of abstract color names, for example, red - or blue. A value for this abstract name is obtained by - searching one or more color name databases. Xlib first searches - zero or more client-side databases; the number, location, and - content of these databases is implementation-dependent and - might depend on the current locale. If the name is not found, - Xlib then looks for the color in the X server's database. If - the color name is not in the Host Portable Character Encoding, - the result is implementation-dependent. - - A numerical color specification consists of a color space name - and a set of values in the following syntax: - -:/.../ - - The following are examples of valid color strings. - -"CIEXYZ:0.3227/0.28133/0.2493" -"RGBi:1.0/0.0/0.0" -"rgb:00/ff/00" -"CIELuv:50.0/0.0/0.0" - - The syntax and semantics of numerical specifications are given - for each standard color space in the following sections. - -RGB Device String Specification - - An RGB Device specification is identified by the prefix - ``rgb:'' and conforms to the following syntax: - -rgb:// - - , , := h | hh | hhh | hhhh - h := single hexadecimal digits (case insignificant) - - Note that h indicates the value scaled in 4 bits, hh the value - scaled in 8 bits, hhh the value scaled in 12 bits, and hhhh the - value scaled in 16 bits, respectively. - - Typical examples are the strings ``rgb:ea/75/52'' and - ``rgb:ccc/320/320'', but mixed numbers of hexadecimal digit - strings (``rgb:ff/a5/0'' and ``rgb:ccc/32/0'') are also - allowed. - - For backward compatibility, an older syntax for RGB Device is - supported, but its continued use is not encouraged. The syntax - is an initial sharp sign character followed by a numeric - specification, in one of the following formats: - - - -#RGB (4 bits each) -#RRGGBB (8 bits each) -#RRRGGGBBB (12 bits each) -#RRRRGGGGBBBB (16 bits each) - - The R, G, and B represent single hexadecimal digits. When fewer - than 16 bits each are specified, they represent the most - significant bits of the value (unlike the ``rgb:'' syntax, in - which values are scaled). For example, the string ``#3a7'' is - the same as ``#3000a0007000''. - -RGB Intensity String Specification - - An RGB intensity specification is identified by the prefix - ``rgbi:'' and conforms to the following syntax: - -rgbi:// - - Note that red, green, and blue are floating-point values - between 0.0 and 1.0, inclusive. The input format for these - values is an optional sign, a string of numbers possibly - containing a decimal point, and an optional exponent field - containing an E or e followed by a possibly signed integer - string. - -Device-Independent String Specifications - - The standard device-independent string specifications have the - following syntax: - -CIEXYZ:// -CIEuvY:// -CIExyY:// -CIELab:// -CIELuv:// -TekHVC:// - - All of the values (C, H, V, X, Y, Z, a, b, u, v, y, x) are - floating-point values. The syntax for these values is an - optional plus or minus sign, a string of digits possibly - containing a decimal point, and an optional exponent field - consisting of an ``E'' or ``e'' followed by an optional plus or - minus followed by a string of digits. - -Color Conversion Contexts and Gamut Mapping - - When Xlib converts device-independent color specifications into - device-dependent specifications and vice versa, it uses - knowledge about the color limitations of the screen hardware. - This information, typically called the device profile, is - available in a Color Conversion Context (CCC). - - Because a specified color may be outside the color gamut of the - target screen and the white point associated with the color - specification may differ from the white point inherent to the - screen, Xlib applies gamut mapping when it encounters certain - conditions: - * Gamut compression occurs when conversion of - device-independent color specifications to device-dependent - color specifications results in a color out of the target - screen's gamut. - * White adjustment occurs when the inherent white point of - the screen differs from the white point assumed by the - client. - - Gamut handling methods are stored as callbacks in the CCC, - which in turn are used by the color space conversion routines. - Client data is also stored in the CCC for each callback. The - CCC also contains the white point the client assumes to be - associated with color specifications (that is, the Client White - Point). The client can specify the gamut handling callbacks and - client data as well as the Client White Point. Xlib does not - preclude the X client from performing other forms of gamut - handling (for example, gamut expansion); however, Xlib does not - provide direct support for gamut handling other than white - adjustment and gamut compression. - - Associated with each colormap is an initial CCC transparently - generated by Xlib. Therefore, when you specify a colormap as an - argument to an Xlib function, you are indirectly specifying a - CCC. There is a default CCC associated with each screen. Newly - created CCCs inherit attributes from the default CCC, so the - default CCC attributes can be modified to affect new CCCs. - - Xcms functions in which gamut mapping can occur return Status - and have specific status values defined for them, as follows: - * XcmsFailure indicates that the function failed. - * XcmsSuccess indicates that the function succeeded. In - addition, if the function performed any color conversion, - the colors did not need to be compressed. - * XcmsSuccessWithCompression indicates the function performed - color conversion and at least one of the colors needed to - be compressed. The gamut compression method is determined - by the gamut compression procedure in the CCC that is - specified directly as a function argument or in the CCC - indirectly specified by means of the colormap argument. - -Creating, Copying, and Destroying Colormaps - - To create a colormap for a screen, use XCreateColormap. - - Colormap XCreateColormap(Display *display, Window w, Visual - *visual, int alloc); - - display - - Specifies the connection to the X server. - - w - - Specifies the window on whose screen you want to create a - colormap. - - visual - - Specifies a visual type supported on the screen. If the visual - type is not one supported by the screen, a BadMatch error - results. - - alloc - - Specifies the colormap entries to be allocated. You can pass - AllocNone or AllocAll. - - The XCreateColormap function creates a colormap of the - specified visual type for the screen on which the specified - window resides and returns the colormap ID associated with it. - Note that the specified window is only used to determine the - screen. - - The initial values of the colormap entries are undefined for - the visual classes GrayScale, PseudoColor, and DirectColor. For - StaticGray, StaticColor, and TrueColor, the entries have - defined values, but those values are specific to the visual and - are not defined by X. For StaticGray, StaticColor, and - TrueColor, alloc must be AllocNone, or a BadMatch error - results. For the other visual classes, if alloc is AllocNone, - the colormap initially has no allocated entries, and clients - can allocate them. For information about the visual types, see - section 3.1. - - If alloc is AllocAll, the entire colormap is allocated - writable. The initial values of all allocated entries are - undefined. For GrayScale and PseudoColor, the effect is as if - an XAllocColorCells call returned all pixel values from zero to - N - 1, where N is the colormap entries value in the specified - visual. For DirectColor, the effect is as if an - XAllocColorPlanes call returned a pixel value of zero and - red_mask, green_mask, and blue_mask values containing the same - bits as the corresponding masks in the specified visual. - However, in all cases, none of these entries can be freed by - using XFreeColors. - - XCreateColormap can generate BadAlloc, BadMatch, BadValue, and - BadWindow errors. - - To create a new colormap when the allocation out of a - previously shared colormap has failed because of resource - exhaustion, use XCopyColormapAndFree. - - Colormap XCopyColormapAndFree(Display *display, Colormap - colormap); - - display - - Specifies the connection to the X server. - - colormap - - Specifies the colormap. - - The XCopyColormapAndFree function creates a colormap of the - same visual type and for the same screen as the specified - colormap and returns the new colormap ID. It also moves all of - the client's existing allocation from the specified colormap to - the new colormap with their color values intact and their - read-only or writable characteristics intact and frees those - entries in the specified colormap. Color values in other - entries in the new colormap are undefined. If the specified - colormap was created by the client with alloc set to AllocAll, - the new colormap is also created with AllocAll, all color - values for all entries are copied from the specified colormap, - and then all entries in the specified colormap are freed. If - the specified colormap was not created by the client with - AllocAll, the allocations to be moved are all those pixels and - planes that have been allocated by the client using - XAllocColor, XAllocNamedColor, XAllocColorCells, or - XAllocColorPlanes and that have not been freed since they were - allocated. - - XCopyColormapAndFree can generate BadAlloc and BadColor errors. - - To destroy a colormap, use XFreeColormap. - - XFreeColormap(Display *display, Colormap colormap); - - display - - Specifies the connection to the X server. - - colormap - - Specifies the colormap that you want to destroy. - - The XFreeColormap function deletes the association between the - colormap resource ID and the colormap and frees the colormap - storage. However, this function has no effect on the default - colormap for a screen. If the specified colormap is an - installed map for a screen, it is uninstalled (see - XUninstallColormap). If the specified colormap is defined as - the colormap for a window (by XCreateWindow, - XSetWindowColormap, or XChangeWindowAttributes), XFreeColormap - changes the colormap associated with the window to None and - generates a ColormapNotify event. X does not define the colors - displayed for a window with a colormap of None. - - XFreeColormap can generate a BadColor error. - -Mapping Color Names to Values - - To map a color name to an RGB value, use XLookupColor. - - Status XLookupColor(Display *display, Colormap colormap, char - *color_name, XColor *exact_def_return, XColor - *screen_def_return); - - display - - Specifies the connection to the X server. - - colormap - - Specifies the colormap. - - color_name - - Specifies the color name string (for example, red) whose color - definition structure you want returned. - - exact_def_return - - Returns the exact RGB values. - - screen_def_return - - Returns the closest RGB values provided by the hardware. - - The XLookupColor function looks up the string name of a color - with respect to the screen associated with the specified - colormap. It returns both the exact color values and the - closest values provided by the screen with respect to the - visual type of the specified colormap. If the color name is not - in the Host Portable Character Encoding, the result is - implementation-dependent. Use of uppercase or lowercase does - not matter. XLookupColor returns nonzero if the name is - resolved; otherwise, it returns zero. - - XLookupColor can generate a BadColor error. - - To map a color name to the exact RGB value, use XParseColor. - - Status XParseColor(Display *display, Colormap colormap, char - *spec, XColor *exact_def_return); - - display - - Specifies the connection to the X server. - - colormap - - Specifies the colormap. - - spec - - Specifies the color name string; case is ignored. - - exact_def_return - - Returns the exact color value for later use and sets the DoRed, - DoGreen, and DoBlue flags. - - The XParseColor function looks up the string name of a color - with respect to the screen associated with the specified - colormap. It returns the exact color value. If the color name - is not in the Host Portable Character Encoding, the result is - implementation-dependent. Use of uppercase or lowercase does - not matter. XParseColor returns nonzero if the name is - resolved; otherwise, it returns zero. - - XParseColor can generate a BadColor error. - - To map a color name to a value in an arbitrary color space, use - XcmsLookupColor. - - Status XcmsLookupColor(Display *display, Colormap colormap, - char *color_string, XcmsColor *color_exact_return, XcmsColor - *color_screen_return, XcmsColorFormat result_format); - - display - - Specifies the connection to the X server. - - colormap - - Specifies the colormap. - - color_string - - Specifies the color string(St. - - color_exact_return - - Returns the color specification parsed from the color string or - parsed from the corresponding string found in a color-name - database. - - color_screen_return - - Returns the color that can be reproduced on the screen. - - result_format - - Specifies the color format for the returned color - specifications (color_screen_return and color_exact_return - arguments). If the format is XcmsUndefinedFormat and the color - string contains a numerical color specification, the - specification is returned in the format used in that numerical - color specification. If the format is XcmsUndefinedFormat and - the color string contains a color name, the specification is - returned in the format used to store the color in the database. - - The XcmsLookupColor function looks up the string name of a - color with respect to the screen associated with the specified - colormap. It returns both the exact color values and the - closest values provided by the screen with respect to the - visual type of the specified colormap. The values are returned - in the format specified by result_format. If the color name is - not in the Host Portable Character Encoding, the result is - implementation-dependent. Use of uppercase or lowercase does - not matter. XcmsLookupColor returns XcmsSuccess or - XcmsSuccessWithCompression if the name is resolved; otherwise, - it returns XcmsFailure. If XcmsSuccessWithCompression is - returned, the color specification returned in - color_screen_return is the result of gamut compression. - -Allocating and Freeing Color Cells - - There are two ways of allocating color cells: explicitly as - read-only entries, one pixel value at a time, or read/write, - where you can allocate a number of color cells and planes - simultaneously. A read-only cell has its RGB value set by the - server. Read/write cells do not have defined colors initially; - functions described in the next section must be used to store - values into them. Although it is possible for any client to - store values into a read/write cell allocated by another - client, read/write cells normally should be considered private - to the client that allocated them. - - Read-only colormap cells are shared among clients. The server - counts each allocation and freeing of the cell by clients. When - the last client frees a shared cell, the cell is finally - deallocated. If a single client allocates the same read-only - cell multiple times, the server counts each such allocation, - not just the first one. - - To allocate a read-only color cell with an RGB value, use - XAllocColor. - - Status XAllocColor(Display *display, Colormap colormap, XColor - *screen_in_out); - - display - - Specifies the connection to the X server. - - colormap - - Specifies the colormap. - - screen_in_out - - Specifies and returns the values actually used in the colormap. - - The XAllocColor function allocates a read-only colormap entry - corresponding to the closest RGB value supported by the - hardware. XAllocColor returns the pixel value of the color - closest to the specified RGB elements supported by the hardware - and returns the RGB value actually used. The corresponding - colormap cell is read-only. In addition, XAllocColor returns - nonzero if it succeeded or zero if it failed. Multiple clients - that request the same effective RGB value can be assigned the - same read-only entry, thus allowing entries to be shared. When - the last client deallocates a shared cell, it is deallocated. - XAllocColor does not use or affect the flags in the XColor - structure. - - XAllocColor can generate a BadColor error. delim %% - - To allocate a read-only color cell with a color in arbitrary - format, use XcmsAllocColor. - - Status XcmsAllocColor(Display *display, Colormap colormap, - XcmsColor *color_in_out, XcmsColorFormat result_format); - - display - - Specifies the connection to the X server. - - colormap - - Specifies the colormap. - - color_in_out - - Specifies the color to allocate and returns the pixel and color - that is actually used in the colormap. - - result_format - - Specifies the color format for the returned color - specification. - - The XcmsAllocColor function is similar to XAllocColor except - the color can be specified in any format. The XcmsAllocColor - function ultimately calls XAllocColor to allocate a read-only - color cell (colormap entry) with the specified color. - XcmsAllocColor first converts the color specified to an RGB - value and then passes this to XAllocColor. XcmsAllocColor - returns the pixel value of the color cell and the color - specification actually allocated. This returned color - specification is the result of converting the RGB value - returned by XAllocColor into the format specified with the - result_format argument. If there is no interest in a returned - color specification, unnecessary computation can be bypassed if - result_format is set to XcmsRGBFormat. The corresponding - colormap cell is read-only. If this routine returns - XcmsFailure, the color_in_out color specification is left - unchanged. - - XcmsAllocColor can generate a BadColor error. - - To allocate a read-only color cell using a color name and - return the closest color supported by the hardware in RGB - format, use XAllocNamedColor. - - Status XAllocNamedColor(Display *display, Colormap colormap, - char *color_name, XColor *screen_def_return, XColor - *exact_def_return); - - display - - Specifies the connection to the X server. - - colormap - - Specifies the colormap. - - color_name - - Specifies the color name string (for example, red) whose color - definition structure you want returned. - - screen_def_return - - Returns the closest RGB values provided by the hardware. - - exact_def_return - - Returns the exact RGB values. - - The XAllocNamedColor function looks up the named color with - respect to the screen that is associated with the specified - colormap. It returns both the exact database definition and the - closest color supported by the screen. The allocated color cell - is read-only. The pixel value is returned in screen_def_return. - If the color name is not in the Host Portable Character - Encoding, the result is implementation-dependent. Use of - uppercase or lowercase does not matter. If screen_def_return - and exact_def_return point to the same structure, the pixel - field will be set correctly, but the color values are - undefined. XAllocNamedColor returns nonzero if a cell is - allocated; otherwise, it returns zero. - - XAllocNamedColor can generate a BadColor error. - - To allocate a read-only color cell using a color name and - return the closest color supported by the hardware in an - arbitrary format, use XcmsAllocNamedColor. - - Status XcmsAllocNamedColor(Display *display, Colormap colormap, - char *color_string, XcmsColor *color_screen_return, XcmsColor - *color_exact_return, XcmsColorFormat result_format); - - display - - Specifies the connection to the X server. - - colormap - - Specifies the colormap. - - color_string - - Specifies the color string whose color definition structure is - to be returned. - - color_screen_return - - Returns the pixel value of the color cell and color - specification that actually is stored for that cell. - - color_exact_return - - Returns the color specification parsed from the color string or - parsed from the corresponding string found in a color-name - database. - - result_format - - Specifies the color format for the returned color - specifications (color_screen_return and color_exact_return - arguments). If the format is XcmsUndefinedFormat and the color - string contains a numerical color specification, the - specification is returned in the format used in that numerical - color specification. If the format is XcmsUndefinedFormat and - the color string contains a color name, the specification is - returned in the format used to store the color in the database. - - The XcmsAllocNamedColor function is similar to XAllocNamedColor - except that the color returned can be in any format specified. - This function ultimately calls XAllocColor to allocate a - read-only color cell with the color specified by a color - string. The color string is parsed into an XcmsColor structure - (see XcmsLookupColor), converted to an RGB value, and finally - passed to XAllocColor. If the color name is not in the Host - Portable Character Encoding, the result is - implementation-dependent. Use of uppercase or lowercase does - not matter. - - This function returns both the color specification as a result - of parsing (exact specification) and the actual color - specification stored (screen specification). This screen - specification is the result of converting the RGB value - returned by XAllocColor into the format specified in - result_format. If there is no interest in a returned color - specification, unnecessary computation can be bypassed if - result_format is set to XcmsRGBFormat. If color_screen_return - and color_exact_return point to the same structure, the pixel - field will be set correctly, but the color values are - undefined. - - XcmsAllocNamedColor can generate a BadColor error. - - To allocate read/write color cell and color plane combinations - for a PseudoColor model, use XAllocColorCells. - - Status XAllocColorCells(Display *display, Colormap colormap, - Bool contig, unsigned long plane_masks_return[], unsigned int - nplanes, unsigned long pixels_return[], unsigned int npixels); - - display - - Specifies the connection to the X server. - - colormap - - Specifies the colormap. - - contig - - Specifies a Boolean value that indicates whether the planes - must be contiguous. - - plane_mask_return - - Returns an array of plane masks. - - nplanes - - Specifies the number of plane masks that are to be returned in - the plane masks array. - - pixels_return - - Returns an array of pixel values. - - npixels - - Specifies the number of pixel values that are to be returned in - the pixels_return array. - - The XAllocColorCells function allocates read/write color cells. - The number of colors must be positive and the number of planes - nonnegative, or a BadValue error results. If ncolors and - nplanes are requested, then ncolors pixels and nplane plane - masks are returned. No mask will have any bits set to 1 in - common with any other mask or with any of the pixels. By ORing - together each pixel with zero or more masks, ncolors × - 2^nplanes distinct pixels can be produced. All of these are - allocated writable by the request. For GrayScale or - PseudoColor, each mask has exactly one bit set to 1. For - DirectColor, each has exactly three bits set to 1. If contig is - True and if all masks are ORed together, a single contiguous - set of bits set to 1 will be formed for GrayScale or - PseudoColor and three contiguous sets of bits set to 1 (one - within each pixel subfield) for DirectColor. The RGB values of - the allocated entries are undefined. XAllocColorCells returns - nonzero if it succeeded or zero if it failed. - - XAllocColorCells can generate BadColor and BadValue errors. - - To allocate read/write color resources for a DirectColor model, - use XAllocColorPlanes. - - Status XAllocColorPlanes(Display *display, Colormap colormap, - Bool contig, unsigned long pixels_return[], int ncolors, int - nreds, int ngreens, int nblues, unsigned long *rmask_return, - unsigned long *gmask_return, unsigned long *bmask_return); - - display - - Specifies the connection to the X server. - - colormap - - Specifies the colormap. - - contig - - Specifies a Boolean value that indicates whether the planes - must be contiguous. - - pixels_return - - Returns an array of pixel values. XAllocColorPlanes returns the - pixel values in this array. - - ncolors - - Specifies the number of pixel values that are to be returned in - the pixels_return array. - - nreds - - ngreens - - nblues - - Specify the number of red, green, and blue planes. The value - you pass must be nonnegative. - - rmask_return - - gmask_return - - bmask_return - - Return bit masks for the red, green, and blue planes. - - The specified ncolors must be positive; and nreds, ngreens, and - nblues must be nonnegative, or a BadValue error results. If - ncolors colors, nreds reds, ngreens greens, and nblues blues - are requested, ncolors pixels are returned; and the masks have - nreds, ngreens, and nblues bits set to 1, respectively. If - contig is True, each mask will have a contiguous set of bits - set to 1. No mask will have any bits set to 1 in common with - any other mask or with any of the pixels. For DirectColor, each - mask will lie within the corresponding pixel subfield. By ORing - together subsets of masks with each pixel value, ncolors × - 2^(nreds+ngreens+nblues) distinct pixel values can be produced. - All of these are allocated by the request. However, in the - colormap, there are only ncolors × 2^nreds independent red - entries, ncolors × 2^ngreens independent green entries, and - ncolors × 2^nblues independent blue entries. This is true even - for PseudoColor. When the colormap entry of a pixel value is - changed (using XStoreColors, XStoreColor, or XStoreNamedColor), - the pixel is decomposed according to the masks, and the - corresponding independent entries are updated. - XAllocColorPlanes returns nonzero if it succeeded or zero if it - failed. - - XAllocColorPlanes can generate BadColor and BadValue errors. - - To free colormap cells, use XFreeColors. - - XFreeColors(Display *display, Colormap colormap, unsigned long - pixels[], int npixels, unsigned long planes); - - display - - Specifies the connection to the X server. - - colormap - - Specifies the colormap. - - pixels - - Specifies an array of pixel values that map to the cells in the - specified colormap. - - npixels - - Specifies the number of pixels. - - planes - - Specifies the planes you want to free. - - The XFreeColors function frees the cells represented by pixels - whose values are in the pixels array. The planes argument - should not have any bits set to 1 in common with any of the - pixels. The set of all pixels is produced by ORing together - subsets of the planes argument with the pixels. The request - frees all of these pixels that were allocated by the client - (using XAllocColor, XAllocNamedColor, XAllocColorCells, and - XAllocColorPlanes). Note that freeing an individual pixel - obtained from XAllocColorPlanes may not actually allow it to be - reused until all of its related pixels are also freed. - Similarly, a read-only entry is not actually freed until it has - been freed by all clients, and if a client allocates the same - read-only entry multiple times, it must free the entry that - many times before the entry is actually freed. - - All specified pixels that are allocated by the client in the - colormap are freed, even if one or more pixels produce an - error. If a specified pixel is not a valid index into the - colormap, a BadValue error results. If a specified pixel is not - allocated by the client (that is, is unallocated or is only - allocated by another client) or if the colormap was created - with all entries writable (by passing AllocAll to - XCreateColormap), a BadAccess error results. If more than one - pixel is in error, the one that gets reported is arbitrary. - - XFreeColors can generate BadAccess, BadColor, and BadValue - errors. - -Modifying and Querying Colormap Cells - - To store an RGB value in a single colormap cell, use - XStoreColor. - - XStoreColor(Display *display, Colormap colormap, XColor - *color); - - display - - Specifies the connection to the X server. - - colormap - - Specifies the colormap. - - color - - Specifies the pixel and RGB values. - - The XStoreColor function changes the colormap entry of the - pixel value specified in the pixel member of the XColor - structure. You specified this value in the pixel member of the - XColor structure. This pixel value must be a read/write cell - and a valid index into the colormap. If a specified pixel is - not a valid index into the colormap, a BadValue error results. - XStoreColor also changes the red, green, and/or blue color - components. You specify which color components are to be - changed by setting DoRed, DoGreen, and/or DoBlue in the flags - member of the XColor structure. If the colormap is an installed - map for its screen, the changes are visible immediately. - - XStoreColor can generate BadAccess, BadColor, and BadValue - errors. - - To store multiple RGB values in multiple colormap cells, use - XStoreColors. - - XStoreColors(Display *display, Colormap colormap, XColor - color[], int ncolors); - - display - - Specifies the connection to the X server. - - colormap - - Specifies the colormap. - - color - - Specifies an array of color definition structures to be stored. - - ncolors - - Specifies the number of XColor structures in the color - definition array. - - The XStoreColors function changes the colormap entries of the - pixel values specified in the pixel members of the XColor - structures. You specify which color components are to be - changed by setting DoRed, DoGreen, and/or DoBlue in the flags - member of the XColor structures. If the colormap is an - installed map for its screen, the changes are visible - immediately. XStoreColors changes the specified pixels if they - are allocated writable in the colormap by any client, even if - one or more pixels generates an error. If a specified pixel is - not a valid index into the colormap, a BadValue error results. - If a specified pixel either is unallocated or is allocated - read-only, a BadAccess error results. If more than one pixel is - in error, the one that gets reported is arbitrary. - - XStoreColors can generate BadAccess, BadColor, and BadValue - errors. - - To store a color of arbitrary format in a single colormap cell, - use XcmsStoreColor. - - Status XcmsStoreColor(Display *display, Colormap colormap, - XcmsColor *color); - - display - - Specifies the connection to the X server. - - colormap - - Specifies the colormap. - - color - - Specifies the color cell and the color to store. Values - specified in this XcmsColor structure remain unchanged on - return. - - The XcmsStoreColor function converts the color specified in the - XcmsColor structure into RGB values. It then uses this RGB - specification in an XColor structure, whose three flags (DoRed, - DoGreen, and DoBlue) are set, in a call to XStoreColor to - change the color cell specified by the pixel member of the - XcmsColor structure. This pixel value must be a valid index for - the specified colormap, and the color cell specified by the - pixel value must be a read/write cell. If the pixel value is - not a valid index, a BadValue error results. If the color cell - is unallocated or is allocated read-only, a BadAccess error - results. If the colormap is an installed map for its screen, - the changes are visible immediately. - - Note that XStoreColor has no return value; therefore, an - XcmsSuccess return value from this function indicates that the - conversion to RGB succeeded and the call to XStoreColor was - made. To obtain the actual color stored, use XcmsQueryColor. - Because of the screen's hardware limitations or gamut - compression, the color stored in the colormap may not be - identical to the color specified. - - XcmsStoreColor can generate BadAccess, BadColor, and BadValue - errors. - - To store multiple colors of arbitrary format in multiple - colormap cells, use XcmsStoreColors. - - Status XcmsStoreColors(Display *display, Colormap colormap, - XcmsColor colors[], int ncolors, Bool - compression_flags_return[]); - - display - - Specifies the connection to the X server. - - colormap - - Specifies the colormap. - - colors - - Specifies the color specification array of XcmsColor - structures, each specifying a color cell and the color to store - in that cell. Values specified in the array remain unchanged - upon return. - - ncolors - - Specifies the number of XcmsColor structures in the - color-specification array. - - compression_flags_return - - Returns an array of Boolean values indicating compression - status. If a non-NULL pointer is supplied, each element of the - array is set to True if the corresponding color was compressed - and False otherwise. Pass NULL if the compression status is not - useful. - - The XcmsStoreColors function converts the colors specified in - the array of XcmsColor structures into RGB values and then uses - these RGB specifications in XColor structures, whose three - flags (DoRed, DoGreen, and DoBlue) are set, in a call to - XStoreColors to change the color cells specified by the pixel - member of the corresponding XcmsColor structure. Each pixel - value must be a valid index for the specified colormap, and the - color cell specified by each pixel value must be a read/write - cell. If a pixel value is not a valid index, a BadValue error - results. If a color cell is unallocated or is allocated - read-only, a BadAccess error results. If more than one pixel is - in error, the one that gets reported is arbitrary. If the - colormap is an installed map for its screen, the changes are - visible immediately. - - Note that XStoreColors has no return value; therefore, an - XcmsSuccess return value from this function indicates that - conversions to RGB succeeded and the call to XStoreColors was - made. To obtain the actual colors stored, use XcmsQueryColors. - Because of the screen's hardware limitations or gamut - compression, the colors stored in the colormap may not be - identical to the colors specified. - - XcmsStoreColors can generate BadAccess, BadColor, and BadValue - errors. - - To store a color specified by name in a single colormap cell, - use XStoreNamedColor. - - XStoreNamedColor(Display *display, Colormap colormap, char - *color, unsigned long pixel, int flags); - - display - - Specifies the connection to the X server. - - colormap - - Specifies the colormap. - - color - - Specifies the color name string (for example, red). - - pixel - - Specifies the entry in the colormap. - - flags - - Specifies which red, green, and blue components are set. - - The XStoreNamedColor function looks up the named color with - respect to the screen associated with the colormap and stores - the result in the specified colormap. The pixel argument - determines the entry in the colormap. The flags argument - determines which of the red, green, and blue components are - set. You can set this member to the bitwise inclusive OR of the - bits DoRed, DoGreen, and DoBlue. If the color name is not in - the Host Portable Character Encoding, the result is - implementation-dependent. Use of uppercase or lowercase does - not matter. If the specified pixel is not a valid index into - the colormap, a BadValue error results. If the specified pixel - either is unallocated or is allocated read-only, a BadAccess - error results. - - XStoreNamedColor can generate BadAccess, BadColor, BadName, and - BadValue errors. - - The XQueryColor and XQueryColors functions take pixel values in - the pixel member of XColor structures and store in the - structures the RGB values for those pixels from the specified - colormap. The values returned for an unallocated entry are - undefined. These functions also set the flags member in the - XColor structure to all three colors. If a pixel is not a valid - index into the specified colormap, a BadValue error results. If - more than one pixel is in error, the one that gets reported is - arbitrary. - - To query the RGB value of a single colormap cell, use - XQueryColor. - - XQueryColor(Display *display, Colormap colormap, XColor - *def_in_out); - - display - - Specifies the connection to the X server. - - colormap - - Specifies the colormap. - - def_in_out - - Specifies and returns the RGB values for the pixel specified in - the structure. - - The XQueryColor function returns the current RGB value for the - pixel in the XColor structure and sets the DoRed, DoGreen, and - DoBlue flags. - - XQueryColor can generate BadColor and BadValue errors. - - To query the RGB values of multiple colormap cells, use - XQueryColors. - - XQueryColors(Display *display, Colormap colormap, XColor - defs_in_out[], int ncolors); - - display - - Specifies the connection to the X server. - - colormap - - Specifies the colormap. - - defs_in_out - - Specifies and returns an array of color definition structures - for the pixel specified in the structure. - - ncolors - - Specifies the number of XColor structures in the color - definition array. - - The XQueryColors function returns the RGB value for each pixel - in each XColor structure and sets the DoRed, DoGreen, and - DoBlue flags in each structure. - - XQueryColors can generate BadColor and BadValue errors. - - To query the color of a single colormap cell in an arbitrary - format, use XcmsQueryColor. - - Status XcmsQueryColor(Display *display, Colormap colormap, - XcmsColor *color_in_out, XcmsColorFormat result_format); - - display - - Specifies the connection to the X server. - - colormap - - Specifies the colormap. - - color_in_out - - Specifies the pixel member that indicates the color cell to - query. The color specification stored for the color cell is - returned in this XcmsColor structure. - - result_format - - Specifies the color format for the returned color - specification. - - The XcmsQueryColor function obtains the RGB value for the pixel - value in the pixel member of the specified XcmsColor structure - and then converts the value to the target format as specified - by the result_format argument. If the pixel is not a valid - index in the specified colormap, a BadValue error results. - - XcmsQueryColor can generate BadColor and BadValue errors. - - To query the color of multiple colormap cells in an arbitrary - format, use XcmsQueryColors. - - Status XcmsQueryColors(Display *display, Colormap colormap, - XcmsColor colors_in_out[], unsigned int ncolors, - XcmsColorFormat result_format); - - display - - Specifies the connection to the X server. - - colormap - - Specifies the colormap. - - colors_in_out - - Specifies an array of XcmsColor structures, each pixel member - indicating the color cell to query. The color specifications - for the color cells are returned in these structures. - - ncolors - - Specifies the number of XcmsColor structures in the - color-specification array. - - result_format - - Specifies the color format for the returned color - specification. - - The XcmsQueryColors function obtains the RGB values for pixel - values in the pixel members of XcmsColor structures and then - converts the values to the target format as specified by the - result_format argument. If a pixel is not a valid index into - the specified colormap, a BadValue error results. If more than - one pixel is in error, the one that gets reported is arbitrary. - - XcmsQueryColors can generate BadColor and BadValue errors. - -Color Conversion Context Functions - - This section describes functions to create, modify, and query - Color Conversion Contexts (CCCs). - - Associated with each colormap is an initial CCC transparently - generated by Xlib. Therefore, when you specify a colormap as an - argument to a function, you are indirectly specifying a CCC. - The CCC attributes that can be modified by the X client are: - * Client White Point - * Gamut compression procedure and client data - * White point adjustment procedure and client data - - The initial values for these attributes are implementation - specific. The CCC attributes for subsequently created CCCs can - be defined by changing the CCC attributes of the default CCC. - There is a default CCC associated with each screen. - -Getting and Setting the Color Conversion Context of a Colormap - - To obtain the CCC associated with a colormap, use - XcmsCCCOfColormap. - - XcmsCCC XcmsCCCOfColormap(Display *display, Colormap colormap); - - display - - Specifies the connection to the X server. - - colormap - - Specifies the colormap. - - The XcmsCCCOfColormap function returns the CCC associated with - the specified colormap. Once obtained, the CCC attributes can - be queried or modified. Unless the CCC associated with the - specified colormap is changed with XcmsSetCCCOfColormap, this - CCC is used when the specified colormap is used as an argument - to color functions. - - To change the CCC associated with a colormap, use - XcmsSetCCCOfColormap. - - XcmsCCC XcmsSetCCCOfColormap(Display *display, Colormap - colormap, XcmsCCC ccc); - - display - - Specifies the connection to the X server. - - colormap - - Specifies the colormap. - - ccc - - Specifies the CCC. - - The XcmsSetCCCOfColormap function changes the CCC associated - with the specified colormap. It returns the CCC previously - associated with the colormap. If they are not used again in the - application, CCCs should be freed by calling XcmsFreeCCC. - Several colormaps may share the same CCC without restriction; - this includes the CCCs generated by Xlib with each colormap. - Xlib, however, creates a new CCC with each new colormap. - -Obtaining the Default Color Conversion Context - - You can change the default CCC attributes for subsequently - created CCCs by changing the CCC attributes of the default CCC. - A default CCC is associated with each screen. - - To obtain the default CCC for a screen, use XcmsDefaultCCC. - - XcmsCCC XcmsDefaultCCC(Display *display, int screen_number); - - display - - Specifies the connection to the X server. - - screen_number - - Specifies the appropriate screen number on the host server. - - The XcmsDefaultCCC function returns the default CCC for the - specified screen. Its visual is the default visual of the - screen. Its initial gamut compression and white point - adjustment procedures as well as the associated client data are - implementation specific. - -Color Conversion Context Macros - - Applications should not directly modify any part of the - XcmsCCC. The following lists the C language macros, their - corresponding function equivalents for other language bindings, - and what data they both can return. - - DisplayOfCCC(XcmsCCC ccc); - - Display *XcmsDisplayOfCCC(XcmsCCC ccc); - - ccc - - Specifies the CCC. - - Both return the display associated with the specified CCC. - - VisualOfCCC(XcmsCCC ccc); - - Visual *XcmsVisualOfCCC(XcmsCCC ccc); - - ccc - - Specifies the CCC. - - Both return the visual associated with the specified CCC. - - ScreenNumberOfCCC(XcmsCCC ccc); - - int XcmsScreenNumberOfCCC(XcmsCCC ccc); - - ccc - - Specifies the CCC. - - Both return the number of the screen associated with the - specified CCC. - - ScreenWhitePointOfCCC(XcmsCCC ccc); - - XcmsColor XcmsScreenWhitePointOfCCC(XcmsCCC ccc); - - ccc - - Specifies the CCC. - - Both return the white point of the screen associated with the - specified CCC. - - ClientWhitePointOfCCC(XcmsCCC ccc); - - XcmsColor *XcmsClientWhitePointOfCCC(XcmsCCC ccc); - - ccc - - Specifies the CCC. - - Both return the Client White Point of the specified CCC. - -Modifying Attributes of a Color Conversion Context - - To set the Client White Point in the CCC, use - XcmsSetWhitePoint. - - Status XcmsSetWhitePoint(XcmsCCC ccc, XcmsColor *color); - - ccc - - Specifies the CCC. - - color - - Specifies the new Client White Point. - - The XcmsSetWhitePoint function changes the Client White Point - in the specified CCC. Note that the pixel member is ignored and - that the color specification is left unchanged upon return. The - format for the new white point must be XcmsCIEXYZFormat, - XcmsCIEuvYFormat, XcmsCIExyYFormat, or XcmsUndefinedFormat. If - the color argument is NULL, this function sets the format - component of the Client White Point specification to - XcmsUndefinedFormat, indicating that the Client White Point is - assumed to be the same as the Screen White Point. - - This function returns nonzero status if the format for the new - white point is valid; otherwise, it returns zero. - - To set the gamut compression procedure and corresponding client - data in a specified CCC, use XcmsSetCompressionProc. - - XcmsCompressionProc XcmsSetCompressionProc(XcmsCCC ccc, - XcmsCompressionProc compression_proc, XPointer client_data); - - ccc - - Specifies the CCC. - - compression_proc - - Specifies the gamut compression procedure that is to be applied - when a color lies outside the screen's color gamut. If NULL is - specified and a function using this CCC must convert a color - specification to a device-dependent format and encounters a - color that lies outside the screen's color gamut, that function - will return XcmsFailure. - - client_data - - Specifies client data for gamut compression procedure or NULL. - - The XcmsSetCompressionProc function first sets the gamut - compression procedure and client data in the specified CCC with - the newly specified procedure and client data and then returns - the old procedure. - - To set the white point adjustment procedure and corresponding - client data in a specified CCC, use XcmsSetWhiteAdjustProc. - - XcmsWhiteAdjustProc XcmsSetWhiteAdjustProc(XcmsCCC ccc, - XcmsWhiteAdjustProc white_adjust_proc, XPointer client_data); - - ccc - - Specifies the CCC. - - white_adjust_proc - - Specifies the white point adjustment procedure. - - client_data - - Specifies client data for white point adjustment procedure or - NULL. - - The XcmsSetWhiteAdjustProc function first sets the white point - adjustment procedure and client data in the specified CCC with - the newly specified procedure and client data and then returns - the old procedure. - -Creating and Freeing a Color Conversion Context - - You can explicitly create a CCC within your application by - calling XcmsCreateCCC. These created CCCs can then be used by - those functions that explicitly call for a CCC argument. Old - CCCs that will not be used by the application should be freed - using XcmsFreeCCC. - - To create a CCC, use XcmsCreateCCC. - - XcmsCCC XcmsCreateCCC(Display *display, int screen_number, - Visual *visual, XcmsColor *client_white_point, - XcmsCompressionProc compression_proc, XPointer - compression_client_data, XcmsWhiteAdjustProc white_adjust_proc, - XPointer white_adjust_client_data); - - display - - Specifies the connection to the X server. - - screen_number - - Specifies the appropriate screen number on the host server. - - visual - - Specifies the visual type. - - client_white_point - - Specifies the Client White Point. If NULL is specified, the - Client White Point is to be assumed to be the same as the - Screen White Point. Note that the pixel member is ignored. - - compression_proc - - Specifies the gamut compression procedure that is to be applied - when a color lies outside the screen's color gamut. If NULL is - specified and a function using this CCC must convert a color - specification to a device-dependent format and encounters a - color that lies outside the screen's color gamut, that function - will return XcmsFailure. - - compression_client_data - - Specifies client data for use by the gamut compression - procedure or NULL. - - white_adjust_proc - - Specifies the white adjustment procedure that is to be applied - when the Client White Point differs from the Screen White - Point. NULL indicates that no white point adjustment is - desired. - - white_adjust_client_data - - Specifies client data for use with the white point adjustment - procedure or NULL. - - The XcmsCreateCCC function creates a CCC for the specified - display, screen, and visual. - - To free a CCC, use XcmsFreeCCC. - - void XcmsFreeCCC(XcmsCCC ccc); - - ccc - - Specifies the CCC. - - The XcmsFreeCCC function frees the memory used for the - specified CCC. Note that default CCCs and those currently - associated with colormaps are ignored. - -Converting between Color Spaces - - To convert an array of color specifications in arbitrary color - formats to a single destination format, use XcmsConvertColors. - - Status XcmsConvertColors(XcmsCCC ccc, XcmsColor - colors_in_out[], unsigned int ncolors, XcmsColorFormat - target_format, Bool compression_flags_return[]); - - ccc - - Specifies the CCC. If conversion is between device-independent - color spaces only (for example, TekHVC to CIELuv), the CCC is - necessary only to specify the Client White Point. - - colors_in_out - - Specifies an array of color specifications. Pixel members are - ignored and remain unchanged upon return. - - ncolors - - Specifies the number of XcmsColor structures in the - color-specification array. - - target_format - - Specifies the target color specification format. - - compression_flags_return - - Returns an array of Boolean values indicating compression - status. If a non-NULL pointer is supplied, each element of the - array is set to True if the corresponding color was compressed - and False otherwise. Pass NULL if the compression status is not - useful. - - The XcmsConvertColors function converts the color - specifications in the specified array of XcmsColor structures - from their current format to a single target format, using the - specified CCC. When the return value is XcmsFailure, the - contents of the color specification array are left unchanged. - - The array may contain a mixture of color specification formats - (for example, 3 CIE XYZ, 2 CIE Luv, and so on). When the array - contains both device-independent and device-dependent color - specifications and the target_format argument specifies a - device-dependent format (for example, XcmsRGBiFormat, - XcmsRGBFormat), all specifications are converted to CIE XYZ - format and then to the target device-dependent format. - -Callback Functions - - This section describes the gamut compression and white point - adjustment callbacks. - - The gamut compression procedure specified in the CCC is called - when an attempt to convert a color specification from - XcmsCIEXYZ to a device-dependent format (typically XcmsRGBi) - results in a color that lies outside the screen's color gamut. - If the gamut compression procedure requires client data, this - data is passed via the gamut compression client data in the - CCC. - - During color specification conversion between - device-independent and device-dependent color spaces, if a - white point adjustment procedure is specified in the CCC, it is - triggered when the Client White Point and Screen White Point - differ. If required, the client data is obtained from the CCC. - -Prototype Gamut Compression Procedure - - The gamut compression callback interface must adhere to the - following: - - typedef Status(*XcmsCompressionProc)(XcmsCCC ccc, XcmsColor - colors_in_out[], unsigned int ncolors, unsigned int index, Bool - compression_flags_return[]); - - ccc - - Specifies the CCC. - - colors_in_out - - Specifies an array of color specifications. Pixel members - should be ignored and must remain unchanged upon return. - - ncolors - - Specifies the number of XcmsColor structures in the - color-specification array. - - index - - Specifies the index into the array of XcmsColor structures for - the encountered color specification that lies outside the - screen's color gamut. Valid values are 0 (for the first - element) to ncolors - 1. - - compression_flags_return - - Returns an array of Boolean values for indicating compression - status. If a non-NULL pointer is supplied and a color at a - given index is compressed, then True should be stored at the - corresponding index in this array; otherwise, the array should - not be modified. - - When implementing a gamut compression procedure, consider the - following rules and assumptions: - * The gamut compression procedure can attempt to compress one - or multiple specifications at a time. - * When called, elements 0 to index - 1 in the color - specification array can be assumed to fall within the - screen's color gamut. In addition, these color - specifications are already in some device-dependent format - (typically XcmsRGBi). If any modifications are made to - these color specifications, they must be in their initial - device-dependent format upon return. - * When called, the element in the color specification array - specified by the index argument contains the color - specification outside the screen's color gamut encountered - by the calling routine. In addition, this color - specification can be assumed to be in XcmsCIEXYZ. Upon - return, this color specification must be in XcmsCIEXYZ. - * When called, elements from index to ncolors - 1 in the - color specification array may or may not fall within the - screen's color gamut. In addition, these color - specifications can be assumed to be in XcmsCIEXYZ. If any - modifications are made to these color specifications, they - must be in XcmsCIEXYZ upon return. - * The color specifications passed to the gamut compression - procedure have already been adjusted to the Screen White - Point. This means that at this point the color - specification's white point is the Screen White Point. - * If the gamut compression procedure uses a - device-independent color space not initially accessible for - use in the color management system, use XcmsAddColorSpace - to ensure that it is added. - -Supplied Gamut Compression Procedures - - The following equations are useful in describing gamut - compression functions: delim %% - -%CIELab~Psychometric~Chroma ~=~ sqrt(a_star sup 2 ~+~ b_star sup 2 )% - -%CIELab~Psychometric~Hue ~=~ tan sup -1 left [ b_star over a_star right -]% - -%CIELuv~Psychometric~Chroma ~=~ sqrt(u_star sup 2 ~+~ v_star sup 2 )% - -%CIELuv~Psychometric~Hue ~=~ tan sup -1 left [ v_star over u_star right -]% - - The gamut compression callback procedures provided by Xlib are - as follows: - * XcmsCIELabClipL - * This brings the encountered out-of-gamut color - specification into the screen's color gamut by reducing or - increasing CIE metric lightness (L*) in the CIE L*a*b* - color space until the color is within the gamut. If the - Psychometric Chroma of the color specification is beyond - maximum for the Psychometric Hue Angle, then while - maintaining the same Psychometric Hue Angle, the color will - be clipped to the CIE L*a*b* coordinates of maximum - Psychometric Chroma. See XcmsCIELabQueryMaxC. No client - data is necessary. - * XcmsCIELabClipab - * This brings the encountered out-of-gamut color - specification into the screen's color gamut by reducing - Psychometric Chroma, while maintaining Psychometric Hue - Angle, until the color is within the gamut. No client data - is necessary. - * XcmsCIELabClipLab - * This brings the encountered out-of-gamut color - specification into the screen's color gamut by replacing it - with CIE L*a*b* coordinates that fall within the color - gamut while maintaining the original Psychometric Hue Angle - and whose vector to the original coordinates is the - shortest attainable. No client data is necessary. - * XcmsCIELuvClipL - * This brings the encountered out-of-gamut color - specification into the screen's color gamut by reducing or - increasing CIE metric lightness (L*) in the CIE L*u*v* - color space until the color is within the gamut. If the - Psychometric Chroma of the color specification is beyond - maximum for the Psychometric Hue Angle, then, while - maintaining the same Psychometric Hue Angle, the color will - be clipped to the CIE L*u*v* coordinates of maximum - Psychometric Chroma. See XcmsCIELuvQueryMaxC. No client - data is necessary. - * XcmsCIELuvClipuv - * This brings the encountered out-of-gamut color - specification into the screen's color gamut by reducing - Psychometric Chroma, while maintaining Psychometric Hue - Angle, until the color is within the gamut. No client data - is necessary. - * XcmsCIELuvClipLuv - * This brings the encountered out-of-gamut color - specification into the screen's color gamut by replacing it - with CIE L*u*v* coordinates that fall within the color - gamut while maintaining the original Psychometric Hue Angle - and whose vector to the original coordinates is the - shortest attainable. No client data is necessary. - * XcmsTekHVCClipV - * This brings the encountered out-of-gamut color - specification into the screen's color gamut by reducing or - increasing the Value dimension in the TekHVC color space - until the color is within the gamut. If Chroma of the color - specification is beyond maximum for the particular Hue, - then, while maintaining the same Hue, the color will be - clipped to the Value and Chroma coordinates that represent - maximum Chroma for that particular Hue. No client data is - necessary. - * XcmsTekHVCClipC - * This brings the encountered out-of-gamut color - specification into the screen's color gamut by reducing the - Chroma dimension in the TekHVC color space until the color - is within the gamut. No client data is necessary. - * XcmsTekHVCClipVC - * This brings the encountered out-of-gamut color - specification into the screen's color gamut by replacing it - with TekHVC coordinates that fall within the color gamut - while maintaining the original Hue and whose vector to the - original coordinates is the shortest attainable. No client - data is necessary. - -Prototype White Point Adjustment Procedure - - The white point adjustment procedure interface must adhere to - the following: - - typedef Status (*XcmsWhiteAdjustProc)(XcmsCCC ccc, XcmsColor - *initial_white_point, XcmsColor *target_white_point, - XcmsColorFormat target_format, XcmsColor colors_in_out[], - unsigned int ncolors, Bool compression_flags_return[]); - - ccc - - Specifies the CCC. - - initial_white_point - - Specifies the initial white point. - - target_white_point - - Specifies the target white point. - - target_format - - Specifies the target color specification format. - - colors_in_out - - Specifies an array of color specifications. Pixel members - should be ignored and must remain unchanged upon return. - - ncolors - - Specifies the number of XcmsColor structures in the - color-specification array. - - compression_flags_return - - Returns an array of Boolean values for indicating compression - status. If a non-NULL pointer is supplied and a color at a - given index is compressed, then True should be stored at the - corresponding index in this array; otherwise, the array should - not be modified. - -Supplied White Point Adjustment Procedures - - White point adjustment procedures provided by Xlib are as - follows: - * XcmsCIELabWhiteShiftColors - * This uses the CIE L*a*b* color space for adjusting the - chromatic character of colors to compensate for the - chromatic differences between the source and destination - white points. This procedure simply converts the color - specifications to XcmsCIELab using the source white point - and then converts to the target specification format using - the destination's white point. No client data is necessary. - * XcmsCIELuvWhiteShiftColors - * This uses the CIE L*u*v* color space for adjusting the - chromatic character of colors to compensate for the - chromatic differences between the source and destination - white points. This procedure simply converts the color - specifications to XcmsCIELuv using the source white point - and then converts to the target specification format using - the destination's white point. No client data is necessary. - * XcmsTekHVCWhiteShiftColors - * This uses the TekHVC color space for adjusting the - chromatic character of colors to compensate for the - chromatic differences between the source and destination - white points. This procedure simply converts the color - specifications to XcmsTekHVC using the source white point - and then converts to the target specification format using - the destination's white point. An advantage of this - procedure over those previously described is an attempt to - minimize hue shift. No client data is necessary. - - From an implementation point of view, these white point - adjustment procedures convert the color specifications to a - device-independent but white-point-dependent color space (for - example, CIE L*u*v*, CIE L*a*b*, TekHVC) using one white point - and then converting those specifications to the target color - space using another white point. In other words, the - specification goes in the color space with one white point but - comes out with another white point, resulting in a chromatic - shift based on the chromatic displacement between the initial - white point and target white point. The CIE color spaces that - are assumed to be white-point-independent are CIE u'v'Y, CIE - XYZ, and CIE xyY. When developing a custom white point - adjustment procedure that uses a device-independent color space - not initially accessible for use in the color management - system, use XcmsAddColorSpace to ensure that it is added. - - As an example, if the CCC specifies a white point adjustment - procedure and if the Client White Point and Screen White Point - differ, the XcmsAllocColor function will use the white point - adjustment procedure twice: - * Once to convert to XcmsRGB - * A second time to convert from XcmsRGB - - For example, assume the specification is in XcmsCIEuvY and the - adjustment procedure is XcmsCIELuvWhiteShiftColors. During - conversion to XcmsRGB, the call to XcmsAllocColor results in - the following series of color specification conversions: - * From XcmsCIEuvY to XcmsCIELuv using the Client White Point - * From XcmsCIELuv to XcmsCIEuvY using the Screen White Point - * From XcmsCIEuvY to XcmsCIEXYZ (CIE u'v'Y and XYZ are - white-point-independent color spaces) - * From XcmsCIEXYZ to XcmsRGBi - * From XcmsRGBi to XcmsRGB - - The resulting RGB specification is passed to XAllocColor, and - the RGB specification returned by XAllocColor is converted back - to XcmsCIEuvY by reversing the color conversion sequence. - -Gamut Querying Functions - - This section describes the gamut querying functions that Xlib - provides. These functions allow the client to query the - boundary of the screen's color gamut in terms of the CIE - L*a*b*, CIE L*u*v*, and TekHVC color spaces. Functions are also - provided that allow you to query the color specification of: - * White (full-intensity red, green, and blue) - * Red (full-intensity red while green and blue are zero) - * Green (full-intensity green while red and blue are zero) - * Blue (full-intensity blue while red and green are zero) - * Black (zero-intensity red, green, and blue) - - The white point associated with color specifications passed to - and returned from these gamut querying functions is assumed to - be the Screen White Point. This is a reasonable assumption, - because the client is trying to query the screen's color gamut. - - The following naming convention is used for the Max and Min - functions: - -XcmsQueryMax - -XcmsQueryMin - - The consists of a letter or letters that identify - the dimensions of the color space that are not fixed. For - example, XcmsTekHVCQueryMaxC is given a fixed Hue and Value for - which maximum Chroma is found. - -Red, Green, and Blue Queries - - To obtain the color specification for black (zero-intensity - red, green, and blue), use XcmsQueryBlack. - - Status XcmsQueryBlack(XcmsCCC ccc, XcmsColorFormat - target_format, XcmsColor *color_return); - - ccc - - Specifies the CCC. The CCC's Client White Point and white point - adjustment procedures are ignored. - - target_format - - Specifies the target color specification format. - - color_return - - Returns the color specification in the specified target format - for zero-intensity red, green, and blue. The white point - associated with the returned color specification is the Screen - White Point. The value returned in the pixel member is - undefined. - - The XcmsQueryBlack function returns the color specification in - the specified target format for zero-intensity red, green, and - blue. - - To obtain the color specification for blue (full-intensity blue - while red and green are zero), use XcmsQueryBlue. - - Status XcmsQueryBlue(XcmsCCC ccc, XcmsColorFormat - target_format, XcmsColor *color_return); - - ccc - - Specifies the CCC. The CCC's Client White Point and white point - adjustment procedures are ignored. - - target_format - - Specifies the target color specification format. - - color_return - - Returns the color specification in the specified target format - for full-intensity blue while red and green are zero. The white - point associated with the returned color specification is the - Screen White Point. The value returned in the pixel member is - undefined. - - The XcmsQueryBlue function returns the color specification in - the specified target format for full-intensity blue while red - and green are zero. - - To obtain the color specification for green (full-intensity - green while red and blue are zero), use XcmsQueryGreen. - - Status XcmsQueryGreen(XcmsCCC ccc, XcmsColorFormat - target_format, XcmsColor *color_return); - - ccc - - Specifies the CCC. The CCC's Client White Point and white point - adjustment procedures are ignored. - - target_format - - Specifies the target color specification format. - - color_return - - Returns the color specification in the specified target format - for full-intensity green while red and blue are zero. The white - point associated with the returned color specification is the - Screen White Point. The value returned in the pixel member is - undefined. - - The XcmsQueryGreen function returns the color specification in - the specified target format for full-intensity green while red - and blue are zero. - - To obtain the color specification for red (full-intensity red - while green and blue are zero), use XcmsQueryRed. - - Status XcmsQueryRed(XcmsCCC ccc, XcmsColorFormat target_format, - XcmsColor *color_return); - - ccc - - Specifies the CCC. The CCC's Client White Point and white point - adjustment procedures are ignored. - - target_format - - Specifies the target color specification format. - - color_return - - Returns the color specification in the specified target format - for full-intensity red while green and blue are zero. The white - point associated with the returned color specification is the - Screen White Point. The value returned in the pixel member is - undefined. - - The XcmsQueryRed function returns the color specification in - the specified target format for full-intensity red while green - and blue are zero. - - To obtain the color specification for white (full-intensity - red, green, and blue), use XcmsQueryWhite. - - Status XcmsQueryWhite(XcmsCCC ccc, XcmsColorFormat - target_format, XcmsColor *color_return); - - ccc - - Specifies the CCC. The CCC's Client White Point and white point - adjustment procedures are ignored. - - target_format - - Specifies the target color specification format. - - color_return - - Returns the color specification in the specified target format - for full-intensity red, green, and blue. The white point - associated with the returned color specification is the Screen - White Point. The value returned in the pixel member is - undefined. - - The XcmsQueryWhite function returns the color specification in - the specified target format for full-intensity red, green, and - blue. - -CIELab Queries - - The following equations are useful in describing the CIELab - query functions: delim %% - -%CIELab~Psychometric~Chroma ~=~ sqrt(a_star sup 2 ~+~ b_star sup 2 )% - -%CIELab~Psychometric~Hue ~=~ tan sup -1 left [ b_star over a_star right -]% - - To obtain the CIE L*a*b* coordinates of maximum Psychometric - Chroma for a given Psychometric Hue Angle and CIE metric - lightness (L*), use XcmsCIELabQueryMaxC. - - Status XcmsCIELabQueryMaxC(XcmsCCC ccc, XcmsFloat hue_angle, - XcmsFloat L_star, XcmsColor *color_return); - - ccc - - Specifies the CCC. The CCC's Client White Point and white point - adjustment procedures are ignored. - - hue_angle - - Specifies the hue angle (in degrees) at which to find maximum - chroma. - - L_star - - Specifies the lightness (L*) at which to find maximum chroma. - - color_return - - Returns the CIE L*a*b* coordinates of maximum chroma - displayable by the screen for the given hue angle and - lightness. The white point associated with the returned color - specification is the Screen White Point. The value returned in - the pixel member is undefined. - - The XcmsCIELabQueryMaxC function, given a hue angle and - lightness, finds the point of maximum chroma displayable by the - screen. It returns this point in CIE L*a*b* coordinates. - - To obtain the CIE L*a*b* coordinates of maximum CIE metric - lightness (L*) for a given Psychometric Hue Angle and - Psychometric Chroma, use XcmsCIELabQueryMaxL. - - Status XcmsCIELabQueryMaxL(XcmsCCC ccc, XcmsFloat hue_angle, - XcmsFloat chroma, XcmsColor *color_return); - - ccc - - Specifies the CCC. The CCC's Client White Point and white point - adjustment procedures are ignored. - - hue_angle - - Specifies the hue angle (in degrees) at which to find maximum - lightness. - - chroma - - Specifies the chroma at which to find maximum lightness. - - color_return - - Returns the CIE L*a*b* coordinates of maximum lightness - displayable by the screen for the given hue angle and chroma. - The white point associated with the returned color - specification is the Screen White Point. The value returned in - the pixel member is undefined. - - The XcmsCIELabQueryMaxL function, given a hue angle and chroma, - finds the point in CIE L*a*b* color space of maximum lightness - (L*) displayable by the screen. It returns this point in CIE - L*a*b* coordinates. An XcmsFailure return value usually - indicates that the given chroma is beyond maximum for the given - hue angle. - - To obtain the CIE L*a*b* coordinates of maximum Psychometric - Chroma for a given Psychometric Hue Angle, use - XcmsCIELabQueryMaxLC. - - Status XcmsCIELabQueryMaxLC(XcmsCCC ccc, XcmsFloat hue_angle, - XcmsColor *color_return); - - ccc - - Specifies the CCC. The CCC's Client White Point and white point - adjustment procedures are ignored. - - hue_angle - - Specifies the hue angle (in degrees) at which to find maximum - chroma. - - color_return - - Returns the CIE L*a*b* coordinates of maximum chroma - displayable by the screen for the given hue angle. The white - point associated with the returned color specification is the - Screen White Point. The value returned in the pixel member is - undefined. - - The XcmsCIELabQueryMaxLC function, given a hue angle, finds the - point of maximum chroma displayable by the screen. It returns - this point in CIE L*a*b* coordinates. - - To obtain the CIE L*a*b* coordinates of minimum CIE metric - lightness (L*) for a given Psychometric Hue Angle and - Psychometric Chroma, use XcmsCIELabQueryMinL. - - Status XcmsCIELabQueryMinL(XcmsCCC ccc, XcmsFloat hue_angle, - XcmsFloat chroma, XcmsColor *color_return); - - ccc - - Specifies the CCC. The CCC's Client White Point and white point - adjustment procedures are ignored. - - hue_angle - - Specifies the hue angle (in degrees) at which to find minimum - lightness. - - chroma - - Specifies the chroma at which to find minimum lightness. - - color_return - - Returns the CIE L*a*b* coordinates of minimum lightness - displayable by the screen for the given hue angle and chroma. - The white point associated with the returned color - specification is the Screen White Point. The value returned in - the pixel member is undefined. - - The XcmsCIELabQueryMinL function, given a hue angle and chroma, - finds the point of minimum lightness (L*) displayable by the - screen. It returns this point in CIE L*a*b* coordinates. An - XcmsFailure return value usually indicates that the given - chroma is beyond maximum for the given hue angle. - -CIELuv Queries - - The following equations are useful in describing the CIELuv - query functions: delim %% - -%CIELuv~Psychometric~Chroma ~=~ sqrt(u_star sup 2 ~+~ v_star sup 2 )% - -%CIELuv~Psychometric~Hue ~=~ tan sup -1 left [ v_star over u_star right -]% - - To obtain the CIE L*u*v* coordinates of maximum Psychometric - Chroma for a given Psychometric Hue Angle and CIE metric - lightness (L*), use XcmsCIELuvQueryMaxC. - - Status XcmsCIELuvQueryMaxC(XcmsCCC ccc, XcmsFloat hue_angle, - XcmsFloat L_star, XcmsColor *color_return); - - ccc - - Specifies the CCC. The CCC's Client White Point and white point - adjustment procedures are ignored. - - hue_angle - - Specifies the hue angle (in degrees) at which to find maximum - chroma. - - L_star - - Specifies the lightness (L*) at which to find maximum chroma. - - color_return - - Returns the CIE L*u*v* coordinates of maximum chroma - displayable by the screen for the given hue angle and - lightness. The white point associated with the returned color - specification is the Screen White Point. The value returned in - the pixel member is undefined. - - The XcmsCIELuvQueryMaxC function, given a hue angle and - lightness, finds the point of maximum chroma displayable by the - screen. It returns this point in CIE L*u*v* coordinates. - - To obtain the CIE L*u*v* coordinates of maximum CIE metric - lightness (L*) for a given Psychometric Hue Angle and - Psychometric Chroma, use XcmsCIELuvQueryMaxL. - - Status XcmsCIELuvQueryMaxL(XcmsCCC ccc, XcmsFloat hue_angle, - XcmsFloat chroma, XcmsColor *color_return); - - ccc - - Specifies the CCC. The CCC's Client White Point and white point - adjustment procedures are ignored. - - hue_angle - - Specifies the hue angle (in degrees) at which to find maximum - lightness. - - L_star - - Specifies the lightness (L*) at which to find maximum - lightness. - - color_return - - Returns the CIE L*u*v* coordinates of maximum lightness - displayable by the screen for the given hue angle and chroma. - The white point associated with the returned color - specification is the Screen White Point. The value returned in - the pixel member is undefined. - - The XcmsCIELuvQueryMaxL function, given a hue angle and chroma, - finds the point in CIE L*u*v* color space of maximum lightness - (L*) displayable by the screen. It returns this point in CIE - L*u*v* coordinates. An XcmsFailure return value usually - indicates that the given chroma is beyond maximum for the given - hue angle. - - To obtain the CIE L*u*v* coordinates of maximum Psychometric - Chroma for a given Psychometric Hue Angle, use - XcmsCIELuvQueryMaxLC. - - Status XcmsCIELuvQueryMaxLC(XcmsCCC ccc, XcmsFloat hue_angle, - XcmsColor *color_return); - - ccc - - Specifies the CCC. The CCC's Client White Point and white point - adjustment procedures are ignored. - - hue_angle - - Specifies the hue angle (in degrees) at which to find maximum - chroma. - - color_return - - Returns the CIE L*u*v* coordinates of maximum chroma - displayable by the screen for the given hue angle. The white - point associated with the returned color specification is the - Screen White Point. The value returned in the pixel member is - undefined. - - The XcmsCIELuvQueryMaxLC function, given a hue angle, finds the - point of maximum chroma displayable by the screen. It returns - this point in CIE L*u*v* coordinates. - - To obtain the CIE L*u*v* coordinates of minimum CIE metric - lightness (L*) for a given Psychometric Hue Angle and - Psychometric Chroma, use XcmsCIELuvQueryMinL. - - Status XcmsCIELuvQueryMinL(XcmsCCC ccc, XcmsFloat hue_angle, - XcmsFloat chroma, XcmsColor *color_return); - - ccc - - Specifies the CCC. The CCC's Client White Point and white point - adjustment procedures are ignored. - - hue_angle - - Specifies the hue angle (in degrees) at which to find minimum - lightness. - - chroma - - Specifies the chroma at which to find minimum lightness. - - color_return - - Returns the CIE L*u*v* coordinates of minimum lightness - displayable by the screen for the given hue angle and chroma. - The white point associated with the returned color - specification is the Screen White Point. The value returned in - the pixel member is undefined. - - The XcmsCIELuvQueryMinL function, given a hue angle and chroma, - finds the point of minimum lightness (L*) displayable by the - screen. It returns this point in CIE L*u*v* coordinates. An - XcmsFailure return value usually indicates that the given - chroma is beyond maximum for the given hue angle. - -TekHVC Queries - - To obtain the maximum Chroma for a given Hue and Value, use - XcmsTekHVCQueryMaxC. - - Status XcmsTekHVCQueryMaxC(XcmsCCC ccc, XcmsFloat hue, - XcmsFloat value, XcmsColor *color_return); - - ccc - - Specifies the CCC. The CCC's Client White Point and white point - adjustment procedures are ignored. - - hue - - Specifies the Hue in which to find the maximum Chroma. - - value - - Specifies the Value in which to find the maximum Chroma. - - color_return - - Returns the maximum Chroma along with the actual Hue and Value - at which the maximum Chroma was found. The white point - associated with the returned color specification is the Screen - White Point. The value returned in the pixel member is - undefined. - - The XcmsTekHVCQueryMaxC function, given a Hue and Value, - determines the maximum Chroma in TekHVC color space displayable - by the screen. It returns the maximum Chroma along with the - actual Hue and Value at which the maximum Chroma was found. - - To obtain the maximum Value for a given Hue and Chroma, use - XcmsTekHVCQueryMaxV. - - Status XcmsTekHVCQueryMaxV(XcmsCCC ccc, XcmsFloat hue, - XcmsFloat chroma, XcmsColor *color_return); - - ccc - - Specifies the CCC. The CCC's Client White Point and white point - adjustment procedures are ignored. - - hue - - Specifies the Hue in which to find the maximum Value. - - chroma - - Specifies the chroma at which to find maximum Value. - - color_return - - Returns the maximum Value along with the Hue and Chroma at - which the maximum Value was found. The white point associated - with the returned color specification is the Screen White - Point. The value returned in the pixel member is undefined. - - The XcmsTekHVCQueryMaxV function, given a Hue and Chroma, - determines the maximum Value in TekHVC color space displayable - by the screen. It returns the maximum Value and the actual Hue - and Chroma at which the maximum Value was found. - - To obtain the maximum Chroma and Value at which it is reached - for a specified Hue, use XcmsTekHVCQueryMaxVC. - - Status XcmsTekHVCQueryMaxVC(XcmsCCC ccc, XcmsFloat hue, - XcmsColor *color_return); - - ccc - - Specifies the CCC. The CCC's Client White Point and white point - adjustment procedures are ignored. - - hue - - Specifies the Hue in which to find the maximum Chroma. - - color_return - - Returns the color specification in XcmsTekHVC for the maximum - Chroma, the Value at which that maximum Chroma is reached, and - the actual Hue at which the maximum Chroma was found. The white - point associated with the returned color specification is the - Screen White Point. The value returned in the pixel member is - undefined. - - The XcmsTekHVCQueryMaxVC function, given a Hue, determines the - maximum Chroma in TekHVC color space displayable by the screen - and the Value at which that maximum Chroma is reached. It - returns the maximum Chroma, the Value at which that maximum - Chroma is reached, and the actual Hue for which the maximum - Chroma was found. - - To obtain a specified number of TekHVC specifications such that - they contain maximum Values for a specified Hue and the Chroma - at which the maximum Values are reached, use - XcmsTekHVCQueryMaxVSamples. - - Status XcmsTekHVCQueryMaxVSamples(XcmsCCC ccc, XcmsFloat hue, - XcmsColor colors_return[], unsigned int nsamples); - - ccc - - Specifies the CCC. The CCC's Client White Point and white point - adjustment procedures are ignored. - - hue - - Specifies the Hue for maximum Chroma/Value samples. - - nsamples - - Specifies the number of samples. - - colors_return - - Returns nsamples of color specifications in XcmsTekHVC such - that the Chroma is the maximum attainable for the Value and - Hue. The white point associated with the returned color - specification is the Screen White Point. The value returned in - the pixel member is undefined. - - The XcmsTekHVCQueryMaxVSamples returns nsamples of maximum - Value, the Chroma at which that maximum Value is reached, and - the actual Hue for which the maximum Chroma was found. These - sample points may then be used to plot the maximum Value/Chroma - boundary of the screen's color gamut for the specified Hue in - TekHVC color space. - - To obtain the minimum Value for a given Hue and Chroma, use - XcmsTekHVCQueryMinV. - - Status XcmsTekHVCQueryMinV(XcmsCCC ccc, XcmsFloat hue, - XcmsFloat chroma, XcmsColor *color_return); - - ccc - - Specifies the CCC. The CCC's Client White Point and white point - adjustment procedures are ignored. - - hue - - Specifies the Hue in which to find the minimum Value. - - value - - Specifies the Value in which to find the minimum Value. - - color_return - - Returns the minimum Value and the actual Hue and Chroma at - which the minimum Value was found. The white point associated - with the returned color specification is the Screen White - Point. The value returned in the pixel member is undefined. - - The XcmsTekHVCQueryMinV function, given a Hue and Chroma, - determines the minimum Value in TekHVC color space displayable - by the screen. It returns the minimum Value and the actual Hue - and Chroma at which the minimum Value was found. - -Color Management Extensions - - The Xlib color management facilities can be extended in two - ways: - * Device-Independent Color Spaces - * Device-independent color spaces that are derivable to CIE - XYZ space can be added using the XcmsAddColorSpace - function. - * Color Characterization Function Set - * A Color Characterization Function Set consists of - device-dependent color spaces and their functions that - convert between these color spaces and the CIE XYZ color - space, bundled together for a specific class of output - devices. A function set can be added using the - XcmsAddFunctionSet function. - -Color Spaces - - The CIE XYZ color space serves as the hub for all conversions - between device-independent and device-dependent color spaces. - Therefore, the knowledge to convert an XcmsColor structure to - and from CIE XYZ format is associated with each color space. - For example, conversion from CIE L*u*v* to RGB requires the - knowledge to convert from CIE L*u*v* to CIE XYZ and from CIE - XYZ to RGB. This knowledge is stored as an array of functions - that, when applied in series, will convert the XcmsColor - structure to or from CIE XYZ format. This color specification - conversion mechanism facilitates the addition of color spaces. - - Of course, when converting between only device-independent - color spaces or only device-dependent color spaces, shortcuts - are taken whenever possible. For example, conversion from - TekHVC to CIE L*u*v* is performed by intermediate conversion to - CIE u*v*Y and then to CIE L*u*v*, thus bypassing conversion - between CIE u*v*Y and CIE XYZ. - -Adding Device-Independent Color Spaces - - To add a device-independent color space, use XcmsAddColorSpace. - - Status XcmsAddColorSpace(XcmsColorSpace *color_space); - - color_space - - Specifies the device-independent color space to add. - - The XcmsAddColorSpace function makes a device-independent color - space (actually an XcmsColorSpace structure) accessible by the - color management system. Because format values for unregistered - color spaces are assigned at run time, they should be treated - as private to the client. If references to an unregistered - color space must be made outside the client (for example, - storing color specifications in a file using the unregistered - color space), then reference should be made by color space - prefix (see XcmsFormatOfPrefix and XcmsPrefixOfFormat). - - If the XcmsColorSpace structure is already accessible in the - color management system, XcmsAddColorSpace returns XcmsSuccess. - - Note that added XcmsColorSpaces must be retained for reference - by Xlib. - -Querying Color Space Format and Prefix - - To obtain the format associated with the color space associated - with a specified color string prefix, use XcmsFormatOfPrefix. - - XcmsColorFormat XcmsFormatOfPrefix(char *prefix); - - prefix - - Specifies the string that contains the color space prefix. - - The XcmsFormatOfPrefix function returns the format for the - specified color space prefix (for example, the string - ``CIEXYZ''). The prefix is case-insensitive. If the color space - is not accessible in the color management system, - XcmsFormatOfPrefix returns XcmsUndefinedFormat. - - To obtain the color string prefix associated with the color - space specified by a color format, use XcmsPrefixOfFormat. - - char *XcmsPrefixOfFormat(XcmsColorFormat format); - - format - - Specifies the color specification format. - - The XcmsPrefixOfFormat function returns the string prefix - associated with the color specification encoding specified by - the format argument. Otherwise, if no encoding is found, it - returns NULL. The returned string must be treated as read-only. - -Creating Additional Color Spaces - - Color space specific information necessary for color space - conversion and color string parsing is stored in an - XcmsColorSpace structure. Therefore, a new structure containing - this information is required for each additional color space. - In the case of device-independent color spaces, a handle to - this new structure (that is, by means of a global variable) is - usually made accessible to the client program for use with the - XcmsAddColorSpace function. - - If a new XcmsColorSpace structure specifies a color space not - registered with the X Consortium, they should be treated as - private to the client because format values for unregistered - color spaces are assigned at run time. If references to an - unregistered color space must be made outside the client (for - example, storing color specifications in a file using the - unregistered color space), then reference should be made by - color space prefix (see XcmsFormatOfPrefix and - XcmsPrefixOfFormat). - - - -typedef (*XcmsConversionProc)(); -typedef XcmsConversionProc *XcmsFuncListPtr; - /* A NULL terminated list of function pointers*/ - -typedef struct _XcmsColorSpace { - char *prefix; - XcmsColorFormat format; - XcmsParseStringProc parseString; - XcmsFuncListPtr to_CIEXYZ; - XcmsFuncListPtr from_CIEXYZ; - int inverse_flag; -} XcmsColorSpace; - - The prefix member specifies the prefix that indicates a color - string is in this color space's string format. For example, the - strings ``ciexyz'' or ``CIEXYZ'' for CIE XYZ, and ``rgb'' or - ``RGB'' for RGB. The prefix is case insensitive. The format - member specifies the color specification format. Formats for - unregistered color spaces are assigned at run time. The - parseString member contains a pointer to the function that can - parse a color string into an XcmsColor structure. This function - returns an integer (int): nonzero if it succeeded and zero - otherwise. The to_CIEXYZ and from_CIEXYZ members contain - pointers, each to a NULL terminated list of function pointers. - When the list of functions is executed in series, it will - convert the color specified in an XcmsColor structure from/to - the current color space format to/from the CIE XYZ format. Each - function returns an integer (int): nonzero if it succeeded and - zero otherwise. The white point to be associated with the - colors is specified explicitly, even though white points can be - found in the CCC. The inverse_flag member, if nonzero, - specifies that for each function listed in to_CIEXYZ, its - inverse function can be found in from_CIEXYZ such that: - -Given: n = number of functions in each list - -for each i, such that 0 <= i < n - from_CIEXYZ[n - i - 1] is the inverse of to_CIEXYZ[i]. - - This allows Xlib to use the shortest conversion path, thus - bypassing CIE XYZ if possible (for example, TekHVC to CIE - L*u*v*). - -Parse String Callback - - The callback in the XcmsColorSpace structure for parsing a - color string for the particular color space must adhere to the - following software interface specification: - - Status XcmsParseStringProc(char *color_string, XcmsColor - *color_return); - - color_string - - Specifies the color string to parse. - - color_return - - Returns the color specification in the color space's format. - -Color Specification Conversion Callback - - Callback functions in the XcmsColorSpace structure for - converting a color specification between device-independent - spaces must adhere to the following software interface - specification: - - Status ConversionProc(XcmsCCC ccc, XcmsColor *white_point, - XcmsColor *colors_in_out, unsigned int ncolors); - - ccc - - Specifies the CCC. - - white_point - - Specifies the white point associated with color specifications. - The pixel member should be ignored, and the entire structure - remain unchanged upon return. - - colors_in_out - - Specifies an array of color specifications. Pixel members - should be ignored and must remain unchanged upon return. - - ncolors - - Specifies the number of XcmsColor structures in the - color-specification array. - - Callback functions in the XcmsColorSpace structure for - converting a color specification to or from a device-dependent - space must adhere to the following software interface - specification: - - Status ConversionProc(XcmsCCC ccc, XcmsColor *colors_in_out, - unsigned int ncolors, Bool compression_flags_return[]); - - ccc - - Specifies the CCC. - - colors_in_out - - Specifies an array of color specifications. Pixel members - should be ignored and must remain unchanged upon return. - - ncolors - - Specifies the number of XcmsColor structures in the - color-specification array. - - compression_flags_return - - Returns an array of Boolean values for indicating compression - status. If a non-NULL pointer is supplied and a color at a - given index is compressed, then True should be stored at the - corresponding index in this array; otherwise, the array should - not be modified. - - Conversion functions are available globally for use by other - color spaces. The conversion functions provided by Xlib are: - Function Converts from Converts to - XcmsCIELabToCIEXYZ XcmsCIELabFormat XcmsCIEXYZFormat - XcmsCIELuvToCIEuvY XcmsCIELuvFormat XcmsCIEuvYFormat - XcmsCIEXYZToCIELab XcmsCIEXYZFormat XcmsCIELabFormat - XcmsCIEXYZToCIEuvY XcmsCIEXYZFormat XcmsCIEuvYFormat - XcmsCIEXYZToCIExyY XcmsCIEXYZFormat XcmsCIExyYFormat - XcmsCIEXYZToRGBi XcmsCIEXYZFormat XcmsRGBiFormat - XcmsCIEuvYToCIELuv XcmsCIEuvYFormat XcmsCIELabFormat - XcmsCIEuvYToCIEXYZ XcmsCIEuvYFormat XcmsCIEXYZFormat - XcmsCIEuvYToTekHVC XcmsCIEuvYFormat XcmsTekHVCFormat - XcmsCIExyYToCIEXYZ XcmsCIExyYFormat XcmsCIEXYZFormat - XcmsRGBToRGBi XcmsRGBFormat XcmsRGBiFormat - XcmsRGBiToCIEXYZ XcmsRGBiFormat XcmsCIEXYZFormat - XcmsRGBiToRGB XcmsRGBiFormat XcmsRGBFormat - XcmsTekHVCToCIEuvY XcmsTekHVCFormat XcmsCIEuvYFormat - -Function Sets - - Functions to convert between device-dependent color spaces and - CIE XYZ may differ for different classes of output devices (for - example, color versus gray monitors). Therefore, the notion of - a Color Characterization Function Set has been developed. A - function set consists of device-dependent color spaces and the - functions that convert color specifications between these - device-dependent color spaces and the CIE XYZ color space - appropriate for a particular class of output devices. The - function set also contains a function that reads color - characterization data off root window properties. It is this - characterization data that will differ between devices within a - class of output devices. For details about how color - characterization data is stored in root window properties, see - the section on Device Color Characterization in the - Inter-Client Communication Conventions Manual. The LINEAR_RGB - function set is provided by Xlib and will support most color - monitors. Function sets may require data that differs from - those needed for the LINEAR_RGB function set. In that case, its - corresponding data may be stored on different root window - properties. - -Adding Function Sets - - To add a function set, use XcmsAddFunctionSet. - - Status XcmsAddFunctionSet(XcmsFunctionSet *function_set); - - function_set - - Specifies the function set to add. - - The XcmsAddFunctionSet function adds a function set to the - color management system. If the function set uses - device-dependent XcmsColorSpace structures not accessible in - the color management system, XcmsAddFunctionSet adds them. If - an added XcmsColorSpace structure is for a device-dependent - color space not registered with the X Consortium, they should - be treated as private to the client because format values for - unregistered color spaces are assigned at run time. If - references to an unregistered color space must be made outside - the client (for example, storing color specifications in a file - using the unregistered color space), then reference should be - made by color space prefix (see XcmsFormatOfPrefix and - XcmsPrefixOfFormat). - - Additional function sets should be added before any calls to - other Xlib routines are made. If not, the XcmsPerScrnInfo - member of a previously created XcmsCCC does not have the - opportunity to initialize with the added function set. - -Creating Additional Function Sets - - The creation of additional function sets should be required - only when an output device does not conform to existing - function sets or when additional device-dependent color spaces - are necessary. A function set consists primarily of a - collection of device-dependent XcmsColorSpace structures and a - means to read and store a screen's color characterization data. - This data is stored in an XcmsFunctionSet structure. A handle - to this structure (that is, by means of global variable) is - usually made accessible to the client program for use with - XcmsAddFunctionSet. - - If a function set uses new device-dependent XcmsColorSpace - structures, they will be transparently processed into the color - management system. Function sets can share an XcmsColorSpace - structure for a device-dependent color space. In addition, - multiple XcmsColorSpace structures are allowed for a - device-dependent color space; however, a function set can - reference only one of them. These XcmsColorSpace structures - will differ in the functions to convert to and from CIE XYZ, - thus tailored for the specific function set. - - - -typedef struct _XcmsFunctionSet { - XcmsColorSpace **DDColorSpaces; - XcmsScreenInitProc screenInitProc; - XcmsScreenFreeProc screenFreeProc; -} XcmsFunctionSet; - - The DDColorSpaces member is a pointer to a NULL terminated list - of pointers to XcmsColorSpace structures for the - device-dependent color spaces that are supported by the - function set. The screenInitProc member is set to the callback - procedure (see the following interface specification) that - initializes the XcmsPerScrnInfo structure for a particular - screen. - - The screen initialization callback must adhere to the following - software interface specification: - - typedef Status (*XcmsScreenInitProc)(Display *display, int - screen_number, ScmsPerScrnInfo *screen_info); - - display - - Specifies the connection to the X server. - - screen_number - - Specifies the appropriate screen number on the host server. - - screen_info - - Specifies the XcmsPerScrnInfo structure, which contains the per - screen information. - - The screen initialization callback in the XcmsFunctionSet - structure fetches the color characterization data (device - profile) for the specified screen, typically off properties on - the screen's root window. It then initializes the specified - XcmsPerScrnInfo structure. If successful, the procedure fills - in the XcmsPerScrnInfo structure as follows: - * It sets the screenData member to the address of the created - device profile data structure (contents known only by the - function set). - * It next sets the screenWhitePoint member. - * It next sets the functionSet member to the address of the - XcmsFunctionSet structure. - * It then sets the state member to XcmsInitSuccess and - finally returns XcmsSuccess. - - If unsuccessful, the procedure sets the state member to - XcmsInitFailure and returns XcmsFailure. - - The XcmsPerScrnInfo structure contains: - - - -typedef struct _XcmsPerScrnInfo { - XcmsColor screenWhitePoint; - XPointer functionSet; - XPointer screenData; - unsigned char state; - char pad[3]; -} XcmsPerScrnInfo; - - The screenWhitePoint member specifies the white point inherent - to the screen. The functionSet member specifies the appropriate - function set. The screenData member specifies the device - profile. The state member is set to one of the following: - * XcmsInitNone indicates initialization has not been - previously attempted. - * XcmsInitFailure indicates initialization has been - previously attempted but failed. - * XcmsInitSuccess indicates initialization has been - previously attempted and succeeded. - - The screen free callback must adhere to the following software - interface specification: - - typedef void (*XcmsScreenFreeProc)(XPointer screenData); - - screenData - - Specifies the data to be freed. - - This function is called to free the screenData stored in an - XcmsPerScrnInfo structure. - -Chapter 7. Graphics Context Functions - - Table of Contents - - Manipulating Graphics Context/State - Using Graphics Context Convenience Routines - - Setting the Foreground, Background, Function, or Plane - Mask - - Setting the Line Attributes and Dashes - Setting the Fill Style and Fill Rule - Setting the Fill Tile and Stipple - Setting the Current Font - Setting the Clip Region - Setting the Arc Mode, Subwindow Mode, and Graphics - Exposure - - A number of resources are used when performing graphics - operations in X. Most information about performing graphics - (for example, foreground color, background color, line style, - and so on) is stored in resources called graphics contexts - (GCs). Most graphics operations (see chapter 8) take a GC as an - argument. Although in theory the X protocol permits sharing of - GCs between applications, it is expected that applications will - use their own GCs when performing operations. Sharing of GCs is - highly discouraged because the library may cache GC state. - - Graphics operations can be performed to either windows or - pixmaps, which collectively are called drawables. Each drawable - exists on a single screen. A GC is created for a specific - screen and drawable depth and can only be used with drawables - of matching screen and depth. - - This chapter discusses how to: - * Manipulate graphics context/state - * Use graphics context convenience functions - -Manipulating Graphics Context/State - - Most attributes of graphics operations are stored in GCs. These - include line width, line style, plane mask, foreground, - background, tile, stipple, clipping region, end style, join - style, and so on. Graphics operations (for example, drawing - lines) use these values to determine the actual drawing - operation. Extensions to X may add additional components to - GCs. The contents of a GC are private to Xlib. - - Xlib implements a write-back cache for all elements of a GC - that are not resource IDs to allow Xlib to implement the - transparent coalescing of changes to GCs. For example, a call - to XSetForeground of a GC followed by a call to - XSetLineAttributes results in only a single-change GC protocol - request to the server. GCs are neither expected nor encouraged - to be shared between client applications, so this write-back - caching should present no problems. Applications cannot share - GCs without external synchronization. Therefore, sharing GCs - between applications is highly discouraged. - - To set an attribute of a GC, set the appropriate member of the - XGCValues structure and OR in the corresponding value bitmask - in your subsequent calls to XCreateGC. The symbols for the - value mask bits and the XGCValues structure are: -/* GC attribute value mask bits */ - -#define GCFunction (1L<<0) -#define GCPlaneMask (1L<<1) -#define GCForeground (1L<<2) -#define GCBackground (1L<<3) -#define GCLineWidth (1L<<4) -#define GCLineStyle (1L<<5) -#define GCCapStyle (1L<<6) -#define GCJoinStyle (1L<<7) -#define GCFillStyle (1L<<8) -#define GCFillRule (1L<<9) -#define GCTile (1L<<10) -#define GCStipple (1L<<11) -#define GCTileStipXOrigin (1L<<12) -#define GCTileStipYOrigin (1L<<13) -#define GCFont (1L<<14) -#define GCSubwindowMode (1L<<15) -#define GCGraphicsExposures (1L<<16) -#define GCClipXOrigin (1L<<17) -#define GCClipYOrigin (1L<<18) -#define GCClipMask (1L<<19) -#define GCDashOffset (1L<<20) -#define GCDashList (1L<<21) -#define GCArcMode (1L<<22) - - - -/* Values */ - -typedef struct { - int function; /* logical operation */ - unsigned long plane_mask; /* plane mask */ - unsigned long foreground; /* foreground pixel */ - unsigned long background; /* background pixel */ - int line_width; /* line width (in pixels) */ - int line_style; /* LineSolid, LineOnOffDash, LineDoub -leDash */ - int cap_style; /* CapNotLast, CapButt, CapRound, Cap -Projecting */ - int join_style; /* JoinMiter, JoinRound, JoinBevel */ - int fill_style; /* FillSolid, FillTiled, FillStippled - FillOpaqueStippled*/ - int fill_rule; /* EvenOddRule, WindingRule */ - int arc_mode; /* ArcChord, ArcPieSlice */ - Pixmap tile; /* tile pixmap for tiling operations -*/ - Pixmap stipple; /* stipple 1 plane pixmap for stippli -ng */ - int ts_x_origin; /* offset for tile or stipple operati -ons */ - int ts_y_origin - Font font; /* default text font for text operati -ons */ - int subwindow_mode; /* ClipByChildren, IncludeInferiors * -/ - Bool graphics_exposures; /* boolean, should exposures be gener -ated */ - int clip_x_origin; /* origin for clipping */ - int clip_y_origin; - Pixmap clip_mask; /* bitmap clipping; other calls for r -ects */ - int dash_offset; /* patterned/dashed line information -*/ - char dashes; -} XGCValues; - - The default GC values are: - Component Default - function GXcopy - plane_mask All ones - foreground 0 - background 1 - line_width 0 - line_style LineSolid - cap_style CapButt - join_style JoinMiter - fill_style FillSolid - fill_rule EvenOddRule - arc_mode ArcPieSlice - tile - - Pixmap of unspecified size filled with foreground pixel - - (that is, client specified pixel if any, else 0) - - (subsequent changes to foreground do not affect this pixmap) - stipple Pixmap of unspecified size filled with ones - ts_x_origin 0 - ts_y_origin 0 - font - subwindow_mode ClipByChildren - graphics_exposures True - clip_x_origin 0 - clip_y_origin 0 - clip_mask None - dash_offset 0 - dashes 4 (that is, the list [4, 4]) - - Note that foreground and background are not set to any values - likely to be useful in a window. - - The function attributes of a GC are used when you update a - section of a drawable (the destination) with bits from - somewhere else (the source). The function in a GC defines how - the new destination bits are to be computed from the source - bits and the old destination bits. GXcopy is typically the most - useful because it will work on a color display, but special - applications may use other functions, particularly in concert - with particular planes of a color display. The 16 GC functions, - defined in , are: - Function Name Value Operation - GXclear 0x0 0 - GXand 0x1 src AND dst - GXandReverse 0x2 src AND NOT dst - GXcopy 0x3 src - GXandInverted 0x4 (NOT src) AND dst - GXnoop 0x5 dst - GXxor 0x6 src XOR dst - GXor 0x7 src OR dst - GXnor 0x8 (NOT src) AND (NOT dst) - GXequiv 0x9 (NOT src) XOR dst - GXinvert 0xa NOT dst - GXorReverse 0xb src OR (NOT dst) - GXcopyInverted 0xc NOT src - GXorInverted 0xd (NOT src) OR dst - GXnand 0xe (NOT src) OR (NOT dst) - GXset 0xf 1 - - Many graphics operations depend on either pixel values or - planes in a GC. The planes attribute is of type long, and it - specifies which planes of the destination are to be modified, - one bit per plane. A monochrome display has only one plane and - will be the least significant bit of the word. As planes are - added to the display hardware, they will occupy more - significant bits in the plane mask. - - In graphics operations, given a source and destination pixel, - the result is computed bitwise on corresponding bits of the - pixels. That is, a Boolean operation is performed in each bit - plane. The plane_mask restricts the operation to a subset of - planes. A macro constant AllPlanes can be used to refer to all - planes of the screen simultaneously. The result is computed by - the following: - -((src FUNC dst) AND plane-mask) OR (dst AND (NOT plane-mask)) - - Range checking is not performed on the values for foreground, - background, or plane_mask. They are simply truncated to the - appropriate number of bits. The line-width is measured in - pixels and either can be greater than or equal to one (wide - line) or can be the special value zero (thin line). - - Wide lines are drawn centered on the path described by the - graphics request. Unless otherwise specified by the join-style - or cap-style, the bounding box of a wide line with endpoints - [x1, y1], [x2, y2] and width w is a rectangle with vertices at - the following real coordinates: - - - -[x1-(w*sn/2), y1+(w*cs/2)], [x1+(w*sn/2), y1-(w*cs/2)], -[x2-(w*sn/2), y2+(w*cs/2)], [x2+(w*sn/2), y2-(w*cs/2)] - - Here sn is the sine of the angle of the line, and cs is the - cosine of the angle of the line. A pixel is part of the line - and so is drawn if the center of the pixel is fully inside the - bounding box (which is viewed as having infinitely thin edges). - If the center of the pixel is exactly on the bounding box, it - is part of the line if and only if the interior is immediately - to its right (x increasing direction). Pixels with centers on a - horizontal edge are a special case and are part of the line if - and only if the interior or the boundary is immediately below - (y increasing direction) and the interior or the boundary is - immediately to the right (x increasing direction). - - Thin lines (zero line-width) are one-pixel-wide lines drawn - using an unspecified, device-dependent algorithm. There are - only two constraints on this algorithm. - * If a line is drawn unclipped from [x1,y1] to [x2,y2] and if - another line is drawn unclipped from [x1+dx,y1+dy] to - [x2+dx,y2+dy], a point [x,y] is touched by drawing the - first line if and only if the point [x+dx,y+dy] is touched - by drawing the second line. - * The effective set of points comprising a line cannot be - affected by clipping. That is, a point is touched in a - clipped line if and only if the point lies inside the - clipping region and the point would be touched by the line - when drawn unclipped. - - A wide line drawn from [x1,y1] to [x2,y2] always draws the same - pixels as a wide line drawn from [x2,y2] to [x1,y1], not - counting cap-style and join-style. It is recommended that this - property be true for thin lines, but this is not required. A - line-width of zero may differ from a line-width of one in which - pixels are drawn. This permits the use of many manufacturers' - line drawing hardware, which may run many times faster than the - more precisely specified wide lines. - - In general, drawing a thin line will be faster than drawing a - wide line of width one. However, because of their different - drawing algorithms, thin lines may not mix well aesthetically - with wide lines. If it is desirable to obtain precise and - uniform results across all displays, a client should always use - a line-width of one rather than a line-width of zero. - - The line-style defines which sections of a line are drawn: - - LineSolid - - The full path of the line is drawn. - - LineDoubleDash - - The full path of the line is drawn, but the even dashes are - filled differently from the odd dashes (see fill-style) with - CapButt style used where even and odd dashes meet. - - LineOnOffDash - - Only the even dashes are drawn, and cap-style applies to all - internal ends of the individual dashes, except CapNotLast is - treated as CapButt. - - The cap-style defines how the endpoints of a path are drawn: - - CapNotLast - - This is equivalent to CapButt except that for a line-width of - zero the final endpoint is not drawn. - - CapButt - - The line is square at the endpoint (perpendicular to the slope - of the line) with no projection beyond. - - CapRound - - The line has a circular arc with the diameter equal to the - line-width, centered on the endpoint. (This is equivalent to - CapButt for line-width of zero). - - CapProjecting - - The line is square at the end, but the path continues beyond - the endpoint for a distance equal to half the line-width. (This - is equivalent to CapButt for line-width of zero). - - The join-style defines how corners are drawn for wide lines: - - JoinMiter - - The outer edges of two lines extend to meet at an angle. - However, if the angle is less than 11 degrees, then a JoinBevel - join-style is used instead. - - JoinRound - - The corner is a circular arc with the diameter equal to the - line-width, centered on the joinpoint. - - JoinBevel - - The corner has CapButt endpoint styles with the triangular - notch filled. - - For a line with coincident endpoints (x1=x2, y1=y2), when the - cap-style is applied to both endpoints, the semantics depends - on the line-width and the cap-style: - CapNotLast thin The results are device dependent, but the - desired effect is that nothing is drawn. - CapButt thin The results are device dependent, but the desired - effect is that a single pixel is drawn. - CapRound thin The results are the same as for CapButt /thin. - CapProjecting thin The results are the same as for CapButt - /thin. - CapButt wide Nothing is drawn. - CapRound wide The closed path is a circle, centered at the - endpoint, and with the diameter equal to the line-width. - CapProjecting wide The closed path is a square, aligned with - the coordinate axes, centered at the endpoint, and with the - sides equal to the line-width. - - For a line with coincident endpoints (x1=x2, y1=y2), when the - join-style is applied at one or both endpoints, the effect is - as if the line was removed from the overall path. However, if - the total path consists of or is reduced to a single point - joined with itself, the effect is the same as when the - cap-style is applied at both endpoints. - - The tile/stipple represents an infinite two-dimensional plane, - with the tile/stipple replicated in all dimensions. When that - plane is superimposed on the drawable for use in a graphics - operation, the upper-left corner of some instance of the - tile/stipple is at the coordinates within the drawable - specified by the tile/stipple origin. The tile/stipple and clip - origins are interpreted relative to the origin of whatever - destination drawable is specified in a graphics request. The - tile pixmap must have the same root and depth as the GC, or a - BadMatch error results. The stipple pixmap must have depth one - and must have the same root as the GC, or a BadMatch error - results. For stipple operations where the fill-style is - FillStippled but not FillOpaqueStippled, the stipple pattern is - tiled in a single plane and acts as an additional clip mask to - be ANDed with the clip-mask. Although some sizes may be faster - to use than others, any size pixmap can be used for tiling or - stippling. - - The fill-style defines the contents of the source for line, - text, and fill requests. For all text and fill requests (for - example, XDrawText, XDrawText16, XFillRectangle, XFillPolygon, - and XFillArc); for line requests with line-style LineSolid (for - example, XDrawLine, XDrawSegments, XDrawRectangle, XDrawArc); - and for the even dashes for line requests with line-style - LineOnOffDash or LineDoubleDash, the following apply: - FillSolid Foreground - FillTiled Tile - FillOpaqueStippled A tile with the same width and height as - stipple, but with background everywhere stipple has a zero and - with foreground everywhere stipple has a one - FillStippled Foreground masked by stipple - - When drawing lines with line-style LineDoubleDash, the odd - dashes are controlled by the fill-style in the following - manner: - FillSolid Background - FillTiled Same as for even dashes - FillOpaqueStippled Same as for even dashes - FillStippled Background masked by stipple - - Storing a pixmap in a GC might or might not result in a copy - being made. If the pixmap is later used as the destination for - a graphics request, the change might or might not be reflected - in the GC. If the pixmap is used simultaneously in a graphics - request both as a destination and as a tile or stipple, the - results are undefined. - - For optimum performance, you should draw as much as possible - with the same GC (without changing its components). The costs - of changing GC components relative to using different GCs - depend on the display hardware and the server implementation. - It is quite likely that some amount of GC information will be - cached in display hardware and that such hardware can only - cache a small number of GCs. - - The dashes value is actually a simplified form of the more - general patterns that can be set with XSetDashes. Specifying a - value of N is equivalent to specifying the two-element list [N, - N] in XSetDashes. The value must be nonzero, or a BadValue - error results. - - The clip-mask restricts writes to the destination drawable. If - the clip-mask is set to a pixmap, it must have depth one and - have the same root as the GC, or a BadMatch error results. If - clip-mask is set to None, the pixels are always drawn - regardless of the clip origin. The clip-mask also can be set by - calling the XSetClipRectangles or XSetRegion functions. Only - pixels where the clip-mask has a bit set to 1 are drawn. Pixels - are not drawn outside the area covered by the clip-mask or - where the clip-mask has a bit set to 0. The clip-mask affects - all graphics requests. The clip-mask does not clip sources. The - clip-mask origin is interpreted relative to the origin of - whatever destination drawable is specified in a graphics - request. - - You can set the subwindow-mode to ClipByChildren or - IncludeInferiors. For ClipByChildren, both source and - destination windows are additionally clipped by all viewable - InputOutput children. For IncludeInferiors, neither source nor - destination window is clipped by inferiors. This will result in - including subwindow contents in the source and drawing through - subwindow boundaries of the destination. The use of - IncludeInferiors on a window of one depth with mapped inferiors - of differing depth is not illegal, but the semantics are - undefined by the core protocol. - - The fill-rule defines what pixels are inside (drawn) for paths - given in XFillPolygon requests and can be set to EvenOddRule or - WindingRule. For EvenOddRule, a point is inside if an infinite - ray with the point as origin crosses the path an odd number of - times. For WindingRule, a point is inside if an infinite ray - with the point as origin crosses an unequal number of clockwise - and counterclockwise directed path segments. A clockwise - directed path segment is one that crosses the ray from left to - right as observed from the point. A counterclockwise segment is - one that crosses the ray from right to left as observed from - the point. The case where a directed line segment is coincident - with the ray is uninteresting because you can simply choose a - different ray that is not coincident with a segment. - - For both EvenOddRule and WindingRule, a point is infinitely - small, and the path is an infinitely thin line. A pixel is - inside if the center point of the pixel is inside and the - center point is not on the boundary. If the center point is on - the boundary, the pixel is inside if and only if the polygon - interior is immediately to its right (x increasing direction). - Pixels with centers on a horizontal edge are a special case and - are inside if and only if the polygon interior is immediately - below (y increasing direction). - - The arc-mode controls filling in the XFillArcs function and can - be set to ArcPieSlice or ArcChord. For ArcPieSlice, the arcs - are pie-slice filled. For ArcChord, the arcs are chord filled. - - The graphics-exposure flag controls GraphicsExpose event - generation for XCopyArea and XCopyPlane requests (and any - similar requests defined by extensions). - - To create a new GC that is usable on a given screen with a - depth of drawable, use XCreateGC. - - GC XCreateGC(Display *display, Drawable d, unsigned long - valuemask, XGCValues *values); - - display - - Specifies the connection to the X server. - - d - - Specifies the drawable. - - valuemask - - Specifies which components in the GC are to be set using the - information in the specified values structure. This argument is - the bitwise inclusive OR of zero or more of the valid GC - component mask bits. - - values - - Specifies any values as specified by the valuemask. - - The XCreateGC function creates a graphics context and returns a - GC. The GC can be used with any destination drawable having the - same root and depth as the specified drawable. Use with other - drawables results in a BadMatch error. - - XCreateGC can generate BadAlloc, BadDrawable, BadFont, - BadMatch, BadPixmap, and BadValue errors. - - To copy components from a source GC to a destination GC, use - XCopyGC. - - XCopyGC(Display *display, GC src, GC dest, unsigned long - valuemask); - - display - - Specifies the connection to the X server. - - src - - Specifies the components of the source GC. - - valuemask - - Specifies which components in the GC are to be copied to the - destination GC. This argument is the bitwise inclusive OR of - zero or more of the valid GC component mask bits. - - dest - - Specifies the destination GC. - - The XCopyGC function copies the specified components from the - source GC to the destination GC. The source and destination GCs - must have the same root and depth, or a BadMatch error results. - The valuemask specifies which component to copy, as for - XCreateGC. - - XCopyGC can generate BadAlloc, BadGC, and BadMatch errors. - - To change the components in a given GC, use XChangeGC. - - XChangeGC(Display *display, GC gc, unsigned long valuemask, - XGCValues *values); - - display - - Specifies the connection to the X server. - - gc - - Specifies the GC. - - valuemask - - Specifies which components in the GC are to be changed using - information in the specified values structure. This argument is - the bitwise inclusive OR of zero or more of the valid GC - component mask bits. - - values - - Specifies any values as specified by the valuemask. - - The XChangeGC function changes the components specified by - valuemask for the specified GC. The values argument contains - the values to be set. The values and restrictions are the same - as for XCreateGC. Changing the clip-mask overrides any previous - XSetClipRectangles request on the context. Changing the - dash-offset or dash-list overrides any previous XSetDashes - request on the context. The order in which components are - verified and altered is server dependent. If an error is - generated, a subset of the components may have been altered. - - XChangeGC can generate BadAlloc, BadFont, BadGC, BadMatch, - BadPixmap, and BadValue errors. - - To obtain components of a given GC, use XGetGCValues. - - Status XGetGCValues(Display *display, GC gc, unsigned long - valuemask, XGCValues *values_return); - - display - - Specifies the connection to the X server. - - gc - - Specifies the GC. - - valuemask - - Specifies which components in the GC are to be returned in the - values_return argument. This argument is the bitwise inclusive - OR of zero or more of the valid GC component mask bits. - - values_return - - Returns the GC values in the specified XGCValues structure. - - The XGetGCValues function returns the components specified by - valuemask for the specified GC. If the valuemask contains a - valid set of GC mask bits (GCFunction, GCPlaneMask, - GCForeground, GCBackground, GCLineWidth, GCLineStyle, - GCCapStyle, GCJoinStyle, GCFillStyle, GCFillRule, GCTile, - GCStipple, GCTileStipXOrigin, GCTileStipYOrigin, GCFont, - GCSubwindowMode, GCGraphicsExposures, GCClipXOrigin, - GCClipYOrigin, GCDashOffset, or GCArcMode) and no error occurs, - XGetGCValues sets the requested components in values_return and - returns a nonzero status. Otherwise, it returns a zero status. - Note that the clip-mask and dash-list (represented by the - GCClipMask and GCDashList bits, respectively, in the valuemask) - cannot be requested. Also note that an invalid resource ID - (with one or more of the three most significant bits set to 1) - will be returned for GCFont, GCTile, and GCStipple if the - component has never been explicitly set by the client. - - To free a given GC, use XFreeGC. - - XFreeGC(Display *display, GC gc); - - display - - Specifies the connection to the X server. - - gc - - Specifies the GC. - - The XFreeGC function destroys the specified GC as well as all - the associated storage. - - XFreeGC can generate a BadGC error. - - To obtain the GContext resource ID for a given GC, use - XGContextFromGC. - - GContext XGContextFromGC(GC gc); - - gc - - Specifies the GC for which you want the resource ID. - - Xlib usually defers sending changes to the components of a GC - to the server until a graphics function is actually called with - that GC. This permits batching of component changes into a - single server request. In some circumstances, however, it may - be necessary for the client to explicitly force sending the - changes to the server. An example might be when a protocol - extension uses the GC indirectly, in such a way that the - extension interface cannot know what GC will be used. To force - sending GC component changes, use XFlushGC. - - void XFlushGC(Display *display, GC gc); - - display - - Specifies the connection to the X server. - - gc - - Specifies the GC. - -Using Graphics Context Convenience Routines - - This section discusses how to set the: - * Foreground, background, plane mask, or function components - * Line attributes and dashes components - * Fill style and fill rule components - * Fill tile and stipple components - * Font component - * Clip region component - * Arc mode, subwindow mode, and graphics exposure components - -Setting the Foreground, Background, Function, or Plane Mask - - To set the foreground, background, plane mask, and function - components for a given GC, use XSetState. - - XSetState(Display *display, GC gc, unsigned long foreground, - unsigned long background, int function, unsigned long - plane_mask); - - display - - Specifies the connection to the X server. - - gc - - Specifies the GC. - - foreground - - Specifies the foreground you want to set for the specified GC. - - background - - Specifies the background you want to set for the specified GC. - - function - - Specifies the function you want to set for the specified GC. - - plane_mask - - Specifies the plane mask. - - XSetState can generate BadAlloc, BadGC, and BadValue errors. - - To set the foreground of a given GC, use XSetForeground. - - XSetForeground(Display *display, GC gc, unsigned long - foreground); - - display - - Specifies the connection to the X server. - - gc - - Specifies the GC. - - foreground - - Specifies the foreground you want to set for the specified GC. - - XSetForeground can generate BadAlloc and BadGC errors. - - To set the background of a given GC, use XSetBackground. - - XSetBackground(Display *display, GC gc, unsigned long - background); - - display - - Specifies the connection to the X server. - - gc - - Specifies the GC. - - background - - Specifies the background you want to set for the specified GC. - - XSetBackground can generate BadAlloc and BadGC errors. - - To set the display function in a given GC, use XSetFunction. - - XSetFunction(Display *display, GC gc, int function); - - display - - Specifies the connection to the X server. - - gc - - Specifies the GC. - - function - - Specifies the function you want to set for the specified GC. - - XSetFunction can generate BadAlloc, BadGC, and BadValue errors. - - To set the plane mask of a given GC, use XSetPlaneMask. - - XSetPlaneMask(Display *display, GC gc, unsigned long - plane_mask); - - display - - Specifies the connection to the X server. - - gc - - Specifies the GC. - - plane_mask - - Specifies the plane mask. - - XSetPlaneMask can generate BadAlloc and BadGC errors. - -Setting the Line Attributes and Dashes - - To set the line drawing components of a given GC, use - XSetLineAttributes. - - XSetLineAttributes(Display *display, GC gc, unsigned int - line_width, int line_style, int cap_style, int join_style); - - display - - Specifies the connection to the X server. - - gc - - Specifies the GC. - - line_width - - Specifies the line-width you want to set for the specified GC. - - line_style - - Specifies the line-style you want to set for the specified GC. - You can pass LineSolid, LineOnOffDash, or LineDoubleDash. - - cap_style - - Specifies the line-style and cap-style you want to set for the - specified GC. You can pass CapNotLast, CapButt, CapRound, or - CapProjecting. - - join_style - - Specifies the line join-style you want to set for the specified - GC. You can pass JoinMiter, JoinRound, or JoinBevel. - - XSetLineAttributes can generate BadAlloc, BadGC, and BadValue - errors. - - To set the dash-offset and dash-list for dashed line styles of - a given GC, use XSetDashes. - - XSetDashes(Display *display, GC gc, int dash_offset, char - dash_list[], int n); - - display - - Specifies the connection to the X server. - - gc - - Specifies the GC. - - dash_offset - - Specifies the phase of the pattern for the dashed line-style - you want to set for the specified GC. - - dash_list - - Specifies the dash-list for the dashed line-style you want to - set for the specified GC. - - n - - Specifies the number of elements in dash_list. - - The XSetDashes function sets the dash-offset and dash-list - attributes for dashed line styles in the specified GC. There - must be at least one element in the specified dash_list, or a - BadValue error results. The initial and alternating elements - (second, fourth, and so on) of the dash_list are the even - dashes, and the others are the odd dashes. Each element - specifies a dash length in pixels. All of the elements must be - nonzero, or a BadValue error results. Specifying an odd-length - list is equivalent to specifying the same list concatenated - with itself to produce an even-length list. - - The dash-offset defines the phase of the pattern, specifying - how many pixels into the dash-list the pattern should actually - begin in any single graphics request. Dashing is continuous - through path elements combined with a join-style but is reset - to the dash-offset between each sequence of joined lines. - - The unit of measure for dashes is the same for the ordinary - coordinate system. Ideally, a dash length is measured along the - slope of the line, but implementations are only required to - match this ideal for horizontal and vertical lines. Failing the - ideal semantics, it is suggested that the length be measured - along the major axis of the line. The major axis is defined as - the x axis for lines drawn at an angle of between -45 and +45 - degrees or between 135 and 225 degrees from the x axis. For all - other lines, the major axis is the y axis. - - XSetDashes can generate BadAlloc, BadGC, and BadValue errors. - -Setting the Fill Style and Fill Rule - - To set the fill-style of a given GC, use XSetFillStyle. - - XSetFillStyle(Display *display, GC gc, int fill_style); - - display - - Specifies the connection to the X server. - - gc - - Specifies the GC. - - fill_style - - Specifies the fill-style you want to set for the specified GC. - You can pass FillSolid, FillTiled, FillStippled, or - FillOpaqueStippled. - - XSetFillStyle can generate BadAlloc, BadGC, and BadValue - errors. - - To set the fill-rule of a given GC, use XSetFillRule. - - XSetFillRule(Display *display, GC gc, int fill_rule); - - display - - Specifies the connection to the X server. - - gc - - Specifies the GC. - - fill_rule - - Specifies the fill-rule you want to set for the specified GC. - You can pass EvenOddRule or WindingRule. - - XSetFillRule can generate BadAlloc, BadGC, and BadValue errors. - -Setting the Fill Tile and Stipple - - Some displays have hardware support for tiling or stippling - with patterns of specific sizes. Tiling and stippling - operations that restrict themselves to those specific sizes run - much faster than such operations with arbitrary size patterns. - Xlib provides functions that you can use to determine the best - size, tile, or stipple for the display as well as to set the - tile or stipple shape and the tile or stipple origin. - - To obtain the best size of a tile, stipple, or cursor, use - XQueryBestSize. - - Status XQueryBestSize(Display *display, int class, Drawable - which_screen, unsigned int width, unsigned int height, unsigned - int *width_return, unsigned int *height_return); - - display - - Specifies the connection to the X server. - - class - - Specifies the class that you are interested in. You can pass - TileShape, CursorShape, or StippleShape. - - which_screen - - Specifies any drawable on the screen. - - width - - height - - Specify the width and height. - - width_return - - height_return - - Return the width and height of the object best supported by the - display hardware. - - The XQueryBestSize function returns the best or closest size to - the specified size. For CursorShape, this is the largest size - that can be fully displayed on the screen specified by - which_screen. For TileShape, this is the size that can be tiled - fastest. For StippleShape, this is the size that can be - stippled fastest. For CursorShape, the drawable indicates the - desired screen. For TileShape and StippleShape, the drawable - indicates the screen and possibly the window class and depth. - An InputOnly window cannot be used as the drawable for - TileShape or StippleShape, or a BadMatch error results. - - XQueryBestSize can generate BadDrawable, BadMatch, and BadValue - errors. - - To obtain the best fill tile shape, use XQueryBestTile. - - Status XQueryBestTile(Display *display, Drawable which_screen, - unsigned int width, unsigned int height, unsigned int - *width_return, unsigned int *height_return); - - display - - Specifies the connection to the X server. - - which_screen - - Specifies any drawable on the screen. - - width - - height - - Specify the width and height. - - width_return - - height_return - - Return the width and height of the object best supported by the - display hardware. - - The XQueryBestTile function returns the best or closest size, - that is, the size that can be tiled fastest on the screen - specified by which_screen. The drawable indicates the screen - and possibly the window class and depth. If an InputOnly window - is used as the drawable, a BadMatch error results. - - XQueryBestTile can generate BadDrawable and BadMatch errors. - - To obtain the best stipple shape, use XQueryBestStipple. - - Status XQueryBestStipple(Display *display, Drawable - which_screen, unsigned int width, unsigned int height, unsigned - int *width_return, unsigned int *height_return); - - display - - Specifies the connection to the X server. - - which_screen - - Specifies any drawable on the screen. - - width - - height - - Specify the width and height. - - width_return - - height_return - - Return the width and height of the object best supported by the - display hardware. - - The XQueryBestStipple function returns the best or closest - size, that is, the size that can be stippled fastest on the - screen specified by which_screen. The drawable indicates the - screen and possibly the window class and depth. If an InputOnly - window is used as the drawable, a BadMatch error results. - - XQueryBestStipple can generate BadDrawable and BadMatch errors. - - To set the fill tile of a given GC, use XSetTile. - - XSetTile(Display *display, GC gc, Pixmap tile); - - display - - Specifies the connection to the X server. - - gc - - Specifies the GC. - - tile - - Specifies the fill tile you want to set for the specified GC. - - The tile and GC must have the same depth, or a BadMatch error - results. - - XSetTile can generate BadAlloc, BadGC, BadMatch, and BadPixmap - errors. - - To set the stipple of a given GC, use XSetStipple. - - XSetStipple(Display *display, GC gc, Pixmap stipple); - - display - - Specifies the connection to the X server. - - gc - - Specifies the GC. - - stipple - - Specifies the stipple you want to set for the specified GC. - - The stipple must have a depth of one, or a BadMatch error - results. - - XSetStipple can generate BadAlloc, BadGC, BadMatch, and - BadPixmap errors. - - To set the tile or stipple origin of a given GC, use - XSetTSOrigin. - - XSetTSOrigin(Display *display, GC gc, int ts_x_origin, int - ts_y_origin); - - display - - Specifies the connection to the X server. - - gc - - Specifies the GC. - - ts_x_origin - - ts_y_origin - - Specify the x and y coordinates of the tile and stipple origin. - - When graphics requests call for tiling or stippling, the - parent's origin will be interpreted relative to whatever - destination drawable is specified in the graphics request. - - XSetTSOrigin can generate BadAlloc and BadGC errors. - -Setting the Current Font - - To set the current font of a given GC, use XSetFont. - - XSetFont(Display *display, GC gc, Font font); - - display - - Specifies the connection to the X server. - - gc - - Specifies the GC. - - font - - Specifies the font. - - XSetFont can generate BadAlloc, BadFont, and BadGC errors. - -Setting the Clip Region - - Xlib provides functions that you can use to set the clip-origin - and the clip-mask or set the clip-mask to a list of rectangles. - - To set the clip-origin of a given GC, use XSetClipOrigin. - - XSetClipOrigin(Display *display, GC gc, int clip_x_origin, int - clip_y_origin); - - display - - Specifies the connection to the X server. - - gc - - Specifies the GC. - - clip_x_origin - - clip_y_origin - - Specify the x and y coordinates of the clip-mask origin. - - The clip-mask origin is interpreted relative to the origin of - whatever destination drawable is specified in the graphics - request. - - XSetClipOrigin can generate BadAlloc and BadGC errors. - - To set the clip-mask of a given GC to the specified pixmap, use - XSetClipMask. - - XSetClipMask(Display *display, GC gc, Pixmap pixmap); - - display - - Specifies the connection to the X server. - - gc - - Specifies the GC. - - pixmap - - Specifies the pixmap or None. - - If the clip-mask is set to None, the pixels are always drawn - (regardless of the clip-origin). - - XSetClipMask can generate BadAlloc, BadGC, BadMatch, and - BadPixmap errors. - - To set the clip-mask of a given GC to the specified list of - rectangles, use XSetClipRectangles. - - XSetClipRectangles(Display *display, GC gc, int clip_x_origin, - int clip_y_origin, XRectangle rectangles[], int n, int - ordering); - - display - - Specifies the connection to the X server. - - gc - - Specifies the GC. - - clip_x_origin - - clip_y_origin - - Specify the x and y coordinates of the clip-mask origin. - - rectangles - - Specifies an array of rectangles that define the clip-mask. - - n - - Specifies the number of rectangles. - - ordering - - Specifies the ordering relations on the rectangles. You can - pass Unsorted, YSorted, YXSorted, or YXBanded. - - The XSetClipRectangles function changes the clip-mask in the - specified GC to the specified list of rectangles and sets the - clip origin. The output is clipped to remain contained within - the rectangles. The clip-origin is interpreted relative to the - origin of whatever destination drawable is specified in a - graphics request. The rectangle coordinates are interpreted - relative to the clip-origin. The rectangles should be - nonintersecting, or the graphics results will be undefined. - Note that the list of rectangles can be empty, which - effectively disables output. This is the opposite of passing - None as the clip-mask in XCreateGC, XChangeGC, and - XSetClipMask. - - If known by the client, ordering relations on the rectangles - can be specified with the ordering argument. This may provide - faster operation by the server. If an incorrect ordering is - specified, the X server may generate a BadMatch error, but it - is not required to do so. If no error is generated, the - graphics results are undefined. Unsorted means the rectangles - are in arbitrary order. YSorted means that the rectangles are - nondecreasing in their Y origin. YXSorted additionally - constrains YSorted order in that all rectangles with an equal Y - origin are nondecreasing in their X origin. YXBanded - additionally constrains YXSorted by requiring that, for every - possible Y scanline, all rectangles that include that scanline - have an identical Y origins and Y extents. - - XSetClipRectangles can generate BadAlloc, BadGC, BadMatch, and - BadValue errors. - - Xlib provides a set of basic functions for performing region - arithmetic. For information about these functions, see section - 16.5. - -Setting the Arc Mode, Subwindow Mode, and Graphics Exposure - - To set the arc mode of a given GC, use XSetArcMode. - - XSetArcMode(Display *display, GC gc, int arc_mode); - - display - - Specifies the connection to the X server. - - gc - - Specifies the GC. - - arc_mode - - Specifies the arc mode. You can pass ArcChord or ArcPieSlice. - - XSetArcMode can generate BadAlloc, BadGC, and BadValue errors. - - To set the subwindow mode of a given GC, use XSetSubwindowMode. - - XSetSubwindowMode(Display *display, GC gc, int subwindow_mode); - - display - - Specifies the connection to the X server. - - gc - - Specifies the GC. - - subwindow_mode - - Specifies the subwindow mode. You can pass ClipByChildren or - IncludeInferiors. - - XSetSubwindowMode can generate BadAlloc, BadGC, and BadValue - errors. - - To set the graphics-exposures flag of a given GC, use - XSetGraphicsExposures. - - XSetGraphicsExposures(Display *display, GC gc, Bool - graphics_exposures); - - display - - Specifies the connection to the X server. - - gc - - Specifies the GC. - - graphics_exposures - - Specifies a Boolean value that indicates whether you want - GraphicsExpose and NoExpose events to be reported when calling - XCopyArea and XCopyPlane with this GC. - - XSetGraphicsExposures can generate BadAlloc, BadGC, and - BadValue errors. - -Chapter 8. Graphics Functions - - Table of Contents - - Clearing Areas - Copying Areas - Drawing Points, Lines, Rectangles, and Arcs - - Drawing Single and Multiple Points - Drawing Single and Multiple Lines - Drawing Single and Multiple Rectangles - Drawing Single and Multiple Arcs - - Filling Areas - - Filling Single and Multiple Rectangles - Filling a Single Polygon - Filling Single and Multiple Arcs - - Font Metrics - - Loading and Freeing Fonts - Obtaining and Freeing Font Names and Information - Computing Character String Sizes - Computing Logical Extents - Querying Character String Sizes - - Drawing Text - - Drawing Complex Text - Drawing Text Characters - Drawing Image Text Characters - - Transferring Images between Client and Server - - Once you have established a connection to a display, you can - use the Xlib graphics functions to: - * Clear and copy areas - * Draw points, lines, rectangles, and arcs - * Fill areas - * Manipulate fonts - * Draw text - * Transfer images between clients and the server - - If the same drawable and GC is used for each call, Xlib batches - back-to-back calls to XDrawPoint, XDrawLine, XDrawRectangle, - XFillArc, and XFillRectangle. Note that this reduces the total - number of requests sent to the server. - -Clearing Areas - - Xlib provides functions that you can use to clear an area or - the entire window. Because pixmaps do not have defined - backgrounds, they cannot be filled by using the functions - described in this section. Instead, to accomplish an analogous - operation on a pixmap, you should use XFillRectangle, which - sets the pixmap to a known value. - - To clear a rectangular area of a given window, use XClearArea. - - XClearArea(Display *display, Window w, int x, int y, unsigned - int width, unsigned int height, Bool exposures); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - x - - y - - Specify the x and y coordinates, which are relative to the - origin of the window and specify the upper-left corner of the - rectangle. - - width - - height - - Specify the width and height, which are the dimensions of the - rectangle. - - exposures - - Specifies a Boolean value that indicates if Expose events are - to be generated. - - The XClearArea function paints a rectangular area in the - specified window according to the specified dimensions with the - window's background pixel or pixmap. The subwindow-mode - effectively is ClipByChildren. If width is zero, it is replaced - with the current width of the window minus x. If height is - zero, it is replaced with the current height of the window - minus y. If the window has a defined background tile, the - rectangle clipped by any children is filled with this tile. If - the window has background None, the contents of the window are - not changed. In either case, if exposures is True, one or more - Expose events are generated for regions of the rectangle that - are either visible or are being retained in a backing store. If - you specify a window whose class is InputOnly, a BadMatch error - results. - - XClearArea can generate BadMatch, BadValue, and BadWindow - errors. - - To clear the entire area in a given window, use XClearWindow. - - XClearWindow(Display *display, Window w); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - The XClearWindow function clears the entire area in the - specified window and is equivalent to XClearArea (display, w, - 0, 0, 0, 0, False). If the window has a defined background - tile, the rectangle is tiled with a plane-mask of all ones and - GXcopy function. If the window has background None, the - contents of the window are not changed. If you specify a window - whose class is InputOnly, a BadMatch error results. - - XClearWindow can generate BadMatch and BadWindow errors. - -Copying Areas - - Xlib provides functions that you can use to copy an area or a - bit plane. - - To copy an area between drawables of the same root and depth, - use XCopyArea. - - XCopyArea(Display *display, Drawable src, Drawable dest, GC gc, - int src_x, int src_y, unsigned int width, unsigned int height, - int dest_x, int dest_y); - - display - - Specifies the connection to the X server. - - src - - dest - - Specify the source and destination rectangles to be combined. - - gc - - Specifies the GC. - - src_x - - src_y - - Specify the x and y coordinates, which are relative to the - origin of the source rectangle and specify its upper-left - corner. - - width - - height - - Specify the width and height, which are the dimensions of both - the source and destination rectangles. - - dest_x - - dest_y - - Specify the x and y coordinates, which are relative to the - origin of the destination rectangle and specify its upper-left - corner. - - The XCopyArea function combines the specified rectangle of src - with the specified rectangle of dest. The drawables must have - the same root and depth, or a BadMatch error results. - - If regions of the source rectangle are obscured and have not - been retained in backing store or if regions outside the - boundaries of the source drawable are specified, those regions - are not copied. Instead, the following occurs on all - corresponding destination regions that are either visible or - are retained in backing store. If the destination is a window - with a background other than None, corresponding regions of the - destination are tiled with that background (with plane-mask of - all ones and GXcopy function). Regardless of tiling or whether - the destination is a window or a pixmap, if graphics-exposures - is True, then GraphicsExpose events for all corresponding - destination regions are generated. If graphics-exposures is - True but no GraphicsExpose events are generated, a NoExpose - event is generated. Note that by default graphics-exposures is - True in new GCs. - - This function uses these GC components: function, plane-mask, - subwindow-mode, graphics-exposures, clip-x-origin, - clip-y-origin, and clip-mask. - - XCopyArea can generate BadDrawable, BadGC, and BadMatch errors. - - To copy a single bit plane of a given drawable, use XCopyPlane. - - XCopyPlane(Display *display, Drawable src, Drawable dest, GC - gc, int src_x, int src_y, unsigned int width, unsigned int - height, int dest_x, int dest_y, unsigned long plane); - - display - - Specifies the connection to the X server. - - src - - dest - - Specify the source and destination rectangles to be combined. - - gc - - Specifies the GC. - - src_x - - src_y - - Specify the x and y coordinates, which are relative to the - origin of the source rectangle and specify its upper-left - corner. - - width - - height - - Specify the width and height, which are the dimensions of both - the source and destination rectangles. - - dest_x - - dest_y - - Specify the x and y coordinates, which are relative to the - origin of the destination rectangle and specify its upper-left - corner. - - plane - - Specifies the bit plane. You must set exactly one bit to 1. - - The XCopyPlane function uses a single bit plane of the - specified source rectangle combined with the specified GC to - modify the specified rectangle of dest. The drawables must have - the same root but need not have the same depth. If the - drawables do not have the same root, a BadMatch error results. - If plane does not have exactly one bit set to 1 and the value - of plane is not less than %2 sup n%, where n is the depth of - src, a BadValue error results. - - Effectively, XCopyPlane forms a pixmap of the same depth as the - rectangle of dest and with a size specified by the source - region. It uses the foreground/background pixels in the GC - (foreground everywhere the bit plane in src contains a bit set - to 1, background everywhere the bit plane in src contains a bit - set to 0) and the equivalent of a CopyArea protocol request is - performed with all the same exposure semantics. This can also - be thought of as using the specified region of the source bit - plane as a stipple with a fill-style of FillOpaqueStippled for - filling a rectangular area of the destination. - - This function uses these GC components: function, plane-mask, - foreground, background, subwindow-mode, graphics-exposures, - clip-x-origin, clip-y-origin, and clip-mask. - - XCopyPlane can generate BadDrawable, BadGC, BadMatch, and - BadValue errors. - -Drawing Points, Lines, Rectangles, and Arcs - - Xlib provides functions that you can use to draw: - * A single point or multiple points - * A single line or multiple lines - * A single rectangle or multiple rectangles - * A single arc or multiple arcs - - Some of the functions described in the following sections use - these structures: - - - -typedef struct { - short x1, y1, x2, y2; -} XSegment; - - - -typedef struct { - short x, y; -} XPoint; - - - -typedef struct { - short x, y; - unsigned short width, height; -} XRectangle; - - - -typedef struct { - short x, y; - unsigned short width, height; - short angle1, angle2; /* Degrees * 64 */ -} XArc; - - All x and y members are signed integers. The width and height - members are 16-bit unsigned integers. You should be careful not - to generate coordinates and sizes out of the 16-bit ranges, - because the protocol only has 16-bit fields for these values. - -Drawing Single and Multiple Points - - To draw a single point in a given drawable, use XDrawPoint. - - XDrawPoint(Display *display, Drawable d, GC gc, int x, int y); - - display - - Specifies the connection to the X server. - - d - - Specifies the drawable. - - gc - - Specifies the GC. - - x - - y - - Specify the x and y coordinates where you want the point drawn. - - To draw multiple points in a given drawable, use XDrawPoints. - - XDrawPoints(Display *display, Drawable d, GC gc, XPoint - *points, int npoints, int mode); - - display - - Specifies the connection to the X server. - - d - - Specifies the drawable. - - gc - - Specifies the GC. - - points - - Specifies an array of points. - - npoints - - Specifies the number of points in the array. - - mode - - Specifies the coordinate mode. You can pass CoordModeOrigin or - CoordModePrevious. - - The XDrawPoint function uses the foreground pixel and function - components of the GC to draw a single point into the specified - drawable; XDrawPoints draws multiple points this way. - CoordModeOrigin treats all coordinates as relative to the - origin, and CoordModePrevious treats all coordinates after the - first as relative to the previous point. XDrawPoints draws the - points in the order listed in the array. - - Both functions use these GC components: function, plane-mask, - foreground, subwindow-mode, clip-x-origin, clip-y-origin, and - clip-mask. - - XDrawPoint can generate BadDrawable, BadGC, and BadMatch - errors. XDrawPoints can generate BadDrawable, BadGC, BadMatch, - and BadValue errors. - -Drawing Single and Multiple Lines - - To draw a single line between two points in a given drawable, - use XDrawLine. - - XDrawLine(Display *display, Drawable d, GC gc, int x1, int y1, - int x2, int y2); - - display - - Specifies the connection to the X server. - - d - - Specifies the drawable. - - gc - - Specifies the GC. - - x1 - - y1 - - x2 - - y2 - - Specify the points (x1, y1) and (x2, y2) to be connected. - - To draw multiple lines in a given drawable, use XDrawLines. - - XDrawLines(Display *display, Drawable d, GC gc, XPoint *points, - int npoints, int mode); - - display - - Specifies the connection to the X server. - - d - - Specifies the drawable. - - gc - - Specifies the GC. - - points - - Specifies an array of points. - - npoints - - Specifies the number of points in the array. - - mode - - Specifies the coordinate mode. You can pass CoordModeOrigin or - CoordModePrevious. - - To draw multiple, unconnected lines in a given drawable, use - XDrawSegments. - - XDrawSegments(Display *display, Drawable d, GC gc, XSegment - *segments, int nsegments); - - display - - Specifies the connection to the X server. - - d - - Specifies the drawable. - - gc - - Specifies the GC. - - segments - - Specifies an array of segments. - - nsegments - - Specifies the number of segments in the array. - - The XDrawLine function uses the components of the specified GC - to draw a line between the specified set of points (x1, y1) and - (x2, y2). It does not perform joining at coincident endpoints. - For any given line, XDrawLine does not draw a pixel more than - once. If lines intersect, the intersecting pixels are drawn - multiple times. - - The XDrawLines function uses the components of the specified GC - to draw npoints-1 lines between each pair of points (point[i], - point[i+1]) in the array of XPoint structures. It draws the - lines in the order listed in the array. The lines join - correctly at all intermediate points, and if the first and last - points coincide, the first and last lines also join correctly. - For any given line, XDrawLines does not draw a pixel more than - once. If thin (zero line-width) lines intersect, the - intersecting pixels are drawn multiple times. If wide lines - intersect, the intersecting pixels are drawn only once, as - though the entire PolyLine protocol request were a single, - filled shape. CoordModeOrigin treats all coordinates as - relative to the origin, and CoordModePrevious treats all - coordinates after the first as relative to the previous point. - - The XDrawSegments function draws multiple, unconnected lines. - For each segment, XDrawSegments draws a line between (x1, y1) - and (x2, y2). It draws the lines in the order listed in the - array of XSegment structures and does not perform joining at - coincident endpoints. For any given line, XDrawSegments does - not draw a pixel more than once. If lines intersect, the - intersecting pixels are drawn multiple times. - - All three functions use these GC components: function, - plane-mask, line-width, line-style, cap-style, fill-style, - subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. - The XDrawLines function also uses the join-style GC component. - All three functions also use these GC mode-dependent - components: foreground, background, tile, stipple, - tile-stipple-x-origin, tile-stipple-y-origin, dash-offset, and - dash-list. - - XDrawLine, XDrawLines, and XDrawSegments can generate - BadDrawable, BadGC, and BadMatch errors. XDrawLines also can - generate BadValue errors. - -Drawing Single and Multiple Rectangles - - To draw the outline of a single rectangle in a given drawable, - use XDrawRectangle. - - XDrawRectangle(Display *display, Drawable d, GC gc, int x, int - y, unsigned int width, unsigned int height); - - display - - Specifies the connection to the X server. - - d - - Specifies the drawable. - - gc - - Specifies the GC. - - x - - y - - Specify the x and y coordinates, which specify the upper-left - corner of the rectangle. - - width - - height - - Specify the width and height, which specify the dimensions of - the rectangle. - - To draw the outline of multiple rectangles in a given drawable, - use XDrawRectangles. - - XDrawRectangles(Display *display, Drawable d, GC gc, XRectangle - rectangles[], int nrectangles); - - display - - Specifies the connection to the X server. - - d - - Specifies the drawable. - - gc - - Specifies the GC. - - rectangles - - Specifies an array of rectangles. - - nrectangles - - Specifies the number of rectangles in the array. - - The XDrawRectangle and XDrawRectangles functions draw the - outlines of the specified rectangle or rectangles as if a - five-point PolyLine protocol request were specified for each - rectangle: - * [x,y] [x+width,y] [x+width,y+height] [x,y+height] [x,y] - - For the specified rectangle or rectangles, these functions do - not draw a pixel more than once. XDrawRectangles draws the - rectangles in the order listed in the array. If rectangles - intersect, the intersecting pixels are drawn multiple times. - - Both functions use these GC components: function, plane-mask, - line-width, line-style, cap-style, join-style, fill-style, - subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. - They also use these GC mode-dependent components: foreground, - background, tile, stipple, tile-stipple-x-origin, - tile-stipple-y-origin, dash-offset, and dash-list. - - XDrawRectangle and XDrawRectangles can generate BadDrawable, - BadGC, and BadMatch errors. - -Drawing Single and Multiple Arcs - - To draw a single arc in a given drawable, use XDrawArc. - - XDrawArc(Display *display, Drawable d, GC gc, int x, int y, - unsigned int width, unsigned int height, int angle1, int - angle2); - - display - - Specifies the connection to the X server. - - d - - Specifies the drawable. - - gc - - Specifies the GC. - - x - - y - - Specify the x and y coordinates, which are relative to the - origin of the drawable and specify the upper-left corner of the - bounding rectangle. - - width - - height - - Specify the width and height, which are the major and minor - axes of the arc. - - angle1 - - Specifies the start of the arc relative to the three-o'clock - position from the center, in units of degrees * 64. - - angle2 - - Specifies the path and extent of the arc relative to the start - of the arc, in units of degrees * 64. - - To draw multiple arcs in a given drawable, use XDrawArcs. - - XDrawArcs(Display *display, Drawable d, GC gc, XArc *arcs, int - narcs); - - display - - Specifies the connection to the X server. - - d - - Specifies the drawable. - - gc - - Specifies the GC. - - arcs - - Specifies an array of arcs. - - narcs - - Specifies the number of arcs in the array. - - delim %% XDrawArc draws a single circular or elliptical arc, - and XDrawArcs draws multiple circular or elliptical arcs. Each - arc is specified by a rectangle and two angles. The center of - the circle or ellipse is the center of the rectangle, and the - major and minor axes are specified by the width and height. - Positive angles indicate counterclockwise motion, and negative - angles indicate clockwise motion. If the magnitude of angle2 is - greater than 360 degrees, XDrawArc or XDrawArcs truncates it to - 360 degrees. - - For an arc specified as %[ ~x, ~y, ~width , ~height, ~angle1, - ~angle2 ]%, the origin of the major and minor axes is at % [ x - +^ {width over 2} , ~y +^ {height over 2} ]%, and the - infinitely thin path describing the entire circle or ellipse - intersects the horizontal axis at % [ x, ~y +^ {height over 2} - ]% and % [ x +^ width , ~y +^ { height over 2 }] % and - intersects the vertical axis at % [ x +^ { width over 2 } , ~y - ]% and % [ x +^ { width over 2 }, ~y +^ height ]%. These - coordinates can be fractional and so are not truncated to - discrete coordinates. The path should be defined by the ideal - mathematical path. For a wide line with line-width lw, the - bounding outlines for filling are given by the two infinitely - thin paths consisting of all points whose perpendicular - distance from the path of the circle/ellipse is equal to lw/2 - (which may be a fractional value). The cap-style and join-style - are applied the same as for a line corresponding to the tangent - of the circle/ellipse at the endpoint. - - For an arc specified as % [ ~x, ~y, ~width, ~height, ~angle1, - ~angle2 ]%, the angles must be specified in the effectively - skewed coordinate system of the ellipse (for a circle, the - angles and coordinate systems are identical). The relationship - between these angles and angles expressed in the normal - coordinate system of the screen (as measured with a protractor) - is as follows: - -% roman "skewed-angle" ~ = ~ atan left ( tan ( roman "normal-angle" ) - * width over height right ) +^ adjust% - - The skewed-angle and normal-angle are expressed in radians - (rather than in degrees scaled by 64) in the range % [ 0 , ~2 - pi ]% and where atan returns a value in the range % [ - pi over - 2 , ~pi over 2 ] % and adjust is: - - - -%0% for normal-angle in the range % [ 0 , ~pi over 2 ]% -%pi% for normal-angle in the range % [ pi over 2 , ~{3 pi} over 2 ] -% -%2 pi% for normal-angle in the range % [ {3 pi} over 2 , ~2 pi ]% - - For any given arc, XDrawArc and XDrawArcs do not draw a pixel - more than once. If two arcs join correctly and if the - line-width is greater than zero and the arcs intersect, - XDrawArc and XDrawArcs do not draw a pixel more than once. - Otherwise, the intersecting pixels of intersecting arcs are - drawn multiple times. Specifying an arc with one endpoint and a - clockwise extent draws the same pixels as specifying the other - endpoint and an equivalent counterclockwise extent, except as - it affects joins. - - If the last point in one arc coincides with the first point in - the following arc, the two arcs will join correctly. If the - first point in the first arc coincides with the last point in - the last arc, the two arcs will join correctly. By specifying - one axis to be zero, a horizontal or vertical line can be - drawn. Angles are computed based solely on the coordinate - system and ignore the aspect ratio. - - Both functions use these GC components: function, plane-mask, - line-width, line-style, cap-style, join-style, fill-style, - subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. - They also use these GC mode-dependent components: foreground, - background, tile, stipple, tile-stipple-x-origin, - tile-stipple-y-origin, dash-offset, and dash-list. - - XDrawArc and XDrawArcs can generate BadDrawable, BadGC, and - BadMatch errors. - -Filling Areas - - Xlib provides functions that you can use to fill: - * A single rectangle or multiple rectangles - * A single polygon - * A single arc or multiple arcs - -Filling Single and Multiple Rectangles - - To fill a single rectangular area in a given drawable, use - XFillRectangle. - - XFillRectangle(Display *display, Drawable d, GC gc, int x, int - y, unsigned int width, unsigned int height); - - display - - Specifies the connection to the X server. - - d - - Specifies the drawable. - - gc - - Specifies the GC. - - x - - y - - Specify the x and y coordinates, which are relative to the - origin of the drawable and specify the upper-left corner of the - rectangle. - - width - - height - - Specify the width and height, which are the dimensions of the - rectangle to be filled. - - To fill multiple rectangular areas in a given drawable, use - XFillRectangles. - - XFillRectangles(Display *display, Drawable d, GC gc, XRectangle - *rectangles, int nrectangles); - - display - - Specifies the connection to the X server. - - d - - Specifies the drawable. - - gc - - Specifies the GC. - - rectangles - - Specifies an array of rectangles. - - nrectangles - - Specifies the number of rectangles in the array. - - The XFillRectangle and XFillRectangles functions fill the - specified rectangle or rectangles as if a four-point - FillPolygon protocol request were specified for each rectangle: - -[x,y] [x+width,y] [x+width,y+height] [x,y+height] - - Each function uses the x and y coordinates, width and height - dimensions, and GC you specify. - - XFillRectangles fills the rectangles in the order listed in the - array. For any given rectangle, XFillRectangle and - XFillRectangles do not draw a pixel more than once. If - rectangles intersect, the intersecting pixels are drawn - multiple times. - - Both functions use these GC components: function, plane-mask, - fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and - clip-mask. They also use these GC mode-dependent components: - foreground, background, tile, stipple, tile-stipple-x-origin, - and tile-stipple-y-origin. - - XFillRectangle and XFillRectangles can generate BadDrawable, - BadGC, and BadMatch errors. - -Filling a Single Polygon - - To fill a polygon area in a given drawable, use XFillPolygon. - - XFillPolygon(Display *display, Drawable d, GC gc, XPoint - *points, int npoints, int shape, int mode); - - display - - Specifies the connection to the X server. - - d - - Specifies the drawable. - - gc - - Specifies the GC. - - points - - Specifies an array of points. - - npoints - - Specifies the number of points in the array. - - shape - - Specifies a shape that helps the server to improve performance. - You can pass Complex, Convex, or Nonconvex. - - mode - - Specifies the coordinate mode. You can pass CoordModeOrigin or - CoordModePrevious. - - XFillPolygon fills the region closed by the specified path. The - path is closed automatically if the last point in the list does - not coincide with the first point. XFillPolygon does not draw a - pixel of the region more than once. CoordModeOrigin treats all - coordinates as relative to the origin, and CoordModePrevious - treats all coordinates after the first as relative to the - previous point. - - Depending on the specified shape, the following occurs: - * If shape is Complex, the path may self-intersect. Note that - contiguous coincident points in the path are not treated as - self-intersection. - * If shape is Convex, for every pair of points inside the - polygon, the line segment connecting them does not - intersect the path. If known by the client, specifying - Convex can improve performance. If you specify Convex for a - path that is not convex, the graphics results are - undefined. - * If shape is Nonconvex, the path does not self-intersect, - but the shape is not wholly convex. If known by the client, - specifying Nonconvex instead of Complex may improve - performance. If you specify Nonconvex for a - self-intersecting path, the graphics results are undefined. - - The fill-rule of the GC controls the filling behavior of - self-intersecting polygons. - - This function uses these GC components: function, plane-mask, - fill-style, fill-rule, subwindow-mode, clip-x-origin, - clip-y-origin, and clip-mask. It also uses these GC - mode-dependent components: foreground, background, tile, - stipple, tile-stipple-x-origin, and tile-stipple-y-origin. - - XFillPolygon can generate BadDrawable, BadGC, BadMatch, and - BadValue errors. - -Filling Single and Multiple Arcs - - To fill a single arc in a given drawable, use XFillArc. - - XFillArc(Display *display, Drawable d, GC gc, int x, int y, - unsigned int width, unsigned int height, int angle1, int - angle2); - - display - - Specifies the connection to the X server. - - d - - Specifies the drawable. - - gc - - Specifies the GC. - - x - - y - - Specify the x and y coordinates, which are relative to the - origin of the drawable and specify the upper-left corner of the - bounding rectangle. - - width - - height - - Specify the width and height, which are the major and minor - axes of the arc. - - angle1 - - Specifies the start of the arc relative to the three-o'clock - position from the center, in units of degrees * 64. - - angle2 - - Specifies the path and extent of the arc relative to the start - of the arc, in units of degrees * 64. - - To fill multiple arcs in a given drawable, use XFillArcs. - - XFillArcs(Display *display, Drawable d, GC gc, XArc *arcs, int - narcs); - - display - - Specifies the connection to the X server. - - d - - Specifies the drawable. - - gc - - Specifies the GC. - - arcs - - Specifies an array of arcs. - - narcs - - Specifies the number of arcs in the array. - - For each arc, XFillArc or XFillArcs fills the region closed by - the infinitely thin path described by the specified arc and, - depending on the arc-mode specified in the GC, one or two line - segments. For ArcChord, the single line segment joining the - endpoints of the arc is used. For ArcPieSlice, the two line - segments joining the endpoints of the arc with the center point - are used. XFillArcs fills the arcs in the order listed in the - array. For any given arc, XFillArc and XFillArcs do not draw a - pixel more than once. If regions intersect, the intersecting - pixels are drawn multiple times. - - Both functions use these GC components: function, plane-mask, - fill-style, arc-mode, subwindow-mode, clip-x-origin, - clip-y-origin, and clip-mask. They also use these GC - mode-dependent components: foreground, background, tile, - stipple, tile-stipple-x-origin, and tile-stipple-y-origin. - - XFillArc and XFillArcs can generate BadDrawable, BadGC, and - BadMatch errors. - -Font Metrics - - A font is a graphical description of a set of characters that - are used to increase efficiency whenever a set of small, - similar sized patterns are repeatedly used. - - This section discusses how to: - * Load and free fonts - * Obtain and free font names - * Compute character string sizes - * Compute logical extents - * Query character string sizes - - The X server loads fonts whenever a program requests a new - font. The server can cache fonts for quick lookup. Fonts are - global across all screens in a server. Several levels are - possible when dealing with fonts. Most applications simply use - XLoadQueryFont to load a font and query the font metrics. - - Characters in fonts are regarded as masks. Except for image - text requests, the only pixels modified are those in which bits - are set to 1 in the character. This means that it makes sense - to draw text using stipples or tiles (for example, many menus - gray-out unusable entries). - - The XFontStruct structure contains all of the information for - the font and consists of the font-specific information as well - as a pointer to an array of XCharStruct structures for the - characters contained in the font. The XFontStruct, XFontProp, - and XCharStruct structures contain: - - - -typedef struct { - short lbearing; /* origin to left edge of raster */ - short rbearing; /* origin to right edge of raster */ - short width; /* advance to next char's origin */ - short ascent; /* baseline to top edge of raster */ - short descent; /* baseline to bottom edge of raster -*/ - unsigned short attributes; /* per char flags (not predefined) */ -} XCharStruct; - - - -typedef struct { - Atom name; - unsigned long card32; -} XFontProp; - - - -typedef struct { /* normal 16 bit characters are two bytes */ - unsigned char byte1; - unsigned char byte2; -} XChar2b; - - - -typedef struct { - XExtData *ext_data; /* hook for extension to hang dat -a */ - Font fid; /* Font id for this font */ - unsigned direction; /* hint about the direction font -is painted */ - unsigned min_char_or_byte2; /* first character */ - unsigned max_char_or_byte2; /* last character */ - unsigned min_byte1; /* first row that exists */ - unsigned max_byte1; /* last row that exists */ - Bool all_chars_exist; /* flag if all characters have no -nzero size */ - unsigned default_char; /* char to print for undefined ch -aracter */ - int n_properties; /* how many properties there are -*/ - XFontProp *properties; /* pointer to array of additional - properties */ - XCharStruct min_bounds; /* minimum bounds over all existi -ng char */ - XCharStruct max_bounds; /* maximum bounds over all existi -ng char */ - XCharStruct *per_char; /* first_char to last_char inform -ation */ - int ascent; /* logical extent above baseline -for spacing */ - int descent; /* logical descent below baseline - for spacing */ -} XFontStruct; - - X supports single byte/character, two bytes/character matrix, - and 16-bit character text operations. Note that any of these - forms can be used with a font, but a single byte/character text - request can only specify a single byte (that is, the first row - of a 2-byte font). You should view 2-byte fonts as a - two-dimensional matrix of defined characters: byte1 specifies - the range of defined rows and byte2 defines the range of - defined columns of the font. Single byte/character fonts have - one row defined, and the byte2 range specified in the structure - defines a range of characters. - - The bounding box of a character is defined by the XCharStruct - of that character. When characters are absent from a font, the - default_char is used. When fonts have all characters of the - same size, only the information in the XFontStruct min and max - bounds are used. - - The members of the XFontStruct have the following semantics: - * The direction member can be either FontLeftToRight or - FontRightToLeft. It is just a hint as to whether most - XCharStruct elements have a positive (FontLeftToRight) or a - negative (FontRightToLeft) character width metric. The core - protocol defines no support for vertical text. - * If the min_byte1 and max_byte1 members are both zero, - min_char_or_byte2 specifies the linear character index - corresponding to the first element of the per_char array, - and max_char_or_byte2 specifies the linear character index - of the last element. - * If either min_byte1 or max_byte1 are nonzero, both - min_char_or_byte2 and max_char_or_byte2 are less than 256, - and the 2-byte character index values corresponding to the - per_char array element N (counting from 0) are: - * byte1 = N/D + min_byte1 byte2 = N\\D + min_char_or_byte2 - * where: - * D = max_char_or_byte2 - min_char_or_byte2 + 1 / = integer - division \\ = integer modulus - * If the per_char pointer is NULL, all glyphs between the - first and last character indexes inclusive have the same - information, as given by both min_bounds and max_bounds. - * If all_chars_exist is True, all characters in the per_char - array have nonzero bounding boxes. - * The default_char member specifies the character that will - be used when an undefined or nonexistent character is - printed. The default_char is a 16-bit character (not a - 2-byte character). For a font using 2-byte matrix format, - the default_char has byte1 in the most-significant byte and - byte2 in the least significant byte. If the default_char - itself specifies an undefined or nonexistent character, no - printing is performed for an undefined or nonexistent - character. - * The min_bounds and max_bounds members contain the most - extreme values of each individual XCharStruct component - over all elements of this array (and ignore nonexistent - characters). The bounding box of the font (the smallest - rectangle enclosing the shape obtained by superimposing all - of the characters at the same origin [x,y]) has its - upper-left coordinate at: - [x + min_bounds.lbearing, y - max_bounds.ascent] - - * Its width is: - max_bounds.rbearing - min_bounds.lbearing - - * Its height is: - max_bounds.ascent + max_bounds.descent - - * The ascent member is the logical extent of the font above - the baseline that is used for determining line spacing. - Specific characters may extend beyond this. - * The descent member is the logical extent of the font at or - below the baseline that is used for determining line - spacing. Specific characters may extend beyond this. - * If the baseline is at Y-coordinate y, the logical extent of - the font is inclusive between the Y-coordinate values (y - - font.ascent) and (y + font.descent - 1). Typically, the - minimum interline spacing between rows of text is given by - ascent + descent. - - For a character origin at [x,y], the bounding box of a - character (that is, the smallest rectangle that encloses the - character's shape) described in terms of XCharStruct components - is a rectangle with its upper-left corner at: - -[x + lbearing, y - ascent] - - Its width is: - -rbearing - lbearing - - Its height is: - -ascent + descent - - The origin for the next character is defined to be: - -[x + width, y] - - The lbearing member defines the extent of the left edge of the - character ink from the origin. The rbearing member defines the - extent of the right edge of the character ink from the origin. - The ascent member defines the extent of the top edge of the - character ink from the origin. The descent member defines the - extent of the bottom edge of the character ink from the origin. - The width member defines the logical width of the character. - - Note that the baseline (the y position of the character origin) - is logically viewed as being the scanline just below - nondescending characters. When descent is zero, only pixels - with Y-coordinates less than y are drawn, and the origin is - logically viewed as being coincident with the left edge of a - nonkerned character. When lbearing is zero, no pixels with - X-coordinate less than x are drawn. Any of the XCharStruct - metric members could be negative. If the width is negative, the - next character will be placed to the left of the current - origin. - - The X protocol does not define the interpretation of the - attributes member in the XCharStruct structure. A nonexistent - character is represented with all members of its XCharStruct - set to zero. - - A font is not guaranteed to have any properties. The - interpretation of the property value (for example, long or - unsigned long) must be derived from a priori knowledge of the - property. A basic set of font properties is specified in the X - Consortium standard X Logical Font Description Conventions. - -Loading and Freeing Fonts - - Xlib provides functions that you can use to load fonts, get - font information, unload fonts, and free font information. A - few font functions use a GContext resource ID or a font ID - interchangeably. - - To load a given font, use XLoadFont. - - Font XLoadFont(Display *display, char *name); - - display - - Specifies the connection to the X server. - - name - - Specifies the name of the font, which is a null-terminated - string. - - The XLoadFont function loads the specified font and returns its - associated font ID. If the font name is not in the Host - Portable Character Encoding, the result is - implementation-dependent. Use of uppercase or lowercase does - not matter. When the characters ``?'' and ``*'' are used in a - font name, a pattern match is performed and any matching font - is used. In the pattern, the ``?'' character will match any - single character, and the ``*'' character will match any number - of characters. A structured format for font names is specified - in the X Consortium standard X Logical Font Description - Conventions. If XLoadFont was unsuccessful at loading the - specified font, a BadName error results. Fonts are not - associated with a particular screen and can be stored as a - component of any GC. When the font is no longer needed, call - XUnloadFont. - - XLoadFont can generate BadAlloc and BadName errors. - - To return information about an available font, use XQueryFont. - - XFontStruct *XQueryFont(Display *display, XID font_ID); - - display - - Specifies the connection to the X server. - - font_ID - - Specifies the font ID or the GContext ID. - - The XQueryFont function returns a pointer to the XFontStruct - structure, which contains information associated with the font. - You can query a font or the font stored in a GC. The font ID - stored in the XFontStruct structure will be the GContext ID, - and you need to be careful when using this ID in other - functions (see XGContextFromGC). If the font does not exist, - XQueryFont returns NULL. To free this data, use XFreeFontInfo. - - To perform a XLoadFont and XQueryFont in a single operation, - use XLoadQueryFont. - - XFontStruct *XLoadQueryFont(Display *display, char *name); - - display - - Specifies the connection to the X server. - - name - - Specifies the name of the font, which is a null-terminated - string. - - The XLoadQueryFont function provides the most common way for - accessing a font. XLoadQueryFont both opens (loads) the - specified font and returns a pointer to the appropriate - XFontStruct structure. If the font name is not in the Host - Portable Character Encoding, the result is - implementation-dependent. If the font does not exist, - XLoadQueryFont returns NULL. - - XLoadQueryFont can generate a BadAlloc error. - - To unload the font and free the storage used by the font - structure that was allocated by XQueryFont or XLoadQueryFont, - use XFreeFont. - - XFreeFont(Display *display, XFontStruct *font_struct); - - display - - Specifies the connection to the X server. - - font_struct - - Specifies the storage associated with the font. - - The XFreeFont function deletes the association between the font - resource ID and the specified font and frees the XFontStruct - structure. The font itself will be freed when no other resource - references it. The data and the font should not be referenced - again. - - XFreeFont can generate a BadFont error. - - To return a given font property, use XGetFontProperty. - - Bool XGetFontProperty(XFontStruct *font_struct, Atom atom, - unsigned long *value_return); - - font_struct - - Specifies the storage associated with the font. - - atom - - Specifies the atom for the property name you want returned. - - value_return - - Returns the value of the font property. - - Given the atom for that property, the XGetFontProperty function - returns the value of the specified font property. - XGetFontProperty also returns False if the property was not - defined or True if it was defined. A set of predefined atoms - exists for font properties, which can be found in - . This set contains the standard properties - associated with a font. Although it is not guaranteed, it is - likely that the predefined font properties will be present. - - To unload a font that was loaded by XLoadFont, use XUnloadFont. - - XUnloadFont(Display *display, Font font); - - display - - Specifies the connection to the X server. - - font - - Specifies the font. - - The XUnloadFont function deletes the association between the - font resource ID and the specified font. The font itself will - be freed when no other resource references it. The font should - not be referenced again. - - XUnloadFont can generate a BadFont error. - -Obtaining and Freeing Font Names and Information - - You obtain font names and information by matching a wildcard - specification when querying a font type for a list of available - sizes and so on. - - To return a list of the available font names, use XListFonts. - - char **XListFonts(Display *display, char *pattern, int - maxnames, int *actual_count_return); - - display - - Specifies the connection to the X server. - - pattern - - Specifies the null-terminated pattern string that can contain - wildcard characters. - - maxnames - - Specifies the maximum number of names to be returned. - - actual_count_return - - Returns the actual number of font names. - - The XListFonts function returns an array of available font - names (as controlled by the font search path; see XSetFontPath) - that match the string you passed to the pattern argument. The - pattern string can contain any characters, but each asterisk - (*) is a wildcard for any number of characters, and each - question mark (?) is a wildcard for a single character. If the - pattern string is not in the Host Portable Character Encoding, - the result is implementation-dependent. Use of uppercase or - lowercase does not matter. Each returned string is - null-terminated. If the data returned by the server is in the - Latin Portable Character Encoding, then the returned strings - are in the Host Portable Character Encoding. Otherwise, the - result is implementation-dependent. If there are no matching - font names, XListFonts returns NULL. The client should call - XFreeFontNames when finished with the result to free the - memory. - - To free a font name array, use XFreeFontNames. - - XFreeFontNames(char *list[]); - - list - - Specifies the array of strings you want to free. - - The XFreeFontNames function frees the array and strings - returned by XListFonts or XListFontsWithInfo. - - To obtain the names and information about available fonts, use - XListFontsWithInfo. - - char **XListFontsWithInfo(Display *display, char *pattern, int - maxnames, int *count_return, XFontStruct **info_return); - - display - - Specifies the connection to the X server. - - pattern - - Specifies the null-terminated pattern string that can contain - wildcard characters. - - maxnames - - Specifies the maximum number of names to be returned. - - count_return - - Returns the actual number of matched font names. - - info_return - - Returns the font information. - - The XListFontsWithInfo function returns a list of font names - that match the specified pattern and their associated font - information. The list of names is limited to size specified by - maxnames. The information returned for each font is identical - to what XLoadQueryFont would return except that the - per-character metrics are not returned. The pattern string can - contain any characters, but each asterisk (*) is a wildcard for - any number of characters, and each question mark (?) is a - wildcard for a single character. If the pattern string is not - in the Host Portable Character Encoding, the result is - implementation-dependent. Use of uppercase or lowercase does - not matter. Each returned string is null-terminated. If the - data returned by the server is in the Latin Portable Character - Encoding, then the returned strings are in the Host Portable - Character Encoding. Otherwise, the result is - implementation-dependent. If there are no matching font names, - XListFontsWithInfo returns NULL. - - To free only the allocated name array, the client should call - XFreeFontNames. To free both the name array and the font - information array or to free just the font information array, - the client should call XFreeFontInfo. - - To free font structures and font names, use XFreeFontInfo. - - XFreeFontInfo(char **names, XFontStruct *free_info, int - actual_count); - - names - - Specifies the list of font names. - - free_info - - Specifies the font information. - - actual_count - - Specifies the actual number of font names. - - The XFreeFontInfo function frees a font structure or an array - of font structures and optionally an array of font names. If - NULL is passed for names, no font names are freed. If a font - structure for an open font (returned by XLoadQueryFont) is - passed, the structure is freed, but the font is not closed; use - XUnloadFont to close the font. - -Computing Character String Sizes - - Xlib provides functions that you can use to compute the width, - the logical extents, and the server information about 8-bit and - 2-byte text strings. The width is computed by adding the - character widths of all the characters. It does not matter if - the font is an 8-bit or 2-byte font. These functions return the - sum of the character metrics in pixels. - - To determine the width of an 8-bit character string, use - XTextWidth. - - int XTextWidth(XFontStruct *font_struct, char *string, int - count); - - font_struct - - Specifies the font used for the width computation. - - string - - Specifies the character string. - - count - - Specifies the character count in the specified string. - - To determine the width of a 2-byte character string, use - XTextWidth16. - - int XTextWidth16(XFontStruct *font_struct, XChar2b *string, int - count); - - font_struct - - Specifies the font used for the width computation. - - string - - Specifies the character string. - - count - - Specifies the character count in the specified string. - -Computing Logical Extents - - To compute the bounding box of an 8-bit character string in a - given font, use XTextExtents. - - XTextExtents(XFontStruct *font_struct, char *string, int - nchars, int *direction_return, int *font_ascent_return, int - *font_descent_return, XCharStruct *overall_return); - - font_struct - - Specifies the XFontStruct structure. - - string - - Specifies the character string. - - nchars - - Specifies the number of characters in the character string. - - direction_return - - Returns the value of the direction hint (FontLeftToRight or - FontRightToLeft). - - font_ascent_return - - Returns the font ascent. - - font_descent_return - - Returns the font descent. - - overall_return - - Returns the overall size in the specified XCharStruct - structure. - - To compute the bounding box of a 2-byte character string in a - given font, use XTextExtents16. - - XTextExtents16(XFontStruct *font_struct, XChar2b *string, int - nchars, int *direction_return, int *font_ascent_return, int - *font_descent_return, XCharStruct *overall_return); - - font_struct - - Specifies the XFontStruct structure. - - string - - Specifies the character string. - - nchars - - Specifies the number of characters in the character string. - - direction_return - - Returns the value of the direction hint (FontLeftToRight or - FontRightToLeft). - - font_ascent_return - - Returns the font ascent. - - font_descent_return - - Returns the font descent. - - overall_return - - Returns the overall size in the specified XCharStruct - structure. - - The XTextExtents and XTextExtents16 functions perform the size - computation locally and, thereby, avoid the round-trip overhead - of XQueryTextExtents and XQueryTextExtents16. Both functions - return an XCharStruct structure, whose members are set to the - values as follows. - - The ascent member is set to the maximum of the ascent metrics - of all characters in the string. The descent member is set to - the maximum of the descent metrics. The width member is set to - the sum of the character-width metrics of all characters in the - string. For each character in the string, let W be the sum of - the character-width metrics of all characters preceding it in - the string. Let L be the left-side-bearing metric of the - character plus W. Let R be the right-side-bearing metric of the - character plus W. The lbearing member is set to the minimum L - of all characters in the string. The rbearing member is set to - the maximum R. - - For fonts defined with linear indexing rather than 2-byte - matrix indexing, each XChar2b structure is interpreted as a - 16-bit number with byte1 as the most significant byte. If the - font has no defined default character, undefined characters in - the string are taken to have all zero metrics. - -Querying Character String Sizes - - To query the server for the bounding box of an 8-bit character - string in a given font, use XQueryTextExtents. - - XQueryTextExtents(Display *display, XID font_ID, char *string, - int nchars, int *direction_return, int *font_ascent_return, int - *font_descent_return, XCharStruct *overall_return); - - display - - Specifies the connection to the X server. - - font_ID - - Specifies either the font ID or the GContext ID that contains - the font. - - string - - Specifies the character string. - - nchars - - Specifies the number of characters in the character string. - - direction_return - - Returns the value of the direction hint (FontLeftToRight or - FontRightToLeft). - - font_ascent_return - - Returns the font ascent. - - font_descent_return - - Returns the font descent. - - overall_return - - Returns the overall size in the specified XCharStruct - structure. - - To query the server for the bounding box of a 2-byte character - string in a given font, use XQueryTextExtents16. - - XQueryTextExtents16(Display *display, XID font_ID, XChar2b - *string, int nchars, int *direction_return, int - *font_ascent_return, int *font_descent_return, XCharStruct - *overall_return); - - display - - Specifies the connection to the X server. - - font_ID - - Specifies either the font ID or the GContext ID that contains - the font. - - string - - Specifies the character string. - - nchars - - Specifies the number of characters in the character string. - - direction_return - - Returns the value of the direction hint (FontLeftToRight or - FontRightToLeft). - - font_ascent_return - - Returns the font ascent. - - font_descent_return - - Returns the font descent. - - overall_return - - Returns the overall size in the specified XCharStruct - structure. - - The XQueryTextExtents and XQueryTextExtents16 functions return - the bounding box of the specified 8-bit and 16-bit character - string in the specified font or the font contained in the - specified GC. These functions query the X server and, - therefore, suffer the round-trip overhead that is avoided by - XTextExtents and XTextExtents16. Both functions return a - XCharStruct structure, whose members are set to the values as - follows. - - The ascent member is set to the maximum of the ascent metrics - of all characters in the string. The descent member is set to - the maximum of the descent metrics. The width member is set to - the sum of the character-width metrics of all characters in the - string. For each character in the string, let W be the sum of - the character-width metrics of all characters preceding it in - the string. Let L be the left-side-bearing metric of the - character plus W. Let R be the right-side-bearing metric of the - character plus W. The lbearing member is set to the minimum L - of all characters in the string. The rbearing member is set to - the maximum R. - - For fonts defined with linear indexing rather than 2-byte - matrix indexing, each XChar2b structure is interpreted as a - 16-bit number with byte1 as the most significant byte. If the - font has no defined default character, undefined characters in - the string are taken to have all zero metrics. - - Characters with all zero metrics are ignored. If the font has - no defined default_char, the undefined characters in the string - are also ignored. - - XQueryTextExtents and XQueryTextExtents16 can generate BadFont - and BadGC errors. - -Drawing Text - - This section discusses how to draw: - * Complex text - * Text characters - * Image text characters - - The fundamental text functions XDrawText and XDrawText16 use - the following structures: - - - -typedef struct { - char *chars; /* pointer to string */ - int nchars; /* number of characters */ - int delta; /* delta between strings */ - Font font; /* Font to print it in, None don't change */ -} XTextItem; - - - -typedef struct { - XChar2b *chars; /* pointer to two-byte characters */ - int nchars; /* number of characters */ - int delta; /* delta between strings */ - Font font; /* font to print it in, None don't change */ -} XTextItem16; - - If the font member is not None, the font is changed before - printing and also is stored in the GC. If an error was - generated during text drawing, the previous items may have been - drawn. The baseline of the characters are drawn starting at the - x and y coordinates that you pass in the text drawing - functions. - - For example, consider the background rectangle drawn by - XDrawImageString. If you want the upper-left corner of the - background rectangle to be at pixel coordinate (x,y), pass the - (x,y + ascent) as the baseline origin coordinates to the text - functions. The ascent is the font ascent, as given in the - XFontStruct structure. If you want the lower-left corner of the - background rectangle to be at pixel coordinate (x,y), pass the - (x,y - descent + 1) as the baseline origin coordinates to the - text functions. The descent is the font descent, as given in - the XFontStruct structure. - -Drawing Complex Text - - To draw 8-bit characters in a given drawable, use XDrawText. - - XDrawText(Display *display, Drawable d, GC gc, int x, int y, - XTextItem *items, int nitems); - - display - - Specifies the connection to the X server. - - d - - Specifies the drawable. - - gc - - Specifies the GC. - - x - - y - - Specify the x and y coordinates, which are relative to the - origin of the specified drawable and define the origin of the - first character. - - items - - Specifies an array of text items. - - nitems - - Specifies the number of text items in the array. - - To draw 2-byte characters in a given drawable, use XDrawText16. - - XDrawText16(Display *display, Drawable d, GC gc, int x, int y, - XTextItem16 *items, int nitems); - - display - - Specifies the connection to the X server. - - d - - Specifies the drawable. - - gc - - Specifies the GC. - - x - - y - - Specify the x and y coordinates, which are relative to the - origin of the specified drawable and define the origin of the - first character. - - items - - Specifies an array of text items. - - nitems - - Specifies the number of text items in the array. - - The XDrawText16 function is similar to XDrawText except that it - uses 2-byte or 16-bit characters. Both functions allow complex - spacing and font shifts between counted strings. - - Each text item is processed in turn. A font member other than - None in an item causes the font to be stored in the GC and used - for subsequent text. A text element delta specifies an - additional change in the position along the x axis before the - string is drawn. The delta is always added to the character - origin and is not dependent on any characteristics of the font. - Each character image, as defined by the font in the GC, is - treated as an additional mask for a fill operation on the - drawable. The drawable is modified only where the font - character has a bit set to 1. If a text item generates a - BadFont error, the previous text items may have been drawn. - - For fonts defined with linear indexing rather than 2-byte - matrix indexing, each XChar2b structure is interpreted as a - 16-bit number with byte1 as the most significant byte. - - Both functions use these GC components: function, plane-mask, - fill-style, font, subwindow-mode, clip-x-origin, clip-y-origin, - and clip-mask. They also use these GC mode-dependent - components: foreground, background, tile, stipple, - tile-stipple-x-origin, and tile-stipple-y-origin. - - XDrawText and XDrawText16 can generate BadDrawable, BadFont, - BadGC, and BadMatch errors. - -Drawing Text Characters - - To draw 8-bit characters in a given drawable, use XDrawString. - - XDrawString(Display *display, Drawable d, GC gc, int x, int y, - char *string, int length); - - display - - Specifies the connection to the X server. - - d - - Specifies the drawable. - - gc - - Specifies the GC. - - x - - y - - Specify the x and y coordinates, which are relative to the - origin of the specified drawable and define the origin of the - first character. - - string - - Specifies the character string. - - length - - Specifies the number of characters in the string argument. - - To draw 2-byte characters in a given drawable, use - XDrawString16. - - XDrawString16(Display *display, Drawable d, GC gc, int x, int - y, XChar2b *string, int length); - - display - - Specifies the connection to the X server. - - d - - Specifies the drawable. - - gc - - Specifies the GC. - - x - - y - - Specify the x and y coordinates, which are relative to the - origin of the specified drawable and define the origin of the - first character. - - string - - Specifies the character string. - - length - - Specifies the number of characters in the string argument. - - Each character image, as defined by the font in the GC, is - treated as an additional mask for a fill operation on the - drawable. The drawable is modified only where the font - character has a bit set to 1. For fonts defined with 2-byte - matrix indexing and used with XDrawString16, each byte is used - as a byte2 with a byte1 of zero. - - Both functions use these GC components: function, plane-mask, - fill-style, font, subwindow-mode, clip-x-origin, clip-y-origin, - and clip-mask. They also use these GC mode-dependent - components: foreground, background, tile, stipple, - tile-stipple-x-origin, and tile-stipple-y-origin. - - XDrawString and XDrawString16 can generate BadDrawable, BadGC, - and BadMatch errors. - -Drawing Image Text Characters - - Some applications, in particular terminal emulators, need to - print image text in which both the foreground and background - bits of each character are painted. This prevents annoying - flicker on many displays. - - To draw 8-bit image text characters in a given drawable, use - XDrawImageString. - - XDrawImageString(Display *display, Drawable d, GC gc, int x, - int y, char *string, int length); - - display - - Specifies the connection to the X server. - - d - - Specifies the drawable. - - gc - - Specifies the GC. - - x - - y - - Specify the x and y coordinates, which are relative to the - origin of the specified drawable and define the origin of the - first character. - - string - - Specifies the character string. - - length - - Specifies the number of characters in the string argument. - - To draw 2-byte image text characters in a given drawable, use - XDrawImageString16. - - XDrawImageString16(Display *display, Drawable d, GC gc, int x, - int y, XChar2b *string, int length); - - display - - Specifies the connection to the X server. - - d - - Specifies the drawable. - - gc - - Specifies the GC. - - x - - y - - Specify the x and y coordinates, which are relative to the - origin of the specified drawable and define the origin of the - first character. - - string - - Specifies the character string. - - length - - Specifies the number of characters in the string argument. - - The XDrawImageString16 function is similar to XDrawImageString - except that it uses 2-byte or 16-bit characters. Both functions - also use both the foreground and background pixels of the GC in - the destination. - - The effect is first to fill a destination rectangle with the - background pixel defined in the GC and then to paint the text - with the foreground pixel. The upper-left corner of the filled - rectangle is at: - -[x, y - font-ascent] - - The width is: - -overall-width - - The height is: - -font-ascent + font-descent - - The overall-width, font-ascent, and font-descent are as would - be returned by XQueryTextExtents using gc and string. The - function and fill-style defined in the GC are ignored for these - functions. The effective function is GXcopy, and the effective - fill-style is FillSolid. - - For fonts defined with 2-byte matrix indexing and used with - XDrawImageString, each byte is used as a byte2 with a byte1 of - zero. - - Both functions use these GC components: plane-mask, foreground, - background, font, subwindow-mode, clip-x-origin, clip-y-origin, - and clip-mask. - - XDrawImageString and XDrawImageString16 can generate - BadDrawable, BadGC, and BadMatch errors. - -Transferring Images between Client and Server - - Xlib provides functions that you can use to transfer images - between a client and the server. Because the server may require - diverse data formats, Xlib provides an image object that fully - describes the data in memory and that provides for basic - operations on that data. You should reference the data through - the image object rather than referencing the data directly. - However, some implementations of the Xlib library may - efficiently deal with frequently used data formats by replacing - functions in the procedure vector with special case functions. - Supported operations include destroying the image, getting a - pixel, storing a pixel, extracting a subimage of an image, and - adding a constant to an image (see section 16.8). - - All the image manipulation functions discussed in this section - make use of the XImage structure, which describes an image as - it exists in the client's memory. - - - -typedef struct _XImage { - int width, height; /* size of image */ - int xoffset; /* number of pixels offset in X directio -n */ - int format; /* XYBitmap, XYPixmap, ZPixmap */ - char *data; /* pointer to image data */ - int byte_order; /* data byte order, LSBFirst, MSBFirst * -/ - int bitmap_unit; /* quant. of scanline 8, 16, 32 */ - int bitmap_bit_order; /* LSBFirst, MSBFirst */ - int bitmap_pad; /* 8, 16, 32 either XY or ZPixmap */ - int depth; /* depth of image */ - int bytes_per_line; /* accelerator to next scanline */ - int bits_per_pixel; /* bits per pixel (ZPixmap) */ - unsigned long red_mask; /* bits in z arrangement */ - unsigned long green_mask; - unsigned long blue_mask; - XPointer obdata; /* hook for the object routines to hang -on */ - struct funcs { /* image manipulation routines */ - struct _XImage *(*create_image)(); - int (*destroy_image)(); - unsigned long (*get_pixel)(); - int (*put_pixel)(); - struct _XImage *(*sub_image)(); - int (*add_pixel)(); - } f; -} XImage; - - To initialize the image manipulation routines of an image - structure, use XInitImage. - - Status XInitImage(XImage *image); - - ximage - - Specifies the image. - - The XInitImage function initializes the internal image - manipulation routines of an image structure, based on the - values of the various structure members. All fields other than - the manipulation routines must already be initialized. If the - bytes_per_line member is zero, XInitImage will assume the image - data is contiguous in memory and set the bytes_per_line member - to an appropriate value based on the other members; otherwise, - the value of bytes_per_line is not changed. All of the - manipulation routines are initialized to functions that other - Xlib image manipulation functions need to operate on the type - of image specified by the rest of the structure. - - This function must be called for any image constructed by the - client before passing it to any other Xlib function. Image - structures created or returned by Xlib do not need to be - initialized in this fashion. - - This function returns a nonzero status if initialization of the - structure is successful. It returns zero if it detected some - error or inconsistency in the structure, in which case the - image is not changed. - - To combine an image with a rectangle of a drawable on the - display, use XPutImage. - - XPutImage(Display *display, Drawable d, GC gc, XImage *image, - int src_x, int src_y, int dest_x, int dest_y, unsigned int - width, unsigned int height); - - display - - Specifies the connection to the X server. - - d - - Specifies the drawable. - - gc - - Specifies the GC. - - image - - Specifies the image you want combined with the rectangle. - - src_x - - Specifies the offset in X from the left edge of the image - defined by the XImage structure. - - src_y - - Specifies the offset in Y from the top edge of the image - defined by the XImage structure. - - dest_x - - dest_y - - Specify the x and y coordinates, which are relative to the - origin of the drawable and are the coordinates of the subimage. - - width - - height - - Specify the width and height of the subimage, which define the - dimensions of the rectangle. - - The XPutImage function combines an image with a rectangle of - the specified drawable. The section of the image defined by the - src_x, src_y, width, and height arguments is drawn on the - specified part of the drawable. If XYBitmap format is used, the - depth of the image must be one, or a BadMatch error results. - The foreground pixel in the GC defines the source for the one - bits in the image, and the background pixel defines the source - for the zero bits. For XYPixmap and ZPixmap, the depth of the - image must match the depth of the drawable, or a BadMatch error - results. - - If the characteristics of the image (for example, byte_order - and bitmap_unit) differ from what the server requires, - XPutImage automatically makes the appropriate conversions. - - This function uses these GC components: function, plane-mask, - subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. It - also uses these GC mode-dependent components: foreground and - background. - - XPutImage can generate BadDrawable, BadGC, BadMatch, and - BadValue errors. - - To return the contents of a rectangle in a given drawable on - the display, use XGetImage. This function specifically supports - rudimentary screen dumps. - - XImage *XGetImage(Display *display, Drawable d, int x, int y, - unsigned int width, unsigned int height, unsigned long - plane_mask, int format); - - display - - Specifies the connection to the X server. - - d - - Specifies the drawable. - - x - - y - - Specify the x and y coordinates, which are relative to the - origin of the drawable and define the upper-left corner of the - rectangle. - - width - - height - - Specify the width and height of the subimage, which define the - dimensions of the rectangle. - - plane_mask - - Specifies the plane mask. - - format - - Specifies the format for the image. You can pass XYPixmap or - ZPixmap. - - The XGetImage function returns a pointer to an XImage - structure. This structure provides you with the contents of the - specified rectangle of the drawable in the format you specify. - If the format argument is XYPixmap, the image contains only the - bit planes you passed to the plane_mask argument. If the - plane_mask argument only requests a subset of the planes of the - display, the depth of the returned image will be the number of - planes requested. If the format argument is ZPixmap, XGetImage - returns as zero the bits in all planes not specified in the - plane_mask argument. The function performs no range checking on - the values in plane_mask and ignores extraneous bits. - - XGetImage returns the depth of the image to the depth member of - the XImage structure. The depth of the image is as specified - when the drawable was created, except when getting a subset of - the planes in XYPixmap format, when the depth is given by the - number of bits set to 1 in plane_mask. - - If the drawable is a pixmap, the given rectangle must be wholly - contained within the pixmap, or a BadMatch error results. If - the drawable is a window, the window must be viewable, and it - must be the case that if there were no inferiors or overlapping - windows, the specified rectangle of the window would be fully - visible on the screen and wholly contained within the outside - edges of the window, or a BadMatch error results. Note that the - borders of the window can be included and read with this - request. If the window has backing-store, the backing-store - contents are returned for regions of the window that are - obscured by noninferior windows. If the window does not have - backing-store, the returned contents of such obscured regions - are undefined. The returned contents of visible regions of - inferiors of a different depth than the specified window's - depth are also undefined. The pointer cursor image is not - included in the returned contents. If a problem occurs, - XGetImage returns NULL. - - XGetImage can generate BadDrawable, BadMatch, and BadValue - errors. - - To copy the contents of a rectangle on the display to a - location within a preexisting image structure, use - XGetSubImage. - - XImage *XGetSubImage(Display *display, Drawable d, int x, int - y, unsigned int width, unsigned int height, unsigned long - plane_mask, int format, XImage *dest_image, int dest_x, int - dest_y); - - display - - Specifies the connection to the X server. - - d - - Specifies the drawable. - - x - - y - - Specify the x and y coordinates, which are relative to the - origin of the drawable and define the upper-left corner of the - rectangle. - - width - - height - - Specify the width and height of the subimage, which define the - dimensions of the rectangle. - - plane_mask - - Specifies the plane mask. - - format - - Specifies the format for the image. You can pass XYPixmap or - ZPixmap. - - dest_image - - Specifies the destination image. - - dest_x - - dest_y - - Specify the x and y coordinates, which are relative to the - origin of the destination rectangle, specify its upper-left - corner, and determine where the subimage is placed in the - destination image. - - The XGetSubImage function updates dest_image with the specified - subimage in the same manner as XGetImage. If the format - argument is XYPixmap, the image contains only the bit planes - you passed to the plane_mask argument. If the format argument - is ZPixmap, XGetSubImage returns as zero the bits in all planes - not specified in the plane_mask argument. The function performs - no range checking on the values in plane_mask and ignores - extraneous bits. As a convenience, XGetSubImage returns a - pointer to the same XImage structure specified by dest_image. - - The depth of the destination XImage structure must be the same - as that of the drawable. If the specified subimage does not fit - at the specified location on the destination image, the right - and bottom edges are clipped. If the drawable is a pixmap, the - given rectangle must be wholly contained within the pixmap, or - a BadMatch error results. If the drawable is a window, the - window must be viewable, and it must be the case that if there - were no inferiors or overlapping windows, the specified - rectangle of the window would be fully visible on the screen - and wholly contained within the outside edges of the window, or - a BadMatch error results. If the window has backing-store, then - the backing-store contents are returned for regions of the - window that are obscured by noninferior windows. If the window - does not have backing-store, the returned contents of such - obscured regions are undefined. The returned contents of - visible regions of inferiors of a different depth than the - specified window's depth are also undefined. If a problem - occurs, XGetSubImage returns NULL. - - XGetSubImage can generate BadDrawable, BadGC, BadMatch, and - BadValue errors. - -Chapter 9. Window and Session Manager Functions - - Table of Contents - - Changing the Parent of a Window - Controlling the Lifetime of a Window - Managing Installed Colormaps - Setting and Retrieving the Font Search Path - Grabbing the Server - Killing Clients - Controlling the Screen Saver - Controlling Host Access - - Adding, Getting, or Removing Hosts - Changing, Enabling, or Disabling Access Control - - Although it is difficult to categorize functions as exclusively - for an application, a window manager, or a session manager, the - functions in this chapter are most often used by window - managers and session managers. It is not expected that these - functions will be used by most application programs. Xlib - provides management functions to: - * Change the parent of a window - * Control the lifetime of a window - * Manage installed colormaps - * Set and retrieve the font search path - * Grab the server - * Kill a client - * Control the screen saver - * Control host access - -Changing the Parent of a Window - - To change a window's parent to another window on the same - screen, use XReparentWindow. There is no way to move a window - between screens. - - XReparentWindow(Display *display, Window w, Window parent, int - x, int y); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - parent - - Specifies the parent window. - - x - - y - - Specify the x and y coordinates of the position in the new - parent window. - - If the specified window is mapped, XReparentWindow - automatically performs an UnmapWindow request on it, removes it - from its current position in the hierarchy, and inserts it as - the child of the specified parent. The window is placed in the - stacking order on top with respect to sibling windows. - - After reparenting the specified window, XReparentWindow causes - the X server to generate a ReparentNotify event. The - override_redirect member returned in this event is set to the - window's corresponding attribute. Window manager clients - usually should ignore this window if this member is set to - True. Finally, if the specified window was originally mapped, - the X server automatically performs a MapWindow request on it. - - The X server performs normal exposure processing on formerly - obscured windows. The X server might not generate Expose events - for regions from the initial UnmapWindow request that are - immediately obscured by the final MapWindow request. A BadMatch - error results if: - * The new parent window is not on the same screen as the old - parent window. - * The new parent window is the specified window or an - inferior of the specified window. - * The new parent is InputOnly, and the window is not. - * The specified window has a ParentRelative background, and - the new parent window is not the same depth as the - specified window. - - XReparentWindow can generate BadMatch and BadWindow errors. - -Controlling the Lifetime of a Window - - The save-set of a client is a list of other clients' windows - that, if they are inferiors of one of the client's windows at - connection close, should not be destroyed and should be - remapped if they are unmapped. For further information about - close-connection processing, see section 2.6. To allow an - application's window to survive when a window manager that has - reparented a window fails, Xlib provides the save-set functions - that you can use to control the longevity of subwindows that - are normally destroyed when the parent is destroyed. For - example, a window manager that wants to add decoration to a - window by adding a frame might reparent an application's - window. When the frame is destroyed, the application's window - should not be destroyed but be returned to its previous place - in the window hierarchy. - - The X server automatically removes windows from the save-set - when they are destroyed. - - To add or remove a window from the client's save-set, use - XChangeSaveSet. - - XChangeSaveSet(Display *display, Window w, int change_mode); - - display - - Specifies the connection to the X server. - - w - - Specifies the window that you want to add to or delete from the - client's save-set. - - change_mode - - Specifies the mode. You can pass SetModeInsert or - SetModeDelete. - - Depending on the specified mode, XChangeSaveSet either inserts - or deletes the specified window from the client's save-set. The - specified window must have been created by some other client, - or a BadMatch error results. - - XChangeSaveSet can generate BadMatch, BadValue, and BadWindow - errors. - - To add a window to the client's save-set, use XAddToSaveSet. - - XAddToSaveSet(Display *display, Window w); - - display - - Specifies the connection to the X server. - - w - - Specifies the window that you want to add to the client's - save-set. - - The XAddToSaveSet function adds the specified window to the - client's save-set. The specified window must have been created - by some other client, or a BadMatch error results. - - XAddToSaveSet can generate BadMatch and BadWindow errors. - - To remove a window from the client's save-set, use - XRemoveFromSaveSet. - - XRemoveFromSaveSet(Display *display, Window w); - - display - - Specifies the connection to the X server. - - w - - Specifies the window that you want to delete from the client's - save-set. - - The XRemoveFromSaveSet function removes the specified window - from the client's save-set. The specified window must have been - created by some other client, or a BadMatch error results. - - XRemoveFromSaveSet can generate BadMatch and BadWindow errors. - -Managing Installed Colormaps - - The X server maintains a list of installed colormaps. Windows - using these colormaps are guaranteed to display with correct - colors; windows using other colormaps may or may not display - with correct colors. Xlib provides functions that you can use - to install a colormap, uninstall a colormap, and obtain a list - of installed colormaps. - - At any time, there is a subset of the installed maps that is - viewed as an ordered list and is called the required list. The - length of the required list is at most M, where M is the - minimum number of installed colormaps specified for the screen - in the connection setup. The required list is maintained as - follows. When a colormap is specified to XInstallColormap, it - is added to the head of the list; the list is truncated at the - tail, if necessary, to keep its length to at most M. When a - colormap is specified to XUninstallColormap and it is in the - required list, it is removed from the list. A colormap is not - added to the required list when it is implicitly installed by - the X server, and the X server cannot implicitly uninstall a - colormap that is in the required list. - - To install a colormap, use XInstallColormap. - - XInstallColormap(Display *display, Colormap colormap); - - display - - Specifies the connection to the X server. - - colormap - - Specifies the colormap. - - The XInstallColormap function installs the specified colormap - for its associated screen. All windows associated with this - colormap immediately display with true colors. You associated - the windows with this colormap when you created them by calling - XCreateWindow, XCreateSimpleWindow, XChangeWindowAttributes, or - XSetWindowColormap. - - If the specified colormap is not already an installed colormap, - the X server generates a ColormapNotify event on each window - that has that colormap. In addition, for every other colormap - that is installed as a result of a call to XInstallColormap, - the X server generates a ColormapNotify event on each window - that has that colormap. - - XInstallColormap can generate a BadColor error. - - To uninstall a colormap, use XUninstallColormap. - - XUninstallColormap(Display *display, Colormap colormap); - - display - - Specifies the connection to the X server. - - colormap - - Specifies the colormap. - - The XUninstallColormap function removes the specified colormap - from the required list for its screen. As a result, the - specified colormap might be uninstalled, and the X server might - implicitly install or uninstall additional colormaps. Which - colormaps get installed or uninstalled is server dependent - except that the required list must remain installed. - - If the specified colormap becomes uninstalled, the X server - generates a ColormapNotify event on each window that has that - colormap. In addition, for every other colormap that is - installed or uninstalled as a result of a call to - XUninstallColormap, the X server generates a ColormapNotify - event on each window that has that colormap. - - XUninstallColormap can generate a BadColor error. - - To obtain a list of the currently installed colormaps for a - given screen, use XListInstalledColormaps. - - Colormap *XListInstalledColormaps(Display *display, Window w, - int *num_return); - - display - - Specifies the connection to the X server. - - w - - Specifies the window that determines the screen. - - num_return - - Returns the number of currently installed colormaps. - - The XListInstalledColormaps function returns a list of the - currently installed colormaps for the screen of the specified - window. The order of the colormaps in the list is not - significant and is no explicit indication of the required list. - When the allocated list is no longer needed, free it by using - XFree. - - XListInstalledColormaps can generate a BadWindow error. - -Setting and Retrieving the Font Search Path - - The set of fonts available from a server depends on a font - search path. Xlib provides functions to set and retrieve the - search path for a server. - - To set the font search path, use XSetFontPath. - - XSetFontPath(Display *display, char **directories, int ndirs); - - display - - Specifies the connection to the X server. - - directories - - Specifies the directory path used to look for a font. Setting - the path to the empty list restores the default path defined - for the X server. - - ndirs - - Specifies the number of directories in the path. - - The XSetFontPath function defines the directory search path for - font lookup. There is only one search path per X server, not - one per client. The encoding and interpretation of the strings - are implementation-dependent, but typically they specify - directories or font servers to be searched in the order listed. - An X server is permitted to cache font information internally; - for example, it might cache an entire font from a file and not - check on subsequent opens of that font to see if the underlying - font file has changed. However, when the font path is changed, - the X server is guaranteed to flush all cached information - about fonts for which there currently are no explicit resource - IDs allocated. The meaning of an error from this request is - implementation-dependent. - - XSetFontPath can generate a BadValue error. - - To get the current font search path, use XGetFontPath. - - char **XGetFontPath(Display *display, int *npaths_return); - - display - - Specifies the connection to the X server. - - npaths_return - - Returns the number of strings in the font path array. - - The XGetFontPath function allocates and returns an array of - strings containing the search path. The contents of these - strings are implementation-dependent and are not intended to be - interpreted by client applications. When it is no longer - needed, the data in the font path should be freed by using - XFreeFontPath. - - To free data returned by XGetFontPath, use XFreeFontPath. - - XFreeFontPath(char **list); - - list - - Specifies the array of strings you want to free. - - The XFreeFontPath function frees the data allocated by - XGetFontPath. - -Grabbing the Server - - Xlib provides functions that you can use to grab and ungrab the - server. These functions can be used to control processing of - output on other connections by the window system server. While - the server is grabbed, no processing of requests or close downs - on any other connection will occur. A client closing its - connection automatically ungrabs the server. Although grabbing - the server is highly discouraged, it is sometimes necessary. - - To grab the server, use XGrabServer. - - XGrabServer(Display *display); - - display - - Specifies the connection to the X server. - - The XGrabServer function disables processing of requests and - close downs on all other connections than the one this request - arrived on. You should not grab the X server any more than is - absolutely necessary. - - To ungrab the server, use XUngrabServer. - - XUngrabServer(Display *display); - - display - - Specifies the connection to the X server. - - The XUngrabServer function restarts processing of requests and - close downs on other connections. You should avoid grabbing the - X server as much as possible. - -Killing Clients - - Xlib provides a function to cause the connection to a client to - be closed and its resources to be destroyed. To destroy a - client, use XKillClient. - - XKillClient(Display *display, XID resource); - - display - - Specifies the connection to the X server. - - resource - - Specifies any resource associated with the client that you want - to destroy or AllTemporary. - - The XKillClient function forces a close down of the client that - created the resource if a valid resource is specified. If the - client has already terminated in either RetainPermanent or - RetainTemporary mode, all of the client's resources are - destroyed. If AllTemporary is specified, the resources of all - clients that have terminated in RetainTemporary are destroyed - (see section 2.5). This permits implementation of window - manager facilities that aid debugging. A client can set its - close-down mode to RetainTemporary. If the client then crashes, - its windows would not be destroyed. The programmer can then - inspect the application's window tree and use the window - manager to destroy the zombie windows. - - XKillClient can generate a BadValue error. - -Controlling the Screen Saver - - Xlib provides functions that you can use to set or reset the - mode of the screen saver, to force or activate the screen - saver, or to obtain the current screen saver values. - - To set the screen saver mode, use XSetScreenSaver. - - XSetScreenSaver(Display *display, int timeout, int interval, - int prefer_blanking, int allow_exposures); - - display - - Specifies the connection to the X server. - - timeout - - Specifies the timeout, in seconds, until the screen saver turns - on. - - interval - - Specifies the interval, in seconds, between screen saver - alterations. - - prefer_blanking - - Specifies how to enable screen blanking. You can pass - DontPreferBlanking, PreferBlanking, or DefaultBlanking. - - allow_exposures - - Specifies the screen save control values. You can pass - DontAllowExposures, AllowExposures, or DefaultExposures. - - Timeout and interval are specified in seconds. A timeout of 0 - disables the screen saver (but an activated screen saver is not - deactivated), and a timeout of -1 restores the default. Other - negative values generate a BadValue error. If the timeout value - is nonzero, XSetScreenSaver enables the screen saver. An - interval of 0 disables the random-pattern motion. If no input - from devices (keyboard, mouse, and so on) is generated for the - specified number of timeout seconds once the screen saver is - enabled, the screen saver is activated. - - For each screen, if blanking is preferred and the hardware - supports video blanking, the screen simply goes blank. - Otherwise, if either exposures are allowed or the screen can be - regenerated without sending Expose events to clients, the - screen is tiled with the root window background tile randomly - re-origined each interval seconds. Otherwise, the screens' - state do not change, and the screen saver is not activated. The - screen saver is deactivated, and all screen states are restored - at the next keyboard or pointer input or at the next call to - XForceScreenSaver with mode ScreenSaverReset. - - If the server-dependent screen saver method supports periodic - change, the interval argument serves as a hint about how long - the change period should be, and zero hints that no periodic - change should be made. Examples of ways to change the screen - include scrambling the colormap periodically, moving an icon - image around the screen periodically, or tiling the screen with - the root window background tile, randomly re-origined - periodically. - - XSetScreenSaver can generate a BadValue error. - - To force the screen saver on or off, use XForceScreenSaver. - - XForceScreenSaver(Display *display, int mode); - - display - - Specifies the connection to the X server. - - mode - - Specifies the mode that is to be applied. You can pass - ScreenSaverActive or ScreenSaverReset. - - If the specified mode is ScreenSaverActive and the screen saver - currently is deactivated, XForceScreenSaver activates the - screen saver even if the screen saver had been disabled with a - timeout of zero. If the specified mode is ScreenSaverReset and - the screen saver currently is enabled, XForceScreenSaver - deactivates the screen saver if it was activated, and the - activation timer is reset to its initial state (as if device - input had been received). - - XForceScreenSaver can generate a BadValue error. - - To activate the screen saver, use XActivateScreenSaver. - - XActivateScreenSaver(Display *display); - - display - - Specifies the connection to the X server. - - To reset the screen saver, use XResetScreenSaver. - - XResetScreenSaver(Display *display); - - display - - Specifies the connection to the X server. - - To get the current screen saver values, use XGetScreenSaver. - - XGetScreenSaver(Display *display, int *timeout_return, int - *interval_return, int *prefer_blanking_return, int - *allow_exposures_return); - - display - - Specifies the connection to the X server. - - timeout_return - - Returns the timeout, in seconds, until the screen saver turns - on. - - interval_return - - Returns the interval between screen saver invocations. - - prefer_blanking_return - - Returns the current screen blanking preference - (DontPreferBlanking, PreferBlanking, or DefaultBlanking). - - allow_exposures_return - - Returns the current screen save control value - (DontAllowExposures, AllowExposures, or DefaultExposures). - -Controlling Host Access - - This section discusses how to: - * Add, get, or remove hosts from the access control list - * Change, enable, or disable access - - X does not provide any protection on a per-window basis. If you - find out the resource ID of a resource, you can manipulate it. - To provide some minimal level of protection, however, - connections are permitted only from machines you trust. This is - adequate on single-user workstations but obviously breaks down - on timesharing machines. Although provisions exist in the X - protocol for proper connection authentication, the lack of a - standard authentication server leaves host-level access control - as the only common mechanism. - - The initial set of hosts allowed to open connections typically - consists of: - * The host the window system is running on. - * On POSIX-conformant systems, each host listed in the - /etc/X?.hosts file. The ? indicates the number of the - display. This file should consist of host names separated - by newlines. DECnet nodes must terminate in :: to - distinguish them from Internet hosts. - - If a host is not in the access control list when the access - control mechanism is enabled and if the host attempts to - establish a connection, the server refuses the connection. To - change the access list, the client must reside on the same host - as the server and/or must have been granted permission in the - initial authorization at connection setup. - - Servers also can implement other access control policies in - addition to or in place of this host access facility. For - further information about other access control implementations, - see X Window System Protocol. - -Adding, Getting, or Removing Hosts - - Xlib provides functions that you can use to add, get, or remove - hosts from the access control list. All the host access control - functions use the XHostAddress structure, which contains: - - - -typedef struct { - int family; /* for example FamilyInternet */ - int length; /* length of address, in bytes */ - char *address; /* pointer to where to find the address */ -} XHostAddress; - - The family member specifies which protocol address family to - use (for example, TCP/IP or DECnet) and can be FamilyInternet, - FamilyInternet6, FamilyServerInterpreted, FamilyDECnet, or - FamilyChaos. The length member specifies the length of the - address in bytes. The address member specifies a pointer to the - address. - - For TCP/IP, the address should be in network byte order. For IP - version 4 addresses, the family should be FamilyInternet and - the length should be 4 bytes. For IP version 6 addresses, the - family should be FamilyInternet6 and the length should be 16 - bytes. - - For the DECnet family, the server performs no automatic - swapping on the address bytes. A Phase IV address is 2 bytes - long. The first byte contains the least significant 8 bits of - the node number. The second byte contains the most significant - 2 bits of the node number in the least significant 2 bits of - the byte and the area in the most significant 6 bits of the - byte. - - For the ServerInterpreted family, the length is ignored and the - address member is a pointer to a XServerInterpretedAddress - structure, which contains: - - - -typedef struct { - int typelength; /* length of type string, in bytes */ - int valuelength; /* length of value string, in bytes */ - char *type; /* pointer to where to find the type string */ - char *value; /* pointer to where to find the address */ -} XServerInterpretedAddress; - - The type and value members point to strings representing the - type and value of the server interpreted entry. These strings - may not be NULL-terminated so care should be used when - accessing them. The typelength and valuelength members specify - the length in byte of the type and value strings. - - To add a single host, use XAddHost. - - XAddHost(Display *display, XHostAddress *host); - - display - - Specifies the connection to the X server. - - host - - Specifies the host that is to be added. - - The XAddHost function adds the specified host to the access - control list for that display. The server must be on the same - host as the client issuing the command, or a BadAccess error - results. - - XAddHost can generate BadAccess and BadValue errors. - - To add multiple hosts at one time, use XAddHosts. - - XAddHosts(Display *display, XHostAddress *hosts, int - num_hosts); - - display - - Specifies the connection to the X server. - - hosts - - Specifies each host that is to be added. - - num_hosts - - Specifies the number of hosts. - - The XAddHosts function adds each specified host to the access - control list for that display. The server must be on the same - host as the client issuing the command, or a BadAccess error - results. - - XAddHosts can generate BadAccess and BadValue errors. - - To obtain a host list, use XListHosts. - - XHostAddress *XListHosts(Display *display, int *nhosts_return, - Bool *state_return); - - display - - Specifies the connection to the X server. - - nhosts_return - - Returns the number of hosts currently in the access control - list. - - state_return - - Returns the state of the access control. - - The XListHosts function returns the current access control list - as well as whether the use of the list at connection setup was - enabled or disabled. XListHosts allows a program to find out - what machines can make connections. It also returns a pointer - to a list of host structures that were allocated by the - function. When no longer needed, this memory should be freed by - calling XFree. - - To remove a single host, use XRemoveHost. - - XRemoveHost(Display *display, XHostAddress *host); - - display - - Specifies the connection to the X server. - - host - - Specifies the host that is to be removed. - - The XRemoveHost function removes the specified host from the - access control list for that display. The server must be on the - same host as the client process, or a BadAccess error results. - If you remove your machine from the access list, you can no - longer connect to that server, and this operation cannot be - reversed unless you reset the server. - - XRemoveHost can generate BadAccess and BadValue errors. - - To remove multiple hosts at one time, use XRemoveHosts. - - XRemoveHosts(Display *display, XHostAddress *hosts, int - num_hosts); - - display - - Specifies the connection to the X server. - - hosts - - Specifies each host that is to be removed. - - num_hosts - - Specifies the number of hosts. - - The XRemoveHosts function removes each specified host from the - access control list for that display. The X server must be on - the same host as the client process, or a BadAccess error - results. If you remove your machine from the access list, you - can no longer connect to that server, and this operation cannot - be reversed unless you reset the server. - - XRemoveHosts can generate BadAccess and BadValue errors. - -Changing, Enabling, or Disabling Access Control - - Xlib provides functions that you can use to enable, disable, or - change access control. - - For these functions to execute successfully, the client - application must reside on the same host as the X server and/or - have been given permission in the initial authorization at - connection setup. - - To change access control, use XSetAccessControl. - - XSetAccessControl(Display *display, int mode); - - display - - Specifies the connection to the X server. - - mode - - Specifies the mode. You can pass EnableAccess or DisableAccess. - - The XSetAccessControl function either enables or disables the - use of the access control list at each connection setup. - - XSetAccessControl can generate BadAccess and BadValue errors. - - To enable access control, use XEnableAccessControl. - - XEnableAccessControl(Display *display); - - display - - Specifies the connection to the X server. - - The XEnableAccessControl function enables the use of the access - control list at each connection setup. - - XEnableAccessControl can generate a BadAccess error. - - To disable access control, use XDisableAccessControl. - - XDisableAccessControl(Display *display); - - display - - Specifies the connection to the X server. - - The XDisableAccessControl function disables the use of the - access control list at each connection setup. - - XDisableAccessControl can generate a BadAccess error. - -Chapter 10. Events - - Table of Contents - - Event Types - Event Structures - Event Masks - Event Processing Overview - Keyboard and Pointer Events - - Pointer Button Events - Keyboard and Pointer Events - - Window Entry/Exit Events - - Normal Entry/Exit Events - Grab and Ungrab Entry/Exit Events - - Input Focus Events - - Normal Focus Events and Focus Events While Grabbed - Focus Events Generated by Grabs - - Key Map State Notification Events - Exposure Events - - Expose Events - GraphicsExpose and NoExpose Events - - Window State Change Events - - CirculateNotify Events - ConfigureNotify Events - CreateNotify Events - DestroyNotify Events - GravityNotify Events - MapNotify Events - MappingNotify Events - ReparentNotify Events - UnmapNotify Events - VisibilityNotify Events - - Structure Control Events - - CirculateRequest Events - ConfigureRequest Events - MapRequest Events - ResizeRequest Events - - Colormap State Change Events - Client Communication Events - - ClientMessage Events - PropertyNotify Events - SelectionClear Events - SelectionRequest Events - SelectionNotify Events - - A client application communicates with the X server through the - connection you establish with the XOpenDisplay function. A - client application sends requests to the X server over this - connection. These requests are made by the Xlib functions that - are called in the client application. Many Xlib functions cause - the X server to generate events, and the user's typing or - moving the pointer can generate events asynchronously. The X - server returns events to the client on the same connection. - - This chapter discusses the following topics associated with - events: - * Event types - * Event structures - * Event masks - * Event processing - - Functions for handling events are dealt with in the next - chapter. - -Event Types - - An event is data generated asynchronously by the X server as a - result of some device activity or as side effects of a request - sent by an Xlib function. Device-related events propagate from - the source window to ancestor windows until some client - application has selected that event type or until the event is - explicitly discarded. The X server generally sends an event to - a client application only if the client has specifically asked - to be informed of that event type, typically by setting the - event-mask attribute of the window. The mask can also be set - when you create a window or by changing the window's - event-mask. You can also mask out events that would propagate - to ancestor windows by manipulating the do-not-propagate mask - of the window's attributes. However, MappingNotify events are - always sent to all clients. - - An event type describes a specific event generated by the X - server. For each event type, a corresponding constant name is - defined in , which is used when referring to an event - type. The following table lists the event category and its - associated event type or types. The processing associated with - these events is discussed in section 10.5. - - Event Category Event Type - Keyboard events KeyPress, KeyRelease - Pointer events ButtonPress, ButtonRelease, MotionNotify - Window crossing events EnterNotify, LeaveNotify - Input focus events FocusIn, FocusOut - Keymap state notification event KeymapNotify - Exposure events Expose, GraphicsExpose, NoExpose - Structure control events CirculateRequest, ConfigureRequest, - MapRequest, ResizeRequest - Window state notification events CirculateNotify, - ConfigureNotify, CreateNotify, DestroyNotify, GravityNotify, - MapNotify, MappingNotify, ReparentNotify, UnmapNotify, - VisibilityNotify - Colormap state notification event ColormapNotify - Client communication events ClientMessage, PropertyNotify, - SelectionClear, SelectionNotify, SelectionRequest - -Event Structures - - For each event type, a corresponding structure is declared in - . All the event structures have the following - common members: - - - -typedef struct { - int type; - unsigned long serial; /* # of last request processed by server -*/ - Bool send_event; /* true if this came from a SendEvent req -uest */ - Display *display; /* Display the event was read from */ - Window window; -} XAnyEvent; - - The type member is set to the event type constant name that - uniquely identifies it. For example, when the X server reports - a GraphicsExpose event to a client application, it sends an - XGraphicsExposeEvent structure with the type member set to - GraphicsExpose. The display member is set to a pointer to the - display the event was read on. The send_event member is set to - True if the event came from a SendEvent protocol request. The - serial member is set from the serial number reported in the - protocol but expanded from the 16-bit least-significant bits to - a full 32-bit value. The window member is set to the window - that is most useful to toolkit dispatchers. - - The X server can send events at any time in the input stream. - Xlib stores any events received while waiting for a reply in an - event queue for later use. Xlib also provides functions that - allow you to check events in the event queue (see section - 11.3). - - In addition to the individual structures declared for each - event type, the XEvent structure is a union of the individual - structures declared for each event type. Depending on the type, - you should access members of each event by using the XEvent - union. - - - -typedef union _XEvent { - int type; /* must not be change -d */ - XAnyEvent xany; - XKeyEvent xkey; - XButtonEvent xbutton; - XMotionEvent xmotion; - XCrossingEvent xcrossing; - XFocusChangeEvent xfocus; - XExposeEvent xexpose; - XGraphicsExposeEvent xgraphicsexpose; - XNoExposeEvent xnoexpose; - XVisibilityEvent xvisibility; - XCreateWindowEvent xcreatewindow; - XDestroyWindowEvent xdestroywindow; - XUnmapEvent xunmap; - XMapEvent xmap; - XMapRequestEvent xmaprequest; - XReparentEvent xreparent; - XConfigureEvent xconfigure; - XGravityEvent xgravity; - XResizeRequestEvent xresizerequest; - XConfigureRequestEvent xconfigurerequest; - XCirculateEvent xcirculate; - XCirculateRequestEvent xcirculaterequest; - XPropertyEvent xproperty; - XSelectionClearEvent xselectionclear; - XSelectionRequestEvent xselectionrequest; - XSelectionEvent xselection; - XColormapEvent xcolormap; - XClientMessageEvent xclient; - XMappingEvent xmapping; - XErrorEvent xerror; - XKeymapEvent xkeymap; - long pad[24]; -} XEvent; - - An XEvent structure's first entry always is the type member, - which is set to the event type. The second member always is the - serial number of the protocol request that generated the event. - The third member always is send_event, which is a Bool that - indicates if the event was sent by a different client. The - fourth member always is a display, which is the display that - the event was read from. Except for keymap events, the fifth - member always is a window, which has been carefully selected to - be useful to toolkit dispatchers. To avoid breaking toolkits, - the order of these first five entries is not to change. Most - events also contain a time member, which is the time at which - an event occurred. In addition, a pointer to the generic event - must be cast before it is used to access any other information - in the structure. - -Event Masks - - Clients select event reporting of most events relative to a - window. To do this, pass an event mask to an Xlib - event-handling function that takes an event_mask argument. The - bits of the event mask are defined in . Each bit in - the event mask maps to an event mask name, which describes the - event or events you want the X server to return to a client - application. - - Unless the client has specifically asked for them, most events - are not reported to clients when they are generated. Unless the - client suppresses them by setting graphics-exposures in the GC - to False, GraphicsExpose and NoExpose are reported by default - as a result of XCopyPlane and XCopyArea. SelectionClear, - SelectionRequest, SelectionNotify, or ClientMessage cannot be - masked. Selection-related events are only sent to clients - cooperating with selections (see section 4.5). When the - keyboard or pointer mapping is changed, MappingNotify is always - sent to clients. - - The following table lists the event mask constants you can pass - to the event_mask argument and the circumstances in which you - would want to specify the event mask: - Event Mask Circumstances - NoEventMask No events wanted - KeyPressMask Keyboard down events wanted - KeyReleaseMask Keyboard up events wanted - ButtonPressMask Pointer button down events wanted - ButtonReleaseMask Pointer button up events wanted - EnterWindowMask Pointer window entry events wanted - LeaveWindowMask Pointer window leave events wanted - PointerMotionMask Pointer motion events wanted - PointerMotionHintMask Pointer motion hints wanted - Button1MotionMask Pointer motion while button 1 down - Button2MotionMask Pointer motion while button 2 down - Button3MotionMask Pointer motion while button 3 down - Button4MotionMask Pointer motion while button 4 down - Button5MotionMask Pointer motion while button 5 down - ButtonMotionMask Pointer motion while any button down - KeymapStateMask Keyboard state wanted at window entry and focus - in - ExposureMask Any exposure wanted - VisibilityChangeMask Any change in visibility wanted - StructureNotifyMask Any change in window structure wanted - ResizeRedirectMask Redirect resize of this window - SubstructureNotifyMask Substructure notification wanted - SubstructureRedirectMask Redirect structure requests on - children - FocusChangeMask Any change in input focus wanted - PropertyChangeMask Any change in property wanted - ColormapChangeMask Any change in colormap wanted - OwnerGrabButtonMask Automatic grabs should activate with - owner_events set to True - -Event Processing Overview - - The event reported to a client application during event - processing depends on which event masks you provide as the - event-mask attribute for a window. For some event masks, there - is a one-to-one correspondence between the event mask constant - and the event type constant. For example, if you pass the event - mask ButtonPressMask, the X server sends back only ButtonPress - events. Most events contain a time member, which is the time at - which an event occurred. - - In other cases, one event mask constant can map to several - event type constants. For example, if you pass the event mask - SubstructureNotifyMask, the X server can send back - CirculateNotify, ConfigureNotify, CreateNotify, DestroyNotify, - GravityNotify, MapNotify, ReparentNotify, or UnmapNotify - events. - - In another case, two event masks can map to one event type. For - example, if you pass either PointerMotionMask or - ButtonMotionMask, the X server sends back a MotionNotify event. - - The following table lists the event mask, its associated event - type or types, and the structure name associated with the event - type. Some of these structures actually are typedefs to a - generic structure that is shared between two event types. Note - that N.A. appears in columns for which the information is not - applicable. - Event Mask Event Type Structure Generic Structure - - ButtonMotionMask - - Button1MotionMask - - Button2MotionMask - - Button3MotionMask - - Button4MotionMask - - Button5MotionMask - MotionNotify XPointerMovedEvent XMotionEvent - ButtonPressMask ButtonPress XButtonPressedEvent XButtonEvent - ButtonReleaseMask ButtonRelease XButtonReleasedEvent - XButtonEvent - ColormapChangeMask ColormapNotify XColormapEvent - EnterWindowMask EnterNotify XEnterWindowEvent XCrossingEvent - LeaveWindowMask LeaveNotify XLeaveWindowEvent XCrossingEvent - ExposureMask Expose XExposeEvent - GCGraphicsExposures in GC GraphicsExpose XGraphicsExposeEvent - NoExpose XNoExposeEvent - FocusChangeMask FocusIn XFocusInEvent XFocusChangeEvent - FocusOut XFocusOutEvent XFocusChangeEvent - KeymapStateMask KeymapNotify XKeymapEvent - KeyPressMask KeyPress XKeyPressedEvent XKeyEvent - KeyReleaseMask KeyRelease XKeyReleasedEvent XKeyEvent - OwnerGrabButtonMask N.A. N.A. - PointerMotionMask MotionNotify XPointerMovedEvent XMotionEvent - PointerMotionHintMask N.A. N.A. - PropertyChangeMask PropertyNotify XPropertyEvent - ResizeRedirectMask ResizeRequest XResizeRequestEvent - StructureNotifyMask CirculateNotify XCirculateEvent - ConfigureNotify XConfigureEvent - DestroyNotify XDestroyWindowEvent - GravityNotify XGravityEvent - MapNotify XMapEvent - ReparentNotify XReparentEvent - UnmapNotify XUnmapEvent - SubstructureNotifyMask CirculateNotify XCirculateEvent - ConfigureNotify XConfigureEvent - CreateNotify XCreateWindowEvent - DestroyNotify XDestroyWindowEvent - GravityNotify XGravityEvent - MapNotify XMapEvent - ReparentNotify XReparentEvent - UnmapNotify XUnmapEvent - SubstructureRedirectMask CirculateRequest - XCirculateRequestEvent - ConfigureRequest XConfigureRequestEvent - MapRequest XMapRequestEvent - N.A. ClientMessage XClientMessageEvent - N.A. MappingNotify XMappingEvent - N.A. SelectionClear XSelectionClearEvent - N.A. SelectionNotify XSelectionEvent - N.A. SelectionRequest XSelectionRequestEvent - VisibilityChangeMask VisibilityNotify XVisibilityEvent - - The sections that follow describe the processing that occurs - when you select the different event masks. The sections are - organized according to these processing categories: - * Keyboard and pointer events - * Window crossing events - * Input focus events - * Keymap state notification events - * Exposure events - * Window state notification events - * Structure control events - * Colormap state notification events - * Client communication events - -Keyboard and Pointer Events - - This section discusses: - * Pointer button events - * Keyboard and pointer events - -Pointer Button Events - - The following describes the event processing that occurs when a - pointer button press is processed with the pointer in some - window w and when no active pointer grab is in progress. - - The X server searches the ancestors of w from the root down, - looking for a passive grab to activate. If no matching passive - grab on the button exists, the X server automatically starts an - active grab for the client receiving the event and sets the - last-pointer-grab time to the current server time. The effect - is essentially equivalent to an XGrabButton with these client - passed arguments: - Argument Value - w The event window - event_mask The client's selected pointer events on the event - window - pointer_mode GrabModeAsync - keyboard_mode GrabModeAsync - owner_events True, if the client has selected - OwnerGrabButtonMask on the event window, otherwise False - confine_to None - cursor None - - The active grab is automatically terminated when the logical - state of the pointer has all buttons released. Clients can - modify the active grab by calling XUngrabPointer and - XChangeActivePointerGrab. - -Keyboard and Pointer Events - - This section discusses the processing that occurs for the - keyboard events KeyPress and KeyRelease and the pointer events - ButtonPress, ButtonRelease, and MotionNotify. For information - about the keyboard event-handling utilities, see chapter 11. - - The X server reports KeyPress or KeyRelease events to clients - wanting information about keys that logically change state. - Note that these events are generated for all keys, even those - mapped to modifier bits. The X server reports ButtonPress or - ButtonRelease events to clients wanting information about - buttons that logically change state. - - The X server reports MotionNotify events to clients wanting - information about when the pointer logically moves. The X - server generates this event whenever the pointer is moved and - the pointer motion begins and ends in the window. The - granularity of MotionNotify events is not guaranteed, but a - client that selects this event type is guaranteed to receive at - least one event when the pointer moves and then rests. - - The generation of the logical changes lags the physical changes - if device event processing is frozen. - - To receive KeyPress, KeyRelease, ButtonPress, and ButtonRelease - events, set KeyPressMask, KeyReleaseMask, ButtonPressMask, and - ButtonReleaseMask bits in the event-mask attribute of the - window. - - To receive MotionNotify events, set one or more of the - following event masks bits in the event-mask attribute of the - window. - * Button1MotionMask - Button5MotionMask - * The client application receives MotionNotify events only - when one or more of the specified buttons is pressed. - * ButtonMotionMask - * The client application receives MotionNotify events only - when at least one button is pressed. - * PointerMotionMask - * The client application receives MotionNotify events - independent of the state of the pointer buttons. - * PointerMotionHintMask - * If PointerMotionHintMask is selected in combination with - one or more of the above masks, the X server is free to - send only one MotionNotify event (with the is_hint member - of the XPointerMovedEvent structure set to NotifyHint) to - the client for the event window, until either the key or - button state changes, the pointer leaves the event window, - or the client calls XQueryPointer or . The server still may - send MotionNotify events without is_hint set to NotifyHint. - - The source of the event is the viewable window that the pointer - is in. The window used by the X server to report these events - depends on the window's position in the window hierarchy and - whether any intervening window prohibits the generation of - these events. Starting with the source window, the X server - searches up the window hierarchy until it locates the first - window specified by a client as having an interest in these - events. If one of the intervening windows has its - do-not-propagate-mask set to prohibit generation of the event - type, the events of those types will be suppressed. Clients can - modify the actual window used for reporting by performing - active grabs and, in the case of keyboard events, by using the - focus window. - - The structures for these event types contain: -typedef struct { - int type; /* ButtonPress or ButtonRelease */ - unsigned long serial; /* # of last request processed by s -erver */ - Bool send_event; /* true if this came from a SendEve -nt request */ - Display *display; /* Display the event was read from -*/ - Window window; /* ``event'' window it is reported -relative to */ - Window root; /* root window that the event occur -red on */ - Window subwindow; /* child window */ - Time time; /* milliseconds */ - int x, y; /* pointer x, y coordinates in even -t window */ - int x_root, y_root; /* coordinates relative to root */ - unsigned int state; /* key or button mask */ - unsigned int button; /* detail */ - Bool same_screen; /* same screen flag */ -} XButtonEvent; -typedef XButtonEvent XButtonPressedEvent; -typedef XButtonEvent XButtonReleasedEvent; - -typedef struct { - int type; /* KeyPress or KeyRelease */ - unsigned long serial; /* # of last request processed by s -erver */ - Bool send_event; /* true if this came from a SendEve -nt request */ - Display *display; /* Display the event was read from -*/ - Window window; /* ``event'' window it is reported -relative to */ - Window root; /* root window that the event occur -red on */ - Window subwindow; /* child window */ - Time time; /* milliseconds */ - int x, y; /* pointer x, y coordinates in even -t window */ - int x_root, y_root; /* coordinates relative to root */ - unsigned int state; /* key or button mask */ - unsigned int keycode; /* detail */ - Bool same_screen; /* same screen flag */ -} XKeyEvent; -typedef XKeyEvent XKeyPressedEvent; -typedef XKeyEvent XKeyReleasedEvent; - -typedef struct { - int type; /* MotionNotify */ - unsigned long serial; /* # of last request processed by - server */ - Bool send_event; /* true if this came from a SendE -vent request */ - Display *display; /* Display the event was read fro -m */ - Window window; /* ``event'' window reported rela -tive to */ - Window root; /* root window that the event occ -urred on */ - Window subwindow; /* child window */ - Time time; /* milliseconds */ - int x, y; /* pointer x, y coordinates in ev -ent window */ - int x_root, y_root; /* coordinates relative to root * -/ - unsigned int state; /* key or button mask */ - char is_hint; /* detail */ - Bool same_screen; /* same screen flag */ -} XMotionEvent; -typedef XMotionEvent XPointerMovedEvent; - - These structures have the following common members: window, - root, subwindow, time, x, y, x_root, y_root, state, and - same_screen. The window member is set to the window on which - the event was generated and is referred to as the event window. - As long as the conditions previously discussed are met, this is - the window used by the X server to report the event. The root - member is set to the source window's root window. The x_root - and y_root members are set to the pointer's coordinates - relative to the root window's origin at the time of the event. - - The same_screen member is set to indicate whether the event - window is on the same screen as the root window and can be - either True or False. If True, the event and root windows are - on the same screen. If False, the event and root windows are - not on the same screen. - - If the source window is an inferior of the event window, the - subwindow member of the structure is set to the child of the - event window that is the source window or the child of the - event window that is an ancestor of the source window. - Otherwise, the X server sets the subwindow member to None. The - time member is set to the time when the event was generated and - is expressed in milliseconds. - - If the event window is on the same screen as the root window, - the x and y members are set to the coordinates relative to the - event window's origin. Otherwise, these members are set to - zero. - - The state member is set to indicate the logical state of the - pointer buttons and modifier keys just prior to the event, - which is the bitwise inclusive OR of one or more of the button - or modifier key masks: Button1Mask, Button2Mask, Button3Mask, - Button4Mask, Button5Mask, ShiftMask, LockMask, ControlMask, - Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, and Mod5Mask. - - Each of these structures also has a member that indicates the - detail. For the XKeyPressedEvent and XKeyReleasedEvent - structures, this member is called a keycode. It is set to a - number that represents a physical key on the keyboard. The - keycode is an arbitrary representation for any key on the - keyboard (see sections 12.7 and 16.1). - - For the XButtonPressedEvent and XButtonReleasedEvent - structures, this member is called button. It represents the - pointer button that changed state and can be the Button1, - Button2, Button3, Button4, or Button5 value. For the - XPointerMovedEvent structure, this member is called is_hint. It - can be set to NotifyNormal or NotifyHint. - - Some of the symbols mentioned in this section have fixed - values, as follows: - Symbol Value - Button1MotionMask (1L<<8) - Button2MotionMask (1L<<9) - Button3MotionMask (1L<<10) - Button4MotionMask (1L<<11) - Button5MotionMask (1L<<12) - Button1Mask (1<<8) - Button2Mask (1<<9) - Button3Mask (1<<10) - Button4Mask (1<<11) - Button5Mask (1<<12) - ShiftMask (1<<0) - LockMask (1<<1) - ControlMask (1<<2) - Mod1Mask (1<<3) - Mod2Mask (1<<4) - Mod3Mask (1<<5) - Mod4Mask (1<<6) - Mod5Mask (1<<7) - Button1 1 - Button2 2 - Button3 3 - Button4 4 - Button5 5 - -Window Entry/Exit Events - - This section describes the processing that occurs for the - window crossing events EnterNotify and LeaveNotify. If a - pointer motion or a window hierarchy change causes the pointer - to be in a different window than before, the X server reports - EnterNotify or LeaveNotify events to clients who have selected - for these events. All EnterNotify and LeaveNotify events caused - by a hierarchy change are generated after any hierarchy event - (UnmapNotify, MapNotify, ConfigureNotify, GravityNotify, - CirculateNotify) caused by that change; however, the X protocol - does not constrain the ordering of EnterNotify and LeaveNotify - events with respect to FocusOut, VisibilityNotify, and Expose - events. - - This contrasts with MotionNotify events, which are also - generated when the pointer moves but only when the pointer - motion begins and ends in a single window. An EnterNotify or - LeaveNotify event also can be generated when some client - application calls XGrabPointer and XUngrabPointer. - - To receive EnterNotify or LeaveNotify events, set the - EnterWindowMask or LeaveWindowMask bits of the event-mask - attribute of the window. - - The structure for these event types contains: - - -typedef struct { - int type; /* EnterNotify or LeaveNotify */ - unsigned long serial; /* # of last request processed by ser -ver */ - Bool send_event; /* true if this came from a SendEvent - request */ - Display *display; /* Display the event was read from */ - Window window; /* ``event'' window reported relative - to */ - Window root; /* root window that the event occurre -d on */ - Window subwindow; /* child window */ - Time time; /* milliseconds */ - int x, y; /* pointer x, y coordinates in event -window */ - int x_root, y_root; /* coordinates relative to root */ - int mode; /* NotifyNormal, NotifyGrab, NotifyUn -grab */ - int detail; - /* - * NotifyAncestor, NotifyVirtual, NotifyInferior, - * NotifyNonlinear,NotifyNonlinearVirtual - */ - Bool same_screen; /* same screen flag */ - Bool focus; /* boolean focus */ - unsigned int state; /* key or button mask */ -} XCrossingEvent; -typedef XCrossingEvent XEnterWindowEvent; -typedef XCrossingEvent XLeaveWindowEvent; - - The window member is set to the window on which the EnterNotify - or LeaveNotify event was generated and is referred to as the - event window. This is the window used by the X server to report - the event, and is relative to the root window on which the - event occurred. The root member is set to the root window of - the screen on which the event occurred. - - For a LeaveNotify event, if a child of the event window - contains the initial position of the pointer, the subwindow - component is set to that child. Otherwise, the X server sets - the subwindow member to None. For an EnterNotify event, if a - child of the event window contains the final pointer position, - the subwindow component is set to that child or None. - - The time member is set to the time when the event was generated - and is expressed in milliseconds. The x and y members are set - to the coordinates of the pointer position in the event window. - This position is always the pointer's final position, not its - initial position. If the event window is on the same screen as - the root window, x and y are the pointer coordinates relative - to the event window's origin. Otherwise, x and y are set to - zero. The x_root and y_root members are set to the pointer's - coordinates relative to the root window's origin at the time of - the event. - - The same_screen member is set to indicate whether the event - window is on the same screen as the root window and can be - either True or False. If True, the event and root windows are - on the same screen. If False, the event and root windows are - not on the same screen. - - The focus member is set to indicate whether the event window is - the focus window or an inferior of the focus window. The X - server can set this member to either True or False. If True, - the event window is the focus window or an inferior of the - focus window. If False, the event window is not the focus - window or an inferior of the focus window. - - The state member is set to indicate the state of the pointer - buttons and modifier keys just prior to the event. The X server - can set this member to the bitwise inclusive OR of one or more - of the button or modifier key masks: Button1Mask, Button2Mask, - Button3Mask, Button4Mask, Button5Mask, ShiftMask, LockMask, - ControlMask, Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, Mod5Mask. - - The mode member is set to indicate whether the events are - normal events, pseudo-motion events when a grab activates, or - pseudo-motion events when a grab deactivates. The X server can - set this member to NotifyNormal, NotifyGrab, or NotifyUngrab. - - The detail member is set to indicate the notify detail and can - be NotifyAncestor, NotifyVirtual, NotifyInferior, - NotifyNonlinear, or NotifyNonlinearVirtual. - -Normal Entry/Exit Events - - EnterNotify and LeaveNotify events are generated when the - pointer moves from one window to another window. Normal events - are identified by XEnterWindowEvent or XLeaveWindowEvent - structures whose mode member is set to NotifyNormal. - * When the pointer moves from window A to window B and A is - an inferior of B, the X server does the following: - * It generates a LeaveNotify event on window A, with the - detail member of the XLeaveWindowEvent structure set to - NotifyAncestor. - * It generates a LeaveNotify event on each window between - window A and window B, exclusive, with the detail member of - each XLeaveWindowEvent structure set to NotifyVirtual. - * It generates an EnterNotify event on window B, with the - detail member of the XEnterWindowEvent structure set to - NotifyInferior. - * When the pointer moves from window A to window B and B is - an inferior of A, the X server does the following: - * It generates a LeaveNotify event on window A, with the - detail member of the XLeaveWindowEvent structure set to - NotifyInferior. - * It generates an EnterNotify event on each window between - window A and window B, exclusive, with the detail member of - each XEnterWindowEvent structure set to NotifyVirtual. - * It generates an EnterNotify event on window B, with the - detail member of the XEnterWindowEvent structure set to - NotifyAncestor. - * When the pointer moves from window A to window B and window - C is their least common ancestor, the X server does the - following: - * It generates a LeaveNotify event on window A, with the - detail member of the XLeaveWindowEvent structure set to - NotifyNonlinear. - * It generates a LeaveNotify event on each window between - window A and window C, exclusive, with the detail member of - each XLeaveWindowEvent structure set to - NotifyNonlinearVirtual. - * It generates an EnterNotify event on each window between - window C and window B, exclusive, with the detail member of - each XEnterWindowEvent structure set to - NotifyNonlinearVirtual. - * It generates an EnterNotify event on window B, with the - detail member of the XEnterWindowEvent structure set to - NotifyNonlinear. - * When the pointer moves from window A to window B on - different screens, the X server does the following: - * It generates a LeaveNotify event on window A, with the - detail member of the XLeaveWindowEvent structure set to - NotifyNonlinear. - * If window A is not a root window, it generates a - LeaveNotify event on each window above window A up to and - including its root, with the detail member of each - XLeaveWindowEvent structure set to NotifyNonlinearVirtual. - * If window B is not a root window, it generates an - EnterNotify event on each window from window B's root down - to but not including window B, with the detail member of - each XEnterWindowEvent structure set to - NotifyNonlinearVirtual. - * It generates an EnterNotify event on window B, with the - detail member of the XEnterWindowEvent structure set to - NotifyNonlinear. - -Grab and Ungrab Entry/Exit Events - - Pseudo-motion mode EnterNotify and LeaveNotify events are - generated when a pointer grab activates or deactivates. Events - in which the pointer grab activates are identified by - XEnterWindowEvent or XLeaveWindowEvent structures whose mode - member is set to NotifyGrab. Events in which the pointer grab - deactivates are identified by XEnterWindowEvent or - XLeaveWindowEvent structures whose mode member is set to - NotifyUngrab (see XGrabPointer). - * When a pointer grab activates after any initial warp into a - confine_to window and before generating any actual - ButtonPress event that activates the grab, G is the - grab_window for the grab, and P is the window the pointer - is in, the X server does the following: - * It generates EnterNotify and LeaveNotify events (see - section 10.6.1) with the mode members of the - XEnterWindowEvent and XLeaveWindowEvent structures set to - NotifyGrab. These events are generated as if the pointer - were to suddenly warp from its current position in P to - some position in G. However, the pointer does not warp, and - the X server uses the pointer position as both the initial - and final positions for the events. - * When a pointer grab deactivates after generating any actual - ButtonRelease event that deactivates the grab, G is the - grab_window for the grab, and P is the window the pointer - is in, the X server does the following: - * It generates EnterNotify and LeaveNotify events (see - section 10.6.1) with the mode members of the - XEnterWindowEvent and XLeaveWindowEvent structures set to - NotifyUngrab. These events are generated as if the pointer - were to suddenly warp from some position in G to its - current position in P. However, the pointer does not warp, - and the X server uses the current pointer position as both - the initial and final positions for the events. - -Input Focus Events - - This section describes the processing that occurs for the input - focus events FocusIn and FocusOut. The X server can report - FocusIn or FocusOut events to clients wanting information about - when the input focus changes. The keyboard is always attached - to some window (typically, the root window or a top-level - window), which is called the focus window. The focus window and - the position of the pointer determine the window that receives - keyboard input. Clients may need to know when the input focus - changes to control highlighting of areas on the screen. - - To receive FocusIn or FocusOut events, set the FocusChangeMask - bit in the event-mask attribute of the window. - - The structure for these event types contains: - - -typedef struct { - int type; /* FocusIn or FocusOut */ - unsigned long serial; /* # of last request processed by server -*/ - Bool send_event; /* true if this came from a SendEvent req -uest */ - Display *display; /* Display the event was read from */ - Window window; /* window of event */ - int mode; /* NotifyNormal, NotifyGrab, NotifyUngrab - */ - int detail; - /* - * NotifyAncestor, NotifyVirtual, NotifyInferior, - * NotifyNonlinear,NotifyNonlinearVirtual, NotifyPoin -ter, - * NotifyPointerRoot, NotifyDetailNone - */ -} XFocusChangeEvent; -typedef XFocusChangeEvent XFocusInEvent; -typedef XFocusChangeEvent XFocusOutEvent; - - The window member is set to the window on which the FocusIn or - FocusOut event was generated. This is the window used by the X - server to report the event. The mode member is set to indicate - whether the focus events are normal focus events, focus events - while grabbed, focus events when a grab activates, or focus - events when a grab deactivates. The X server can set the mode - member to NotifyNormal, NotifyWhileGrabbed, NotifyGrab, or - NotifyUngrab. - - All FocusOut events caused by a window unmap are generated - after any UnmapNotify event; however, the X protocol does not - constrain the ordering of FocusOut events with respect to - generated EnterNotify, LeaveNotify, VisibilityNotify, and - Expose events. - - Depending on the event mode, the detail member is set to - indicate the notify detail and can be NotifyAncestor, - NotifyVirtual, NotifyInferior, NotifyNonlinear, - NotifyNonlinearVirtual, NotifyPointer, NotifyPointerRoot, or - NotifyDetailNone. - -Normal Focus Events and Focus Events While Grabbed - - Normal focus events are identified by XFocusInEvent or - XFocusOutEvent structures whose mode member is set to - NotifyNormal. Focus events while grabbed are identified by - XFocusInEvent or XFocusOutEvent structures whose mode member is - set to NotifyWhileGrabbed. The X server processes normal focus - and focus events while grabbed according to the following: - * When the focus moves from window A to window B, A is an - inferior of B, and the pointer is in window P, the X server - does the following: - * It generates a FocusOut event on window A, with the detail - member of the XFocusOutEvent structure set to - NotifyAncestor. - * It generates a FocusOut event on each window between window - A and window B, exclusive, with the detail member of each - XFocusOutEvent structure set to NotifyVirtual. - * It generates a FocusIn event on window B, with the detail - member of the XFocusOutEvent structure set to - NotifyInferior. - * If window P is an inferior of window B but window P is not - window A or an inferior or ancestor of window A, it - generates a FocusIn event on each window below window B, - down to and including window P, with the detail member of - each XFocusInEvent structure set to NotifyPointer. - * When the focus moves from window A to window B, B is an - inferior of A, and the pointer is in window P, the X server - does the following: - * If window P is an inferior of window A but P is not an - inferior of window B or an ancestor of B, it generates a - FocusOut event on each window from window P up to but not - including window A, with the detail member of each - XFocusOutEvent structure set to NotifyPointer. - * It generates a FocusOut event on window A, with the detail - member of the XFocusOutEvent structure set to - NotifyInferior. - * It generates a FocusIn event on each window between window - A and window B, exclusive, with the detail member of each - XFocusInEvent structure set to NotifyVirtual. - * It generates a FocusIn event on window B, with the detail - member of the XFocusInEvent structure set to - NotifyAncestor. - * When the focus moves from window A to window B, window C is - their least common ancestor, and the pointer is in window - P, the X server does the following: - * If window P is an inferior of window A, it generates a - FocusOut event on each window from window P up to but not - including window A, with the detail member of the - XFocusOutEvent structure set to NotifyPointer. - * It generates a FocusOut event on window A, with the detail - member of the XFocusOutEvent structure set to - NotifyNonlinear. - * It generates a FocusOut event on each window between window - A and window C, exclusive, with the detail member of each - XFocusOutEvent structure set to NotifyNonlinearVirtual. - * It generates a FocusIn event on each window between C and - B, exclusive, with the detail member of each XFocusInEvent - structure set to NotifyNonlinearVirtual. - * It generates a FocusIn event on window B, with the detail - member of the XFocusInEvent structure set to - NotifyNonlinear. - * If window P is an inferior of window B, it generates a - FocusIn event on each window below window B down to and - including window P, with the detail member of the - XFocusInEvent structure set to NotifyPointer. - * When the focus moves from window A to window B on different - screens and the pointer is in window P, the X server does - the following: - * If window P is an inferior of window A, it generates a - FocusOut event on each window from window P up to but not - including window A, with the detail member of each - XFocusOutEvent structure set to NotifyPointer. - * It generates a FocusOut event on window A, with the detail - member of the XFocusOutEvent structure set to - NotifyNonlinear. - * If window A is not a root window, it generates a FocusOut - event on each window above window A up to and including its - root, with the detail member of each XFocusOutEvent - structure set to NotifyNonlinearVirtual. - * If window B is not a root window, it generates a FocusIn - event on each window from window B's root down to but not - including window B, with the detail member of each - XFocusInEvent structure set to NotifyNonlinearVirtual. - * It generates a FocusIn event on window B, with the detail - member of each XFocusInEvent structure set to - NotifyNonlinear. - * If window P is an inferior of window B, it generates a - FocusIn event on each window below window B down to and - including window P, with the detail member of each - XFocusInEvent structure set to NotifyPointer. - * When the focus moves from window A to PointerRoot (events - sent to the window under the pointer) or None (discard), - and the pointer is in window P, the X server does the - following: - * If window P is an inferior of window A, it generates a - FocusOut event on each window from window P up to but not - including window A, with the detail member of each - XFocusOutEvent structure set to NotifyPointer. - * It generates a FocusOut event on window A, with the detail - member of the XFocusOutEvent structure set to - NotifyNonlinear. - * If window A is not a root window, it generates a FocusOut - event on each window above window A up to and including its - root, with the detail member of each XFocusOutEvent - structure set to NotifyNonlinearVirtual. - * It generates a FocusIn event on the root window of all - screens, with the detail member of each XFocusInEvent - structure set to NotifyPointerRoot (or NotifyDetailNone). - * If the new focus is PointerRoot, it generates a FocusIn - event on each window from window P's root down to and - including window P, with the detail member of each - XFocusInEvent structure set to NotifyPointer. - * When the focus moves from PointerRoot (events sent to the - window under the pointer) or None to window A, and the - pointer is in window P, the X server does the following: - * If the old focus is PointerRoot, it generates a FocusOut - event on each window from window P up to and including - window P's root, with the detail member of each - XFocusOutEvent structure set to NotifyPointer. - * It generates a FocusOut event on all root windows, with the - detail member of each XFocusOutEvent structure set to - NotifyPointerRoot (or NotifyDetailNone). - * If window A is not a root window, it generates a FocusIn - event on each window from window A's root down to but not - including window A, with the detail member of each - XFocusInEvent structure set to NotifyNonlinearVirtual. - * It generates a FocusIn event on window A, with the detail - member of the XFocusInEvent structure set to - NotifyNonlinear. - * If window P is an inferior of window A, it generates a - FocusIn event on each window below window A down to and - including window P, with the detail member of each - XFocusInEvent structure set to NotifyPointer. - * When the focus moves from PointerRoot (events sent to the - window under the pointer) to None (or vice versa), and the - pointer is in window P, the X server does the following: - * If the old focus is PointerRoot, it generates a FocusOut - event on each window from window P up to and including - window P's root, with the detail member of each - XFocusOutEvent structure set to NotifyPointer. - * It generates a FocusOut event on all root windows, with the - detail member of each XFocusOutEvent structure set to - either NotifyPointerRoot or NotifyDetailNone. - * It generates a FocusIn event on all root windows, with the - detail member of each XFocusInEvent structure set to - NotifyDetailNone or NotifyPointerRoot. - * If the new focus is PointerRoot, it generates a FocusIn - event on each window from window P's root down to and - including window P, with the detail member of each - XFocusInEvent structure set to NotifyPointer. - -Focus Events Generated by Grabs - - Focus events in which the keyboard grab activates are - identified by XFocusInEvent or XFocusOutEvent structures whose - mode member is set to NotifyGrab. Focus events in which the - keyboard grab deactivates are identified by XFocusInEvent or - XFocusOutEvent structures whose mode member is set to - NotifyUngrab (see XGrabKeyboard). - * When a keyboard grab activates before generating any actual - KeyPress event that activates the grab, G is the - grab_window, and F is the current focus, the X server does - the following: - * It generates FocusIn and FocusOut events, with the mode - members of the XFocusInEvent and XFocusOutEvent structures - set to NotifyGrab. These events are generated as if the - focus were to change from F to G. - * When a keyboard grab deactivates after generating any - actual KeyRelease event that deactivates the grab, G is the - grab_window, and F is the current focus, the X server does - the following: - * It generates FocusIn and FocusOut events, with the mode - members of the XFocusInEvent and XFocusOutEvent structures - set to NotifyUngrab. These events are generated as if the - focus were to change from G to F. - -Key Map State Notification Events - - The X server can report KeymapNotify events to clients that - want information about changes in their keyboard state. - - To receive KeymapNotify events, set the KeymapStateMask bit in - the event-mask attribute of the window. The X server generates - this event immediately after every EnterNotify and FocusIn - event. - - The structure for this event type contains: - - - -/* generated on EnterWindow and FocusIn when KeymapState selected */ -typedef struct { - int type; /* KeymapNotify */ - unsigned long serial; /* # of last request processed by se -rver */ - Bool send_event; /* true if this came from a SendEven -t request */ - Display *display; /* Display the event was read from * -/ - Window window; - char key_vector[32]; -} XKeymapEvent; - - The window member is not used but is present to aid some - toolkits. The key_vector member is set to the bit vector of the - keyboard. Each bit set to 1 indicates that the corresponding - key is currently pressed. The vector is represented as 32 - bytes. Byte N (from 0) contains the bits for keys 8N to 8N + 7 - with the least significant bit in the byte representing key 8N. - -Exposure Events - - The X protocol does not guarantee to preserve the contents of - window regions when the windows are obscured or reconfigured. - Some implementations may preserve the contents of windows. - Other implementations are free to destroy the contents of - windows when exposed. X expects client applications to assume - the responsibility for restoring the contents of an exposed - window region. (An exposed window region describes a formerly - obscured window whose region becomes visible.) Therefore, the X - server sends Expose events describing the window and the region - of the window that has been exposed. A naive client application - usually redraws the entire window. A more sophisticated client - application redraws only the exposed region. - -Expose Events - - The X server can report Expose events to clients wanting - information about when the contents of window regions have been - lost. The circumstances in which the X server generates Expose - events are not as definite as those for other events. However, - the X server never generates Expose events on windows whose - class you specified as InputOnly. The X server can generate - Expose events when no valid contents are available for regions - of a window and either the regions are visible, the regions are - viewable and the server is (perhaps newly) maintaining backing - store on the window, or the window is not viewable but the - server is (perhaps newly) honoring the window's backing-store - attribute of Always or WhenMapped. The regions decompose into - an (arbitrary) set of rectangles, and an Expose event is - generated for each rectangle. For any given window, the X - server guarantees to report contiguously all of the regions - exposed by some action that causes Expose events, such as - raising a window. - - To receive Expose events, set the ExposureMask bit in the - event-mask attribute of the window. - - The structure for this event type contains: - - - -typedef struct { - int type; /* Expose */ - unsigned long serial; /* # of last request processed by ser -ver */ - Bool send_event; /* true if this came from a SendEvent - request */ - Display *display; /* Display the event was read from */ - Window window; - int x, y; - int width, height; - int count; /* if nonzero, at least this many mor -e */ -} XExposeEvent; - - The window member is set to the exposed (damaged) window. The x - and y members are set to the coordinates relative to the - window's origin and indicate the upper-left corner of the - rectangle. The width and height members are set to the size - (extent) of the rectangle. The count member is set to the - number of Expose events that are to follow. If count is zero, - no more Expose events follow for this window. However, if count - is nonzero, at least that number of Expose events (and possibly - more) follow for this window. Simple applications that do not - want to optimize redisplay by distinguishing between subareas - of its window can just ignore all Expose events with nonzero - counts and perform full redisplays on events with zero counts. - -GraphicsExpose and NoExpose Events - - The X server can report GraphicsExpose events to clients - wanting information about when a destination region could not - be computed during certain graphics requests: XCopyArea or - XCopyPlane. The X server generates this event whenever a - destination region could not be computed because of an obscured - or out-of-bounds source region. In addition, the X server - guarantees to report contiguously all of the regions exposed by - some graphics request (for example, copying an area of a - drawable to a destination drawable). - - The X server generates a NoExpose event whenever a graphics - request that might produce a GraphicsExpose event does not - produce any. In other words, the client is really asking for a - GraphicsExpose event but instead receives a NoExpose event. - - To receive GraphicsExpose or NoExpose events, you must first - set the graphics-exposure attribute of the graphics context to - True. You also can set the graphics-expose attribute when - creating a graphics context using XCreateGC or by calling - XSetGraphicsExposures. - - The structures for these event types contain: - - - -typedef struct { - int type; /* GraphicsExpose */ - unsigned long serial; /* # of last request processed by se -rver */ - Bool send_event; /* true if this came from a SendEven -t request */ - Display *display; /* Display the event was read from * -/ - Drawable drawable; - int x, y; - int width, height; - int count; /* if nonzero, at least this many mo -re */ - int major_code; /* core is CopyArea or CopyPlane */ - int minor_code; /* not defined in the core */ -} XGraphicsExposeEvent; - - - -typedef struct { - int type; /* NoExpose */ - unsigned long serial; /* # of last request processed by serve -r */ - Bool send_event; /* true if this came from a SendEvent r -equest */ - Display *display; /* Display the event was read from */ - Drawable drawable; - int major_code; /* core is CopyArea or CopyPlane */ - int minor_code; /* not defined in the core */ -} XNoExposeEvent; - - Both structures have these common members: drawable, - major_code, and minor_code. The drawable member is set to the - drawable of the destination region on which the graphics - request was to be performed. The major_code member is set to - the graphics request initiated by the client and can be either - X_CopyArea or X_CopyPlane. If it is X_CopyArea, a call to - XCopyArea initiated the request. If it is X_CopyPlane, a call - to XCopyPlane initiated the request. These constants are - defined in . The minor_code member, like the - major_code member, indicates which graphics request was - initiated by the client. However, the minor_code member is not - defined by the core X protocol and will be zero in these cases, - although it may be used by an extension. - - The XGraphicsExposeEvent structure has these additional - members: x, y, width, height, and count. The x and y members - are set to the coordinates relative to the drawable's origin - and indicate the upper-left corner of the rectangle. The width - and height members are set to the size (extent) of the - rectangle. The count member is set to the number of - GraphicsExpose events to follow. If count is zero, no more - GraphicsExpose events follow for this window. However, if count - is nonzero, at least that number of GraphicsExpose events (and - possibly more) are to follow for this window. - -Window State Change Events - - The following sections discuss: - * CirculateNotify events - * ConfigureNotify events - * CreateNotify events - * DestroyNotify events - * GravityNotify events - * MapNotify events - * MappingNotify events - * ReparentNotify events - * UnmapNotify events - * VisibilityNotify events - -CirculateNotify Events - - The X server can report CirculateNotify events to clients - wanting information about when a window changes its position in - the stack. The X server generates this event type whenever a - window is actually restacked as a result of a client - application calling XCirculateSubwindows, - XCirculateSubwindowsUp, or XCirculateSubwindowsDown. - - To receive CirculateNotify events, set the StructureNotifyMask - bit in the event-mask attribute of the window or the - SubstructureNotifyMask bit in the event-mask attribute of the - parent window (in which case, circulating any child generates - an event). - - The structure for this event type contains: - - - -typedef struct { - int type; /* CirculateNotify */ - unsigned long serial; /* # of last request processed by server -*/ - Bool send_event; /* true if this came from a SendEvent request -*/ - Display *display; /* Display the event was read from */ - Window event; - Window window; - int place; /* PlaceOnTop, PlaceOnBottom */ -} XCirculateEvent; - - The event member is set either to the restacked window or to - its parent, depending on whether StructureNotify or - SubstructureNotify was selected. The window member is set to - the window that was restacked. The place member is set to the - window's position after the restack occurs and is either - PlaceOnTop or PlaceOnBottom. If it is PlaceOnTop, the window is - now on top of all siblings. If it is PlaceOnBottom, the window - is now below all siblings. - -ConfigureNotify Events - - The X server can report ConfigureNotify events to clients - wanting information about actual changes to a window's state, - such as size, position, border, and stacking order. The X - server generates this event type whenever one of the following - configure window requests made by a client application actually - completes: - * A window's size, position, border, and/or stacking order is - reconfigured by calling XConfigureWindow. - * The window's position in the stacking order is changed by - calling XLowerWindow, XRaiseWindow, or XRestackWindows. - * A window is moved by calling XMoveWindow. - * A window's size is changed by calling XResizeWindow. - * A window's size and location is changed by calling - XMoveResizeWindow. - * A window is mapped and its position in the stacking order - is changed by calling XMapRaised. - * A window's border width is changed by calling - XSetWindowBorderWidth. - - To receive ConfigureNotify events, set the StructureNotifyMask - bit in the event-mask attribute of the window or the - SubstructureNotifyMask bit in the event-mask attribute of the - parent window (in which case, configuring any child generates - an event). - - The structure for this event type contains: - - -typedef struct { - int type; /* ConfigureNotify */ - unsigned long serial; /* # of last request processed by server -*/ - Bool send_event; /* true if this came from a SendEvent req -uest */ - Display *display; /* Display the event was read from */ - Window event; - Window window; - int x, y; - int width, height; - int border_width; - Window above; - Bool override_redirect; -} XConfigureEvent; - - The event member is set either to the reconfigured window or to - its parent, depending on whether StructureNotify or - SubstructureNotify was selected. The window member is set to - the window whose size, position, border, and/or stacking order - was changed. - - The x and y members are set to the coordinates relative to the - parent window's origin and indicate the position of the - upper-left outside corner of the window. The width and height - members are set to the inside size of the window, not including - the border. The border_width member is set to the width of the - window's border, in pixels. - - The above member is set to the sibling window and is used for - stacking operations. If the X server sets this member to None, - the window whose state was changed is on the bottom of the - stack with respect to sibling windows. However, if this member - is set to a sibling window, the window whose state was changed - is placed on top of this sibling window. - - The override_redirect member is set to the override-redirect - attribute of the window. Window manager clients normally should - ignore this window if the override_redirect member is True. - -CreateNotify Events - - The X server can report CreateNotify events to clients wanting - information about creation of windows. The X server generates - this event whenever a client application creates a window by - calling XCreateWindow or XCreateSimpleWindow. - - To receive CreateNotify events, set the SubstructureNotifyMask - bit in the event-mask attribute of the window. Creating any - children then generates an event. - - The structure for the event type contains: - - - -typedef struct { - int type; /* CreateNotify */ - unsigned long serial; /* # of last request processed by - server */ - Bool send_event; /* true if this came from a SendE -vent request */ - Display *display; /* Display the event was read fro -m */ - Window parent; /* parent of the window */ - Window window; /* window id of window created */ - int x, y; /* window location */ - int width, height; /* size of window */ - int border_width; /* border width */ - Bool override_redirect; /* creation should be overridden -*/ -} XCreateWindowEvent; - - The parent member is set to the created window's parent. The - window member specifies the created window. The x and y members - are set to the created window's coordinates relative to the - parent window's origin and indicate the position of the - upper-left outside corner of the created window. The width and - height members are set to the inside size of the created window - (not including the border) and are always nonzero. The - border_width member is set to the width of the created window's - border, in pixels. The override_redirect member is set to the - override-redirect attribute of the window. Window manager - clients normally should ignore this window if the - override_redirect member is True. - -DestroyNotify Events - - The X server can report DestroyNotify events to clients wanting - information about which windows are destroyed. The X server - generates this event whenever a client application destroys a - window by calling XDestroyWindow or XDestroySubwindows. - - The ordering of the DestroyNotify events is such that for any - given window, DestroyNotify is generated on all inferiors of - the window before being generated on the window itself. The X - protocol does not constrain the ordering among siblings and - across subhierarchies. - - To receive DestroyNotify events, set the StructureNotifyMask - bit in the event-mask attribute of the window or the - SubstructureNotifyMask bit in the event-mask attribute of the - parent window (in which case, destroying any child generates an - event). - - The structure for this event type contains: - - - -typedef struct { - int type; /* DestroyNotify */ - unsigned long serial; /* # of last request processed by server -*/ - Bool send_event; /* true if this came from a SendEvent req -uest */ - Display *display; /* Display the event was read from */ - Window event; - Window window; -} XDestroyWindowEvent; - - The event member is set either to the destroyed window or to - its parent, depending on whether StructureNotify or - SubstructureNotify was selected. The window member is set to - the window that is destroyed. - -GravityNotify Events - - The X server can report GravityNotify events to clients wanting - information about when a window is moved because of a change in - the size of its parent. The X server generates this event - whenever a client application actually moves a child window as - a result of resizing its parent by calling XConfigureWindow, - XMoveResizeWindow, or XResizeWindow. - - To receive GravityNotify events, set the StructureNotifyMask - bit in the event-mask attribute of the window or the - SubstructureNotifyMask bit in the event-mask attribute of the - parent window (in which case, any child that is moved because - its parent has been resized generates an event). - - The structure for this event type contains: - - - -typedef struct { - int type; /* GravityNotify */ - unsigned long serial; /* # of last request processed by server -*/ - Bool send_event; /* true if this came from a SendEvent req -uest */ - Display *display; /* Display the event was read from */ - Window event; - Window window; - int x, y; -} XGravityEvent; - - The event member is set either to the window that was moved or - to its parent, depending on whether StructureNotify or - SubstructureNotify was selected. The window member is set to - the child window that was moved. The x and y members are set to - the coordinates relative to the new parent window's origin and - indicate the position of the upper-left outside corner of the - window. - -MapNotify Events - - The X server can report MapNotify events to clients wanting - information about which windows are mapped. The X server - generates this event type whenever a client application changes - the window's state from unmapped to mapped by calling - XMapWindow, XMapRaised, XMapSubwindows, XReparentWindow, or as - a result of save-set processing. - - To receive MapNotify events, set the StructureNotifyMask bit in - the event-mask attribute of the window or the - SubstructureNotifyMask bit in the event-mask attribute of the - parent window (in which case, mapping any child generates an - event). - - The structure for this event type contains: - - - -typedef struct { - int type; /* MapNotify */ - unsigned long serial; /* # of last request processed - by server */ - Bool send_event; /* true if this came from a Se -ndEvent request */ - Display *display; /* Display the event was read -from */ - Window event; - Window window; - Bool override_redirect; /* boolean, is override set... - */ -} XMapEvent; - - The event member is set either to the window that was mapped or - to its parent, depending on whether StructureNotify or - SubstructureNotify was selected. The window member is set to - the window that was mapped. The override_redirect member is set - to the override-redirect attribute of the window. Window - manager clients normally should ignore this window if the - override-redirect attribute is True, because these events - usually are generated from pop-ups, which override structure - control. - -MappingNotify Events - - The X server reports MappingNotify events to all clients. There - is no mechanism to express disinterest in this event. The X - server generates this event type whenever a client application - successfully calls: - * XSetModifierMapping to indicate which KeyCodes are to be - used as modifiers - * XChangeKeyboardMapping to change the keyboard mapping - * XSetPointerMapping to set the pointer mapping - - The structure for this event type contains: - - - -typedef struct { - int type; /* MappingNotify */ - unsigned long serial; /* # of last request processed by ser -ver */ - Bool send_event; /* true if this came from a SendEvent - request */ - Display *display; /* Display the event was read from */ - Window window; /* unused */ - int request; /* one of MappingModifier, MappingKey -board, - MappingPointer */ - int first_keycode; /* first keycode */ - int count; /* defines range of change w. first_k -eycode*/ -} XMappingEvent; - - The request member is set to indicate the kind of mapping - change that occurred and can be MappingModifier, - MappingKeyboard, or MappingPointer. If it is MappingModifier, - the modifier mapping was changed. If it is MappingKeyboard, the - keyboard mapping was changed. If it is MappingPointer, the - pointer button mapping was changed. The first_keycode and count - members are set only if the request member was set to - MappingKeyboard. The number in first_keycode represents the - first number in the range of the altered mapping, and count - represents the number of keycodes altered. - - To update the client application's knowledge of the keyboard, - you should call XRefreshKeyboardMapping. - -ReparentNotify Events - - The X server can report ReparentNotify events to clients - wanting information about changing a window's parent. The X - server generates this event whenever a client application calls - XReparentWindow and the window is actually reparented. - - To receive ReparentNotify events, set the StructureNotifyMask - bit in the event-mask attribute of the window or the - SubstructureNotifyMask bit in the event-mask attribute of - either the old or the new parent window (in which case, - reparenting any child generates an event). - - The structure for this event type contains: - - - -typedef struct { - int type; /* ReparentNotify */ - unsigned long serial; /* # of last request processed by server -*/ - Bool send_event; /* true if this came from a SendEvent req -uest */ - Display *display; /* Display the event was read from */ - Window event; - Window window; - Window parent; - int x, y; - Bool override_redirect; -} XReparentEvent; - - The event member is set either to the reparented window or to - the old or the new parent, depending on whether StructureNotify - or SubstructureNotify was selected. The window member is set to - the window that was reparented. The parent member is set to the - new parent window. The x and y members are set to the - reparented window's coordinates relative to the new parent - window's origin and define the upper-left outer corner of the - reparented window. The override_redirect member is set to the - override-redirect attribute of the window specified by the - window member. Window manager clients normally should ignore - this window if the override_redirect member is True. - -UnmapNotify Events - - The X server can report UnmapNotify events to clients wanting - information about which windows are unmapped. The X server - generates this event type whenever a client application changes - the window's state from mapped to unmapped. - - To receive UnmapNotify events, set the StructureNotifyMask bit - in the event-mask attribute of the window or the - SubstructureNotifyMask bit in the event-mask attribute of the - parent window (in which case, unmapping any child window - generates an event). - - The structure for this event type contains: - - - -typedef struct { - int type; /* UnmapNotify */ - unsigned long serial; /* # of last request processed by server -*/ - Bool send_event; /* true if this came from a SendEvent req -uest */ - Display *display; /* Display the event was read from */ - Window event; - Window window; - Bool from_configure; -} XUnmapEvent; - - The event member is set either to the unmapped window or to its - parent, depending on whether StructureNotify or - SubstructureNotify was selected. This is the window used by the - X server to report the event. The window member is set to the - window that was unmapped. The from_configure member is set to - True if the event was generated as a result of a resizing of - the window's parent when the window itself had a win_gravity of - UnmapGravity. - -VisibilityNotify Events - - The X server can report VisibilityNotify events to clients - wanting any change in the visibility of the specified window. A - region of a window is visible if someone looking at the screen - can actually see it. The X server generates this event whenever - the visibility changes state. However, this event is never - generated for windows whose class is InputOnly. - - All VisibilityNotify events caused by a hierarchy change are - generated after any hierarchy event (UnmapNotify, MapNotify, - ConfigureNotify, GravityNotify, CirculateNotify) caused by that - change. Any VisibilityNotify event on a given window is - generated before any Expose events on that window, but it is - not required that all VisibilityNotify events on all windows be - generated before all Expose events on all windows. The X - protocol does not constrain the ordering of VisibilityNotify - events with respect to FocusOut, EnterNotify, and LeaveNotify - events. - - To receive VisibilityNotify events, set the - VisibilityChangeMask bit in the event-mask attribute of the - window. - - The structure for this event type contains: - - - -typedef struct { - int type; /* VisibilityNotify */ - unsigned long serial; /* # of last request processed by server -*/ - Bool send_event; /* true if this came from a SendEvent req -uest */ - Display *display; /* Display the event was read from */ - Window window; - int state; -} XVisibilityEvent; - - The window member is set to the window whose visibility state - changes. The state member is set to the state of the window's - visibility and can be VisibilityUnobscured, - VisibilityPartiallyObscured, or VisibilityFullyObscured. The X - server ignores all of a window's subwindows when determining - the visibility state of the window and processes - VisibilityNotify events according to the following: - * When the window changes state from partially obscured, - fully obscured, or not viewable to viewable and completely - unobscured, the X server generates the event with the state - member of the XVisibilityEvent structure set to - VisibilityUnobscured. - * When the window changes state from viewable and completely - unobscured or not viewable to viewable and partially - obscured, the X server generates the event with the state - member of the XVisibilityEvent structure set to - VisibilityPartiallyObscured. - * When the window changes state from viewable and completely - unobscured, viewable and partially obscured, or not - viewable to viewable and fully obscured, the X server - generates the event with the state member of the - XVisibilityEvent structure set to VisibilityFullyObscured. - -Structure Control Events - - This section discusses: - * CirculateRequest events - * ConfigureRequest events - * MapRequest events - * ResizeRequest events - -CirculateRequest Events - - The X server can report CirculateRequest events to clients - wanting information about when another client initiates a - circulate window request on a specified window. The X server - generates this event type whenever a client initiates a - circulate window request on a window and a subwindow actually - needs to be restacked. The client initiates a circulate window - request on the window by calling XCirculateSubwindows, - XCirculateSubwindowsUp, or XCirculateSubwindowsDown. - - To receive CirculateRequest events, set the - SubstructureRedirectMask in the event-mask attribute of the - window. Then, in the future, the circulate window request for - the specified window is not executed, and thus, any subwindow's - position in the stack is not changed. For example, suppose a - client application calls XCirculateSubwindowsUp to raise a - subwindow to the top of the stack. If you had selected - SubstructureRedirectMask on the window, the X server reports to - you a CirculateRequest event and does not raise the subwindow - to the top of the stack. - - The structure for this event type contains: - - - -typedef struct { - int type; /* CirculateRequest */ - unsigned long serial; /* # of last request processed by server -*/ - Bool send_event; /* true if this came from a SendEvent req -uest */ - Display *display; /* Display the event was read from */ - Window parent; - Window window; - int place; /* PlaceOnTop, PlaceOnBottom */ -} XCirculateRequestEvent; - - The parent member is set to the parent window. The window - member is set to the subwindow to be restacked. The place - member is set to what the new position in the stacking order - should be and is either PlaceOnTop or PlaceOnBottom. If it is - PlaceOnTop, the subwindow should be on top of all siblings. If - it is PlaceOnBottom, the subwindow should be below all - siblings. - -ConfigureRequest Events - - The X server can report ConfigureRequest events to clients - wanting information about when a different client initiates a - configure window request on any child of a specified window. - The configure window request attempts to reconfigure a window's - size, position, border, and stacking order. The X server - generates this event whenever a different client initiates a - configure window request on a window by calling - XConfigureWindow, XLowerWindow, XRaiseWindow, XMapRaised, - XMoveResizeWindow, XMoveWindow, XResizeWindow, XRestackWindows, - or XSetWindowBorderWidth. - - To receive ConfigureRequest events, set the - SubstructureRedirectMask bit in the event-mask attribute of the - window. ConfigureRequest events are generated when a - ConfigureWindow protocol request is issued on a child window by - another client. For example, suppose a client application calls - XLowerWindow to lower a window. If you had selected - SubstructureRedirectMask on the parent window and if the - override-redirect attribute of the window is set to False, the - X server reports a ConfigureRequest event to you and does not - lower the specified window. - - The structure for this event type contains: - - - -typedef struct { - int type; /* ConfigureRequest */ - unsigned long serial; /* # of last request processed by serve -r */ - Bool send_event; /* true if this came from a SendEvent r -equest */ - Display *display; /* Display the event was read from */ - Window parent; - Window window; - int x, y; - int width, height; - int border_width; - Window above; - int detail; /* Above, Below, TopIf, BottomIf, Oppos -ite */ - unsigned long value_mask; -} XConfigureRequestEvent; - - The parent member is set to the parent window. The window - member is set to the window whose size, position, border width, - and/or stacking order is to be reconfigured. The value_mask - member indicates which components were specified in the - ConfigureWindow protocol request. The corresponding values are - reported as given in the request. The remaining values are - filled in from the current geometry of the window, except in - the case of above (sibling) and detail (stack-mode), which are - reported as None and Above, respectively, if they are not given - in the request. - -MapRequest Events - - The X server can report MapRequest events to clients wanting - information about a different client's desire to map windows. A - window is considered mapped when a map window request - completes. The X server generates this event whenever a - different client initiates a map window request on an unmapped - window whose override_redirect member is set to False. Clients - initiate map window requests by calling XMapWindow, XMapRaised, - or XMapSubwindows. - - To receive MapRequest events, set the SubstructureRedirectMask - bit in the event-mask attribute of the window. This means - another client's attempts to map a child window by calling one - of the map window request functions is intercepted, and you are - sent a MapRequest instead. For example, suppose a client - application calls XMapWindow to map a window. If you (usually a - window manager) had selected SubstructureRedirectMask on the - parent window and if the override-redirect attribute of the - window is set to False, the X server reports a MapRequest event - to you and does not map the specified window. Thus, this event - gives your window manager client the ability to control the - placement of subwindows. - - The structure for this event type contains: - - - -typedef struct { - int type; /* MapRequest */ - unsigned long serial; /* # of last request processed by server -*/ - Bool send_event; /* true if this came from a SendEvent req -uest */ - Display *display; /* Display the event was read from */ - Window parent; - Window window; -} XMapRequestEvent; - - The parent member is set to the parent window. The window - member is set to the window to be mapped. - -ResizeRequest Events - - The X server can report ResizeRequest events to clients wanting - information about another client's attempts to change the size - of a window. The X server generates this event whenever some - other client attempts to change the size of the specified - window by calling XConfigureWindow, XResizeWindow, or - XMoveResizeWindow. - - To receive ResizeRequest events, set the ResizeRedirect bit in - the event-mask attribute of the window. Any attempts to change - the size by other clients are then redirected. - - The structure for this event type contains: - - - -typedef struct { - int type; /* ResizeRequest */ - unsigned long serial; /* # of last request processed by server - */ - Bool send_event; /* true if this came from a SendEvent re -quest */ - Display *display; /* Display the event was read from */ - Window window; - int width, height; -} XResizeRequestEvent; - - The window member is set to the window whose size another - client attempted to change. The width and height members are - set to the inside size of the window, excluding the border. - -Colormap State Change Events - - The X server can report ColormapNotify events to clients - wanting information about when the colormap changes and when a - colormap is installed or uninstalled. The X server generates - this event type whenever a client application: - * Changes the colormap member of the XSetWindowAttributes - structure by calling XChangeWindowAttributes, - XFreeColormap, or XSetWindowColormap - * Installs or uninstalls the colormap by calling - XInstallColormap or XUninstallColormap - - To receive ColormapNotify events, set the ColormapChangeMask - bit in the event-mask attribute of the window. - - The structure for this event type contains: - - - -typedef struct { - int type; /* ColormapNotify */ - unsigned long serial; /* # of last request processed by server -*/ - Bool send_event; /* true if this came from a SendEvent req -uest */ - Display *display; /* Display the event was read from */ - Window window; - Colormap colormap; /* colormap or None */ - Bool new; - int state; /* ColormapInstalled, ColormapUninstalled - */ -} XColormapEvent; - - The window member is set to the window whose associated - colormap is changed, installed, or uninstalled. For a colormap - that is changed, installed, or uninstalled, the colormap member - is set to the colormap associated with the window. For a - colormap that is changed by a call to XFreeColormap, the - colormap member is set to None. The new member is set to - indicate whether the colormap for the specified window was - changed or installed or uninstalled and can be True or False. - If it is True, the colormap was changed. If it is False, the - colormap was installed or uninstalled. The state member is - always set to indicate whether the colormap is installed or - uninstalled and can be ColormapInstalled or - ColormapUninstalled. - -Client Communication Events - - This section discusses: - * ClientMessage events - * PropertyNotify events - * SelectionClear events - * SelectionNotify events - * SelectionRequest events - -ClientMessage Events - - The X server generates ClientMessage events only when a client - calls the function XSendEvent. - - The structure for this event type contains: - - - -typedef struct { - int type; /* ClientMessage */ - unsigned long serial; /* # of last request processed by ser -ver */ - Bool send_event; /* true if this came from a SendEvent - request */ - Display *display; /* Display the event was read from */ - Window window; - Atom message_type; - int format; - union { - char b[20]; - short s[10]; - long l[5]; - } data; -} XClientMessageEvent; - - The message_type member is set to an atom that indicates how - the data should be interpreted by the receiving client. The - format member is set to 8, 16, or 32 and specifies whether the - data should be viewed as a list of bytes, shorts, or longs. The - data member is a union that contains the members b, s, and l. - The b, s, and l members represent data of twenty 8-bit values, - ten 16-bit values, and five 32-bit values. Particular message - types might not make use of all these values. The X server - places no interpretation on the values in the window, - message_type, or data members. - -PropertyNotify Events - - The X server can report PropertyNotify events to clients - wanting information about property changes for a specified - window. - - To receive PropertyNotify events, set the PropertyChangeMask - bit in the event-mask attribute of the window. - - The structure for this event type contains: - - - -typedef struct { - int type; /* PropertyNotify */ - unsigned long serial; /* # of last request processed by server -*/ - Bool send_event; /* true if this came from a SendEvent req -uest */ - Display *display; /* Display the event was read from */ - Window window; - Atom atom; - Time time; - int state; /* PropertyNewValue or PropertyDelete */ -} XPropertyEvent; - - The window member is set to the window whose associated - property was changed. The atom member is set to the property's - atom and indicates which property was changed or desired. The - time member is set to the server time when the property was - changed. The state member is set to indicate whether the - property was changed to a new value or deleted and can be - PropertyNewValue or PropertyDelete. The state member is set to - PropertyNewValue when a property of the window is changed using - XChangeProperty or XRotateWindowProperties (even when adding - zero-length data using XChangeProperty) and when replacing all - or part of a property with identical data using XChangeProperty - or XRotateWindowProperties. The state member is set to - PropertyDelete when a property of the window is deleted using - XDeleteProperty or, if the delete argument is True, - XGetWindowProperty. - -SelectionClear Events - - The X server reports SelectionClear events to the client losing - ownership of a selection. The X server generates this event - type when another client asserts ownership of the selection by - calling XSetSelectionOwner. - - The structure for this event type contains: - - - -typedef struct { - int type; /* SelectionClear */ - unsigned long serial; /* # of last request processed by server -*/ - Bool send_event; /* true if this came from a SendEvent req -uest */ - Display *display; /* Display the event was read from */ - Window window; - Atom selection; - Time time; -} XSelectionClearEvent; - - The selection member is set to the selection atom. The time - member is set to the last change time recorded for the - selection. The window member is the window that was specified - by the current owner (the owner losing the selection) in its - XSetSelectionOwner call. - -SelectionRequest Events - - The X server reports SelectionRequest events to the owner of a - selection. The X server generates this event whenever a client - requests a selection conversion by calling XConvertSelection - for the owned selection. - - The structure for this event type contains: - - - -typedef struct { - int type; /* SelectionRequest */ - unsigned long serial; /* # of last request processed by server -*/ - Bool send_event; /* true if this came from a SendEvent req -uest */ - Display *display; /* Display the event was read from */ - Window owner; - Window requestor; - Atom selection; - Atom target; - Atom property; - Time time; -} XSelectionRequestEvent; - - The owner member is set to the window that was specified by the - current owner in its XSetSelectionOwner call. The requestor - member is set to the window requesting the selection. The - selection member is set to the atom that names the selection. - For example, PRIMARY is used to indicate the primary selection. - The target member is set to the atom that indicates the type - the selection is desired in. The property member can be a - property name or None. The time member is set to the timestamp - or CurrentTime value from the ConvertSelection request. - - The owner should convert the selection based on the specified - target type and send a SelectionNotify event back to the - requestor. A complete specification for using selections is - given in the X Consortium standard Inter-Client Communication - Conventions Manual. - -SelectionNotify Events - - This event is generated by the X server in response to a - ConvertSelection protocol request when there is no owner for - the selection. When there is an owner, it should be generated - by the owner of the selection by using XSendEvent. The owner of - a selection should send this event to a requestor when a - selection has been converted and stored as a property or when a - selection conversion could not be performed (which is indicated - by setting the property member to None). - - If None is specified as the property in the ConvertSelection - protocol request, the owner should choose a property name, - store the result as that property on the requestor window, and - then send a SelectionNotify giving that actual property name. - - The structure for this event type contains: - - - -typedef struct { - int type; /* SelectionNotify */ - unsigned long serial; /* # of last request processed by server -*/ - Bool send_event; /* true if this came from a SendEvent req -uest */ - Display *display; /* Display the event was read from */ - Window requestor; - Atom selection; - Atom target; - Atom property; /* atom or None */ - Time time; -} XSelectionEvent; - - The requestor member is set to the window associated with the - requestor of the selection. The selection member is set to the - atom that indicates the selection. For example, PRIMARY is used - for the primary selection. The target member is set to the atom - that indicates the converted type. For example, PIXMAP is used - for a pixmap. The property member is set to the atom that - indicates which property the result was stored on. If the - conversion failed, the property member is set to None. The time - member is set to the time the conversion took place and can be - a timestamp or CurrentTime. - -Chapter 11. Event Handling Functions - - Table of Contents - - Selecting Events - Handling the Output Buffer - Event Queue Management - Manipulating the Event Queue - - Returning the Next Event - Selecting Events Using a Predicate Procedure - Selecting Events Using a Window or Event Mask - - Putting an Event Back into the Queue - Sending Events to Other Applications - Getting Pointer Motion History - Handling Protocol Errors - - Enabling or Disabling Synchronization - Using the Default Error Handlers - - This chapter discusses the Xlib functions you can use to: - * Select events - * Handle the output buffer and the event queue - * Select events from the event queue - * Send and get events - * Handle protocol errors - -Note - - Some toolkits use their own event-handling functions and do not - allow you to interchange these event-handling functions with - those in Xlib. For further information, see the documentation - supplied with the toolkit. - - Most applications simply are event loops: they wait for an - event, decide what to do with it, execute some amount of code - that results in changes to the display, and then wait for the - next event. - -Selecting Events - - There are two ways to select the events you want reported to - your client application. One way is to set the event_mask - member of the XSetWindowAttributes structure when you call - XCreateWindow and XChangeWindowAttributes. Another way is to - use XSelectInput. - - XSelectInput(Display *display, Window w, long event_mask); - - display - - Specifies the connection to the X server. - - w - - Specifies the window whose events you are interested in. - - event_mask - - Specifies the event mask. - - The XSelectInput function requests that the X server report the - events associated with the specified event mask. Initially, X - will not report any of these events. Events are reported - relative to a window. If a window is not interested in a device - event, it usually propagates to the closest ancestor that is - interested, unless the do_not_propagate mask prohibits it. - - Setting the event-mask attribute of a window overrides any - previous call for the same window but not for other clients. - Multiple clients can select for the same events on the same - window with the following restrictions: - * Multiple clients can select events on the same window - because their event masks are disjoint. When the X server - generates an event, it reports it to all interested - clients. - * Only one client at a time can select CirculateRequest, - ConfigureRequest, or MapRequest events, which are - associated with the event mask SubstructureRedirectMask. - * Only one client at a time can select a ResizeRequest event, - which is associated with the event mask ResizeRedirectMask. - * Only one client at a time can select a ButtonPress event, - which is associated with the event mask ButtonPressMask. - - The server reports the event to all interested clients. - - XSelectInput can generate a BadWindow error. - -Handling the Output Buffer - - The output buffer is an area used by Xlib to store requests. - The functions described in this section flush the output buffer - if the function would block or not return an event. That is, - all requests residing in the output buffer that have not yet - been sent are transmitted to the X server. These functions - differ in the additional tasks they might perform. - - To flush the output buffer, use XFlush. - - XFlush(Display *display); - - display - - Specifies the connection to the X server. - - The XFlush function flushes the output buffer. Most client - applications need not use this function because the output - buffer is automatically flushed as needed by calls to XPending, - XNextEvent, and XWindowEvent. Events generated by the server - may be enqueued into the library's event queue. - - To flush the output buffer and then wait until all requests - have been processed, use XSync. - - XSync(Display *display, Bool discard); - - display - - Specifies the connection to the X server. - - discard - - Specifies a Boolean value that indicates whether XSync discards - all events on the event queue. - - The XSync function flushes the output buffer and then waits - until all requests have been received and processed by the X - server. Any errors generated must be handled by the error - handler. For each protocol error received by Xlib, XSync calls - the client application's error handling routine (see section - 11.8.2). Any events generated by the server are enqueued into - the library's event queue. - - Finally, if you passed False, XSync does not discard the events - in the queue. If you passed True, XSync discards all events in - the queue, including those events that were on the queue before - XSync was called. Client applications seldom need to call - XSync. - -Event Queue Management - - Xlib maintains an event queue. However, the operating system - also may be buffering data in its network connection that is - not yet read into the event queue. - - To check the number of events in the event queue, use - XEventsQueued. - - int XEventsQueued(Display *display, int mode); - - display - - Specifies the connection to the X server. - - mode - - Specifies the mode. You can pass QueuedAlready, - QueuedAfterFlush, or QueuedAfterReading. - - If mode is QueuedAlready, XEventsQueued returns the number of - events already in the event queue (and never performs a system - call). If mode is QueuedAfterFlush, XEventsQueued returns the - number of events already in the queue if the number is nonzero. - If there are no events in the queue, XEventsQueued flushes the - output buffer, attempts to read more events out of the - application's connection, and returns the number read. If mode - is QueuedAfterReading, XEventsQueued returns the number of - events already in the queue if the number is nonzero. If there - are no events in the queue, XEventsQueued attempts to read more - events out of the application's connection without flushing the - output buffer and returns the number read. - - XEventsQueued always returns immediately without I/O if there - are events already in the queue. XEventsQueued with mode - QueuedAfterFlush is identical in behavior to XPending. - XEventsQueued with mode QueuedAlready is identical to the - XQLength function. - - To return the number of events that are pending, use XPending. - - int XPending(Display *display); - - display - - Specifies the connection to the X server. - - The XPending function returns the number of events that have - been received from the X server but have not been removed from - the event queue. XPending is identical to XEventsQueued with - the mode QueuedAfterFlush specified. - -Manipulating the Event Queue - - Xlib provides functions that let you manipulate the event - queue. This section discusses how to: - * Obtain events, in order, and remove them from the queue - * Peek at events in the queue without removing them - * Obtain events that match the event mask or the arbitrary - predicate procedures that you provide - -Returning the Next Event - - To get the next event and remove it from the queue, use - XNextEvent. - - XNextEvent(Display *display, XEvent *event_return); - - display - - Specifies the connection to the X server. - - event_return - - Returns the next event in the queue. - - The XNextEvent function copies the first event from the event - queue into the specified XEvent structure and then removes it - from the queue. If the event queue is empty, XNextEvent flushes - the output buffer and blocks until an event is received. - - To peek at the event queue, use XPeekEvent. - - XPeekEvent(Display *display, XEvent *event_return); - - display - - Specifies the connection to the X server. - - event_return - - Returns a copy of the matched event's associated structure. - - The XPeekEvent function returns the first event from the event - queue, but it does not remove the event from the queue. If the - queue is empty, XPeekEvent flushes the output buffer and blocks - until an event is received. It then copies the event into the - client-supplied XEvent structure without removing it from the - event queue. - -Selecting Events Using a Predicate Procedure - - Each of the functions discussed in this section requires you to - pass a predicate procedure that determines if an event matches - what you want. Your predicate procedure must decide if the - event is useful without calling any Xlib functions. If the - predicate directly or indirectly causes the state of the event - queue to change, the result is not defined. If Xlib has been - initialized for threads, the predicate is called with the - display locked and the result of a call by the predicate to any - Xlib function that locks the display is not defined unless the - caller has first called XLockDisplay. - - The predicate procedure and its associated arguments are: - - Bool(Display *display, XEvent *event, XPointer arg); - - display - - Specifies the connection to the X server. - - event - - Specifies the XEvent structure. - - arg - - Specifies the argument passed in from the XIfEvent, - XCheckIfEvent, or XPeekIfEvent function. - - The predicate procedure is called once for each event in the - queue until it finds a match. After finding a match, the - predicate procedure must return True. If it did not find a - match, it must return False. - - To check the event queue for a matching event and, if found, - remove the event from the queue, use XIfEvent. - - XIfEvent(Display *display, XEvent *event_return, Bool - (*predicate)(), XPointer arg); - - display - - Specifies the connection to the X server. - - event_return - - Returns the matched event's associated structure. - - predicate - - Specifies the procedure that is to be called to determine if - the next event in the queue matches what you want. - - arg - - Specifies the user-supplied argument that will be passed to the - predicate procedure. - - The XIfEvent function completes only when the specified - predicate procedure returns True for an event, which indicates - an event in the queue matches. XIfEvent flushes the output - buffer if it blocks waiting for additional events. XIfEvent - removes the matching event from the queue and copies the - structure into the client-supplied XEvent structure. - - To check the event queue for a matching event without blocking, - use XCheckIfEvent. - - Bool XCheckIfEvent(Display *display, XEvent *event_return, Bool - (*predicate)(), XPointer arg); - - display - - Specifies the connection to the X server. - - event_return - - Returns a copy of the matched event's associated structure. - - predicate - - Specifies the procedure that is to be called to determine if - the next event in the queue matches what you want. - - arg - - Specifies the user-supplied argument that will be passed to the - predicate procedure. - - When the predicate procedure finds a match, XCheckIfEvent - copies the matched event into the client-supplied XEvent - structure and returns True. (This event is removed from the - queue.) If the predicate procedure finds no match, - XCheckIfEvent returns False, and the output buffer will have - been flushed. All earlier events stored in the queue are not - discarded. - - To check the event queue for a matching event without removing - the event from the queue, use XPeekIfEvent. - - XPeekIfEvent(Display *display, XEvent *event_return, Bool - (*predicate)(), XPointer arg); - - display - - Specifies the connection to the X server. - - event_return - - Returns a copy of the matched event's associated structure. - - predicate - - Specifies the procedure that is to be called to determine if - the next event in the queue matches what you want. - - arg - - Specifies the user-supplied argument that will be passed to the - predicate procedure. - - The XPeekIfEvent function returns only when the specified - predicate procedure returns True for an event. After the - predicate procedure finds a match, XPeekIfEvent copies the - matched event into the client-supplied XEvent structure without - removing the event from the queue. XPeekIfEvent flushes the - output buffer if it blocks waiting for additional events. - -Selecting Events Using a Window or Event Mask - - The functions discussed in this section let you select events - by window or event types, allowing you to process events out of - order. - - To remove the next event that matches both a window and an - event mask, use XWindowEvent. - - XWindowEvent(Display *display, Window w, long event_mask, - XEvent *event_return); - - display - - Specifies the connection to the X server. - - w - - Specifies the window whose events you are interested in. - - event_mask - - Specifies the event mask. - - event_return - - Returns the matched event's associated structure. - - The XWindowEvent function searches the event queue for an event - that matches both the specified window and event mask. When it - finds a match, XWindowEvent removes that event from the queue - and copies it into the specified XEvent structure. The other - events stored in the queue are not discarded. If a matching - event is not in the queue, XWindowEvent flushes the output - buffer and blocks until one is received. - - To remove the next event that matches both a window and an - event mask (if any), use XCheckWindowEvent. This function is - similar to XWindowEvent except that it never blocks and it - returns a Bool indicating if the event was returned. - - Bool XCheckWindowEvent(Display *display, Window w, long - event_mask, XEvent *event_return); - - display - - Specifies the connection to the X server. - - w - - Specifies the window whose events you are interested in. - - event_mask - - Specifies the event mask. - - event_return - - Returns the matched event's associated structure. - - The XCheckWindowEvent function searches the event queue and - then the events available on the server connection for the - first event that matches the specified window and event mask. - If it finds a match, XCheckWindowEvent removes that event, - copies it into the specified XEvent structure, and returns - True. The other events stored in the queue are not discarded. - If the event you requested is not available, XCheckWindowEvent - returns False, and the output buffer will have been flushed. - - To remove the next event that matches an event mask, use - XMaskEvent. - - XMaskEvent(Display *display, long event_mask, XEvent - *event_return); - - display - - Specifies the connection to the X server. - - event_mask - - Specifies the event mask. - - event_return - - Returns the matched event's associated structure. - - The XMaskEvent function searches the event queue for the events - associated with the specified mask. When it finds a match, - XMaskEvent removes that event and copies it into the specified - XEvent structure. The other events stored in the queue are not - discarded. If the event you requested is not in the queue, - XMaskEvent flushes the output buffer and blocks until one is - received. - - To return and remove the next event that matches an event mask - (if any), use XCheckMaskEvent. This function is similar to - XMaskEvent except that it never blocks and it returns a Bool - indicating if the event was returned. - - Bool XCheckMaskEvent(Display *display, long event_mask, XEvent - *event_return); - - display - - Specifies the connection to the X server. - - event_mask - - Specifies the event mask. - - event_return - - Returns the matched event's associated structure. - - The XCheckMaskEvent function searches the event queue and then - any events available on the server connection for the first - event that matches the specified mask. If it finds a match, - XCheckMaskEvent removes that event, copies it into the - specified XEvent structure, and returns True. The other events - stored in the queue are not discarded. If the event you - requested is not available, XCheckMaskEvent returns False, and - the output buffer will have been flushed. - - To return and remove the next event in the queue that matches - an event type, use XCheckTypedEvent. - - Bool XCheckTypedEvent(Display *display, int event_type, XEvent - *event_return); - - display - - Specifies the connection to the X server. - - event_type - - Specifies the event type to be compared. - - event_return - - Returns the matched event's associated structure. - - The XCheckTypedEvent function searches the event queue and then - any events available on the server connection for the first - event that matches the specified type. If it finds a match, - XCheckTypedEvent removes that event, copies it into the - specified XEvent structure, and returns True. The other events - in the queue are not discarded. If the event is not available, - XCheckTypedEvent returns False, and the output buffer will have - been flushed. - - To return and remove the next event in the queue that matches - an event type and a window, use XCheckTypedWindowEvent. - - Bool XCheckTypedWindowEvent(Display *display, Window w, int - event_type, XEvent *event_return); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - event_type - - Specifies the event type to be compared. - - event_return - - Returns the matched event's associated structure. - - The XCheckTypedWindowEvent function searches the event queue - and then any events available on the server connection for the - first event that matches the specified type and window. If it - finds a match, XCheckTypedWindowEvent removes the event from - the queue, copies it into the specified XEvent structure, and - returns True. The other events in the queue are not discarded. - If the event is not available, XCheckTypedWindowEvent returns - False, and the output buffer will have been flushed. - -Putting an Event Back into the Queue - - To push an event back into the event queue, use XPutBackEvent. - - XPutBackEvent(Display *display, XEvent *event); - - display - - Specifies the connection to the X server. - - event - - Specifies the event. - - The XPutBackEvent function pushes an event back onto the head - of the display's event queue by copying the event into the - queue. This can be useful if you read an event and then decide - that you would rather deal with it later. There is no limit to - the number of times in succession that you can call - XPutBackEvent. - -Sending Events to Other Applications - - To send an event to a specified window, use XSendEvent. This - function is often used in selection processing. For example, - the owner of a selection should use XSendEvent to send a - SelectionNotify event to a requestor when a selection has been - converted and stored as a property. - - Status XSendEvent(Display *display, Window w, Bool propagate, - long event_mask, XEvent *event_send); - - display - - Specifies the connection to the X server. - - w - - Specifies the window the event is to be sent to, or - PointerWindow, or InputFocus. - - propagate - - Specifies a Boolean value. - - event_mask - - Specifies the event mask. - - event_send - - Specifies the event that is to be sent. - - The XSendEvent function identifies the destination window, - determines which clients should receive the specified events, - and ignores any active grabs. This function requires you to - pass an event mask. For a discussion of the valid event mask - names, see section 10.3. This function uses the w argument to - identify the destination window as follows: - * If w is PointerWindow, the destination window is the window - that contains the pointer. - * If w is InputFocus and if the focus window contains the - pointer, the destination window is the window that contains - the pointer; otherwise, the destination window is the focus - window. - - To determine which clients should receive the specified events, - XSendEvent uses the propagate argument as follows: - * If event_mask is the empty set, the event is sent to the - client that created the destination window. If that client - no longer exists, no event is sent. - * If propagate is False, the event is sent to every client - selecting on destination any of the event types in the - event_mask argument. - * If propagate is True and no clients have selected on - destination any of the event types in event-mask, the - destination is replaced with the closest ancestor of - destination for which some client has selected a type in - event-mask and for which no intervening window has that - type in its do-not-propagate-mask. If no such window exists - or if the window is an ancestor of the focus window and - InputFocus was originally specified as the destination, the - event is not sent to any clients. Otherwise, the event is - reported to every client selecting on the final destination - any of the types specified in event_mask. - - The event in the XEvent structure must be one of the core - events or one of the events defined by an extension (or a - BadValue error results) so that the X server can correctly - byte-swap the contents as necessary. The contents of the event - are otherwise unaltered and unchecked by the X server except to - force send_event to True in the forwarded event and to set the - serial number in the event correctly; therefore these fields - and the display field are ignored by XSendEvent. - - XSendEvent returns zero if the conversion to wire protocol - format failed and returns nonzero otherwise. - - XSendEvent can generate BadValue and BadWindow errors. - -Getting Pointer Motion History - - Some X server implementations will maintain a more complete - history of pointer motion than is reported by event - notification. The pointer position at each pointer hardware - interrupt may be stored in a buffer for later retrieval. This - buffer is called the motion history buffer. For example, a few - applications, such as paint programs, want to have a precise - history of where the pointer traveled. However, this historical - information is highly excessive for most applications. - - To determine the approximate maximum number of elements in the - motion buffer, use XDisplayMotionBufferSize. - - unsigned long(Display *display); - - display - - Specifies the connection to the X server. - - The server may retain the recent history of the pointer motion - and do so to a finer granularity than is reported by - MotionNotify events. The function makes this history available. - - To get the motion history for a specified window and time, use - . - - XTimeCoord *XGetMotionEvents(Display *display, Window w, Time - start, Time stop, int *nevents_return); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - start - - stop - - Specify the time interval in which the events are returned from - the motion history buffer. You can pass a timestamp or - CurrentTime. - - nevents_return - - Returns the number of events from the motion history buffer. - - The function returns all events in the motion history buffer - that fall between the specified start and stop times, - inclusive, and that have coordinates that lie within the - specified window (including its borders) at its present - placement. If the server does not support motion history, if - the start time is later than the stop time, or if the start - time is in the future, no events are returned; returns NULL. If - the stop time is in the future, it is equivalent to specifying - CurrentTime. The return type for this function is a structure - defined as follows: - - - -typedef struct { - Time time; - short x, y; -} XTimeCoord; - - The time member is set to the time, in milliseconds. The x and - y members are set to the coordinates of the pointer and are - reported relative to the origin of the specified window. To - free the data returned from this call, use XFree. - - can generate a BadWindow error. - -Handling Protocol Errors - - Xlib provides functions that you can use to enable or disable - synchronization and to use the default error handlers. - -Enabling or Disabling Synchronization - - When debugging X applications, it often is very convenient to - require Xlib to behave synchronously so that errors are - reported as they occur. The following function lets you disable - or enable synchronous behavior. Note that graphics may occur 30 - or more times more slowly when synchronization is enabled. On - POSIX-conformant systems, there is also a global variable - _Xdebug that, if set to nonzero before starting a program under - a debugger, will force synchronous library behavior. - - After completing their work, all Xlib functions that generate - protocol requests call what is known as an after function. sets - which function is to be called. - - int(Display *display, int (*procedure)()); - - display - - Specifies the connection to the X server. - - procedure - - Specifies the procedure to be called. - - The specified procedure is called with only a display pointer. - returns the previous after function. - - To enable or disable synchronization, use XSynchronize. - - int(Display *display, Bool onoff); - - display - - Specifies the connection to the X server. - - onoff - - Specifies a Boolean value that indicates whether to enable or - disable synchronization. - - The XSynchronize function returns the previous after function. - If onoff is True, XSynchronize turns on synchronous behavior. - If onoff is False, XSynchronize turns off synchronous behavior. - -Using the Default Error Handlers - - There are two default error handlers in Xlib: one to handle - typically fatal conditions (for example, the connection to a - display server dying because a machine crashed) and one to - handle protocol errors from the X server. These error handlers - can be changed to user-supplied routines if you prefer your own - error handling and can be changed as often as you like. If - either function is passed a NULL pointer, it will reinvoke the - default handler. The action of the default handlers is to print - an explanatory message and exit. - - To set the error handler, use XSetErrorHandler. - - int *XSetErrorHandler(int *handler); - - handler - - Specifies the program's supplied error handler. - - Xlib generally calls the program's supplied error handler - whenever an error is received. It is not called on BadName - errors from OpenFont, LookupColor, or AllocNamedColor protocol - requests or on BadFont errors from a QueryFont protocol - request. These errors generally are reflected back to the - program through the procedural interface. Because this - condition is not assumed to be fatal, it is acceptable for your - error handler to return; the returned value is ignored. - However, the error handler should not call any functions - (directly or indirectly) on the display that will generate - protocol requests or that will look for input events. The - previous error handler is returned. - - The XErrorEvent structure contains: - - - -typedef struct { - int type; - Display *display; /* Display the event was read from */ - unsigned long serial; /* serial number of failed reque -st */ - unsigned char error_code; /* error code of failed request -*/ - unsigned char request_code; /* Major op-code of failed reque -st */ - unsigned char minor_code; /* Minor op-code of failed reque -st */ - XID resourceid; /* resource id */ -} XErrorEvent; - - The serial member is the number of requests, starting from one, - sent over the network connection since it was opened. It is the - number that was the value of NextRequest immediately before the - failing call was made. The request_code member is a protocol - request of the procedure that failed, as defined in - . The following error codes can be returned by - the functions described in this chapter: - Error Code Description - BadAccess - - A client attempts to grab a key/button combination already - grabbed by another client. - - A client attempts to free a colormap entry that it had not - already allocated or to free an entry in a colormap that was - created with all entries writable. - - A client attempts to store into a read-only or unallocated - colormap entry. - - A client attempts to modify the access control list from other - than the local (or otherwise authorized) host. - - A client attempts to select an event type that another client - has already selected. - BadAlloc The server fails to allocate the requested resource. - Note that the explicit listing of BadAlloc errors in requests - only covers allocation errors at a very coarse level and is not - intended to (nor can it in practice hope to) cover all cases of - a server running out of allocation space in the middle of - service. The semantics when a server runs out of allocation - space are left unspecified, but a server may generate a - BadAlloc error on any request for this reason, and clients - should be prepared to receive such errors and handle or discard - them. - BadAtom A value for an atom argument does not name a defined - atom. - BadColor A value for a colormap argument does not name a - defined colormap. - BadCursor A value for a cursor argument does not name a defined - cursor. - BadDrawable A value for a drawable argument does not name a - defined window or pixmap. - BadFont A value for a font argument does not name a defined - font (or, in some cases, GContext). - BadGC A value for a GContext argument does not name a defined - GContext. - BadIDChoice The value chosen for a resource identifier either - is not included in the range assigned to the client or is - already in use. Under normal circumstances, this cannot occur - and should be considered a server or Xlib error. - BadImplementation The server does not implement some aspect of - the request. A server that generates this error for a core - request is deficient. As such, this error is not listed for any - of the requests, but clients should be prepared to receive such - errors and handle or discard them. - BadLength - - The length of a request is shorter or longer than that required - to contain the arguments. This is an internal Xlib or server - error. - - The length of a request exceeds the maximum length accepted by - the server. - BadMatch - - In a graphics request, the root and depth of the graphics - context do not match those of the drawable. - - An InputOnly window is used as a drawable. - - Some argument or pair of arguments has the correct type and - range, but it fails to match in some other way required by the - request. - - An InputOnly window lacks this attribute. - BadName A font or color of the specified name does not exist. - BadPixmap A value for a pixmap argument does not name a defined - pixmap. - BadRequest The major or minor opcode does not specify a valid - request. This usually is an Xlib or server error. - BadValue Some numeric value falls outside of the range of - values accepted by the request. Unless a specific range is - specified for an argument, the full range defined by the - argument's type is accepted. Any argument defined as a set of - alternatives typically can generate this error (due to the - encoding). - BadWindow A value for a window argument does not name a defined - window. - -Note - - The BadAtom, BadColor, BadCursor, BadDrawable, BadFont, BadGC, - BadPixmap, and BadWindow errors are also used when the argument - type is extended by a set of fixed alternatives. - - To obtain textual descriptions of the specified error code, use - XGetErrorText. - - XGetErrorText(Display *display, int code, char *buffer_return, - int length); - - display - - Specifies the connection to the X server. - - code - - Specifies the error code for which you want to obtain a - description. - - buffer_return - - Returns the error description. - - length - - Specifies the size of the buffer. - - The XGetErrorText function copies a null-terminated string - describing the specified error code into the specified buffer. - The returned text is in the encoding of the current locale. It - is recommended that you use this function to obtain an error - description because extensions to Xlib may define their own - error codes and error strings. - - To obtain error messages from the error database, use - XGetErrorDatabaseText. - - XGetErrorDatabaseText(Display *display, char *name, char - *message, char *default_string, char *buffer_return, int - length); - - display - - Specifies the connection to the X server. - - name - - Specifies the name of the application. - - message - - Specifies the type of the error message. - - default_string - - Specifies the default error message if none is found in the - database. - - buffer_return - - Returns the error description. - - length - - Specifies the size of the buffer. - - The XGetErrorDatabaseText function returns a null-terminated - message (or the default message) from the error message - database. Xlib uses this function internally to look up its - error messages. The text in the default_string argument is - assumed to be in the encoding of the current locale, and the - text stored in the buffer_return argument is in the encoding of - the current locale. - - The name argument should generally be the name of your - application. The message argument should indicate which type of - error message you want. If the name and message are not in the - Host Portable Character Encoding, the result is - implementation-dependent. Xlib uses three predefined - ``application names'' to report errors. In these names, - uppercase and lowercase matter. - - XProtoError - - The protocol error number is used as a string for the message - argument. - - XlibMessage - - These are the message strings that are used internally by the - library. - - XRequest - - For a core protocol request, the major request protocol number - is used for the message argument. For an extension request, the - extension name (as given by InitExtension) followed by a period - (.) and the minor request protocol number is used for the - message argument. If no string is found in the error database, - the default_string is returned to the buffer argument. - - To report an error to the user when the requested display does - not exist, use XDisplayName. - - char *XDisplayName(char *string); - - string - - Specifies the character string. - - The XDisplayName function returns the name of the display that - XOpenDisplay would attempt to use. If a NULL string is - specified, XDisplayName looks in the environment for the - display and returns the display name that XOpenDisplay would - attempt to use. This makes it easier to report to the user - precisely which display the program attempted to open when the - initial connection attempt failed. - - To handle fatal I/O errors, use XSetIOErrorHandler. - - int(int(*handler)(Display *)); - - handler - - Specifies the program's supplied error handler. - - The XSetIOErrorHandler sets the fatal I/O error handler. Xlib - calls the program's supplied error handler if any sort of - system call error occurs (for example, the connection to the - server was lost). This is assumed to be a fatal condition, and - the called routine should not return. If the I/O error handler - does return, the client process exits. - - Note that the previous error handler is returned. - -Chapter 12. Input Device Functions - - Table of Contents - - Pointer Grabbing - Keyboard Grabbing - Resuming Event Processing - Moving the Pointer - Controlling Input Focus - Manipulating the Keyboard and Pointer Settings - Manipulating the Keyboard Encoding - - You can use the Xlib input device functions to: - * Grab the pointer and individual buttons on the pointer - * Grab the keyboard and individual keys on the keyboard - * Resume event processing - * Move the pointer - * Set the input focus - * Manipulate the keyboard and pointer settings - * Manipulate the keyboard encoding - -Pointer Grabbing - - Xlib provides functions that you can use to control input from - the pointer, which usually is a mouse. Usually, as soon as - keyboard and mouse events occur, the X server delivers them to - the appropriate client, which is determined by the window and - input focus. The X server provides sufficient control over - event delivery to allow window managers to support mouse ahead - and various other styles of user interface. Many of these user - interfaces depend on synchronous delivery of events. The - delivery of pointer and keyboard events can be controlled - independently. - - When mouse buttons or keyboard keys are grabbed, events will be - sent to the grabbing client rather than the normal client who - would have received the event. If the keyboard or pointer is in - asynchronous mode, further mouse and keyboard events will - continue to be processed. If the keyboard or pointer is in - synchronous mode, no further events are processed until the - grabbing client allows them (see XAllowEvents). The keyboard or - pointer is considered frozen during this interval. The event - that triggered the grab can also be replayed. - - Note that the logical state of a device (as seen by client - applications) may lag the physical state if device event - processing is frozen. - - There are two kinds of grabs: active and passive. An active - grab occurs when a single client grabs the keyboard and/or - pointer explicitly (see XGrabPointer and XGrabKeyboard). A - passive grab occurs when clients grab a particular keyboard key - or pointer button in a window, and the grab will activate when - the key or button is actually pressed. Passive grabs are - convenient for implementing reliable pop-up menus. For example, - you can guarantee that the pop-up is mapped before the up - pointer button event occurs by grabbing a button requesting - synchronous behavior. The down event will trigger the grab and - freeze further processing of pointer events until you have the - chance to map the pop-up window. You can then allow further - event processing. The up event will then be correctly processed - relative to the pop-up window. - - For many operations, there are functions that take a time - argument. The X server includes a timestamp in various events. - One special time, called CurrentTime, represents the current - server time. The X server maintains the time when the input - focus was last changed, when the keyboard was last grabbed, - when the pointer was last grabbed, or when a selection was last - changed. Your application may be slow reacting to an event. You - often need some way to specify that your request should not - occur if another application has in the meanwhile taken control - of the keyboard, pointer, or selection. By providing the - timestamp from the event in the request, you can arrange that - the operation not take effect if someone else has performed an - operation in the meanwhile. - - A timestamp is a time value, expressed in milliseconds. It - typically is the time since the last server reset. Timestamp - values wrap around (after about 49.7 days). The server, given - its current time is represented by timestamp T, always - interprets timestamps from clients by treating half of the - timestamp space as being later in time than T. One timestamp - value, named CurrentTime, is never generated by the server. - This value is reserved for use in requests to represent the - current server time. - - For many functions in this section, you pass pointer event mask - bits. The valid pointer event mask bits are: ButtonPressMask, - ButtonReleaseMask, EnterWindowMask, LeaveWindowMask, - PointerMotionMask, PointerMotionHintMask, Button1MotionMask, - Button2MotionMask, Button3MotionMask, Button4MotionMask, - Button5MotionMask, ButtonMotionMask, and KeymapStateMask. For - other functions in this section, you pass keymask bits. The - valid keymask bits are: ShiftMask, LockMask, ControlMask, - Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, and Mod5Mask. - - To grab the pointer, use XGrabPointer. - - int XGrabPointer(Display *display, Window grab_window, Bool - owner_events, unsigned int event_mask, int pointer_mode, int - keyboard_mode, Window confine_to, Cursor cursor, Time time); - - display - - Specifies the connection to the X server. - - grab_window - - Specifies the grab window. - - owner_events - - Specifies a Boolean value that indicates whether the pointer - events are to be reported as usual or reported with respect to - the grab window if selected by the event mask. - - event_mask - - Specifies which pointer events are reported to the client. The - mask is the bitwise inclusive OR of the valid pointer event - mask bits. - - pointer_mode - - Specifies further processing of pointer events. You can pass - GrabModeSync or GrabModeAsync. - - keyboard_mode - - Specifies further processing of keyboard events. You can pass - GrabModeSync or GrabModeAsync. - - confine_to - - Specifies the window to confine the pointer in or None. - - cursor - - Specifies the cursor that is to be displayed during the grab or - None. - - time - - Specifies the time. You can pass either a timestamp or - CurrentTime. - - The XGrabPointer function actively grabs control of the pointer - and returns GrabSuccess if the grab was successful. Further - pointer events are reported only to the grabbing client. - XGrabPointer overrides any active pointer grab by this client. - If owner_events is False, all generated pointer events are - reported with respect to grab_window and are reported only if - selected by event_mask. If owner_events is True and if a - generated pointer event would normally be reported to this - client, it is reported as usual. Otherwise, the event is - reported with respect to the grab_window and is reported only - if selected by event_mask. For either value of owner_events, - unreported events are discarded. - - If the pointer_mode is GrabModeAsync, pointer event processing - continues as usual. If the pointer is currently frozen by this - client, the processing of events for the pointer is resumed. If - the pointer_mode is GrabModeSync, the state of the pointer, as - seen by client applications, appears to freeze, and the X - server generates no further pointer events until the grabbing - client calls XAllowEvents or until the pointer grab is - released. Actual pointer changes are not lost while the pointer - is frozen; they are simply queued in the server for later - processing. - - If the keyboard_mode is GrabModeAsync, keyboard event - processing is unaffected by activation of the grab. If the - keyboard_mode is GrabModeSync, the state of the keyboard, as - seen by client applications, appears to freeze, and the X - server generates no further keyboard events until the grabbing - client calls XAllowEvents or until the pointer grab is - released. Actual keyboard changes are not lost while the - pointer is frozen; they are simply queued in the server for - later processing. - - If a cursor is specified, it is displayed regardless of what - window the pointer is in. If None is specified, the normal - cursor for that window is displayed when the pointer is in - grab_window or one of its subwindows; otherwise, the cursor for - grab_window is displayed. - - If a confine_to window is specified, the pointer is restricted - to stay contained in that window. The confine_to window need - have no relationship to the grab_window. If the pointer is not - initially in the confine_to window, it is warped automatically - to the closest edge just before the grab activates and - enter/leave events are generated as usual. If the confine_to - window is subsequently reconfigured, the pointer is warped - automatically, as necessary, to keep it contained in the - window. - - The time argument allows you to avoid certain circumstances - that come up if applications take a long time to respond or if - there are long network delays. Consider a situation where you - have two applications, both of which normally grab the pointer - when clicked on. If both applications specify the timestamp - from the event, the second application may wake up faster and - successfully grab the pointer before the first application. The - first application then will get an indication that the other - application grabbed the pointer before its request was - processed. - - XGrabPointer generates EnterNotify and LeaveNotify events. - - Either if grab_window or confine_to window is not viewable or - if the confine_to window lies completely outside the boundaries - of the root window, XGrabPointer fails and returns - GrabNotViewable. If the pointer is actively grabbed by some - other client, it fails and returns AlreadyGrabbed. If the - pointer is frozen by an active grab of another client, it fails - and returns GrabFrozen. If the specified time is earlier than - the last-pointer-grab time or later than the current X server - time, it fails and returns GrabInvalidTime. Otherwise, the - last-pointer-grab time is set to the specified time - (CurrentTime is replaced by the current X server time). - - XGrabPointer can generate BadCursor, BadValue, and BadWindow - errors. - - To ungrab the pointer, use XUngrabPointer. - - XUngrabPointer(Display *display, Time time); - - display - - Specifies the connection to the X server. - - time - - Specifies the time. You can pass either a timestamp or - CurrentTime. - - The XUngrabPointer function releases the pointer and any queued - events if this client has actively grabbed the pointer from - XGrabPointer, XGrabButton, or from a normal button press. - XUngrabPointer does not release the pointer if the specified - time is earlier than the last-pointer-grab time or is later - than the current X server time. It also generates EnterNotify - and LeaveNotify events. The X server performs an UngrabPointer - request automatically if the event window or confine_to window - for an active pointer grab becomes not viewable or if window - reconfiguration causes the confine_to window to lie completely - outside the boundaries of the root window. - - To change an active pointer grab, use XChangeActivePointerGrab. - - XChangeActivePointerGrab(Display *display, unsigned int - event_mask, Cursor cursor, Time time); - - display - - Specifies the connection to the X server. - - event_mask - - Specifies which pointer events are reported to the client. The - mask is the bitwise inclusive OR of the valid pointer event - mask bits. - - cursor - - Specifies the cursor that is to be displayed or None. - - time - - Specifies the time. You can pass either a timestamp or - CurrentTime. - - The XChangeActivePointerGrab function changes the specified - dynamic parameters if the pointer is actively grabbed by the - client and if the specified time is no earlier than the - last-pointer-grab time and no later than the current X server - time. This function has no effect on the passive parameters of - an XGrabButton. The interpretation of event_mask and cursor is - the same as described in XGrabPointer. - - XChangeActivePointerGrab can generate BadCursor and BadValue - errors. - - To grab a pointer button, use XGrabButton. - - XGrabButton(Display *display, unsigned int button, unsigned int - modifiers, Window grab_window, Bool owner_events, unsigned int - event_mask, int pointer_mode, int keyboard_mode, Window - confine_to, Cursor cursor); - - display - - Specifies the connection to the X server. - - button - - Specifies the pointer button that is to be grabbed or - AnyButton. - - modifiers - - Specifies the set of keymasks or AnyModifier. The mask is the - bitwise inclusive OR of the valid keymask bits. - - grab_window - - Specifies the grab window. - - owner_events - - Specifies a Boolean value that indicates whether the pointer - events are to be reported as usual or reported with respect to - the grab window if selected by the event mask. - - event_mask - - Specifies which pointer events are reported to the client. The - mask is the bitwise inclusive OR of the valid pointer event - mask bits. - - pointer_mode - - Specifies further processing of pointer events. You can pass - GrabModeSync or GrabModeAsync. - - keyboard_mode - - Specifies further processing of keyboard events. You can pass - GrabModeSync or GrabModeAsync. - - confine_to - - Specifies the window to confine the pointer in or None. - - cursor - - Specifies the cursor that is to be displayed or None. - - The XGrabButton function establishes a passive grab. In the - future, the pointer is actively grabbed (as for XGrabPointer), - the last-pointer-grab time is set to the time at which the - button was pressed (as transmitted in the ButtonPress event), - and the ButtonPress event is reported if all of the following - conditions are true: - * The pointer is not grabbed, and the specified button is - logically pressed when the specified modifier keys are - logically down, and no other buttons or modifier keys are - logically down. - * The grab_window contains the pointer. - * The confine_to window (if any) is viewable. - * A passive grab on the same button/key combination does not - exist on any ancestor of grab_window. - - The interpretation of the remaining arguments is as for - XGrabPointer. The active grab is terminated automatically when - the logical state of the pointer has all buttons released - (independent of the state of the logical modifier keys). - - Note that the logical state of a device (as seen by client - applications) may lag the physical state if device event - processing is frozen. - - This request overrides all previous grabs by the same client on - the same button/key combinations on the same window. A - modifiers of AnyModifier is equivalent to issuing the grab - request for all possible modifier combinations (including the - combination of no modifiers). It is not required that all - modifiers specified have currently assigned KeyCodes. A button - of AnyButton is equivalent to issuing the request for all - possible buttons. Otherwise, it is not required that the - specified button currently be assigned to a physical button. - - If some other client has already issued an XGrabButton with the - same button/key combination on the same window, a BadAccess - error results. When using AnyModifier or AnyButton, the request - fails completely, and a BadAccess error results (no grabs are - established) if there is a conflicting grab for any - combination. XGrabButton has no effect on an active grab. - - XGrabButton can generate BadCursor, BadValue, and BadWindow - errors. - - To ungrab a pointer button, use XUngrabButton. - - XUngrabButton(Display *display, unsigned int button, unsigned - int modifiers, Window grab_window); - - display - - Specifies the connection to the X server. - - button - - Specifies the pointer button that is to be released or - AnyButton. - - modifiers - - Specifies the set of keymasks or AnyModifier. The mask is the - bitwise inclusive OR of the valid keymask bits. - - grab_window - - Specifies the grab window. - - The XUngrabButton function releases the passive button/key - combination on the specified window if it was grabbed by this - client. A modifiers of AnyModifier is equivalent to issuing the - ungrab request for all possible modifier combinations, - including the combination of no modifiers. A button of - AnyButton is equivalent to issuing the request for all possible - buttons. XUngrabButton has no effect on an active grab. - - XUngrabButton can generate BadValue and BadWindow errors. - -Keyboard Grabbing - - Xlib provides functions that you can use to grab or ungrab the - keyboard as well as allow events. - - For many functions in this section, you pass keymask bits. The - valid keymask bits are: ShiftMask, LockMask, ControlMask, - Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, and Mod5Mask. - - To grab the keyboard, use XGrabKeyboard. - - int XGrabKeyboard(Display *display, Window grab_window, Bool - owner_events, int pointer_mode, int keyboard_mode, Time time); - - display - - Specifies the connection to the X server. - - grab_window - - Specifies the grab window. - - owner_events - - Specifies a Boolean value that indicates whether the keyboard - events are to be reported as usual. - - pointer_mode - - Specifies further processing of pointer events. You can pass - GrabModeSync or GrabModeAsync. - - keyboard_mode - - Specifies further processing of keyboard events. You can pass - GrabModeSync or GrabModeAsync. - - time - - Specifies the time. You can pass either a timestamp or - CurrentTime. - - The XGrabKeyboard function actively grabs control of the - keyboard and generates FocusIn and FocusOut events. Further key - events are reported only to the grabbing client. XGrabKeyboard - overrides any active keyboard grab by this client. If - owner_events is False, all generated key events are reported - with respect to grab_window. If owner_events is True and if a - generated key event would normally be reported to this client, - it is reported normally; otherwise, the event is reported with - respect to the grab_window. Both KeyPress and KeyRelease events - are always reported, independent of any event selection made by - the client. - - If the keyboard_mode argument is GrabModeAsync, keyboard event - processing continues as usual. If the keyboard is currently - frozen by this client, then processing of keyboard events is - resumed. If the keyboard_mode argument is GrabModeSync, the - state of the keyboard (as seen by client applications) appears - to freeze, and the X server generates no further keyboard - events until the grabbing client issues a releasing - XAllowEvents call or until the keyboard grab is released. - Actual keyboard changes are not lost while the keyboard is - frozen; they are simply queued in the server for later - processing. - - If pointer_mode is GrabModeAsync, pointer event processing is - unaffected by activation of the grab. If pointer_mode is - GrabModeSync, the state of the pointer (as seen by client - applications) appears to freeze, and the X server generates no - further pointer events until the grabbing client issues a - releasing XAllowEvents call or until the keyboard grab is - released. Actual pointer changes are not lost while the pointer - is frozen; they are simply queued in the server for later - processing. - - If the keyboard is actively grabbed by some other client, - XGrabKeyboard fails and returns AlreadyGrabbed. If grab_window - is not viewable, it fails and returns GrabNotViewable. If the - keyboard is frozen by an active grab of another client, it - fails and returns GrabFrozen. If the specified time is earlier - than the last-keyboard-grab time or later than the current X - server time, it fails and returns GrabInvalidTime. Otherwise, - the last-keyboard-grab time is set to the specified time - (CurrentTime is replaced by the current X server time). - - XGrabKeyboard can generate BadValue and BadWindow errors. - - To ungrab the keyboard, use XUngrabKeyboard. - - XUngrabKeyboard(Display *display, Time time); - - display - - Specifies the connection to the X server. - - time - - Specifies the time. You can pass either a timestamp or - CurrentTime. - - The XUngrabKeyboard function releases the keyboard and any - queued events if this client has it actively grabbed from - either XGrabKeyboard or XGrabKey. XUngrabKeyboard does not - release the keyboard and any queued events if the specified - time is earlier than the last-keyboard-grab time or is later - than the current X server time. It also generates FocusIn and - FocusOut events. The X server automatically performs an - UngrabKeyboard request if the event window for an active - keyboard grab becomes not viewable. - - To passively grab a single key of the keyboard, use XGrabKey. - - XGrabKey(Display *display, int keycode, unsigned int modifiers, - Window grab_window, Bool owner_events, int pointer_mode, int - keyboard_mode); - - display - - Specifies the connection to the X server. - - keycode - - Specifies the KeyCode or AnyKey. - - modifiers - - Specifies the set of keymasks or AnyModifier. The mask is the - bitwise inclusive OR of the valid keymask bits. - - grab_window - - Specifies the grab window. - - owner_events - - Specifies a Boolean value that indicates whether the keyboard - events are to be reported as usual. - - pointer_mode - - Specifies further processing of pointer events. You can pass - GrabModeSync or GrabModeAsync. - - keyboard_mode - - Specifies further processing of keyboard events. You can pass - GrabModeSync or GrabModeAsync. - - The XGrabKey function establishes a passive grab on the - keyboard. In the future, the keyboard is actively grabbed (as - for XGrabKeyboard), the last-keyboard-grab time is set to the - time at which the key was pressed (as transmitted in the - KeyPress event), and the KeyPress event is reported if all of - the following conditions are true: - * The keyboard is not grabbed and the specified key (which - can itself be a modifier key) is logically pressed when the - specified modifier keys are logically down, and no other - modifier keys are logically down. - * Either the grab_window is an ancestor of (or is) the focus - window, or the grab_window is a descendant of the focus - window and contains the pointer. - * A passive grab on the same key combination does not exist - on any ancestor of grab_window. - - The interpretation of the remaining arguments is as for - XGrabKeyboard. The active grab is terminated automatically when - the logical state of the keyboard has the specified key - released (independent of the logical state of the modifier - keys). - - Note that the logical state of a device (as seen by client - applications) may lag the physical state if device event - processing is frozen. - - A modifiers argument of AnyModifier is equivalent to issuing - the request for all possible modifier combinations (including - the combination of no modifiers). It is not required that all - modifiers specified have currently assigned KeyCodes. A keycode - argument of AnyKey is equivalent to issuing the request for all - possible KeyCodes. Otherwise, the specified keycode must be in - the range specified by min_keycode and max_keycode in the - connection setup, or a BadValue error results. - - If some other client has issued a XGrabKey with the same key - combination on the same window, a BadAccess error results. When - using AnyModifier or AnyKey, the request fails completely, and - a BadAccess error results (no grabs are established) if there - is a conflicting grab for any combination. - - XGrabKey can generate BadAccess, BadValue, and BadWindow - errors. - - To ungrab a key, use XUngrabKey. - - XUngrabKey(Display *display, int keycode, unsigned int - modifiers, Window grab_window); - - display - - Specifies the connection to the X server. - - keycode - - Specifies the KeyCode or AnyKey. - - modifiers - - Specifies the set of keymasks or AnyModifier. The mask is the - bitwise inclusive OR of the valid keymask bits. - - grab_window - - Specifies the grab window. - - The XUngrabKey function releases the key combination on the - specified window if it was grabbed by this client. It has no - effect on an active grab. A modifiers of AnyModifier is - equivalent to issuing the request for all possible modifier - combinations (including the combination of no modifiers). A - keycode argument of AnyKey is equivalent to issuing the request - for all possible key codes. - - XUngrabKey can generate BadValue and BadWindow errors. - -Resuming Event Processing - - The previous sections discussed grab mechanisms with which - processing of events by the server can be temporarily - suspended. This section describes the mechanism for resuming - event processing. - - To allow further events to be processed when the device has - been frozen, use XAllowEvents. - - XAllowEvents(Display *display, int event_mode, Time time); - - display - - Specifies the connection to the X server. - - event_mode - - Specifies the event mode. You can pass AsyncPointer, - SyncPointer, AsyncKeyboard, SyncKeyboard, ReplayPointer, - ReplayKeyboard, AsyncBoth, or SyncBoth. - - time - - Specifies the time. You can pass either a timestamp or - CurrentTime. - - The XAllowEvents function releases some queued events if the - client has caused a device to freeze. It has no effect if the - specified time is earlier than the last-grab time of the most - recent active grab for the client or if the specified time is - later than the current X server time. Depending on the - event_mode argument, the following occurs: - AsyncPointer If the pointer is frozen by the client, pointer - event processing continues as usual. If the pointer is frozen - twice by the client on behalf of two separate grabs, - AsyncPointer thaws for both. AsyncPointer has no effect if the - pointer is not frozen by the client, but the pointer need not - be grabbed by the client. - SyncPointer If the pointer is frozen and actively grabbed by - the client, pointer event processing continues as usual until - the next ButtonPress or ButtonRelease event is reported to the - client. At this time, the pointer again appears to freeze. - However, if the reported event causes the pointer grab to be - released, the pointer does not freeze. SyncPointer has no - effect if the pointer is not frozen by the client or if the - pointer is not grabbed by the client. - ReplayPointer If the pointer is actively grabbed by the client - and is frozen as the result of an event having been sent to the - client (either from the activation of an XGrabButton or from a - previous XAllowEvents with mode SyncPointer but not from an - XGrabPointer), the pointer grab is released and that event is - completely reprocessed. This time, however, the function - ignores any passive grabs at or above (toward the root of) the - grab_window of the grab just released. The request has no - effect if the pointer is not grabbed by the client or if the - pointer is not frozen as the result of an event. - AsyncKeyboard If the keyboard is frozen by the client, keyboard - event processing continues as usual. If the keyboard is frozen - twice by the client on behalf of two separate grabs, - AsyncKeyboard thaws for both. AsyncKeyboard has no effect if - the keyboard is not frozen by the client, but the keyboard need - not be grabbed by the client. - SyncKeyboard If the keyboard is frozen and actively grabbed by - the client, keyboard event processing continues as usual until - the next KeyPress or KeyRelease event is reported to the - client. At this time, the keyboard again appears to freeze. - However, if the reported event causes the keyboard grab to be - released, the keyboard does not freeze. SyncKeyboard has no - effect if the keyboard is not frozen by the client or if the - keyboard is not grabbed by the client. - ReplayKeyboard If the keyboard is actively grabbed by the - client and is frozen as the result of an event having been sent - to the client (either from the activation of an XGrabKey or - from a previous XAllowEvents with mode SyncKeyboard but not - from an XGrabKeyboard), the keyboard grab is released and that - event is completely reprocessed. This time, however, the - function ignores any passive grabs at or above (toward the root - of) the grab_window of the grab just released. The request has - no effect if the keyboard is not grabbed by the client or if - the keyboard is not frozen as the result of an event. - SyncBoth If both pointer and keyboard are frozen by the client, - event processing for both devices continues as usual until the - next ButtonPress, ButtonRelease, KeyPress, or KeyRelease event - is reported to the client for a grabbed device (button event - for the pointer, key event for the keyboard), at which time the - devices again appear to freeze. However, if the reported event - causes the grab to be released, then the devices do not freeze - (but if the other device is still grabbed, then a subsequent - event for it will still cause both devices to freeze). SyncBoth - has no effect unless both pointer and keyboard are frozen by - the client. If the pointer or keyboard is frozen twice by the - client on behalf of two separate grabs, SyncBoth thaws for both - (but a subsequent freeze for SyncBoth will only freeze each - device once). - AsyncBoth If the pointer and the keyboard are frozen by the - client, event processing for both devices continues as usual. - If a device is frozen twice by the client on behalf of two - separate grabs, AsyncBoth thaws for both. AsyncBoth has no - effect unless both pointer and keyboard are frozen by the - client. - - AsyncPointer, SyncPointer, and ReplayPointer have no effect on - the processing of keyboard events. AsyncKeyboard, SyncKeyboard, - and ReplayKeyboard have no effect on the processing of pointer - events. It is possible for both a pointer grab and a keyboard - grab (by the same or different clients) to be active - simultaneously. If a device is frozen on behalf of either grab, - no event processing is performed for the device. It is possible - for a single device to be frozen because of both grabs. In this - case, the freeze must be released on behalf of both grabs - before events can again be processed. If a device is frozen - twice by a single client, then a single XAllowEvents releases - both. - - XAllowEvents can generate a BadValue error. - -Moving the Pointer - - Although movement of the pointer normally should be left to the - control of the end user, sometimes it is necessary to move the - pointer to a new position under program control. - - To move the pointer to an arbitrary point in a window, use - XWarpPointer. - - XWarpPointer(Display *display, Window src_w, Window dest_w, int - src_x, int src_y, unsigned int src_width, unsigned int - src_height, int dest_x, int dest_y); - - display - - Specifies the connection to the X server. - - src_w - - Specifies the source window or None. - - dest_w - - Specifies the destination window or None. - - src_x - - src_y - - src_width - - src_height - - Specify a rectangle in the source window. - - dest_x - - dest_y - - Specify the x and y coordinates within the destination window. - - If dest_w is None, XWarpPointer moves the pointer by the - offsets (dest_x, dest_y) relative to the current position of - the pointer. If dest_w is a window, XWarpPointer moves the - pointer to the offsets (dest_x, dest_y) relative to the origin - of dest_w. However, if src_w is a window, the move only takes - place if the window src_w contains the pointer and if the - specified rectangle of src_w contains the pointer. - - The src_x and src_y coordinates are relative to the origin of - src_w. If src_height is zero, it is replaced with the current - height of src_w minus src_y. If src_width is zero, it is - replaced with the current width of src_w minus src_x. - - There is seldom any reason for calling this function. The - pointer should normally be left to the user. If you do use this - function, however, it generates events just as if the user had - instantaneously moved the pointer from one position to another. - Note that you cannot use XWarpPointer to move the pointer - outside the confine_to window of an active pointer grab. An - attempt to do so will only move the pointer as far as the - closest edge of the confine_to window. - - XWarpPointer can generate a BadWindow error. - -Controlling Input Focus - - Xlib provides functions that you can use to set and get the - input focus. The input focus is a shared resource, and - cooperation among clients is required for correct interaction. - See the Inter-Client Communication Conventions Manual for input - focus policy. - - To set the input focus, use XSetInputFocus. - - XSetInputFocus(Display *display, Window focus, int revert_to, - Time time); - - display - - Specifies the connection to the X server. - - focus - - Specifies the window, PointerRoot, or None. - - revert_to - - Specifies where the input focus reverts to if the window - becomes not viewable. You can pass RevertToParent, - RevertToPointerRoot, or RevertToNone. - - time - - Specifies the time. You can pass either a timestamp or - CurrentTime. - - The XSetInputFocus function changes the input focus and the - last-focus-change time. It has no effect if the specified time - is earlier than the current last-focus-change time or is later - than the current X server time. Otherwise, the - last-focus-change time is set to the specified time - (CurrentTime is replaced by the current X server time). - XSetInputFocus causes the X server to generate FocusIn and - FocusOut events. - - Depending on the focus argument, the following occurs: - * If focus is None, all keyboard events are discarded until a - new focus window is set, and the revert_to argument is - ignored. - * If focus is a window, it becomes the keyboard's focus - window. If a generated keyboard event would normally be - reported to this window or one of its inferiors, the event - is reported as usual. Otherwise, the event is reported - relative to the focus window. - * If focus is PointerRoot, the focus window is dynamically - taken to be the root window of whatever screen the pointer - is on at each keyboard event. In this case, the revert_to - argument is ignored. - - The specified focus window must be viewable at the time - XSetInputFocus is called, or a BadMatch error results. If the - focus window later becomes not viewable, the X server evaluates - the revert_to argument to determine the new focus window as - follows: - * If revert_to is RevertToParent, the focus reverts to the - parent (or the closest viewable ancestor), and the new - revert_to value is taken to be RevertToNone. - * If revert_to is RevertToPointerRoot or RevertToNone, the - focus reverts to PointerRoot or None, respectively. When - the focus reverts, the X server generates FocusIn and - FocusOut events, but the last-focus-change time is not - affected. - - XSetInputFocus can generate BadMatch, BadValue, and BadWindow - errors. - - To obtain the current input focus, use XGetInputFocus. - - XGetInputFocus(Display *display, Window *focus_return, int - *revert_to_return); - - display - - Specifies the connection to the X server. - - focus_return - - Returns the focus window, PointerRoot, or None. - - revert_to_return - - Returns the current focus state (RevertToParent, - RevertToPointerRoot, or RevertToNone). - - The XGetInputFocus function returns the focus window and the - current focus state. - -Manipulating the Keyboard and Pointer Settings - - Xlib provides functions that you can use to change the keyboard - control, obtain a list of the auto-repeat keys, turn keyboard - auto-repeat on or off, ring the bell, set or obtain the pointer - button or keyboard mapping, and obtain a bit vector for the - keyboard. - - This section discusses the user-preference options of bell, key - click, pointer behavior, and so on. The default values for many - of these options are server dependent. Not all implementations - will actually be able to control all of these parameters. - - The XChangeKeyboardControl function changes control of a - keyboard and operates on a XKeyboardControl structure: -/* Mask bits for ChangeKeyboardControl */ - - -#define KBBellPercent (1L<<0) -#define KBBellPitch (1L<<1) -#define KBBellDuration (1L<<2) -#define KBLed (1L<<3) -#define KBLedMode (1L<<4) -#define KBKey (1L<<5) -#define KBAutoRepeatMode (1L<<6) - - -/* Values */ - -typedef struct { -int key_click_percent; -int bell_percent; -int bell_pitch; -int bell_duration; -int led; -int led_mode; /* LedModeOn, LedModeOff */ -int key; -int auto_repeat_mode; /* AutoRepeatModeOff, AutoRepeatModeOn, - AutoRepeatModeDefault */ -} XKeyboardControl; - - - The key_click_percent member sets the volume for key clicks - between 0 (off) and 100 (loud) inclusive, if possible. A - setting of -1 restores the default. Other negative values - generate a BadValue error. - - The bell_percent sets the base volume for the bell between 0 - (off) and 100 (loud) inclusive, if possible. A setting of -1 - restores the default. Other negative values generate a BadValue - error. The bell_pitch member sets the pitch (specified in Hz) - of the bell, if possible. A setting of -1 restores the default. - Other negative values generate a BadValue error. The - bell_duration member sets the duration of the bell specified in - milliseconds, if possible. A setting of -1 restores the - default. Other negative values generate a BadValue error. - - If both the led_mode and led members are specified, the state - of that LED is changed, if possible. The led_mode member can be - set to LedModeOn or LedModeOff. If only led_mode is specified, - the state of all LEDs are changed, if possible. At most 32 LEDs - numbered from one are supported. No standard interpretation of - LEDs is defined. If led is specified without led_mode, a - BadMatch error results. - - If both the auto_repeat_mode and key members are specified, the - auto_repeat_mode of that key is changed (according to - AutoRepeatModeOn, AutoRepeatModeOff, or AutoRepeatModeDefault), - if possible. If only auto_repeat_mode is specified, the global - auto_repeat_mode for the entire keyboard is changed, if - possible, and does not affect the per-key settings. If a key is - specified without an auto_repeat_mode, a BadMatch error - results. Each key has an individual mode of whether or not it - should auto-repeat and a default setting for the mode. In - addition, there is a global mode of whether auto-repeat should - be enabled or not and a default setting for that mode. When - global mode is AutoRepeatModeOn, keys should obey their - individual auto-repeat modes. When global mode is - AutoRepeatModeOff, no keys should auto-repeat. An - auto-repeating key generates alternating KeyPress and - KeyRelease events. When a key is used as a modifier, it is - desirable for the key not to auto-repeat, regardless of its - auto-repeat setting. - - A bell generator connected with the console but not directly on - a keyboard is treated as if it were part of the keyboard. The - order in which controls are verified and altered is - server-dependent. If an error is generated, a subset of the - controls may have been altered. - - XChangeKeyboardControl(Display *display, unsigned long - value_mask, XKeyboardControl *values); - - display - - Specifies the connection to the X server. - - value_mask - - Specifies which controls to change. This mask is the bitwise - inclusive OR of the valid control mask bits. - - values - - Specifies one value for each bit set to 1 in the mask. - - The XChangeKeyboardControl function controls the keyboard - characteristics defined by the XKeyboardControl structure. The - value_mask argument specifies which values are to be changed. - - XChangeKeyboardControl can generate BadMatch and BadValue - errors. - - To obtain the current control values for the keyboard, use - XGetKeyboardControl. - - XGetKeyboardControl(Display *display, XKeyboardState - *values_return); - - display - - Specifies the connection to the X server. - - values_return - - Returns the current keyboard controls in the specified - XKeyboardState structure. - - The XGetKeyboardControl function returns the current control - values for the keyboard to the XKeyboardState structure. - - - -typedef struct { - int key_click_percent; - int bell_percent; - unsigned int bell_pitch, bell_duration; - unsigned long led_mask; - int global_auto_repeat; - char auto_repeats[32]; -} XKeyboardState; - - For the LEDs, the least significant bit of led_mask corresponds - to LED one, and each bit set to 1 in led_mask indicates an LED - that is lit. The global_auto_repeat member can be set to - AutoRepeatModeOn or AutoRepeatModeOff. The auto_repeats member - is a bit vector. Each bit set to 1 indicates that auto-repeat - is enabled for the corresponding key. The vector is represented - as 32 bytes. Byte N (from 0) contains the bits for keys 8N to - 8N + 7 with the least significant bit in the byte representing - key 8N. - - To turn on keyboard auto-repeat, use XAutoRepeatOn. - - XAutoRepeatOn(Display *display); - - display - - Specifies the connection to the X server. - - The XAutoRepeatOn function turns on auto-repeat for the - keyboard on the specified display. - - To turn off keyboard auto-repeat, use XAutoRepeatOff. - - XAutoRepeatOff(Display *display); - - display - - Specifies the connection to the X server. - - The XAutoRepeatOff function turns off auto-repeat for the - keyboard on the specified display. - - To ring the bell, use XBell. - - XBell(Display *display, int percent); - - display - - Specifies the connection to the X server. - - percent - - Specifies the volume for the bell, which can range from -100 to - 100 inclusive. - - The XBell function rings the bell on the keyboard on the - specified display, if possible. The specified volume is - relative to the base volume for the keyboard. If the value for - the percent argument is not in the range -100 to 100 inclusive, - a BadValue error results. The volume at which the bell rings - when the percent argument is nonnegative is: - * base - [(base * percent) / 100] + percent - - The volume at which the bell rings when the percent argument is - negative is: - * base + [(base * percent) / 100] - - To change the base volume of the bell, use - XChangeKeyboardControl. - - XBell can generate a BadValue error. - - To obtain a bit vector that describes the state of the - keyboard, use XQueryKeymap. - - XQueryKeymap(Display *display, char keys_return[32]); - - display - - Specifies the connection to the X server. - - keys_return - - Returns an array of bytes that identifies which keys are - pressed down. Each bit represents one key of the keyboard. - - The XQueryKeymap function returns a bit vector for the logical - state of the keyboard, where each bit set to 1 indicates that - the corresponding key is currently pressed down. The vector is - represented as 32 bytes. Byte N (from 0) contains the bits for - keys 8N to 8N + 7 with the least significant bit in the byte - representing key 8N. - - Note that the logical state of a device (as seen by client - applications) may lag the physical state if device event - processing is frozen. - - To set the mapping of the pointer buttons, use - XSetPointerMapping. - - int XSetPointerMapping(Display *display, unsignedchar map[], - int nmap); - - display - - Specifies the connection to the X server. - - map - - Specifies the mapping list. - - nmap - - Specifies the number of items in the mapping list. - - The XSetPointerMapping function sets the mapping of the - pointer. If it succeeds, the X server generates a MappingNotify - event, and XSetPointerMapping returns MappingSuccess. Element - map[i] defines the logical button number for the physical - button i+1. The length of the list must be the same as - XGetPointerMapping would return, or a BadValue error results. A - zero element disables a button, and elements are not restricted - in value by the number of physical buttons. However, no two - elements can have the same nonzero value, or a BadValue error - results. If any of the buttons to be altered are logically in - the down state, XSetPointerMapping returns MappingBusy, and the - mapping is not changed. - - XSetPointerMapping can generate a BadValue error. - - To get the pointer mapping, use XGetPointerMapping. - - int XGetPointerMapping(Display *display, unsignedchar - map_return[], int nmap); - - display - - Specifies the connection to the X server. - - map_return - - Returns the mapping list. - - nmap - - Specifies the number of items in the mapping list. - - The XGetPointerMapping function returns the current mapping of - the pointer. Pointer buttons are numbered starting from one. - XGetPointerMapping returns the number of physical buttons - actually on the pointer. The nominal mapping for a pointer is - map[i]=i+1. The nmap argument specifies the length of the array - where the pointer mapping is returned, and only the first nmap - elements are returned in map_return. - - To control the pointer's interactive feel, use - XChangePointerControl. - - XChangePointerControl(Display *display, Bool do_accel, Bool - do_threshold, int accel_numerator, int accel_denominator, int - threshold); - - display - - Specifies the connection to the X server. - - do_accel - - Specifies a Boolean value that controls whether the values for - the accel_numerator or accel_denominator are used. - - do_threshold - - Specifies a Boolean value that controls whether the value for - the threshold is used. - - accel_numerator - - Specifies the numerator for the acceleration multiplier. - - accel_denominator - - Specifies the denominator for the acceleration multiplier. - - threshold - - Specifies the acceleration threshold. - - The XChangePointerControl function defines how the pointing - device moves. The acceleration, expressed as a fraction, is a - multiplier for movement. For example, specifying 3/1 means the - pointer moves three times as fast as normal. The fraction may - be rounded arbitrarily by the X server. Acceleration only takes - effect if the pointer moves more than threshold pixels at once - and only applies to the amount beyond the value in the - threshold argument. Setting a value to -1 restores the default. - The values of the do_accel and do_threshold arguments must be - True for the pointer values to be set, or the parameters are - unchanged. Negative values (other than -1) generate a BadValue - error, as does a zero value for the accel_denominator argument. - - XChangePointerControl can generate a BadValue error. - - To get the current pointer parameters, use XGetPointerControl. - - XGetPointerControl(Display *display, int - *accel_numerator_return, int *accel_denominator_return, int - *threshold_return); - - display - - Specifies the connection to the X server. - - accel_numerator_return - - Returns the numerator for the acceleration multiplier. - - accel_denominator_return - - Returns the denominator for the acceleration multiplier. - - threshold_return - - Returns the acceleration threshold. - - The XGetPointerControl function returns the pointer's current - acceleration multiplier and acceleration threshold. - -Manipulating the Keyboard Encoding - - A KeyCode represents a physical (or logical) key. KeyCodes lie - in the inclusive range [8,255]. A KeyCode value carries no - intrinsic information, although server implementors may attempt - to encode geometry (for example, matrix) information in some - fashion so that it can be interpreted in a server-dependent - fashion. The mapping between keys and KeyCodes cannot be - changed. - - A KeySym is an encoding of a symbol on the cap of a key. The - set of defined KeySyms includes the ISO Latin character sets - (1-4), Katakana, Arabic, Cyrillic, Greek, Technical, Special, - Publishing, APL, Hebrew, Thai, Korean and a miscellany of keys - found on keyboards (Return, Help, Tab, and so on). To the - extent possible, these sets are derived from international - standards. In areas where no standards exist, some of these - sets are derived from Digital Equipment Corporation standards. - The list of defined symbols can be found in . - Unfortunately, some C preprocessors have limits on the number - of defined symbols. If you must use KeySyms not in the Latin - 1-4, Greek, and miscellaneous classes, you may have to define a - symbol for those sets. Most applications usually only include - , which defines symbols for ISO Latin 1-4, Greek, - and miscellaneous. - - A list of KeySyms is associated with each KeyCode. The list is - intended to convey the set of symbols on the corresponding key. - If the list (ignoring trailing NoSymbol entries) is a single - KeySym ``K'', then the list is treated as if it were the list - ``K NoSymbol K NoSymbol''. If the list (ignoring trailing - NoSymbol entries) is a pair of KeySyms ``K1 K2'', then the list - is treated as if it were the list ``K1 K2 K1 K2''. If the list - (ignoring trailing NoSymbol entries) is a triple of KeySyms - ``K1 K2 K3'', then the list is treated as if it were the list - ``K1 K2 K3 NoSymbol''. When an explicit ``void'' element is - desired in the list, the value VoidSymbol can be used. - - The first four elements of the list are split into two groups - of KeySyms. Group 1 contains the first and second KeySyms; - Group 2 contains the third and fourth KeySyms. Within each - group, if the second element of the group is NoSymbol, then the - group should be treated as if the second element were the same - as the first element, except when the first element is an - alphabetic KeySym ``K'' for which both lowercase and uppercase - forms are defined. In that case, the group should be treated as - if the first element were the lowercase form of ``K'' and the - second element were the uppercase form of ``K''. - - The standard rules for obtaining a KeySym from a KeyPress event - make use of only the Group 1 and Group 2 KeySyms; no - interpretation of other KeySyms in the list is given. Which - group to use is determined by the modifier state. Switching - between groups is controlled by the KeySym named MODE SWITCH, - by attaching that KeySym to some KeyCode and attaching that - KeyCode to any one of the modifiers Mod1 through Mod5. This - modifier is called the group modifier. For any KeyCode, Group 1 - is used when the group modifier is off, and Group 2 is used - when the group modifier is on. - - The Lock modifier is interpreted as CapsLock when the KeySym - named XK_Caps_Lock is attached to some KeyCode and that KeyCode - is attached to the Lock modifier. The Lock modifier is - interpreted as ShiftLock when the KeySym named XK_Shift_Lock is - attached to some KeyCode and that KeyCode is attached to the - Lock modifier. If the Lock modifier could be interpreted as - both CapsLock and ShiftLock, the CapsLock interpretation is - used. - - The operation of keypad keys is controlled by the KeySym named - XK_Num_Lock, by attaching that KeySym to some KeyCode and - attaching that KeyCode to any one of the modifiers Mod1 through - Mod5. This modifier is called the numlock modifier. The - standard KeySyms with the prefix ``XK_KP_'' in their name are - called keypad KeySyms; these are KeySyms with numeric value in - the hexadecimal range 0xFF80 to 0xFFBD inclusive. In addition, - vendor-specific KeySyms in the hexadecimal range 0x11000000 to - 0x1100FFFF are also keypad KeySyms. - - Within a group, the choice of KeySym is determined by applying - the first rule that is satisfied from the following list: - * The numlock modifier is on and the second KeySym is a - keypad KeySym. In this case, if the Shift modifier is on, - or if the Lock modifier is on and is interpreted as - ShiftLock, then the first KeySym is used, otherwise the - second KeySym is used. - * The Shift and Lock modifiers are both off. In this case, - the first KeySym is used. - * The Shift modifier is off, and the Lock modifier is on and - is interpreted as CapsLock. In this case, the first KeySym - is used, but if that KeySym is lowercase alphabetic, then - the corresponding uppercase KeySym is used instead. - * The Shift modifier is on, and the Lock modifier is on and - is interpreted as CapsLock. In this case, the second KeySym - is used, but if that KeySym is lowercase alphabetic, then - the corresponding uppercase KeySym is used instead. - * The Shift modifier is on, or the Lock modifier is on and is - interpreted as ShiftLock, or both. In this case, the second - KeySym is used. - - No spatial geometry of the symbols on the key is defined by - their order in the KeySym list, although a geometry might be - defined on a server-specific basis. The X server does not use - the mapping between KeyCodes and KeySyms. Rather, it merely - stores it for reading and writing by clients. - - To obtain the legal KeyCodes for a display, use - XDisplayKeycodes. - - XDisplayKeycodes(Display *display, int *min_keycodes_return, - int *max_keycodes_return); - - display - - Specifies the connection to the X server. - - min_keycodes_return - - Returns the minimum number of KeyCodes. - - max_keycodes_return - - Returns the maximum number of KeyCodes. - - The XDisplayKeycodes function returns the min-keycodes and - max-keycodes supported by the specified display. The minimum - number of KeyCodes returned is never less than 8, and the - maximum number of KeyCodes returned is never greater than 255. - Not all KeyCodes in this range are required to have - corresponding keys. - - To obtain the symbols for the specified KeyCodes, use - XGetKeyboardMapping. - - KeySym *XGetKeyboardMapping(Display *display, KeyCode - first_keycode, int keycode_count, int - *keysyms_per_keycode_return); - - display - - Specifies the connection to the X server. - - first_keycode - - Specifies the first KeyCode that is to be returned. - - keycode_count - - Specifies the number of KeyCodes that are to be returned. - - keysyms_per_keycode_return - - Returns the number of KeySyms per KeyCode. - - The XGetKeyboardMapping function returns the symbols for the - specified number of KeyCodes starting with first_keycode. The - value specified in first_keycode must be greater than or equal - to min_keycode as returned by XDisplayKeycodes, or a BadValue - error results. In addition, the following expression must be - less than or equal to max_keycode as returned by - XDisplayKeycodes: - -first_keycode + keycode_count - 1 - - If this is not the case, a BadValue error results. The number - of elements in the KeySyms list is: - -keycode_count * keysyms_per_keycode_return - - KeySym number N, counting from zero, for KeyCode K has the - following index in the list, counting from zero: -(K - first_code) * keysyms_per_code_return + N - - The X server arbitrarily chooses the keysyms_per_keycode_return - value to be large enough to report all requested symbols. A - special KeySym value of NoSymbol is used to fill in unused - elements for individual KeyCodes. To free the storage returned - by XGetKeyboardMapping, use XFree. - - XGetKeyboardMapping can generate a BadValue error. - - To change the keyboard mapping, use XChangeKeyboardMapping. - - XChangeKeyboardMapping(Display *display, int first_keycode, int - keysyms_per_keycode, KeySym *keysyms, int num_codes); - - display - - Specifies the connection to the X server. - - first_keycode - - Specifies the first KeyCode that is to be changed. - - keysyms_per_keycode - - Specifies the number of KeySyms per KeyCode. - - keysyms - - Specifies an array of KeySyms. - - num_codes - - Specifies the number of KeyCodes that are to be changed. - - The XChangeKeyboardMapping function defines the symbols for the - specified number of KeyCodes starting with first_keycode. The - symbols for KeyCodes outside this range remain unchanged. The - number of elements in keysyms must be: - -num_codes * keysyms_per_keycode - - The specified first_keycode must be greater than or equal to - min_keycode returned by XDisplayKeycodes, or a BadValue error - results. In addition, the following expression must be less - than or equal to max_keycode as returned by XDisplayKeycodes, - or a BadValue error results: - -first_keycode + num_codes - 1 - - KeySym number N, counting from zero, for KeyCode K has the - following index in keysyms, counting from zero: - -(K - first_keycode) * keysyms_per_keycode + N - - The specified keysyms_per_keycode can be chosen arbitrarily by - the client to be large enough to hold all desired symbols. A - special KeySym value of NoSymbol should be used to fill in - unused elements for individual KeyCodes. It is legal for - NoSymbol to appear in nontrailing positions of the effective - list for a KeyCode. XChangeKeyboardMapping generates a - MappingNotify event. - - There is no requirement that the X server interpret this - mapping. It is merely stored for reading and writing by - clients. - - XChangeKeyboardMapping can generate BadAlloc and BadValue - errors. - - The next six functions make use of the XModifierKeymap data - structure, which contains: - - - -typedef struct { - int max_keypermod; /* This server's max number of keys per -modifier */ - KeyCode *modifiermap; /* An 8 by max_keypermod array of the mo -difiers */ -} XModifierKeymap; - - To create an XModifierKeymap structure, use XNewModifiermap. - - XModifierKeymap *XNewModifiermap(int max_keys_per_mod); - - max_keys_per_mod - - Specifies the number of KeyCode entries preallocated to the - modifiers in the map. - - The XNewModifiermap function returns a pointer to - XModifierKeymap structure for later use. - - To add a new entry to an XModifierKeymap structure, use - XInsertModifiermapEntry. - - XModifierKeymap *XInsertModifiermapEntry(XModifierKeymap - *modmap, KeyCode keycode_entry, int modifier); - - modmap - - Specifies the XModifierKeymap structure. - - keycode_entry - - Specifies the KeyCode. - - modifier - - Specifies the modifier. - - The XInsertModifiermapEntry function adds the specified KeyCode - to the set that controls the specified modifier and returns the - resulting XModifierKeymap structure (expanded as needed). - - To delete an entry from an XModifierKeymap structure, use - XDeleteModifiermapEntry. - - XModifierKeymap *XDeleteModifiermapEntry(XModifierKeymap - *modmap, KeyCode keycode_entry, int modifier); - - modmap - - Specifies the XModifierKeymap structure. - - keycode_entry - - Specifies the KeyCode. - - modifier - - Specifies the modifier. - - The XDeleteModifiermapEntry function deletes the specified - KeyCode from the set that controls the specified modifier and - returns a pointer to the resulting XModifierKeymap structure. - - To destroy an XModifierKeymap structure, use XFreeModifiermap. - - XFreeModifiermap(XModifierKeymap *modmap); - - modmap - - Specifies the XModifierKeymap structure. - - The XFreeModifiermap function frees the specified - XModifierKeymap structure. - - To set the KeyCodes to be used as modifiers, use - XSetModifierMapping. - - int XSetModifierMapping(Display *display, XModifierKeymap - *modmap); - - display - - Specifies the connection to the X server. - - modmap - - Specifies the XModifierKeymap structure. - - The XSetModifierMapping function specifies the KeyCodes of the - keys (if any) that are to be used as modifiers. If it succeeds, - the X server generates a MappingNotify event, and - XSetModifierMapping returns MappingSuccess. X permits at most 8 - modifier keys. If more than 8 are specified in the - XModifierKeymap structure, a BadLength error results. - - The modifiermap member of the XModifierKeymap structure - contains 8 sets of max_keypermod KeyCodes, one for each - modifier in the order Shift, Lock, Control, Mod1, Mod2, Mod3, - Mod4, and Mod5. Only nonzero KeyCodes have meaning in each set, - and zero KeyCodes are ignored. In addition, all of the nonzero - KeyCodes must be in the range specified by min_keycode and - max_keycode in the Display structure, or a BadValue error - results. - - An X server can impose restrictions on how modifiers can be - changed, for example, if certain keys do not generate up - transitions in hardware, if auto-repeat cannot be disabled on - certain keys, or if multiple modifier keys are not supported. - If some such restriction is violated, the status reply is - MappingFailed, and none of the modifiers are changed. If the - new KeyCodes specified for a modifier differ from those - currently defined and any (current or new) keys for that - modifier are in the logically down state, XSetModifierMapping - returns MappingBusy, and none of the modifiers is changed. - - XSetModifierMapping can generate BadAlloc and BadValue errors. - - To obtain the KeyCodes used as modifiers, use - XGetModifierMapping. - - XModifierKeymap *XGetModifierMapping(Display *display); - - display - - Specifies the connection to the X server. - - The XGetModifierMapping function returns a pointer to a newly - created XModifierKeymap structure that contains the keys being - used as modifiers. The structure should be freed after use by - calling XFreeModifiermap. If only zero values appear in the set - for any modifier, that modifier is disabled. - -Chapter 13. Locales and Internationalized Text Functions - - Table of Contents - - X Locale Management - Locale and Modifier Dependencies - Variable Argument Lists - Output Methods - - Output Method Overview - Output Method Functions - X Output Method Values - Output Context Functions - Output Context Values - Creating and Freeing a Font Set - Obtaining Font Set Metrics - Drawing Text Using Font Sets - - Input Methods - - Input Method Overview - Input Method Management - Input Method Functions - Input Method Values - Input Context Functions - Input Context Values - Input Method Callback Semantics - Event Filtering - Getting Keyboard Input - Input Method Conventions - - String Constants - - An internationalized application is one that is adaptable to - the requirements of different native languages, local customs, - and character string encodings. The process of adapting the - operation to a particular native language, local custom, or - string encoding is called localization. A goal of - internationalization is to permit localization without program - source modifications or recompilation. - - As one of the localization mechanisms, Xlib provides an X Input - Method (XIM) functional interface for internationalized text - input and an X Output Method (XOM) functional interface for - internationalized text output. - - Internationalization in X is based on the concept of a locale. - A locale defines the localized behavior of a program at run - time. Locales affect Xlib in its: - * Encoding and processing of input method text - * Encoding of resource files and values - * Encoding and imaging of text strings - * Encoding and decoding for inter-client text communication - - o Encoding and decoding for inter-client text communication - Characters from various languages are represented in a computer - using an encoding. Different languages have different - encodings, and there are even different encodings for the same - characters in the same language. - - This chapter defines support for localized text imaging and - text input and describes the locale mechanism that controls all - locale-dependent Xlib functions. Sets of functions are provided - for multibyte (char *) text as well as wide character (wchar_t) - text in the form supported by the host C language environment. - The multibyte and wide character functions are equivalent - except for the form of the text argument. - - The Xlib internationalization functions are not meant to - provide support for multilingual applications (mixing multiple - languages within a single piece of text), but they make it - possible to implement applications that work in limited fashion - with more than one language in independent contexts. - - The remainder of this chapter discusses: - * X locale management - * Locale and modifier dependencies - * Variable argument lists - * Output methods - * Input methods - * String constants - -X Locale Management - - X supports one or more of the locales defined by the host - environment. On implementations that conform to the ANSI C - library, the locale announcement method is setlocale. This - function configures the locale operation of both the host C - library and Xlib. The operation of Xlib is governed by the - LC_CTYPE category; this is called the current locale. An - implementation is permitted to provide implementation-dependent - mechanisms for announcing the locale in addition to setlocale. - - On implementations that do not conform to the ANSI C library, - the locale announcement method is Xlib - implementation-dependent. - - The mechanism by which the semantic operation of Xlib is - defined for a specific locale is implementation-dependent. - - X is not required to support all the locales supported by the - host. To determine if the current locale is supported by X, use - XSupportsLocale. - - Bool XSupportsLocale(void); - - The XSupportsLocale function returns True if Xlib functions are - capable of operating under the current locale. If it returns - False, Xlib locale-dependent functions for which the - XLocaleNotSupported return status is defined will return - XLocaleNotSupported. Other Xlib locale-dependent routines will - operate in the ``C'' locale. - - The client is responsible for selecting its locale and X - modifiers. Clients should provide a means for the user to - override the clients' locale selection at client invocation. - Most single-display X clients operate in a single locale for - both X and the host processing environment. They will configure - the locale by calling three functions: the host locale - configuration function, XSupportsLocale, and - XSetLocaleModifiers. - - The semantics of certain categories of X internationalization - capabilities can be configured by setting modifiers. Modifiers - are named by implementation-dependent and locale-specific - strings. The only standard use for this capability at present - is selecting one of several styles of keyboard input method. - - To configure Xlib locale modifiers for the current locale, use - XSetLocaleModifiers. - - char *XSetLocaleModifiers(char *modifier_list); - - modifier_list - - Specifies the modifiers. - - The XSetLocaleModifiers function sets the X modifiers for the - current locale setting. The modifier_list argument is a - null-terminated string of the form ``{@category=value}'', that - is, having zero or more concatenated ``@category=value'' - entries, where category is a category name and value is the - (possibly empty) setting for that category. The values are - encoded in the current locale. Category names are restricted to - the POSIX Portable Filename Character Set. - - The local host X locale modifiers announcer (on POSIX-compliant - systems, the XMODIFIERS environment variable) is appended to - the modifier_list to provide default values on the local host. - If a given category appears more than once in the list, the - first setting in the list is used. If a given category is not - included in the full modifier list, the category is set to an - implementation-dependent default for the current locale. An - empty value for a category explicitly specifies the - implementation-dependent default. - - If the function is successful, it returns a pointer to a - string. The contents of the string are such that a subsequent - call with that string (in the same locale) will restore the - modifiers to the same settings. If modifier_list is a NULL - pointer, XSetLocaleModifiers also returns a pointer to such a - string, and the current locale modifiers are not changed. - - If invalid values are given for one or more modifier categories - supported by the locale, a NULL pointer is returned, and none - of the current modifiers are changed. - - At program startup, the modifiers that are in effect are - unspecified until the first successful call to set them. - Whenever the locale is changed, the modifiers that are in - effect become unspecified until the next successful call to set - them. Clients should always call XSetLocaleModifiers with a - non-NULL modifier_list after setting the locale before they - call any locale-dependent Xlib routine. - - The only standard modifier category currently defined is - ``im'', which identifies the desired input method. The values - for input method are not standardized. A single locale may use - multiple input methods, switching input method under user - control. The modifier may specify the initial input method in - effect or an ordered list of input methods. Multiple input - methods may be specified in a single im value string in an - implementation-dependent manner. - - The returned modifiers string is owned by Xlib and should not - be modified or freed by the client. It may be freed by Xlib - after the current locale or modifiers are changed. Until freed, - it will not be modified by Xlib. - - The recommended procedure for clients initializing their locale - and modifiers is to obtain locale and modifier announcers - separately from one of the following prioritized sources: - * A command line option - * A resource - * The empty string ("") - - The first of these that is defined should be used. Note that - when a locale command line option or locale resource is - defined, the effect should be to set all categories to the - specified locale, overriding any category-specific settings in - the local host environment. - -Locale and Modifier Dependencies - - The internationalized Xlib functions operate in the current - locale configured by the host environment and X locale - modifiers set by XSetLocaleModifiers or in the locale and - modifiers configured at the time some object supplied to the - function was created. For each locale-dependent function, the - following table describes the locale (and modifiers) - dependency: - Locale from Affects the Function In - Locale Query/Configuration: - setlocale XSupportsLocale Locale queried - XSetLocaleModifiers Locale modified - Resources: - setlocale - - XrmGetFileDatabase - - XrmGetStringDatabase - Locale of XrmDatabase - XrmDatabase - - XrmPutFileDatabase - - XrmLocaleOfDatabase - Locale of XrmDatabase - Setting Standard Properties: - setlocale XmbSetWMProperties Encoding of supplied/returned text - (some WM_ property text in environment locale) - setlocale - - XmbTextPropertyToTextList - - XwcTextPropertyToTextList - - XmbTextListToTextProperty - - XwcTextListToTextProperty - Encoding of supplied/returned text - Text Input: - setlocale XOpenIM XIM input method selection - XRegisterIMInstantiateCallback XIM selection - XUnregisterIMInstantiateCallback XIM selection - XIM XCreateIC XIC input method configuration - XLocaleOfIM, and so on Queried locale - XIC XmbLookupString Keyboard layout - XwcLookupString Encoding of returned text - Text Drawing: - setlocale XOpenOM XOM output method selection - XCreateFontSet Charsets of fonts in XFontSet - XOM XCreateOC XOC output method configuration - XLocaleOfOM, and so on Queried locale - XFontSet XmbDrawText, Locale of supplied text - XwcDrawText, and so on Locale of supplied text - - XExtentsOfFontSet, and so on - - XmbTextExtents, - - XwcTextExtents, and so on - Locale-dependent metrics - Xlib Errors: - setlocale - - XGetErrorDatabaseText, - - XGetErrorText, and so on - Locale of error message - - Clients may assume that a locale-encoded text string returned - by an X function can be passed to a C library routine, or vice - versa, if the locale is the same at the two calls. - - All text strings processed by internationalized Xlib functions - are assumed to begin in the initial state of the encoding of - the locale, if the encoding is state-dependent. - - All Xlib functions behave as if they do not change the current - locale or X modifier setting. (This means that if they do - change locale or call XSetLocaleModifiers with a non-NULL - argument, they must save and restore the current state on entry - and exit.) Also, Xlib functions on implementations that conform - to the ANSI C library do not alter the global state associated - with the ANSI C functions mblen, mbtowc, wctomb, and strtok. - -Variable Argument Lists - - Various functions in this chapter have arguments that conform - to the ANSI C variable argument list calling convention. Each - function denoted with an argument of the form ``...'' takes a - variable-length list of name and value pairs, where each name - is a string and each value is of type XPointer. A name argument - that is NULL identifies the end of the list. - - A variable-length argument list may contain a nested list. If - the name XNVaNestedList is specified in place of an argument - name, then the following value is interpreted as an - XVaNestedList value that specifies a list of values logically - inserted into the original list at the point of declaration. A - NULL identifies the end of a nested list. - - To allocate a nested variable argument list dynamically, use - XVaCreateNestedList. - - XVaNestedList XVaCreateNestedList(int dummy); - - dummy - - Specifies an unused argument (required by ANSI C). - - ... - - Specifies the variable length argument list(Al. - - The XVaCreateNestedList function allocates memory and copies - its arguments into a single list pointer, which may be used as - a value for arguments requiring a list value. Any entries are - copied as specified. Data passed by reference is not copied; - the caller must ensure data remains valid for the lifetime of - the nested list. The list should be freed using XFree when it - is no longer needed. - -Output Methods - - This section provides discussions of the following X Output - Method (XOM) topics: - * Output method overview - * Output method functions - * Output method values - * Output context functions - * Output context values - * Creating and freeing a font set - * Obtaining font set metrics - * Drawing text using font sets - -Output Method Overview - - Locale-dependent text may include one or more text components, - each of which may require different fonts and character set - encodings. In some languages, each component might have a - different drawing direction, and some components might contain - context-dependent characters that change shape based on - relationships with neighboring characters. - - When drawing such locale-dependent text, some locale-specific - knowledge is required; for example, what fonts are required to - draw the text, how the text can be separated into components, - and which fonts are selected to draw each component. Further, - when bidirectional text must be drawn, the internal - representation order of the text must be changed into the - visual representation order to be drawn. - - An X Output Method provides a functional interface so that - clients do not have to deal directly with such locale-dependent - details. Output methods provide the following capabilities: - * Creating a set of fonts required to draw locale-dependent - text. - * Drawing locale-dependent text with a font set without the - caller needing to be aware of locale dependencies. - * Obtaining the escapement and extents in pixels of - locale-dependent text. - * Determining if bidirectional or context-dependent drawing - is required in a specific locale with a specific font set. - - Two different abstractions are used in the representation of - the output method for clients. - - The abstraction used to communicate with an output method is an - opaque data structure represented by the XOM data type. The - abstraction for representing the state of a particular output - thread is called an output context. The Xlib representation of - an output context is an XOC, which is compatible with XFontSet - in terms of its functional interface, but is a broader, more - generalized abstraction. - -Output Method Functions - - To open an output method, use XOpenOM. - - XOM XOpenOM(Display *display, XrmDatabase db, char *res_name, - char *res_class); - - display - - Specifies the connection to the X server. - - db - - Specifies a pointer to the resource database. - - res_name - - Specifies the full resource name of the application. - - res_class - - Specifies the full class name of the application. - - The XOpenOM function opens an output method matching the - current locale and modifiers specification. The current locale - and modifiers are bound to the output method when XOpenOM is - called. The locale associated with an output method cannot be - changed. - - The specific output method to which this call will be routed is - identified on the basis of the current locale and modifiers. - XOpenOM will identify a default output method corresponding to - the current locale. That default can be modified using - XSetLocaleModifiers to set the output method modifier. - - The db argument is the resource database to be used by the - output method for looking up resources that are private to the - output method. It is not intended that this database be used to - look up values that can be set as OC values in an output - context. If db is NULL, no database is passed to the output - method. - - The res_name and res_class arguments specify the resource name - and class of the application. They are intended to be used as - prefixes by the output method when looking up resources that - are common to all output contexts that may be created for this - output method. The characters used for resource names and - classes must be in the X Portable Character Set. The resources - looked up are not fully specified if res_name or res_class is - NULL. - - The res_name and res_class arguments are not assumed to exist - beyond the call to XOpenOM. The specified resource database is - assumed to exist for the lifetime of the output method. - - XOpenOM returns NULL if no output method could be opened. - - To close an output method, use XCloseOM. - - Status XCloseOM(XOM om); - - om - - Specifies the output method. - - The XCloseOM function closes the specified output method. - - To set output method attributes, use XSetOMValues. - - char *XSetOMValues(XOM om); - - om - - Specifies the output method. - - ... - - Specifies the variable-length argument list to set XOM values. - - The XSetOMValues function presents a variable argument list - programming interface for setting properties or features of the - specified output method. This function returns NULL if it - succeeds; otherwise, it returns the name of the first argument - that could not be obtained. - - No standard arguments are currently defined by Xlib. - - To query an output method, use XGetOMValues. - - char *XGetOMValues(XOM om); - - om - - Specifies the output method. - - ... - - Specifies the variable-length argument list to get XOM values. - - The XGetOMValues function presents a variable argument list - programming interface for querying properties or features of - the specified output method. This function returns NULL if it - succeeds; otherwise, it returns the name of the first argument - that could not be obtained. - - To obtain the display associated with an output method, use - XDisplayOfOM. - - Display *XDisplayOfOM(XOM om); - - om - - Specifies the output method. - - The XDisplayOfOM function returns the display associated with - the specified output method. - - To get the locale associated with an output method, use - XLocaleOfOM. - - char *XLocaleOfOM(XOM om); - - om - - Specifies the output method. - - The XLocaleOfOM returns the locale associated with the - specified output method. - -X Output Method Values - - The following table describes how XOM values are interpreted by - an output method. The first column lists the XOM values. The - second column indicates how each of the XOM values are treated - by a particular output style. - - The following key applies to this table. - Key Explanation - G This value may be read using XGetOMValues. - - XOM Value Key - XNRequiredCharSet G - XNQueryOrientation G - XNDirectionalDependentDrawing G - XNContextualDrawing G - -Required Char Set - - The XNRequiredCharSet argument returns the list of charsets - that are required for loading the fonts needed for the locale. - The value of the argument is a pointer to a structure of type - XOMCharSetList. - - The XOMCharSetList structure is defined as follows: - - -typedef struct { - int charset_count; - char **charset_list; -} XOMCharSetList; - - The charset_list member is a list of one or more - null-terminated charset names, and the charset_count member is - the number of charset names. - - The required charset list is owned by Xlib and should not be - modified or freed by the client. It will be freed by a call to - XCloseOM with the associated XOM. Until freed, its contents - will not be modified by Xlib. - -Query Orientation - - The XNQueryOrientation argument returns the global orientation - of text when drawn. Other than XOMOrientation_LTR_TTB, the set - of orientations supported is locale-dependent. The value of the - argument is a pointer to a structure of type XOMOrientation. - Clients are responsible for freeing the XOMOrientation - structure by using XFree; this also frees the contents of the - structure. - - -typedef struct { - int num_orientation; - XOrientation *orientation; /* Input Text description */ -} XOMOrientation; - -typedef enum { - XOMOrientation_LTR_TTB, - XOMOrientation_RTL_TTB, - XOMOrientation_TTB_LTR, - XOMOrientation_TTB_RTL, - XOMOrientation_Context -} XOrientation; - - The possible value for XOrientation may be: - * XOMOrientation_LTR_TTB left-to-right, top-to-bottom global - orientation - * XOMOrientation_RTL_TTB right-to-left, top-to-bottom global - orientation - * XOMOrientation_TTB_LTR top-to-bottom, left-to-right global - orientation - * XOMOrientation_TTB_RTL top-to-bottom, right-to-left global - orientation - * XOMOrientation_Context contextual global orientation - -Directional Dependent Drawing - - The XNDirectionalDependentDrawing argument indicates whether - the text rendering functions implement implicit handling of - directional text. If this value is True, the output method has - knowledge of directional dependencies and reorders text as - necessary when rendering text. If this value is False, the - output method does not implement any directional text handling, - and all character directions are assumed to be left-to-right. - - Regardless of the rendering order of characters, the origins of - all characters are on the primary draw direction side of the - drawing origin. - - This OM value presents functionality identical to the - XDirectionalDependentDrawing function. - -Context Dependent Drawing - - The XNContextualDrawing argument indicates whether the text - rendering functions implement implicit context-dependent - drawing. If this value is True, the output method has knowledge - of context dependencies and performs character shape editing, - combining glyphs to present a single character as necessary. - The actual shape editing is dependent on the locale - implementation and the font set used. - - This OM value presents functionality identical to the - XContextualDrawing function. - -Output Context Functions - - An output context is an abstraction that contains both the data - required by an output method and the information required to - display that data. There can be multiple output contexts for - one output method. The programming interfaces for creating, - reading, or modifying an output context use a variable argument - list. The name elements of the argument lists are referred to - as XOC values. It is intended that output methods be controlled - by these XOC values. As new XOC values are created, they should - be registered with the X Consortium. An XOC can be used - anywhere an XFontSet can be used, and vice versa; XFontSet is - retained for compatibility with previous releases. The concepts - of output methods and output contexts include broader, more - generalized abstraction than font set, supporting complex and - more intelligent text display, and dealing not only with - multiple fonts but also with context dependencies. However, - XFontSet is widely used in several interfaces, so XOC is - defined as an upward compatible type of XFontSet. - - To create an output context, use XCreateOC. - - XOC XCreateOC(XOM om); - - om - - Specifies the output method. - - ... - - Specifies the variable-length argument list to set XOC values. - - The XCreateOC function creates an output context within the - specified output method. - - The base font names argument is mandatory at creation time, and - the output context will not be created unless it is provided. - All other output context values can be set later. - - XCreateOC returns NULL if no output context could be created. - NULL can be returned for any of the following reasons: - * A required argument was not set. - * A read-only argument was set. - * An argument name is not recognized. - * The output method encountered an output method - implementation-dependent error. - - XCreateOC can generate a BadAtom error. - - To destroy an output context, use XDestroyOC. - - void XDestroyOC(XOC oc); - - oc - - Specifies the output context. - - The XDestroyOC function destroys the specified output context. - - To get the output method associated with an output context, use - XOMOfOC. - - XOM XOMOfOC(XOC oc); - - oc - - Specifies the output context. - - The XOMOfOC function returns the output method associated with - the specified output context. - - Xlib provides two functions for setting and reading output - context values, respectively, XSetOCValues and XGetOCValues. - Both functions have a variable-length argument list. In that - argument list, any XOC value's name must be denoted with a - character string using the X Portable Character Set. - - To set XOC values, use XSetOCValues. - - char *XSetOCValues(XOC oc); - - oc - - Specifies the output context. - - ... - - Specifies the variable-length argument list to set XOC values. - - The XSetOCValues function returns NULL if no error occurred; - otherwise, it returns the name of the first argument that could - not be set. An argument might not be set for any of the - following reasons: - * The argument is read-only. - * The argument name is not recognized. - * An implementation-dependent error occurs. - - Each value to be set must be an appropriate datum, matching the - data type imposed by the semantics of the argument. - - XSetOCValues can generate a BadAtom error. - - To obtain XOC values, use XGetOCValues. - - char *XGetOCValues(XOC oc); - - oc - - Specifies the output context. - - ... - - Specifies the variable-length argument list to get XOC values. - - The XGetOCValues function returns NULL if no error occurred; - otherwise, it returns the name of the first argument that could - not be obtained. An argument might not be obtained for any of - the following reasons: - * The argument name is not recognized. - * An implementation-dependent error occurs. - - Each argument value following a name must point to a location - where the value is to be stored. - -Output Context Values - - The following table describes how XOC values are interpreted by - an output method. The first column lists the XOC values. The - second column indicates the alternative interfaces that - function identically and are provided for compatibility with - previous releases. The third column indicates how each of the - XOC values is treated. - - The following keys apply to this table. - Key Explanation - C This value must be set with XCreateOC. - D This value may be set using XCreateOC. If it is not set,a - default is provided. - G This value may be read using XGetOCValues. - S This value must be set using XSetOCValues. - - XOC Value Alternative Interface Key - BaseFontName XCreateFontSet C-G - MissingCharSet XCreateFontSet G - DefaultString XCreateFontSet G - Orientation - D-S-G - ResourceName - S-G - ResourceClass - S-G - FontInfo XFontsOfFontSet G - OMAutomatic - G - -Base Font Name - - The XNBaseFontName argument is a list of base font names that - Xlib uses to load the fonts needed for the locale. The base - font names are a comma-separated list. The string is - null-terminated and is assumed to be in the Host Portable - Character Encoding; otherwise, the result is - implementation-dependent. White space immediately on either - side of a separating comma is ignored. - - Use of XLFD font names permits Xlib to obtain the fonts needed - for a variety of locales from a single locale-independent base - font name. The single base font name should name a family of - fonts whose members are encoded in the various charsets needed - by the locales of interest. - - An XLFD base font name can explicitly name a charset needed for - the locale. This allows the user to specify an exact font for - use with a charset required by a locale, fully controlling the - font selection. - - If a base font name is not an XLFD name, Xlib will attempt to - obtain an XLFD name from the font properties for the font. If - Xlib is successful, the XGetOCValues function will return this - XLFD name instead of the client-supplied name. - - This argument must be set at creation time and cannot be - changed. If no fonts exist for any of the required charsets, or - if the locale definition in Xlib requires that a font exist for - a particular charset and a font is not found for that charset, - XCreateOC returns NULL. - - When querying for the XNBaseFontName XOC value, XGetOCValues - returns a null-terminated string identifying the base font - names that Xlib used to load the fonts needed for the locale. - This string is owned by Xlib and should not be modified or - freed by the client. The string will be freed by a call to - XDestroyOC with the associated XOC. Until freed, the string - contents will not be modified by Xlib. - -Missing CharSet - - The XNMissingCharSet argument returns the list of required - charsets that are missing from the font set. The value of the - argument is a pointer to a structure of type XOMCharSetList. - - If fonts exist for all of the charsets required by the current - locale, charset_list is set to NULL and charset_count is set to - zero. If no fonts exist for one or more of the required - charsets, charset_list is set to a list of one or more - null-terminated charset names for which no fonts exist, and - charset_count is set to the number of missing charsets. The - charsets are from the list of the required charsets for the - encoding of the locale and do not include any charsets to which - Xlib may be able to remap a required charset. - - The missing charset list is owned by Xlib and should not be - modified or freed by the client. It will be freed by a call to - XDestroyOC with the associated XOC. Until freed, its contents - will not be modified by Xlib. - -Default String - - When a drawing or measuring function is called with an XOC that - has missing charsets, some characters in the locale will not be - drawable. The XNDefaultString argument returns a pointer to a - string that represents the glyphs that are drawn with this XOC - when the charsets of the available fonts do not include all - glyphs required to draw a character. The string does not - necessarily consist of valid characters in the current locale - and is not necessarily drawn with the fonts loaded for the font - set, but the client can draw or measure the default glyphs by - including this string in a string being drawn or measured with - the XOC. - - If the XNDefaultString argument returned the empty string (""), - no glyphs are drawn and the escapement is zero. The returned - string is null-terminated. It is owned by Xlib and should not - be modified or freed by the client. It will be freed by a call - to XDestroyOC with the associated XOC. Until freed, its - contents will not be modified by Xlib. - -Orientation - - The XNOrientation argument specifies the current orientation of - text when drawn. The value of this argument is one of the - values returned by the XGetOMValues function with the - XNQueryOrientation argument specified in the XOrientation list. - The value of the argument is of type XOrientation. When - XNOrientation is queried, the value specifies the current - orientation. When XNOrientation is set, a value is used to set - the current orientation. - - When XOMOrientation_Context is set, the text orientation of the - text is determined according to an implementation-defined - method (for example, ISO 6429 control sequences), and the - initial text orientation for locale-dependent Xlib functions is - assumed to be XOMOrientation_LTR_TTB. - - The XNOrientation value does not change the prime drawing - direction for Xlib drawing functions. - -Resource Name and Class - - The XNResourceName and XNResourceClass arguments are strings - that specify the full name and class used by the client to - obtain resources for the display of the output context. These - values should be used as prefixes for name and class when - looking up resources that may vary according to the output - context. If these values are not set, the resources will not be - fully specified. - - It is not intended that values that can be set as XOM values be - set as resources. - - When querying for the XNResourceName or XNResourceClass XOC - value, XGetOCValues returns a null-terminated string. This - string is owned by Xlib and should not be modified or freed by - the client. The string will be freed by a call to XDestroyOC - with the associated XOC or when the associated value is changed - via XSetOCValues. Until freed, the string contents will not be - modified by Xlib. - -Font Info - - The XNFontInfo argument specifies a list of one or more - XFontStruct structures and font names for the fonts used for - drawing by the given output context. The value of the argument - is a pointer to a structure of type XOMFontInfo. - - - -typedef struct { - int num_font; - XFontStruct **font_struct_list; - char **font_name_list; -} XOMFontInfo; - - A list of pointers to the XFontStruct structures is returned to - font_struct_list. A list of pointers to null-terminated, - fully-specified font name strings in the locale of the output - context is returned to font_name_list. The font_name_list order - corresponds to the font_struct_list order. The number of - XFontStruct structures and font names is returned to num_font. - - Because it is not guaranteed that a given character will be - imaged using a single font glyph, there is no provision for - mapping a character or default string to the font properties, - font ID, or direction hint for the font for the character. The - client may access the XFontStruct list to obtain these values - for all the fonts currently in use. - - Xlib does not guarantee that fonts are loaded from the server - at the creation of an XOC. Xlib may choose to cache font data, - loading it only as needed to draw text or compute text - dimensions. Therefore, existence of the per_char metrics in the - XFontStruct structures in the XFontStructSet is undefined. - Also, note that all properties in the XFontStruct structures - are in the STRING encoding. - - The client must not free the XOMFontInfo struct itself; it will - be freed when the XOC is closed. - -OM Automatic - - The XNOMAutomatic argument returns whether the associated - output context was created by XCreateFontSet or not. Because - the XFreeFontSet function not only destroys the output context - but also closes the implicit output method associated with it, - XFreeFontSet should be used with any output context created by - XCreateFontSet. However, it is possible that a client does not - know how the output context was created. Before a client - destroys the output context, it can query whether XNOMAutomatic - is set to determine whether XFreeFontSet or XDestroyOC should - be used to destroy the output context. - -Creating and Freeing a Font Set - - Xlib international text drawing is done using a set of one or - more fonts, as needed for the locale of the text. Fonts are - loaded according to a list of base font names supplied by the - client and the charsets required by the locale. The XFontSet is - an opaque type representing the state of a particular output - thread and is equivalent to the type XOC. - - The XCreateFontSet function is a convenience function for - creating an output context using only default values. The - returned XFontSet has an implicitly created XOM. This XOM has - an OM value XNOMAutomatic automatically set to True so that the - output context self indicates whether it was created by - XCreateOC or XCreateFontSet. - - XFontSet XCreateFontSet(Display *display, char - *base_font_name_list, char ***missing_charset_list_return, int - *missing_charset_count_return, char **def_string_return); - - display - - Specifies the connection to the X server. - - base_font_name_list - - Specifies the base font names. - - missing_charset_list_return - - Returns the missing charsets. - - missing_charset_count_return - - Returns the number of missing charsets. - - def_string_return - - Returns the string drawn for missing charsets. - - The XCreateFontSet function creates a font set for the - specified display. The font set is bound to the current locale - when XCreateFontSet is called. The font set may be used in - subsequent calls to obtain font and character information and - to image text in the locale of the font set. - - The base_font_name_list argument is a list of base font names - that Xlib uses to load the fonts needed for the locale. The - base font names are a comma-separated list. The string is - null-terminated and is assumed to be in the Host Portable - Character Encoding; otherwise, the result is - implementation-dependent. White space immediately on either - side of a separating comma is ignored. - - Use of XLFD font names permits Xlib to obtain the fonts needed - for a variety of locales from a single locale-independent base - font name. The single base font name should name a family of - fonts whose members are encoded in the various charsets needed - by the locales of interest. - - An XLFD base font name can explicitly name a charset needed for - the locale. This allows the user to specify an exact font for - use with a charset required by a locale, fully controlling the - font selection. - - If a base font name is not an XLFD name, Xlib will attempt to - obtain an XLFD name from the font properties for the font. If - this action is successful in obtaining an XLFD name, the - XBaseFontNameListOfFontSet function will return this XLFD name - instead of the client-supplied name. - - Xlib uses the following algorithm to select the fonts that will - be used to display text with the XFontSet. - - For each font charset required by the locale, the base font - name list is searched for the first appearance of one of the - following cases that names a set of fonts that exist at the - server: - * The first XLFD-conforming base font name that specifies the - required charset or a superset of the required charset in - its CharSetRegistry and CharSetEncoding fields. The - implementation may use a base font name whose specified - charset is a superset of the required charset, for example, - an ISO8859-1 font for an ASCII charset. - * The first set of one or more XLFD-conforming base font - names that specify one or more charsets that can be - remapped to support the required charset. The Xlib - implementation may recognize various mappings from a - required charset to one or more other charsets and use the - fonts for those charsets. For example, JIS Roman is ASCII - with tilde and backslash replaced by yen and overbar; Xlib - may load an ISO8859-1 font to support this character set if - a JIS Roman font is not available. - * The first XLFD-conforming font name or the first non-XLFD - font name for which an XLFD font name can be obtained, - combined with the required charset (replacing the - CharSetRegistry and CharSetEncoding fields in the XLFD font - name). As in case 1, the implementation may use a charset - that is a superset of the required charset. - * The first font name that can be mapped in some - implementation-dependent manner to one or more fonts that - support imaging text in the charset. - - For example, assume that a locale required the charsets: - -ISO8859-1 -JISX0208.1983 -JISX0201.1976 -GB2312-1980.0 - - The user could supply a base_font_name_list that explicitly - specifies the charsets, ensuring that specific fonts are used - if they exist. For example: - -"-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240-JISX0208.1983-0,\\ --JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120-JISX0201.1976-0,\\ --GB-Fixed-Medium-R-Normal--26-180-100-100-C-240-GB2312-1980.0,\\ --Adobe-Courier-Bold-R-Normal--25-180-75-75-M-150-ISO8859-1" - - Alternatively, the user could supply a base_font_name_list that - omits the charsets, letting Xlib select font charsets required - for the locale. For example: - -"-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240,\\ --JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120,\\ --GB-Fixed-Medium-R-Normal--26-180-100-100-C-240,\\ --Adobe-Courier-Bold-R-Normal--25-180-100-100-M-150" - - Alternatively, the user could simply supply a single base font - name that allows Xlib to select from all available fonts that - meet certain minimum XLFD property requirements. For example: - -"-*-*-*-R-Normal--*-180-100-100-*-*" - - If XCreateFontSet is unable to create the font set, either - because there is insufficient memory or because the current - locale is not supported, XCreateFontSet returns NULL, - missing_charset_list_return is set to NULL, and - missing_charset_count_return is set to zero. If fonts exist for - all of the charsets required by the current locale, - XCreateFontSet returns a valid XFontSet, - missing_charset_list_return is set to NULL, and - missing_charset_count_return is set to zero. - - If no font exists for one or more of the required charsets, - XCreateFontSet sets missing_charset_list_return to a list of - one or more null-terminated charset names for which no font - exists and sets missing_charset_count_return to the number of - missing fonts. The charsets are from the list of the required - charsets for the encoding of the locale and do not include any - charsets to which Xlib may be able to remap a required charset. - - If no font exists for any of the required charsets or if the - locale definition in Xlib requires that a font exist for a - particular charset and a font is not found for that charset, - XCreateFontSet returns NULL. Otherwise, XCreateFontSet returns - a valid XFontSet to font_set. - - When an Xmb/wc drawing or measuring function is called with an - XFontSet that has missing charsets, some characters in the - locale will not be drawable. If def_string_return is non-NULL, - XCreateFontSet returns a pointer to a string that represents - the glyphs that are drawn with this XFontSet when the charsets - of the available fonts do not include all font glyphs required - to draw a codepoint. The string does not necessarily consist of - valid characters in the current locale and is not necessarily - drawn with the fonts loaded for the font set, but the client - can draw and measure the default glyphs by including this - string in a string being drawn or measured with the XFontSet. - - If the string returned to def_string_return is the empty string - (""), no glyphs are drawn, and the escapement is zero. The - returned string is null-terminated. It is owned by Xlib and - should not be modified or freed by the client. It will be freed - by a call to XFreeFontSet with the associated XFontSet. Until - freed, its contents will not be modified by Xlib. - - The client is responsible for constructing an error message - from the missing charset and default string information and may - choose to continue operation in the case that some fonts did - not exist. - - The returned XFontSet and missing charset list should be freed - with XFreeFontSet and XFreeStringList, respectively. The - client-supplied base_font_name_list may be freed by the client - after calling XCreateFontSet. - - To obtain a list of XFontStruct structures and full font names - given an XFontSet, use XFontsOfFontSet. - - int XFontsOfFontSet(XFontSet font_set, XFontStruct - ***font_struct_list_return, char ***font_name_list_return); - - font_set - - Specifies the font set. - - font_struct_list_return - - Returns the list of font structs. - - font_name_list_return - - Returns the list of font names. - - The XFontsOfFontSet function returns a list of one or more - XFontStructs and font names for the fonts used by the Xmb and - Xwc layers for the given font set. A list of pointers to the - XFontStruct structures is returned to font_struct_list_return. - A list of pointers to null-terminated, fully specified font - name strings in the locale of the font set is returned to - font_name_list_return. The font_name_list order corresponds to - the font_struct_list order. The number of XFontStruct - structures and font names is returned as the value of the - function. - - Because it is not guaranteed that a given character will be - imaged using a single font glyph, there is no provision for - mapping a character or default string to the font properties, - font ID, or direction hint for the font for the character. The - client may access the XFontStruct list to obtain these values - for all the fonts currently in use. - - Xlib does not guarantee that fonts are loaded from the server - at the creation of an XFontSet. Xlib may choose to cache font - data, loading it only as needed to draw text or compute text - dimensions. Therefore, existence of the per_char metrics in the - XFontStruct structures in the XFontStructSet is undefined. - Also, note that all properties in the XFontStruct structures - are in the STRING encoding. - - The XFontStruct and font name lists are owned by Xlib and - should not be modified or freed by the client. They will be - freed by a call to XFreeFontSet with the associated XFontSet. - Until freed, their contents will not be modified by Xlib. - - To obtain the base font name list and the selected font name - list given an XFontSet, use XBaseFontNameListOfFontSet. - - char *XBaseFontNameListOfFontSet(XFontSet font_set); - - font_set - - Specifies the font set. - - The XBaseFontNameListOfFontSet function returns the original - base font name list supplied by the client when the XFontSet - was created. A null-terminated string containing a list of - comma-separated font names is returned as the value of the - function. White space may appear immediately on either side of - separating commas. - - If XCreateFontSet obtained an XLFD name from the font - properties for the font specified by a non-XLFD base name, the - XBaseFontNameListOfFontSet function will return the XLFD name - instead of the non-XLFD base name. - - The base font name list is owned by Xlib and should not be - modified or freed by the client. It will be freed by a call to - XFreeFontSet with the associated XFontSet. Until freed, its - contents will not be modified by Xlib. - - To obtain the locale name given an XFontSet, use - XLocaleOfFontSet. - - char *XLocaleOfFontSet(XFontSet font_set); - - font_set - - Specifies the font set. - - The XLocaleOfFontSet function returns the name of the locale - bound to the specified XFontSet, as a null-terminated string. - - The returned locale name string is owned by Xlib and should not - be modified or freed by the client. It may be freed by a call - to XFreeFontSet with the associated XFontSet. Until freed, it - will not be modified by Xlib. - - The XFreeFontSet function is a convenience function for freeing - an output context. XFreeFontSet also frees its associated XOM - if the output context was created by XCreateFontSet. - - void XFreeFontSet(Display *display, XFontSet font_set); - - display - - Specifies the connection to the X server. - - font_set - - Specifies the font set. - - The XFreeFontSet function frees the specified font set. The - associated base font name list, font name list, XFontStruct - list, and XFontSetExtents, if any, are freed. - -Obtaining Font Set Metrics - - Metrics for the internationalized text drawing functions are - defined in terms of a primary draw direction, which is the - default direction in which the character origin advances for - each succeeding character in the string. The Xlib interface is - currently defined to support only a left-to-right primary draw - direction. The drawing origin is the position passed to the - drawing function when the text is drawn. The baseline is a line - drawn through the drawing origin parallel to the primary draw - direction. Character ink is the pixels painted in the - foreground color and does not include interline or - intercharacter spacing or image text background pixels. - - The drawing functions are allowed to implement implicit text - directionality control, reversing the order in which characters - are rendered along the primary draw direction in response to - locale-specific lexical analysis of the string. - - Regardless of the character rendering order, the origins of all - characters are on the primary draw direction side of the - drawing origin. The screen location of a particular character - image may be determined with XmbTextPerCharExtents or - XwcTextPerCharExtents. - - The drawing functions are allowed to implement - context-dependent rendering, where the glyphs drawn for a - string are not simply a concatenation of the glyphs that - represent each individual character. A string of two characters - drawn with XmbDrawString may render differently than if the two - characters were drawn with separate calls to XmbDrawString. If - the client appends or inserts a character in a previously drawn - string, the client may need to redraw some adjacent characters - to obtain proper rendering. - - To find out about direction-dependent rendering, use - XDirectionalDependentDrawing. - - Bool XDirectionalDependentDrawing(XFontSet font_set); - - font_set - - Specifies the font set. - - The XDirectionalDependentDrawing function returns True if the - drawing functions implement implicit text directionality; - otherwise, it returns False. - - To find out about context-dependent rendering, use - XContextualDrawing. - - Bool XContextualDrawing(XFontSet font_set); - - font_set - - Specifies the font set. - - The XContextualDrawing function returns True if text drawn with - the font set might include context-dependent drawing; - otherwise, it returns False. - - To find out about context-dependent or direction-dependent - rendering, use XContextDependentDrawing. - - Bool XContextDependentDrawing(XFontSet font_set); - - font_set - - Specifies the font set. - - The XContextDependentDrawing function returns True if the - drawing functions implement implicit text directionality or if - text drawn with the font_set might include context-dependent - drawing; otherwise, it returns False. - - The drawing functions do not interpret newline, tab, or other - control characters. The behavior when nonprinting characters - other than space are drawn is implementation-dependent. It is - the client's responsibility to interpret control characters in - a text stream. - - The maximum character extents for the fonts that are used by - the text drawing layers can be accessed by the XFontSetExtents - structure: - - - -typedef struct { - XRectangle max_ink_extent; /* over all drawable characters */ - XRectangle max_logical_extent; /* over all drawable characters */ -} XFontSetExtents; - - The XRectangle structures used to return font set metrics are - the usual Xlib screen-oriented rectangles with x, y giving the - upper left corner, and width and height always positive. - - The max_ink_extent member gives the maximum extent, over all - drawable characters, of the rectangles that bound the character - glyph image drawn in the foreground color, relative to a - constant origin. See XmbTextExtents and XwcTextExtents for - detailed semantics. - - The max_logical_extent member gives the maximum extent, over - all drawable characters, of the rectangles that specify minimum - spacing to other graphical features, relative to a constant - origin. Other graphical features drawn by the client, for - example, a border surrounding the text, should not intersect - this rectangle. The max_logical_extent member should be used to - compute minimum interline spacing and the minimum area that - must be allowed in a text field to draw a given number of - arbitrary characters. - - Due to context-dependent rendering, appending a given character - to a string may change the string's extent by an amount other - than that character's individual extent. - - The rectangles for a given character in a string can be - obtained from XmbTextPerCharExtents or XwcTextPerCharExtents. - - To obtain the maximum extents structure given an XFontSet, use - XExtentsOfFontSet. - - XFontSetExtents *XExtentsOfFontSet(XFontSet font_set); - - font_set - - Specifies the font set. - - The XExtentsOfFontSet function returns an XFontSetExtents - structure for the fonts used by the Xmb and Xwc layers for the - given font set. - - The XFontSetExtents structure is owned by Xlib and should not - be modified or freed by the client. It will be freed by a call - to XFreeFontSet with the associated XFontSet. Until freed, its - contents will not be modified by Xlib. - - To obtain the escapement in pixels of the specified text as a - value, use XmbTextEscapement or XwcTextEscapement. - - int XmbTextEscapement(XFontSet font_set, char *string, int - num_bytes); - - int XwcTextEscapement(XFontSet font_set, wchar_t *string, int - num_wchars); - - font_set - - Specifies the font set. - - string - - Specifies the character string. - - num_bytes - - Specifies the number of bytes in the string argument. - - num_wchars - - Specifies the number of characters in the string argument. - - The XmbTextEscapement and XwcTextEscapement functions return - the escapement in pixels of the specified string as a value, - using the fonts loaded for the specified font set. The - escapement is the distance in pixels in the primary draw - direction from the drawing origin to the origin of the next - character to be drawn, assuming that the rendering of the next - character is not dependent on the supplied string. - - Regardless of the character rendering order, the escapement is - always positive. - - To obtain the overall_ink_return and overall_logical_return - arguments, the overall bounding box of the string's image, and - a logical bounding box, use XmbTextExtents or XwcTextExtents. - - int XmbTextExtents(XFontSet font_set, char *string, int - num_bytes, XRectangle *overall_ink_return, XRectangle - *overall_logical_return); - - int XwcTextExtents(XFontSet font_set, wchar_t *string, int - num_wchars, XRectangle *overall_ink_return, XRectangle - *overall_logical_return); - - font_set - - Specifies the font set. - - string - - Specifies the character string. - - num_bytes - - Specifies the number of bytes in the string argument. - - num_wchars - - Specifies the number of characters in the string argument. - - overall_ink_return - - Returns the overall ink dimensions. - - overall_logical_return - - Returns the overall logical dimensions. - - The XmbTextExtents and XwcTextExtents functions set the - components of the specified overall_ink_return and - overall_logical_return arguments to the overall bounding box of - the string's image and a logical bounding box for spacing - purposes, respectively. They return the value returned by - XmbTextEscapement or XwcTextEscapement. These metrics are - relative to the drawing origin of the string, using the fonts - loaded for the specified font set. - - If the overall_ink_return argument is non-NULL, it is set to - the bounding box of the string's character ink. The - overall_ink_return for a nondescending, horizontally drawn - Latin character is conventionally entirely above the baseline; - that is, overall_ink_return.height <= -overall_ink_return.y. - The overall_ink_return for a nonkerned character is entirely - at, and to the right of, the origin; that is, - overall_ink_return.x >= 0. A character consisting of a single - pixel at the origin would set overall_ink_return fields y = 0, - x = 0, width = 1, and height = 1. - - If the overall_logical_return argument is non-NULL, it is set - to the bounding box that provides minimum spacing to other - graphical features for the string. Other graphical features, - for example, a border surrounding the text, should not - intersect this rectangle. - - When the XFontSet has missing charsets, metrics for each - unavailable character are taken from the default string - returned by XCreateFontSet so that the metrics represent the - text as it will actually be drawn. The behavior for an invalid - codepoint is undefined. - - To determine the effective drawing origin for a character in a - drawn string, the client should call XmbTextPerCharExtents on - the entire string, then on the character, and subtract the x - values of the returned rectangles for the character. This is - useful to redraw portions of a line of text or to justify - words, but for context-dependent rendering, the client should - not assume that it can redraw the character by itself and get - the same rendering. - - To obtain per-character information for a text string, use - XmbTextPerCharExtents or XwcTextPerCharExtents. - - Status XmbTextPerCharExtents(XFontSet font_set, char *string, - int num_bytes, XRectangle *ink_array_return, XRectangle - *logical_array_return, int array_size, int *num_chars_return, - XRectangle *overall_ink_return, XRectangle - *overall_logical_return); - - Status XwcTextPerCharExtents(XFontSet font_set, wchar_t - *string, int num_wchars, XRectangle *ink_array_return, - XRectangle *logical_array_return, int array_size, int - *num_chars_return, XRectangle *overall_ink_return, XRectangle - *overall_logical_return); - - font_set - - Specifies the font set. - - string - - Specifies the character string. - - num_bytes - - Specifies the number of bytes in the string argument. - - num_wchars - - Specifies the number of characters in the string argument. - - ink_array_return - - Returns the ink dimensions for each character. - - logical_array_return - - Returns the logical dimensions for each character. - - array_size - - Specifies the size of ink_array_return and - logical_array_return. The caller must pass in arrays of this - size. - - num_chars_return - - Returns the number of characters in the string argument. - - overall_ink_return - - Returns the overall ink dimensions. - - overall_logical_return - - Returns the overall logical dimensions. - - The XmbTextPerCharExtents and XwcTextPerCharExtents functions - return the text dimensions of each character of the specified - text, using the fonts loaded for the specified font set. Each - successive element of ink_array_return and logical_array_return - is set to the successive character's drawn metrics, relative to - the drawing origin of the string and one rectangle for each - character in the supplied text string. The number of elements - of ink_array_return and logical_array_return that have been set - is returned to num_chars_return. - - Each element of ink_array_return is set to the bounding box of - the corresponding character's drawn foreground color. Each - element of logical_array_return is set to the bounding box that - provides minimum spacing to other graphical features for the - corresponding character. Other graphical features should not - intersect any of the logical_array_return rectangles. - - Note that an XRectangle represents the effective drawing - dimensions of the character, regardless of the number of font - glyphs that are used to draw the character or the direction in - which the character is drawn. If multiple characters map to a - single character glyph, the dimensions of all the XRectangles - of those characters are the same. - - When the XFontSet has missing charsets, metrics for each - unavailable character are taken from the default string - returned by XCreateFontSet so that the metrics represent the - text as it will actually be drawn. The behavior for an invalid - codepoint is undefined. - - If the array_size is too small for the number of characters in - the supplied text, the functions return zero and - num_chars_return is set to the number of rectangles required. - Otherwise, the functions return a nonzero value. - - If the overall_ink_return or overall_logical_return argument is - non-NULL, XmbTextPerCharExtents and XwcTextPerCharExtents - return the maximum extent of the string's metrics to - overall_ink_return or overall_logical_return, as returned by - XmbTextExtents or XwcTextExtents. - -Drawing Text Using Font Sets - - The functions defined in this section draw text at a specified - location in a drawable. They are similar to the functions - XDrawText, XDrawString, and XDrawImageString except that they - work with font sets instead of single fonts and interpret the - text based on the locale of the font set instead of treating - the bytes of the string as direct font indexes. See section 8.6 - for details of the use of Graphics Contexts (GCs) and possible - protocol errors. If a BadFont error is generated, characters - prior to the offending character may have been drawn. - - The text is drawn using the fonts loaded for the specified font - set; the font in the GC is ignored and may be modified by the - functions. No validation that all fonts conform to some width - rule is performed. - - The text functions XmbDrawText and XwcDrawText use the - following structures: - - - -typedef struct { - char *chars; /* pointer to string */ - int nchars; /* number of bytes */ - int delta; /* pixel delta between strings */ - XFontSet font_set; /* fonts, None means don't change */ -} XmbTextItem; - - - -typedef struct { - wchar_t *chars; /* pointer to wide char string */ - int nchars; /* number of wide characters */ - int delta; /* pixel delta between strings */ - XFontSet font_set; /* fonts, None means don't change */ -} XwcTextItem; - - To draw text using multiple font sets in a given drawable, use - XmbDrawText or XwcDrawText. - - void XmbDrawText(Display *display, Drawable d, GC gc, int x, - int y, XmbTextItem *items, int nitems); - - void XwcDrawText(Display *display, Drawable d, GC gc, int x, - int y, XwcTextItem *items, int nitems); - - display - - Specifies the connection to the X server. - - d - - Specifies the drawable. - - gc - - Specifies the GC. - - x - - y - - Specify the x and y coordinates of the position in the new - parent window. - - items - - Specifies an array of text items. - - nitems - - Specifies the number of text items in the array. - - The XmbDrawText and XwcDrawText functions allow complex spacing - and font set shifts between text strings. Each text item is - processed in turn, with the origin of a text element advanced - in the primary draw direction by the escapement of the previous - text item. A text item delta specifies an additional escapement - of the text item drawing origin in the primary draw direction. - A font_set member other than None in an item causes the font - set to be used for this and subsequent text items in the - text_items list. Leading text items with a font_set member set - to None will not be drawn. - - XmbDrawText and XwcDrawText do not perform any - context-dependent rendering between text segments. Clients may - compute the drawing metrics by passing each text segment to - XmbTextExtents and XwcTextExtents or XmbTextPerCharExtents and - XwcTextPerCharExtents. When the XFontSet has missing charsets, - each unavailable character is drawn with the default string - returned by XCreateFontSet. The behavior for an invalid - codepoint is undefined. - - To draw text using a single font set in a given drawable, use - XmbDrawString or XwcDrawString. - - void XmbDrawString(Display *display, Drawable d, XFontSet - font_set, GC gc, int x, int y, char *string, int num_bytes); - - void XwcDrawString(Display *display, Drawable d, XFontSet - font_set, GC gc, int x, int y, wchar_t *string, int - num_wchars); - - display - - Specifies the connection to the X server. - - d - - Specifies the drawable. - - font_set - - Specifies the font set. - - gc - - Specifies the GC. - - x - - y - - Specify the x and y coordinates of the position in the new - parent window. - - string - - Specifies the character string. - - num_bytes - - Specifies the number of bytes in the string argument. - - num_wchars - - Specifies the number of characters in the string argument. - - The XmbDrawString and XwcDrawString functions draw the - specified text with the foreground pixel. When the XFontSet has - missing charsets, each unavailable character is drawn with the - default string returned by XCreateFontSet. The behavior for an - invalid codepoint is undefined. - - To draw image text using a single font set in a given drawable, - use XmbDrawImageString or XwcDrawImageString. - - void XmbDrawImageString(Display *display, Drawable d, XFontSet - font_set, GC gc, int x, int y, char *string, int num_bytes); - - void XwcDrawImageString(Display *display, Drawable d, XFontSet - font_set, GC gc, int x, int y, wchar_t *string, int - num_wchars); - - display - - Specifies the connection to the X server. - - d - - Specifies the drawable. - - font_set - - Specifies the font set. - - gc - - Specifies the GC. - - x - - y - - Specify the x and y coordinates of the position in the new - parent window. - - string - - Specifies the character string. - - num_bytes - - Specifies the number of bytes in the string argument. - - num_wchars - - Specifies the number of characters in the string argument. - - The XmbDrawImageString and XwcDrawImageString functions fill a - destination rectangle with the background pixel defined in the - GC and then paint the text with the foreground pixel. The - filled rectangle is the rectangle returned to - overall_logical_return by XmbTextExtents or XwcTextExtents for - the same text and XFontSet. - - When the XFontSet has missing charsets, each unavailable - character is drawn with the default string returned by - XCreateFontSet. The behavior for an invalid codepoint is - undefined. - -Input Methods - - This section provides discussions of the following X Input - Method (XIM) topics: - * Input method overview - * Input method management - * Input method functions - * Input method values - * Input context functions - * Input context values - * Input method callback semantics - * Event filtering - * Getting keyboard input - * Input method conventions - -Input Method Overview - - This section provides definitions for terms and concepts used - for internationalized text input and a brief overview of the - intended use of the mechanisms provided by Xlib. - - A large number of languages in the world use alphabets - consisting of a small set of symbols (letters) to form words. - To enter text into a computer in an alphabetic language, a user - usually has a keyboard on which there exist key symbols - corresponding to the alphabet. Sometimes, a few characters of - an alphabetic language are missing on the keyboard. Many - computer users who speak a Latin-alphabet-based language only - have an English-based keyboard. They need to hit a combination - of keystrokes to enter a character that does not exist directly - on the keyboard. A number of algorithms have been developed for - entering such characters. These are known as European input - methods, compose input methods, or dead-key input methods. - - Japanese is an example of a language with a phonetic symbol - set, where each symbol represents a specific sound. There are - two phonetic symbol sets in Japanese: Katakana and Hiragana. In - general, Katakana is used for words that are of foreign origin, - and Hiragana is used for writing native Japanese words. - Collectively, the two systems are called Kana. Each set - consists of 48 characters. - - Korean also has a phonetic symbol set, called Hangul. Each of - the 24 basic phonetic symbols (14 consonants and 10 vowels) - represents a specific sound. A syllable is composed of two or - three parts: the initial consonants, the vowels, and the - optional last consonants. With Hangul, syllables can be treated - as the basic units on which text processing is done. For - example, a delete operation may work on a phonetic symbol or a - syllable. Korean code sets include several thousands of these - syllables. A user types the phonetic symbols that make up the - syllables of the words to be entered. The display may change as - each phonetic symbol is entered. For example, when the second - phonetic symbol of a syllable is entered, the first phonetic - symbol may change its shape and size. Likewise, when the third - phonetic symbol is entered, the first two phonetic symbols may - change their shape and size. - - Not all languages rely solely on alphabetic or phonetic - systems. Some languages, including Japanese and Korean, employ - an ideographic writing system. In an ideographic system, rather - than taking a small set of symbols and combining them in - different ways to create words, each word consists of one - unique symbol (or, occasionally, several symbols). The number - of symbols can be very large: approximately 50,000 have been - identified in Hanzi, the Chinese ideographic system. - - Two major aspects of ideographic systems impact their use with - computers. First, the standard computer character sets in - Japan, China, and Korea include roughly 8,000 characters, while - sets in Taiwan have between 15,000 and 30,000 characters. This - makes it necessary to use more than one byte to represent a - character. Second, it obviously is impractical to have a - keyboard that includes all of a given language's ideographic - symbols. Therefore, a mechanism is required for entering - characters so that a keyboard with a reasonable number of keys - can be used. Those input methods are usually based on - phonetics, but there also exist methods based on the graphical - properties of characters. - - In Japan, both Kana and the ideographic system Kanji are used. - In Korea, Hangul and sometimes the ideographic system Hanja are - used. Now consider entering ideographs in Japan, Korea, China, - and Taiwan. - - In Japan, either Kana or English characters are typed and then - a region is selected (sometimes automatically) for conversion - to Kanji. Several Kanji characters may have the same phonetic - representation. If that is the case with the string entered, a - menu of characters is presented and the user must choose the - appropriate one. If no choice is necessary or a preference has - been established, the input method does the substitution - directly. When Latin characters are converted to Kana or Kanji, - it is called a romaji conversion. - - In Korea, it is usually acceptable to keep Korean text in - Hangul form, but some people may choose to write - Hanja-originated words in Hanja rather than in Hangul. To - change Hangul to Hanja, the user selects a region for - conversion and then follows the same basic method as that - described for Japanese. - - Probably because there are well-accepted phonetic writing - systems for Japanese and Korean, computer input methods in - these countries for entering ideographs are fairly standard. - Keyboard keys have both English characters and phonetic symbols - engraved on them, and the user can switch between the two sets. - - The situation is different for Chinese. While there is a - phonetic system called Pinyin promoted by authorities, there is - no consensus for entering Chinese text. Some vendors use a - phonetic decomposition (Pinyin or another), others use - ideographic decomposition of Chinese words, with various - implementations and keyboard layouts. There are about 16 known - methods, none of which is a clear standard. - - Also, there are actually two ideographic sets used: Traditional - Chinese (the original written Chinese) and Simplified Chinese. - Several years ago, the People's Republic of China launched a - campaign to simplify some ideographic characters and eliminate - redundancies altogether. Under the plan, characters would be - streamlined every five years. Characters have been revised - several times now, resulting in the smaller, simpler set that - makes up Simplified Chinese. - -Input Method Architecture - - As shown in the previous section, there are many different - input methods in use today, each varying with language, - culture, and history. A common feature of many input methods is - that the user may type multiple keystrokes to compose a single - character (or set of characters). The process of composing - characters from keystrokes is called preediting. It may require - complex algorithms and large dictionaries involving substantial - computer resources. - - Input methods may require one or more areas in which to show - the feedback of the actual keystrokes, to propose - disambiguation to the user, to list dictionaries, and so on. - The input method areas of concern are as follows: - * The status area is a logical extension of the LEDs that - exist on the physical keyboard. It is a window that is - intended to present the internal state of the input method - that is critical to the user. The status area may consist - of text data and bitmaps or some combination. - * The preedit area displays the intermediate text for those - languages that are composing prior to the client handling - the data. - * The auxiliary area is used for pop-up menus and customizing - dialogs that may be required for an input method. There may - be multiple auxiliary areas for an input method. Auxiliary - areas are managed by the input method independent of the - client. Auxiliary areas are assumed to be separate dialogs, - which are maintained by the input method. - - There are various user interaction styles used for preediting. - The ones supported by Xlib are as follows: - * For on-the-spot input methods, preediting data will be - displayed directly in the application window. Application - data is moved to allow preedit data to appear at the point - of insertion. - * Over-the-spot preediting means that the data is displayed - in a preedit window that is placed over the point of - insertion. - * Off-the-spot preediting means that the preedit window is - inside the application window but not at the point of - insertion. Often, this type of window is placed at the - bottom of the application window. - * Root-window preediting refers to input methods that use a - preedit window that is the child of RootWindow. - - It would require a lot of computing resources if portable - applications had to include input methods for all the languages - in the world. To avoid this, a goal of the Xlib design is to - allow an application to communicate with an input method placed - in a separate process. Such a process is called an input - server. The server to which the application should connect is - dependent on the environment when the application is started - up, that is, the user language and the actual encoding to be - used for it. The input method connection is said to be - locale-dependent. It is also user-dependent. For a given - language, the user can choose, to some extent, the user - interface style of input method (if choice is possible among - several). - - Using an input server implies communication overhead, but - applications can be migrated without relinking. Input methods - can be implemented either as a stub communicating to an input - server or as a local library. - - An input method may be based on a front-end or a back-end - architecture. In a front-end architecture, there are two - separate connections to the X server: keystrokes go directly - from the X server to the input method on one connection and - other events to the regular client connection. The input method - is then acting as a filter and sends composed strings to the - client. A front-end architecture requires synchronization - between the two connections to avoid lost key events or locking - issues. - - In a back-end architecture, a single X server connection is - used. A dispatching mechanism must decide on this channel to - delegate appropriate keystrokes to the input method. For - instance, it may retain a Help keystroke for its own purpose. - In the case where the input method is a separate process (that - is, a server), there must be a special communication protocol - between the back-end client and the input server. - - A front-end architecture introduces synchronization issues and - a filtering mechanism for noncharacter keystrokes (Function - keys, Help, and so on). A back-end architecture sometimes - implies more communication overhead and more process switching. - If all three processes (X server, input server, client) are - running on a single workstation, there are two process switches - for each keystroke in a back-end architecture, but there is - only one in a front-end architecture. - - The abstraction used by a client to communicate with an input - method is an opaque data structure represented by the XIM data - type. This data structure is returned by the XOpenIM function, - which opens an input method on a given display. Subsequent - operations on this data structure encapsulate all communication - between client and input method. There is no need for an X - client to use any networking library or natural language - package to use an input method. - - A single input server may be used for one or more languages, - supporting one or more encoding schemes. But the strings - returned from an input method will always be encoded in the - (single) locale associated with the XIM object. - -Input Contexts - - Xlib provides the ability to manage a multi-threaded state for - text input. A client may be using multiple windows, each window - with multiple text entry areas, and the user possibly switching - among them at any time. The abstraction for representing the - state of a particular input thread is called an input context. - The Xlib representation of an input context is an XIC. - - An input context is the abstraction retaining the state, - properties, and semantics of communication between a client and - an input method. An input context is a combination of an input - method, a locale specifying the encoding of the character - strings to be returned, a client window, internal state - information, and various layout or appearance characteristics. - The input context concept somewhat matches for input the - graphics context abstraction defined for graphics output. - - One input context belongs to exactly one input method. - Different input contexts may be associated with the same input - method, possibly with the same client window. An XIC is created - with the XCreateIC function, providing an XIM argument and - affiliating the input context to the input method for its - lifetime. When an input method is closed with XCloseIM, all of - its affiliated input contexts should not be used any more (and - should preferably be destroyed before closing the input - method). - - Considering the example of a client window with multiple text - entry areas, the application programmer could, for example, - choose to implement as follows: - * As many input contexts are created as text entry areas, and - the client will get the input accumulated on each context - each time it looks up in that context. - * A single context is created for a top-level window in the - application. If such a window contains several text entry - areas, each time the user moves to another text entry area, - the client has to indicate changes in the context. - - A range of choices can be made by application designers to use - either a single or multiple input contexts, according to the - needs of their application. - -Getting Keyboard Input - - To obtain characters from an input method, a client must call - the function XmbLookupString or XwcLookupString with an input - context created from that input method. Both a locale and - display are bound to an input method when it is opened, and an - input context inherits this locale and display. Any strings - returned by XmbLookupString or XwcLookupString will be encoded - in that locale. - -Focus Management - - For each text entry area in which the XmbLookupString or - XwcLookupString functions are used, there will be an associated - input context. - - When the application focus moves to a text entry area, the - application must set the input context focus to the input - context associated with that area. The input context focus is - set by calling XSetICFocus with the appropriate input context. - - Also, when the application focus moves out of a text entry - area, the application should unset the focus for the associated - input context by calling XUnsetICFocus. As an optimization, if - XSetICFocus is called successively on two different input - contexts, setting the focus on the second will automatically - unset the focus on the first. - - To set and unset the input context focus correctly, it is - necessary to track application-level focus changes. Such focus - changes do not necessarily correspond to X server focus - changes. - - If a single input context is being used to do input for - multiple text entry areas, it will also be necessary to set the - focus window of the input context whenever the focus window - changes (see section 13.5.6.3). - -Geometry Management - - In most input method architectures (on-the-spot being the - notable exception), the input method will perform the display - of its own data. To provide better visual locality, it is often - desirable to have the input method areas embedded within a - client. To do this, the client may need to allocate space for - an input method. Xlib provides support that allows the size and - position of input method areas to be provided by a client. The - input method areas that are supported for geometry management - are the status area and the preedit area. - - The fundamental concept on which geometry management for input - method windows is based is the proper division of - responsibilities between the client (or toolkit) and the input - method. The division of responsibilities is as follows: - * The client is responsible for the geometry of the input - method window. - * The input method is responsible for the contents of the - input method window. - - An input method is able to suggest a size to the client, but it - cannot suggest a placement. Also the input method can only - suggest a size. It does not determine the size, and it must - accept the size it is given. - - Before a client provides geometry management for an input - method, it must determine if geometry management is needed. The - input method indicates the need for geometry management by - setting XIMPreeditArea or XIMStatusArea in its XIMStyles value - returned by XGetIMValues. When a client has decided that it - will provide geometry management for an input method, it - indicates that decision by setting the XNInputStyle value in - the XIC. - - After a client has established with the input method that it - will do geometry management, the client must negotiate the - geometry with the input method. The geometry is negotiated by - the following steps: - * The client suggests an area to the input method by setting - the XNAreaNeeded value for that area. If the client has no - constraints for the input method, it either will not - suggest an area or will set the width and height to zero. - Otherwise, it will set one of the values. - * The client will get the XIC value XNAreaNeeded. The input - method will return its suggested size in this value. The - input method should pay attention to any constraints - suggested by the client. - * The client sets the XIC value XNArea to inform the input - method of the geometry of its window. The client should try - to honor the geometry requested by the input method. The - input method must accept this geometry. - - Clients doing geometry management must be aware that setting - other XIC values may affect the geometry desired by an input - method. For example, XNFontSet and XNLineSpace may change the - geometry desired by the input method. - - The table of XIC values (see section 13.5.6) indicates the - values that can cause the desired geometry to change when they - are set. It is the responsibility of the client to renegotiate - the geometry of the input method window when it is needed. - - In addition, a geometry management callback is provided by - which an input method can initiate a geometry change. - -Event Filtering - - A filtering mechanism is provided to allow input methods to - capture X events transparently to clients. It is expected that - toolkits (or clients) using XmbLookupString or XwcLookupString - will call this filter at some point in the event processing - mechanism to make sure that events needed by an input method - can be filtered by that input method. - - If there were no filter, a client could receive and discard - events that are necessary for the proper functioning of an - input method. The following provides a few examples of such - events: - * Expose events on preedit window in local mode. - * Events may be used by an input method to communicate with - an input server. Such input server protocol-related events - have to be intercepted if one does not want to disturb - client code. - * Key events can be sent to a filter before they are bound to - translations such as those the X Toolkit Intrinsics library - provides. - - Clients are expected to get the XIC value XNFilterEvents and - augment the event mask for the client window with that event - mask. This mask may be zero. - -Callbacks - - When an on-the-spot input method is implemented, only the - client can insert or delete preedit data in place and possibly - scroll existing text. This means that the echo of the - keystrokes has to be achieved by the client itself, tightly - coupled with the input method logic. - - When the user enters a keystroke, the client calls - XmbLookupString or XwcLookupString. At this point, in the - on-the-spot case, the echo of the keystroke in the preedit has - not yet been done. Before returning to the client logic that - handles the input characters, the look-up function must call - the echoing logic to insert the new keystroke. If the - keystrokes entered so far make up a character, the keystrokes - entered need to be deleted, and the composed character will be - returned. Hence, what happens is that, while being called by - client code, the input method logic has to call back to the - client before it returns. The client code, that is, a callback - procedure, is called from the input method logic. - - There are a number of cases where the input method logic has to - call back the client. Each of those cases is associated with a - well-defined callback action. It is possible for the client to - specify, for each input context, what callback is to be called - for each action. - - There are also callbacks provided for feedback of status - information and a callback to initiate a geometry request for - an input method. - -Visible Position Feedback Masks - - In the on-the-spot input style, there is a problem when - attempting to draw preedit strings that are longer than the - available space. Once the display area is exceeded, it is not - clear how best to display the preedit string. The visible - position feedback masks of XIMText help resolve this problem by - allowing the input method to specify hints that indicate the - essential portions of the preedit string. For example, such - hints can help developers implement scrolling of a long preedit - string within a short preedit display area. - -Preedit String Management - - As highlighted before, the input method architecture provides - preediting, which supports a type of preprocessor input - composition. In this case, composition consists of interpreting - a sequence of key events and returning a committed string via - XmbLookupString or XwcLookupString. This provides the basics - for input methods. - - In addition to preediting based on key events, a general - framework is provided to give a client that desires it more - advanced preediting based on the text within the client. This - framework is called string conversion and is provided using XIC - values. The fundamental concept of string conversion is to - allow the input method to manipulate the client's text - independent of any user preediting operation. - - The need for string conversion is based on language needs and - input method capabilities. The following are some examples of - string conversion: - * Transliteration conversion provides language-specific - conversions within the input method. In the case of Korean - input, users wish to convert a Hangul string into a Hanja - string while in preediting, after preediting, or in other - situations (for example, on a selected string). The - conversion is triggered when the user presses a - Hangul-to-Hanja key sequence (which may be input method - specific). Sometimes the user may want to invoke the - conversion after finishing preediting or on a user-selected - string. Thus, the string to be converted is in an - application buffer, not in the preedit area of the input - method. The string conversion services allow the client to - request this transliteration conversion from the input - method. There are many other transliteration conversions - defined for various languages, for example, Kana-to-Kanji - conversion in Japanese. The key to remember is that - transliteration conversions are triggered at the request of - the user and returned to the client immediately without - affecting the preedit area of the input method. - * Reconversion of a previously committed string or a selected - string is supported by many input methods as a convenience - to the user. For example, a user tends to mistype the - commit key while preediting. In that case, some input - methods provide a special key sequence to request a - ``reconvert'' operation on the committed string, similiar - to the undo facility provided by most text editors. Another - example is where the user is proofreading a document that - has some misconversions from preediting and wants to - correct the misconverted text. Such reconversion is again - triggered by the user invoking some special action, but - reconversions should not affect the state of the preedit - area. - * Context-sensitive conversion is required for some languages - and input methods that need to retrieve text that surrounds - the current spot location (cursor position) of the client's - buffer. Such text is needed when the preediting operation - depends on some surrounding characters (usually preceding - the spot location). For example, in Thai language input, - certain character sequences may be invalid and the input - method may want to check whether characters constitute a - valid word. Input methods that do such context-dependent - checking need to retrieve the characters surrounding the - current cursor position to obtain complete words. Unlike - other conversions, this conversion is not explicitly - requested by the user. Input methods that provide such - context-sensitive conversion continuously need to request - context from the client, and any change in the context of - the spot location may affect such conversions. The client's - context would be needed if the user moves the cursor and - starts editing again. For this reason, an input method - supporting this type of conversion should take notice of - when the client calls XmbResetIC or XwcResetIC, which is - usually an indication of a context change. - - Context-sensitive conversions just need a copy of the client's - text, while other conversions replace the client's text with - new text to achieve the reconversion or transliteration. Yet in - all cases the result of a conversion, either immediately or via - preediting, is returned by the XmbLookupString and - XwcLookupString functions. - - String conversion support is dependent on the availability of - the XNStringConversion or XNStringConversionCallback XIC - values. Because the input method may not support string - conversions, clients have to query the availability of string - conversion operations by checking the supported XIC values list - by calling XGetIMValues with the XNQueryICValuesList IM value. - - The difference between these two values is whether the - conversion is invoked by the client or the input method. The - XNStringConversion XIC value is used by clients to request a - string conversion from the input method. The client is - responsible for determining which events are used to trigger - the string conversion and whether the string to be converted - should be copied or deleted. The type of conversion is - determined by the input method; the client can only pass the - string to be converted. The client is guaranteed that no - XNStringConversionCallback will be issued when this value is - set; thus, the client need only set one of these values. - - The XNStringConversionCallback XIC value is used by the client - to notify the input method that it will accept requests from - the input method for string conversion. If this value is set, - it is the input method's responsibility to determine which - events are used to trigger the string conversion. When such - events occur, the input method issues a call to the - client-supplied procedure to retrieve the string to be - converted. The client's callback procedure is notified whether - to copy or delete the string and is provided with hints as to - the amount of text needed. The - XIMStringConversionCallbackStruct specifies which text should - be passed back to the input method. - - Finally, the input method may call the client's - XNStringConversionCallback procedure multiple times if the - string returned from the callback is not sufficient to perform - a successful conversion. The arguments to the client's - procedure allow the input method to define a position (in - character units) relative to the client's cursor position and - the size of the text needed. By varying the position and size - of the desired text in subsequent callbacks, the input method - can retrieve additional text. - -Input Method Management - - The interface to input methods might appear to be simply - creating an input method (XOpenIM) and freeing an input method - (XCloseIM). However, input methods may require complex - communication with input method servers (IM servers), for - example: - * If the X server, IM server, and X clients are started - asynchronously, some clients may attempt to connect to the - IM server before it is fully operational, and fail. - Therefore, some mechanism is needed to allow clients to - detect when an IM server has started. - - It is up to clients to decide what should be done when an IM - server is not available (for example, wait, or use some other - IM server). - - * Some input methods may allow the underlying IM server to be - switched. Such customization may be desired without - restarting the entire client. - - To support management of input methods in these cases, the - following functions are provided: - XRegisterIMInstantiateCallback This function allows clients to - register a callback procedure to be called when Xlib detects - that an IM server is up and available. - XOpenIM A client calls this function as a result of the - callback procedure being called. - XSetIMValues, XSetICValues These functions use the XIM and XIC - values, XNDestroyCallback, to allow a client to register a - callback procedure to be called when Xlib detects that an IM - server that was associated with an opened input method is no - longer available. In addition, this function can be used to - switch IM servers for those input methods that support such - functionality. The IM value for switching IM servers is - implementation-dependent; see the description below about - switching IM servers. - XUnregisterIMInstantiateCallback This function removes a - callback procedure registered by the client. - - Input methods that support switching of IM servers may exhibit - some side-effects: - * The input method will ensure that any new IM server - supports any of the input styles being used by input - contexts already associated with the input method. However, - the list of supported input styles may be different. - - * Geometry management requests on previously created input - contexts may be initiated by the new IM server. - -Hot Keys - - Some clients need to guarantee which keys can be used to escape - from the input method, regardless of the input method state; - for example, the client-specific Help key or the keys to move - the input focus. The HotKey mechanism allows clients to specify - a set of keys for this purpose. However, the input method might - not allow clients to specify hot keys. Therefore, clients have - to query support of hot keys by checking the supported XIC - values list by calling XGetIMValues with the - XNQueryICValuesList IM value. When the hot keys specified - conflict with the key bindings of the input method, hot keys - take precedence over the key bindings of the input method. - -Preedit State Operation - - An input method may have several internal states, depending on - its implementation and the locale. However, one state that is - independent of locale and implementation is whether the input - method is currently performing a preediting operation. Xlib - provides the ability for an application to manage the preedit - state programmatically. Two methods are provided for retrieving - the preedit state of an input context. One method is to query - the state by calling XGetICValues with the XNPreeditState XIC - value. Another method is to receive notification whenever the - preedit state is changed. To receive such notification, an - application needs to register a callback by calling - XSetICValues with the XNPreeditStateNotifyCallback XIC value. - In order to change the preedit state programmatically, an - application needs to call XSetICValues with XNPreeditState. - - Availability of the preedit state is input method dependent. - The input method may not provide the ability to set the state - or to retrieve the state programmatically. Therefore, clients - have to query availability of preedit state operations by - checking the supported XIC values list by calling XGetIMValues - with the XNQueryICValuesList IM value. - -Input Method Functions - - To open a connection, use XOpenIM. - - XIM XOpenIM(Display *display, XrmDatabase db, char *res_name, - char *res_class); - - display - - Specifies the connection to the X server. - - db - - Specifies a pointer to the resource database. - - res_name - - Specifies the full resource name of the application. - - res_class - - Specifies the full class name of the application. - - The XOpenIM function opens an input method, matching the - current locale and modifiers specification. Current locale and - modifiers are bound to the input method at opening time. The - locale associated with an input method cannot be changed - dynamically. This implies that the strings returned by - XmbLookupString or XwcLookupString, for any input context - affiliated with a given input method, will be encoded in the - locale current at the time the input method is opened. - - The specific input method to which this call will be routed is - identified on the basis of the current locale. XOpenIM will - identify a default input method corresponding to the current - locale. That default can be modified using XSetLocaleModifiers - for the input method modifier. - - The db argument is the resource database to be used by the - input method for looking up resources that are private to the - input method. It is not intended that this database be used to - look up values that can be set as IC values in an input - context. If db is NULL, no database is passed to the input - method. - - The res_name and res_class arguments specify the resource name - and class of the application. They are intended to be used as - prefixes by the input method when looking up resources that are - common to all input contexts that may be created for this input - method. The characters used for resource names and classes must - be in the X Portable Character Set. The resources looked up are - not fully specified if res_name or res_class is NULL. - - The res_name and res_class arguments are not assumed to exist - beyond the call to XOpenIM. The specified resource database is - assumed to exist for the lifetime of the input method. - - XOpenIM returns NULL if no input method could be opened. - - To close a connection, use XCloseIM. - - Status XCloseIM(XIM im); - - im - - Specifies the input method. - - The XCloseIM function closes the specified input method. - - To set input method attributes, use XSetIMValues. - - char *XSetIMValues(XIM im); - - im - - Specifies the input method. - - ... - - Specifies the variable-length argument list to set XIM values. - - The XSetIMValues function presents a variable argument list - programming interface for setting attributes of the specified - input method. It returns NULL if it succeeds; otherwise, it - returns the name of the first argument that could not be set. - Xlib does not attempt to set arguments from the supplied list - that follow the failed argument; all arguments in the list - preceding the failed argument have been set correctly. - - To query an input method, use XGetIMValues. - - char *XGetIMValues(XIM im); - - im - - Specifies the input method. - - ... - - Specifies the variable length argument list to get XIM values. - - The XGetIMValues function presents a variable argument list - programming interface for querying properties or features of - the specified input method. This function returns NULL if it - succeeds; otherwise, it returns the name of the first argument - that could not be obtained. - - Each XIM value argument (following a name) must point to a - location where the XIM value is to be stored. That is, if the - XIM value is of type T, the argument must be of type T*. If T - itself is a pointer type, then XGetIMValues allocates memory to - store the actual data, and the client is responsible for - freeing this data by calling XFree with the returned pointer. - - To obtain the display associated with an input method, use - XDisplayOfIM. - - Display *XDisplayOfIM(XIM im); - - im - - Specifies the input method. - - The XDisplayOfIM function returns the display associated with - the specified input method. - - To get the locale associated with an input method, use - XLocaleOfIM. - - char *XLocaleOfIM(XIM im); - - im - - Specifies the input method. - - The XLocaleOfIM function returns the locale associated with the - specified input method. - - To register an input method instantiate callback, use - XRegisterIMInstantiateCallback. - - Bool XRegisterIMInstantiateCallback(Display *display, - XrmDatabase db, char *res_name, char *res_class, XIMProc - callback, XPointer *client_data); - - display - - Specifies the connection to the X server. - - db - - Specifies a pointer to the resource database. - - res_name - - Specifies the full resource name of the application. - - res_class - - Specifies the full class name of the application. - - callback - - Specifies a pointer to the input method instantiate callback. - - client_data - - Specifies the additional client data. - - The XRegisterIMInstantiateCallback function registers a - callback to be invoked whenever a new input method becomes - available for the specified display that matches the current - locale and modifiers. - - The function returns True if it succeeds; otherwise, it returns - False. - - The generic prototype is as follows: - - void IMInstantiateCallback(Display *display, XPointer - client_data, XPointer call_data); - - display - - Specifies the connection to the X server. - - client_data - - Specifies the additional client data. - - call_data - - Not used for this callback and always passed as NULL. - - To unregister an input method instantiation callback, use - XUnregisterIMInstantiateCallback. - - Bool XUnregisterIMInstantiateCallback(Display *display, - XrmDatabase db, char *res_name, char *res_class, XIMProc - callback, XPointer *client_data); - - display - - Specifies the connection to the X server. - - db - - Specifies a pointer to the resource database. - - res_name - - Specifies the full resource name of the application. - - res_class - - Specifies the full class name of the application. - - callback - - Specifies a pointer to the input method instantiate callback. - - client_data - - Specifies the additional client data. - - The XUnregisterIMInstantiateCallback function removes an input - method instantiation callback previously registered. The - function returns True if it succeeds; otherwise, it returns - False. - -Input Method Values - - The following table describes how XIM values are interpreted by - an input method. The first column lists the XIM values. The - second column indicates how each of the XIM values are treated - by that input style. - - The following keys apply to this table. - Key Explanation - D This value may be set using XSetIMValues. If it is not set, a - default is provided. - S This value may be set using XSetIMValues. - G This value may be read using XGetIMValues. - - XIM Value Key - XNQueryInputStyle G - XNResourceName D-S-G - XNResourceClass D-S-G - XNDestroyCallback D-S-G - XNQueryIMValuesList G - XNQueryICValuesList G - XNVisiblePosition G - XNR6PreeditCallback D-S-G - - XNR6PreeditCallback is obsolete and its use is not recommended - (see section 13.5.4.6). - -Query Input Style - - A client should always query the input method to determine - which input styles are supported. The client should then find - an input style it is capable of supporting. - - If the client cannot find an input style that it can support, - it should negotiate with the user the continuation of the - program (exit, choose another input method, and so on). - - The argument value must be a pointer to a location where the - returned value will be stored. The returned value is a pointer - to a structure of type XIMStyles. Clients are responsible for - freeing the XIMStyles structure. To do so, use XFree. - - The XIMStyles structure is defined as follows: -typedef unsigned long XIMStyle; - - -#define XIMPreeditArea 0x0001L -#define XIMPreeditCallbacks 0x0002L -#define XIMPreeditPosition 0x0004L -#define XIMPreeditNothing 0x0008L -#define XIMPreeditNone 0x0010L - -#define XIMStatusArea 0x0100L -#define XIMStatusCallbacks 0x0200L -#define XIMStatusNothing 0x0400L -#define XIMStatusNone 0x0800L - -typedef struct { - unsigned short count_styles; - XIMStyle * supported_styles; -} XIMStyles; - - - An XIMStyles structure contains the number of input styles - supported in its count_styles field. This is also the size of - the supported_styles array. - - The supported styles is a list of bitmask combinations, which - indicate the combination of styles for each of the areas - supported. These areas are described later. Each element in the - list should select one of the bitmask values for each area. The - list describes the complete set of combinations supported. Only - these combinations are supported by the input method. - - The preedit category defines what type of support is provided - by the input method for preedit information. - XIMPreeditArea If chosen, the input method would require the - client to provide some area values for it to do its preediting. - Refer to XIC values XNArea and XNAreaNeeded. - XIMPreeditPosition If chosen, the input method would require - the client to provide positional values. Refer to XIC values - XNSpotLocation and XNFocusWindow. - XIMPreeditCallbacks If chosen, the input method would require - the client to define the set of preedit callbacks. Refer to XIC - values XNPreeditStartCallback, XNPreeditDoneCallback, - XNPreeditDrawCallback, and XNPreeditCaretCallback. - XIMPreeditNothing If chosen, the input method can function - without any preedit values. - XIMPreeditNone The input method does not provide any preedit - feedback. Any preedit value is ignored. This style is mutually - exclusive with the other preedit styles. - - The status category defines what type of support is provided by - the input method for status information. - XIMStatusArea The input method requires the client to provide - some area values for it to do its status feedback. See XNArea - and XNAreaNeeded. - XIMStatusCallbacks The input method requires the client to - define the set of status callbacks, XNStatusStartCallback, - XNStatusDoneCallback, and XNStatusDrawCallback. - XIMStatusNothing The input method can function without any - status values. - XIMStatusNone The input method does not provide any status - feedback. If chosen, any status value is ignored. This style is - mutually exclusive with the other status styles. - -Resource Name and Class - - The XNResourceName and XNResourceClass arguments are strings - that specify the full name and class used by the input method. - These values should be used as prefixes for the name and class - when looking up resources that may vary according to the input - method. If these values are not set, the resources will not be - fully specified. - - It is not intended that values that can be set as XIM values be - set as resources. - -Destroy Callback - - The XNDestroyCallback argument is a pointer to a structure of - type XIMCallback. XNDestroyCallback is triggered when an input - method stops its service for any reason. After the callback is - invoked, the input method is closed and the associated input - context(s) are destroyed by Xlib. Therefore, the client should - not call XCloseIM or XDestroyIC. - - The generic prototype of this callback function is as follows: - - void DestroyCallback(XIM im, XPointer client_data, XPointer - call_data); - - im - - Specifies the input method. - - client_data - - Specifies the additional client data. - - call_data - - Not used for this callback and always passed as NULL. - - A DestroyCallback is always called with a NULL call_data - argument. - -Query IM/IC Values List - - XNQueryIMValuesList and XNQueryICValuesList are used to query - about XIM and XIC values supported by the input method. - - The argument value must be a pointer to a location where the - returned value will be stored. The returned value is a pointer - to a structure of type XIMValuesList. Clients are responsible - for freeing the XIMValuesList structure. To do so, use XFree. - - The XIMValuesList structure is defined as follows: - - -typedef struct { - unsigned short count_values; - char **supported_values; -} XIMValuesList; - -Visible Position - - The XNVisiblePosition argument indicates whether the visible - position masks of XIMFeedback in XIMText are available. - - The argument value must be a pointer to a location where the - returned value will be stored. The returned value is of type - Bool. If the returned value is True, the input method uses the - visible position masks of XIMFeedback in XIMText; otherwise, - the input method does not use the masks. - - Because this XIM value is optional, a client should call - XGetIMValues with argument XNQueryIMValuesList before using - this argument. If the XNVisiblePosition does not exist in the - IM values list returned from XNQueryIMValuesList, the visible - position masks of XIMFeedback in XIMText are not used to - indicate the visible position. - -Preedit Callback Behavior - - The XNR6PreeditCallback argument originally included in the - X11R6 specification has been deprecated.\(dg During formulation - of the X11R6 specification, the behavior of the R6 - PreeditDrawCallbacks was going to differ significantly from - that of the R5 callbacks. Late changes to the specification - converged the R5 and R6 behaviors, eliminating the need for - XNR6PreeditCallback. Unfortunately, this argument was not - removed from the R6 specification before it was published. - - The XNR6PreeditCallback argument indicates whether the behavior - of preedit callbacks regarding XIMPreeditDrawCallbackStruct - values follows Release 5 or Release 6 semantics. - - The value is of type Bool. When querying for - XNR6PreeditCallback, if the returned value is True, the input - method uses the Release 6 behavior; otherwise, it uses the - Release 5 behavior. The default value is False. In order to use - Release 6 semantics, the value of XNR6PreeditCallback must be - set to True. - - Because this XIM value is optional, a client should call - XGetIMValues with argument XNQueryIMValuesList before using - this argument. If the XNR6PreeditCallback does not exist in the - IM values list returned from XNQueryIMValuesList, the - PreeditCallback behavior is Release 5 semantics. - -Input Context Functions - - An input context is an abstraction that is used to contain both - the data required (if any) by an input method and the - information required to display that data. There may be - multiple input contexts for one input method. The programming - interfaces for creating, reading, or modifying an input context - use a variable argument list. The name elements of the argument - lists are referred to as XIC values. It is intended that input - methods be controlled by these XIC values. As new XIC values - are created, they should be registered with the X Consortium. - - To create an input context, use XCreateIC. - - XIC XCreateIC(XIM im); - - im - - Specifies the input method. - - ... - - Specifies the variable length argument list to set XIC values. - - The XCreateIC function creates a context within the specified - input method. - - Some of the arguments are mandatory at creation time, and the - input context will not be created if those arguments are not - provided. The mandatory arguments are the input style and the - set of text callbacks (if the input style selected requires - callbacks). All other input context values can be set later. - - XCreateIC returns a NULL value if no input context could be - created. A NULL value could be returned for any of the - following reasons: - * A required argument was not set. - * A read-only argument was set (for example, XNFilterEvents). - * The argument name is not recognized. - * The input method encountered an input method - implementation-dependent error. - - XCreateIC can generate BadAtom, BadColor, BadPixmap, and - BadWindow errors. - - To destroy an input context, use XDestroyIC. - - void XDestroyIC(XIC ic); - - ic - - Specifies the input context. - - XDestroyIC destroys the specified input context. - - To communicate to and synchronize with input method for any - changes in keyboard focus from the client side, use XSetICFocus - and XUnsetICFocus. - - void XSetICFocus(XIC ic); - - ic - - Specifies the input context. - - The XSetICFocus function allows a client to notify an input - method that the focus window attached to the specified input - context has received keyboard focus. The input method should - take action to provide appropriate feedback. Complete feedback - specification is a matter of user interface policy. - - Calling XSetICFocus does not affect the focus window value. - - void XUnsetICFocus(XIC ic); - - ic - - Specifies the input context. - - The XUnsetICFocus function allows a client to notify an input - method that the specified input context has lost the keyboard - focus and that no more input is expected on the focus window - attached to that input context. The input method should take - action to provide appropriate feedback. Complete feedback - specification is a matter of user interface policy. - - Calling XUnsetICFocus does not affect the focus window value; - the client may still receive events from the input method that - are directed to the focus window. - - To reset the state of an input context to its initial state, - use XmbResetIC or XwcResetIC. - - char *XmbResetIC(XIC ic); - - wchar_t *XwcResetIC(XIC ic); - - ic - - Specifies the input context. - - When XNResetState is set to XIMInitialState, XmbResetIC and - XwcResetIC reset an input context to its initial state; when - XNResetState is set to XIMPreserveState, the current input - context state is preserved. In both cases, any input pending on - that context is deleted. The input method is required to clear - the preedit area, if any, and update the status accordingly. - Calling XmbResetIC or XwcResetIC does not change the focus. - - The return value of XmbResetIC is its current preedit string as - a multibyte string. If there is any preedit text drawn or - visible to the user, then these procedures must return a - non-NULL string. If there is no visible preedit text, then it - is input method implementation-dependent whether these - procedures return a non-NULL string or NULL. - - The client should free the returned string by calling XFree. - - To get the input method associated with an input context, use - XIMOfIC. - - XIM XIMOfIC(XIC ic); - - ic - - Specifies the input context. - - The XIMOfIC function returns the input method associated with - the specified input context. - - Xlib provides two functions for setting and reading XIC values, - respectively, XSetICValues and XGetICValues. Both functions - have a variable-length argument list. In that argument list, - any XIC value's name must be denoted with a character string - using the X Portable Character Set. - - To set XIC values, use XSetICValues. - - char *XSetICValues(XIC ic); - - ic - - Specifies the input context. - - ... - - Specifies the variable length argument list to set XIC values. - - The XSetICValues function returns NULL if no error occurred; - otherwise, it returns the name of the first argument that could - not be set. An argument might not be set for any of the - following reasons: - * The argument is read-only (for example, XNFilterEvents). - * The argument name is not recognized. - * An implementation-dependent error occurs. - - Each value to be set must be an appropriate datum, matching the - data type imposed by the semantics of the argument. - - XSetICValues can generate BadAtom, BadColor, BadCursor, - BadPixmap, and BadWindow errors. - - To obtain XIC values, use XGetICValues. - - char *XGetICValues(XIC ic); - - ic - - Specifies the input context. - - ... - - Specifies the variable length argument list to get XIC values. - - The XGetICValues function returns NULL if no error occurred; - otherwise, it returns the name of the first argument that could - not be obtained. An argument could not be obtained for any of - the following reasons: - * The argument name is not recognized. - * The input method encountered an implementation-dependent - error. - - Each IC attribute value argument (following a name) must point - to a location where the IC value is to be stored. That is, if - the IC value is of type T, the argument must be of type T*. If - T itself is a pointer type, then XGetICValues allocates memory - to store the actual data, and the client is responsible for - freeing this data by calling XFree with the returned pointer. - The exception to this rule is for an IC value of type - XVaNestedList (for preedit and status attributes). In this - case, the argument must also be of type XVaNestedList. Then, - the rule of changing type T to T* and freeing the allocated - data applies to each element of the nested list. - -Input Context Values - - The following tables describe how XIC values are interpreted by - an input method depending on the input style chosen by the - user. - - The first column lists the XIC values. The second column - indicates which values are involved in affecting, negotiating, - and setting the geometry of the input method windows. The - subentries under the third column indicate the different input - styles that are supported. Each of these columns indicates how - each of the XIC values are treated by that input style. - - The following keys apply to these tables. - Key Explanation - C This value must be set with XCreateIC. - D This value may be set using XCreateIC.> If it is not set,> a - default is provided. - G This value may be read using XGetICValues. - GN This value may cause geometry negotiation when its value is - set by means of XCreateIC or XSetICValues. - GR This value will be the response of the input method when any - GN value is changed. - GS This value will cause the geometry of the input method - window to be set. - O This value must be set once and only once. It need not be set - at create time. - S This value may be set with XSetICValues. - Ignored This value is ignored by the input method for the given - input style. - - XIC Value Geometry Mangement Preedit Callback Preedit Position - Input Style Preedit Area Preedit Nothing Preedit None - Input Style C-G C-G C-G C-G C-G - Client Window O-G O-G O-G O-G Ignored - Focus Window GN D-S-G D-S-G D-S-G D-S-G Ignored - Resource Name Ignored D-S-G D-S-G D-S-G Ignored - Resource Class Ignored D-S-G D-S-G D-S-G Ignored - Geometry Callback Ignored Ignored D-S-G Ignored Ignored - Filter Events G G G G Ignored - Destroy Callback D-S-G D-S-G D-S-G D-S-G D-S-G - String Conversion Callback S-G S-G S-G S-G S-G - String Conversion D-S-G D-S-G D-S-G D-S-G D-S-G - Reset State D-S-G D-S-G D-S-G D-S-G Ignored - HotKey S-G S-G S-G S-G Ignored - HotKeyState D-S-G D-S-G D-S-G D-S-G Ignored - Preedit - Area GS Ignored D-S-G D-S-G Ignored Ignored - Area Needed GN-GR Ignored Ignored S-G Ignored Ignored - Spot Location Ignored D-S-G Ignored Ignored Ignored - Colormap Ignored D-S-G D-S-G D-S-G Ignored - Foreground Ignored D-S-G D-S-G D-S-G Ignored - Background Ignored D-S-G D-S-G D-S-G Ignored - Background Pixmap Ignored D-S-G D-S-G D-S-G Ignored - Font Set GN Ignored D-S-G D-S-G D-S-G Ignored - Line Spacing GN Ignored D-S-G D-S-G D-S-G Ignored - Cursor Ignored D-S-G D-S-G D-S-G Ignored - Preedit State D-S-G D-S-G D-S-G D-S-G Ignored - Preedit State Notify Callback S-G S-G S-G S-G Ignored - Preedit Callbacks C-S-G Ignored Ignored Ignored Ignored - - XIC Value Geomentry Management Status Callback Status Area - Status Nothing Status None - Input Style C-G C-G C-G C-G - Client Window O-G O-G O-G Ignored - Focus Window GN D-S-G D-S-G D-S-G Ignored - Resource Name Ignored D-S-G D-S-G Ignored - Resource Class Ignored D-S-G D-S-G Ignored - Geometry Callback Ignored D-S-G Ignored Ignored - Filter Events G G G G - Status - Area GS Ignored D-S-G Ignored Ignored - Area Needed GN-GR Ignored S-G Ignored Ignored - Colormap Ignored D-S-G D-S-G Ignored - Foreground Ignored D-S-G D-S-G Ignored - Background Ignored D-S-G D-S-G Ignored - Background Pixmap Ignored D-S-G D-S-G Ignored - Font Set GN Ignored D-S-G D-S-G Ignored - Line Spacing GN Ignored D-S-G D-S-G Ignored - Cursor Ignored D-S-G D-S-G Ignored - Status Callbacks C-S-G Ignored Ignored Ignored - -Input Style - - The XNInputStyle argument specifies the input style to be used. - The value of this argument must be one of the values returned - by the XGetIMValues function with the XNQueryInputStyle - argument specified in the supported_styles list. - - Note that this argument must be set at creation time and cannot - be changed. - -Client Window - - The XNClientWindow argument specifies to the input method the - client window in which the input method can display data or - create subwindows. Geometry values for input method areas are - given with respect to the client window. Dynamic change of - client window is not supported. This argument may be set only - once and should be set before any input is done using this - input context. If it is not set, the input method may not - operate correctly. - - If an attempt is made to set this value a second time with - XSetICValues, the string XNClientWindow will be returned by - XSetICValues, and the client window will not be changed. - - If the client window is not a valid window ID on the display - attached to the input method, a BadWindow error can be - generated when this value is used by the input method. - -Focus Window - - The XNFocusWindow argument specifies the focus window. The - primary purpose of the XNFocusWindow is to identify the window - that will receive the key event when input is composed. In - addition, the input method may possibly affect the focus window - as follows: - * Select events on it - * Send events to it - * Modify its properties - * Grab the keyboard within that window - - The associated value must be of type Window. If the focus - window is not a valid window ID on the display attached to the - input method, a BadWindow error can be generated when this - value is used by the input method. - - When this XIC value is left unspecified, the input method will - use the client window as the default focus window. - -Resource Name and Class - - The XNResourceName and XNResourceClass arguments are strings - that specify the full name and class used by the client to - obtain resources for the client window. These values should be - used as prefixes for name and class when looking up resources - that may vary according to the input context. If these values - are not set, the resources will not be fully specified. - - It is not intended that values that can be set as XIC values be - set as resources. - -Geometry Callback - - The XNGeometryCallback argument is a structure of type - XIMCallback (see section 13.5.6.13.12). - - The XNGeometryCallback argument specifies the geometry callback - that a client can set. This callback is not required for - correct operation of either an input method or a client. It can - be set for a client whose user interface policy permits an - input method to request the dynamic change of that input - method's window. An input method that does dynamic change will - need to filter any events that it uses to initiate the change. - -Filter Events - - The XNFilterEvents argument returns the event mask that an - input method needs to have selected for. The client is expected - to augment its own event mask for the client window with this - one. - - This argument is read-only, is set by the input method at - create time, and is never changed. - - The type of this argument is unsigned long. Setting this value - will cause an error. - -Destroy Callback - - The XNDestroyCallback argument is a pointer to a structure of - type XIMCallback (see section 13.5.6.13.12). This callback is - triggered when the input method stops its service for any - reason; for example, when a connection to an IM server is - broken. After the destroy callback is called, the input context - is destroyed and the input method is closed. Therefore, the - client should not call XDestroyIC and XCloseIM. - -String Conversion Callback - - The XNStringConversionCallback argument is a structure of type - XIMCallback (see section 13.5.6.13.12). - - The XNStringConversionCallback argument specifies a string - conversion callback. This callback is not required for correct - operation of either the input method or the client. It can be - set by a client to support string conversions that may be - requested by the input method. An input method that does string - conversions will filter any events that it uses to initiate the - conversion. - - Because this XIC value is optional, a client should call - XGetIMValues with argument XNQueryICValuesList before using - this argument. - -String Conversion - - The XNStringConversion argument is a structure of type - XIMStringConversionText. - - The XNStringConversion argument specifies the string to be - converted by an input method. This argument is not required for - correct operation of either the input method or the client. - - String conversion facilitates the manipulation of text - independent of preediting. It is essential for some input - methods and clients to manipulate text by performing - context-sensitive conversion, reconversion, or transliteration - conversion on it. - - Because this XIC value is optional, a client should call - XGetIMValues with argument XNQueryICValuesList before using - this argument. - - The XIMStringConversionText structure is defined as follows: - - -typedef struct _XIMStringConversionText { - unsigned short length; - XIMStringConversionFeedback *feedback; - Bool encoding_is_wchar; - union { - char *mbs; - wchar_t *wcs; - } string; -} XIMStringConversionText; - -typedef unsigned long XIMStringConversionFeedback; - - The feedback member is reserved for future use. The text to be - converted is defined by the string and length members. The - length is indicated in characters. To prevent the library from - freeing memory pointed to by an uninitialized pointer, the - client should set the feedback element to NULL. - -Reset State - - The XNResetState argument specifies the state the input context - will return to after calling XmbResetIC or XwcResetIC. - - The XIC state may be set to its initial state, as specified by - the XNPreeditState value when XCreateIC was called, or it may - be set to preserve the current state. - - The valid masks for XIMResetState are as follows: - -typedef unsigned long XIMResetState; - -#define XIMInitialState (1L) -#define XIMPreserveState (1L<<1) - - - If XIMInitialState is set, then XmbResetIC and XwcResetIC will - return to the initial XNPreeditState state of the XIC. - - If XIMPreserveState is set, then XmbResetIC and XwcResetIC will - preserve the current state of the XIC. - - If XNResetState is left unspecified, the default is - XIMInitialState. - - XIMResetState values other than those specified above will - default to XIMInitialState. - - Because this XIC value is optional, a client should call - XGetIMValues with argument XNQueryICValuesList before using - this argument. - -Hot Keys - - The XNHotKey argument specifies the hot key list to the XIC. - The hot key list is a pointer to the structure of type - XIMHotKeyTriggers, which specifies the key events that must be - received without any interruption of the input method. For the - hot key list set with this argument to be utilized, the client - must also set XNHotKeyState to XIMHotKeyStateON. - - Because this XIC value is optional, a client should call - XGetIMValues with argument XNQueryICValuesList before using - this functionality. - - The value of the argument is a pointer to a structure of type - XIMHotKeyTriggers. - - If an event for a key in the hot key list is found, then the - process will receive the event and it will be processed inside - the client. - - - -typedef struct { - KeySym keysym; - unsigned int modifier; - unsigned int modifier_mask; -} XIMHotKeyTrigger; - -typedef struct { - int num_hot_key; - XIMHotKeyTrigger *key; -} XIMHotKeyTriggers; - - The combination of modifier and modifier_mask are used to - represent one of three states for each modifier: either the - modifier must be on, or the modifier must be off, or the - modifier is a ``don't care'' - it may be on or off. When a - modifier_mask bit is set to 0, the state of the associated - modifier is ignored when evaluating whether the key is hot or - not. - Modifier Bit Mask Bit Meaning - 0 1 The modifier must be off. - 1 1 The modifier must be on. - n/a 0 Do not care if the modifier is on or off. - -Hot Key State - - The XNHotKeyState argument specifies the hot key state of the - input method. This is usually used to switch the input method - between hot key operation and normal input processing. - - The value of the argument is a pointer to a structure of type - XIMHotKeyState . -typedef unsigned long XIMHotKeyState; - -#define XIMHotKeyStateON (0x0001L) -#define XIMHotKeyStateOFF (0x0002L) - - - If not specified, the default is XIMHotKeyStateOFF. - -Preedit and Status Attributes - - The XNPreeditAttributes and XNStatusAttributes arguments - specify to an input method the attributes to be used for the - preedit and status areas, if any. Those attributes are passed - to XSetICValues or XGetICValues as a nested variable-length - list. The names to be used in these lists are described in the - following sections. - -Area - - The value of the XNArea argument must be a pointer to a - structure of type XRectangle. The interpretation of the XNArea - argument is dependent on the input method style that has been - set. - - If the input method style is XIMPreeditPosition, XNArea - specifies the clipping region within which preediting will take - place. If the focus window has been set, the coordinates are - assumed to be relative to the focus window. Otherwise, the - coordinates are assumed to be relative to the client window. If - neither has been set, the results are undefined. - - If XNArea is not specified, is set to NULL, or is invalid, the - input method will default the clipping region to the geometry - of the XNFocusWindow. If the area specified is NULL or invalid, - the results are undefined. - - If the input style is XIMPreeditArea or XIMStatusArea, XNArea - specifies the geometry provided by the client to the input - method. The input method may use this area to display its data, - either preedit or status depending on the area designated. The - input method may create a window as a child of the client - window with dimensions that fit the XNArea. The coordinates are - relative to the client window. If the client window has not - been set yet, the input method should save these values and - apply them when the client window is set. If XNArea is not - specified, is set to NULL, or is invalid, the results are - undefined. - -Area Needed - - When set, the XNAreaNeeded argument specifies the geometry - suggested by the client for this area (preedit or status). The - value associated with the argument must be a pointer to a - structure of type XRectangle. Note that the x, y values are not - used and that nonzero values for width or height are the - constraints that the client wishes the input method to respect. - - When read, the XNAreaNeeded argument specifies the preferred - geometry desired by the input method for the area. - - This argument is only valid if the input style is - XIMPreeditArea or XIMStatusArea. It is used for geometry - negotiation between the client and the input method and has no - other effect on the input method (see section 13.5.1.5). - -Spot Location - - The XNSpotLocation argument specifies to the input method the - coordinates of the spot to be used by an input method executing - with XNInputStyle set to XIMPreeditPosition. When specified to - any input method other than XIMPreeditPosition, this XIC value - is ignored. - - The x coordinate specifies the position where the next - character would be inserted. The y coordinate is the position - of the baseline used by the current text line in the focus - window. The x and y coordinates are relative to the focus - window, if it has been set; otherwise, they are relative to the - client window. If neither the focus window nor the client - window has been set, the results are undefined. - - The value of the argument is a pointer to a structure of type - XPoint. - -Colormap - - Two different arguments can be used to indicate what colormap - the input method should use to allocate colors, a colormap ID, - or a standard colormap name. - - The XNColormap argument is used to specify a colormap ID. The - argument value is of type Colormap. An invalid argument may - generate a BadColor error when it is used by the input method. - - The XNStdColormap argument is used to indicate the name of the - standard colormap in which the input method should allocate - colors. The argument value is an Atom that should be a valid - atom for calling XGetRGBColormaps. An invalid argument may - generate a BadAtom error when it is used by the input method. - - If the colormap is left unspecified, the client window colormap - becomes the default. - -Foreground and Background - - The XNForeground and XNBackground arguments specify the - foreground and background pixel, respectively. The argument - value is of type unsigned long. It must be a valid pixel in the - input method colormap. - - If these values are left unspecified, the default is determined - by the input method. - -Background Pixmap - - The XNBackgroundPixmap argument specifies a background pixmap - to be used as the background of the window. The value must be - of type Pixmap. An invalid argument may generate a BadPixmap - error when it is used by the input method. - - If this value is left unspecified, the default is determined by - the input method. - -Font Set - - The XNFontSet argument specifies to the input method what font - set is to be used. The argument value is of type XFontSet. - - If this value is left unspecified, the default is determined by - the input method. - -Line Spacing - - The XNLineSpace argument specifies to the input method what - line spacing is to be used in the preedit window if more than - one line is to be used. This argument is of type int. - - If this value is left unspecified, the default is determined by - the input method. - -Cursor - - The XNCursor argument specifies to the input method what cursor - is to be used in the specified window. This argument is of type - Cursor. - - An invalid argument may generate a BadCursor error when it is - used by the input method. If this value is left unspecified, - the default is determined by the input method. - -Preedit State - - The XNPreeditState argument specifies the state of input - preediting for the input method. Input preediting can be on or - off. - - The valid mask names for XNPreeditState are as follows: - -typedef unsigned long XIMPreeditState; - -#define XIMPreeditUnknown 0L -#define XIMPreeditEnable 1L -#define XIMPreeditDisable (1L<<1) - - - If a value of XIMPreeditEnable is set, then input preediting is - turned on by the input method. - - If a value of XIMPreeditDisable is set, then input preediting - is turned off by the input method. - - If XNPreeditState is left unspecified, then the state will be - implementation-dependent. - - When XNResetState is set to XIMInitialState, the XNPreeditState - value specified at the creation time will be reflected as the - initial state for XmbResetIC and XwcResetIC. - - Because this XIC value is optional, a client should call - XGetIMValues with argument XNQueryICValuesList before using - this argument. - -Preedit State Notify Callback - - The preedit state notify callback is triggered by the input - method when the preediting state has changed. The value of the - XNPreeditStateNotifyCallback argument is a pointer to a - structure of type XIMCallback. The generic prototype is as - follows: - - void PreeditStateNotifyCallback(XIC ic, XPointer client_data, - XIMPreeditStateNotifyCallbackStruct *call_data); - - ic - - Specifies the input context. - - client_data - - Specifies the additional client data. - - call_data - - Specifies the current preedit state. - - The XIMPreeditStateNotifyCallbackStruct structure is defined as - follows: - - - -typedef struct _XIMPreeditStateNotifyCallbackStruct { - XIMPreeditState state; -} XIMPreeditStateNotifyCallbackStruct; - - Because this XIC value is optional, a client should call - XGetIMValues with argument XNQueryICValuesList before using - this argument. - -Preedit and Status Callbacks - - A client that wants to support the input style - XIMPreeditCallbacks must provide a set of preedit callbacks to - the input method. The set of preedit callbacks is as follows: - XNPreeditStartCallback This is called when the input method - starts preedit. - XNPreeditDoneCallback This is called when the input method - stops preedit. - XNPreeditDrawCallback This is called when a number of preedit - keystrokes should be echoed. - XNPreeditCaretCallback This is called to move the text - insertion point within the preedit string. - - A client that wants to support the input style - XIMStatusCallbacks must provide a set of status callbacks to - the input method. The set of status callbacks is as follows: - XNStatusStartCallback This is called when the input method - initializes the status area. - XNStatusDoneCallback This is called when the input method no - longer needs the status area. - XNStatusDrawCallback This is called when updating of the status - area is required. - - The value of any status or preedit argument is a pointer to a - structure of type XIMCallback. - - - -typedef void (*XIMProc)(); - -typedef struct { - XPointer client_data; - XIMProc callback; -} XIMCallback; - - Each callback has some particular semantics and will carry the - data that expresses the environment necessary to the client - into a specific data structure. This paragraph only describes - the arguments to be used to set the callback. - - Setting any of these values while doing preedit may cause - unexpected results. - -Input Method Callback Semantics - - XIM callbacks are procedures defined by clients or text drawing - packages that are to be called from the input method when - selected events occur. Most clients will use a text editing - package or a toolkit and, hence, will not need to define such - callbacks. This section defines the callback semantics, when - they are triggered, and what their arguments are. This - information is mostly useful for X toolkit implementors. - - Callbacks are mostly provided so that clients (or text editing - packages) can implement on-the-spot preediting in their own - window. In that case, the input method needs to communicate and - synchronize with the client. The input method needs to - communicate changes in the preedit window when it is under - control of the client. Those callbacks allow the client to - initialize the preedit area, display a new preedit string, move - the text insertion point during preedit, terminate preedit, or - update the status area. - - All callback procedures follow the generic prototype: - - void CallbackPrototype(XIC ic, XPointer client_data, SomeType - call_data); - - ic - - Specifies the input context. - - client_data - - Specifies the additional client data. - - call_data - - Specifies data specific to the callback. - - The call_data argument is a structure that expresses the - arguments needed to achieve the semantics; that is, it is a - specific data structure appropriate to the callback. In cases - where no data is needed in the callback, this call_data - argument is NULL. The client_data argument is a closure that - has been initially specified by the client when specifying the - callback and passed back. It may serve, for example, to inherit - application context in the callback. - - The following paragraphs describe the programming semantics and - specific data structure associated with the different reasons. - -Geometry Callback - - The geometry callback is triggered by the input method to - indicate that it wants the client to negotiate geometry. The - generic prototype is as follows: - - void GeometryCallback(XIC ic, XPointer client_data, XPointer - call_data); - - ic - - Specifies the input context. - - client_data - - Specifies the additional client data. - - call_data - - Not used for this callback and always passed as NULL. - - The callback is called with a NULL call_data argument. - -Destroy Callback - - The destroy callback is triggered by the input method when it - stops service for any reason. After the callback is invoked, - the input context will be freed by Xlib. The generic prototype - is as follows: - - void DestroyCallback(XIC ic, XPointer client_data, XPointer - call_data); - - ic - - Specifies the input context. - - client_data - - Specifies the additional client data. - - call_data - - Not used for this callback and always passed as NULL. - - The callback is called with a NULL call_data argument. - -String Conversion Callback - - The string conversion callback is triggered by the input method - to request the client to return the string to be converted. The - returned string may be either a multibyte or wide character - string, with an encoding matching the locale bound to the input - context. The callback prototype is as follows: - - void StringConversionCallback(XIC ic, XPointer client_data, - XIMStringConversionCallbackStruct *call_data); - - ic - - Specifies the input method. - - client_data - - Specifies the additional client data. - - call_data - - Specifies the amount of the string to be converted. - - The callback is passed an XIMStringConversionCallbackStruct - structure in the call_data argument. The text member is an - XIMStringConversionText structure (see section 13.5.6.9) to be - filled in by the client and describes the text to be sent to - the input method. The data pointed to by the string and - feedback elements of the XIMStringConversionText structure will - be freed using XFree by the input method after the callback - returns. So the client should not point to internal buffers - that are critical to the client. Similarly, because the - feedback element is currently reserved for future use, the - client should set feedback to NULL to prevent the library from - freeing memory at some random location due to an uninitialized - pointer. - - The XIMStringConversionCallbackStruct structure is defined as - follows: - -typedef struct _XIMStringConversionCallbackStruct { - XIMStringConversionPosition position; - XIMCaretDirection direction; - short factor; - XIMStringConversionOperation operation; - XIMStringConversionText *text; -} XIMStringConversionCallbackStruct; - -typedef short XIMStringConversionPosition; - -typedef unsigned short XIMStringConversionOperation; - -#define XIMStringConversionSubstitution (0x0001) -#define XIMStringConversionRetrieval (0x0001) - - - XIMStringConversionPosition specifies the starting position of - the string to be returned in the XIMStringConversionText - structure. The value identifies a position, in units of - characters, relative to the client's cursor position in the - client's buffer. - - The ending position of the text buffer is determined by the - direction and factor members. Specifically, it is the character - position relative to the starting point as defined by the - XIMCaretDirection. The factor member of - XIMStringConversionCallbackStruct specifies the number of - XIMCaretDirection positions to be applied. For example, if the - direction specifies XIMLineEnd and factor is 1, then all - characters from the starting position to the end of the current - display line are returned. If the direction specifies - XIMForwardChar or XIMBackwardChar, then the factor specifies a - relative position, indicated in characters, from the starting - position. - - XIMStringConversionOperation specifies whether the string to be - converted should be deleted (substitution) or copied - (retrieval) from the client's buffer. When the - XIMStringConversionOperation is - XIMStringConversionSubstitution, the client must delete the - string to be converted from its own buffer. When the - XIMStringConversionOperation is XIMStringConversionRetrieval, - the client must not delete the string to be converted from its - buffer. The substitute operation is typically used for - reconversion and transliteration conversion, while the - retrieval operation is typically used for context-sensitive - conversion. - -Preedit State Callbacks - - When the input method turns preediting on or off, a - PreeditStartCallback or PreeditDoneCallback callback is - triggered to let the toolkit do the setup or the cleanup for - the preedit region. - - int PreeditStartCallback(XIC ic, XPointer client_data, XPointer - call_data); - - ic - - Specifies the input context. - - client_data - - Specifies the additional client data. - - call_data - - Not used for this callback and always passed as NULL. - - When preedit starts on the specified input context, the - callback is called with a NULL call_data argument. - PreeditStartCallback will return the maximum size of the - preedit string. A positive number indicates the maximum number - of bytes allowed in the preedit string, and a value of -1 - indicates there is no limit. - - void PreeditDoneCallback(XIC ic, XPointer client_data, XPointer - call_data); - - ic - - Specifies the input context. - - client_data - - Specifies the additional client data. - - call_data - - Not used for this callback and always passed as NULL. - - When preedit stops on the specified input context, the callback - is called with a NULL call_data argument. The client can - release the data allocated by PreeditStartCallback. - - PreeditStartCallback should initialize appropriate data needed - for displaying preedit information and for handling further - PreeditDrawCallback calls. Once PreeditStartCallback is called, - it will not be called again before PreeditDoneCallback has been - called. - -Preedit Draw Callback - - This callback is triggered to draw and insert, delete or - replace, preedit text in the preedit region. The preedit text - may include unconverted input text such as Japanese Kana, - converted text such as Japanese Kanji characters, or characters - of both kinds. That string is either a multibyte or wide - character string, whose encoding matches the locale bound to - the input context. The callback prototype is as follows: - - void PreeditDrawCallback(XIC ic, XPointer client_data, - XIMPreeditDrawCallbackStruct *call_data); - - ic - - Specifies the input context. - - client_data - - Specifies the additional client data. - - call_data - - Specifies the preedit drawing information. - - The callback is passed an XIMPreeditDrawCallbackStruct - structure in the call_data argument. The text member of this - structure contains the text to be drawn. After the string has - been drawn, the caret should be moved to the specified - location. - - The XIMPreeditDrawCallbackStruct structure is defined as - follows: - - - -typedef struct _XIMPreeditDrawCallbackStruct { - int caret; /* Cursor offset within preedit string */ - int chg_first; /* Starting change position */ - int chg_length; /* Length of the change in character count */ - XIMText *text; -} XIMPreeditDrawCallbackStruct; - - The client must keep updating a buffer of the preedit text and - the callback arguments referring to indexes in that buffer. The - call_data fields have specific meanings according to the - operation, as follows: - * To indicate text deletion, the call_data member specifies a - NULL text field. The text to be deleted is then the current - text in the buffer from position chg_first (starting at - zero) on a character length of chg_length. - * When text is non-NULL, it indicates insertion or - replacement of text in the buffer. - * The chg_length member identifies the number of characters - in the current preedit buffer that are affected by this - call. A positive chg_length indicates that chg_length - number of characters, starting at chg_first, must be - deleted or must be replaced by text, whose length is - specified in the XIMText structure. - * A chg_length value of zero indicates that text must be - inserted right at the position specified by chg_first. A - value of zero for chg_first specifies the first character - in the buffer. - * chg_length and chg_first combine to identify the - modification required to the preedit buffer; beginning at - chg_first, replace chg_length number of characters with the - text in the supplied XIMText structure. For example, - suppose the preedit buffer contains the string "ABCDE". - * - -Text: A B C D E - ^ ^ ^ ^ ^ ^ -CharPos: 0 1 2 3 4 5 - - - - The CharPos in the diagram shows the location of the - character position relative to the character. - * If the value of chg_first is 1 and the value of chg_length - is 3, this says to replace 3 characters beginning at - character position 1 with the string in the XIMText - structure. Hence, BCD would be replaced by the value in the - structure. - * Though chg_length and chg_first are both signed integers - they will never have a negative value. - * The caret member identifies the character position before - which the cursor should be placed - after modification to - the preedit buffer has been completed. For example, if - caret is zero, the cursor is at the beginning of the - buffer. If the caret is one, the cursor is between the - first and second character. - - -typedef struct _XIMText { - unsigned short length; - XIMFeedback * feedback; - Bool encoding_is_wchar; - union { - char * multi_byte; - wchar_t * wide_char; - } string; -} XIMText; - - The text string passed is actually a structure specifying as - follows: - * The length member is the text length in characters. - * The encoding_is_wchar member is a value that indicates if - the text string is encoded in wide character or multibyte - format. The text string may be passed either as multibyte - or as wide character; the input method controls in which - form data is passed. The client's callback routine must be - able to handle data passed in either form. - * The string member is the text string. - * The feedback member indicates rendering type for each - character in the string member. If string is NULL - (indicating that only highlighting of the existing preedit - buffer should be updated), feedback points to length - highlight elements that should be applied to the existing - preedit buffer, beginning at chg_first. - - The feedback member expresses the types of rendering feedback - the callback should apply when drawing text. Rendering of the - text to be drawn is specified either in generic ways (for - example, primary, secondary) or in specific ways (reverse, - underline). When generic indications are given, the client is - free to choose the rendering style. It is necessary, however, - that primary and secondary be mapped to two distinct rendering - styles. - - If an input method wants to control display of the preedit - string, an input method can indicate the visibility hints using - feedbacks in a specific way. The XIMVisibleToForward, - XIMVisibleToBackword, and XIMVisibleToCenter masks are - exclusively used for these visibility hints. The - XIMVisibleToForward mask indicates that the preedit text is - preferably displayed in the primary draw direction from the - caret position in the preedit area forward. The - XIMVisibleToBackword mask indicates that the preedit text is - preferably displayed from the caret position in the preedit - area backward, relative to the primary draw direction. The - XIMVisibleToCenter mask indicates that the preedit text is - preferably displayed with the caret position in the preedit - area centered. - - The insertion point of the preedit string could exist outside - of the visible area when visibility hints are used. Only one of - the masks is valid for the entire preedit string, and only one - character can hold one of these feedbacks for a given input - context at one time. This feedback may be OR'ed together with - another highlight (such as XIMReverse). Only the most recently - set feedback is valid, and any previous feedback is - automatically canceled. This is a hint to the client, and the - client is free to choose how to display the preedit string. - - The feedback member also specifies how rendering of the text - argument should be performed. If the feedback is NULL, the - callback should apply the same feedback as is used for the - surrounding characters in the preedit buffer; if chg_first is - at a highlight boundary, the client can choose which of the two - highlights to use. If feedback is not NULL, feedback specifies - an array defining the rendering for each character of the - string, and the length of the array is thus length. - - If an input method wants to indicate that it is only updating - the feedback of the preedit text without changing the content - of it, the XIMText structure will contain a NULL value for the - string field, the number of characters affected (relative to - chg_first) will be in the length field, and the feedback field - will point to an array of XIMFeedback. - - Each element in the feedback array is a bitmask represented by - a value of type XIMFeedback. The valid mask names are as - follows: - -typedef unsigned long XIMFeedback; - -#define XIMReverse 1L -#define XIMUnderline (1L<<1) -#define XIMHighlight (1L<<2) -#define XIMPrimary (1L<<5)* -#define XIMSecondary (1L<<6)* -#define XIMTertiary (1L<<7)* -#define XIMVisibleToForward (1L<<8) -#define XIMVisibleToBackward (1L<<9) -#define XIMVisibleToCenter (1L<<10) - -*/- The values for XIMPrimary, XIMSecondary, and XIMTertiary were incorr -ectly defined in -the R5 specification. The X Consortium's X11R5 implementation correctly -implemented the values for these highlights. The value of these highligh -ts has -been corrected in this specification to agree with the values in the -Consortium's X11R5 and X11R6 implementations. - - - Characters drawn with the XIMReverse highlight should be drawn - by swapping the foreground and background colors used to draw - normal, unhighlighted characters. Characters drawn with the - XIMUnderline highlight should be underlined. Characters drawn - with the XIMHighlight, XIMPrimary, XIMSecondary, and - XIMTertiary highlights should be drawn in some unique manner - that must be different from XIMReverse and XIMUnderline. The - values for XIMPrimary, XIMSecondary, and XIMTertiary were - incorrectly defined in the R5 specification. The X Consortium's - X11R5 implementation correctly implemented the values for these - highlights. The value of these highlights has been corrected in - this specification to agree with the values in the Consortium's - X11R5 and X11R6 implementations. - -Preedit Caret Callback - - An input method may have its own navigation keys to allow the - user to move the text insertion point in the preedit area (for - example, to move backward or forward). Consequently, input - method needs to indicate to the client that it should move the - text insertion point. It then calls the PreeditCaretCallback. - - void PreeditCaretCallback(XIC ic, XPointer client_data, - XIMPreeditCaretCallbackStruct *call_data); - - ic - - Specifies the input context. - - client_data - - Specifies the additional client data. - - call_data - - Specifies the preedit caret information. - - The input method will trigger PreeditCaretCallback to move the - text insertion point during preedit. The call_data argument - contains a pointer to an XIMPreeditCaretCallbackStruct - structure, which indicates where the caret should be moved. The - callback must move the insertion point to its new location and - return, in field position, the new offset value from the - initial position. - - The XIMPreeditCaretCallbackStruct structure is defined as - follows: - - - -typedef struct _XIMPreeditCaretCallbackStruct { - int position; /* Caret offset within preedit string */ - XIMCaretDirection direction; /* Caret moves direction */ - XIMCaretStyle style; /* Feedback of the caret */ -} XIMPreeditCaretCallbackStruct; - - The XIMCaretStyle structure is defined as follows: - - - -typedef enum { - XIMIsInvisible, /* Disable caret feedback */ - XIMIsPrimary, /* UI defined caret feedback */ - XIMIsSecondary, /* UI defined caret feedback */ -} XIMCaretStyle; - - The XIMCaretDirection structure is defined as follows: - - - -typedef enum { - XIMForwardChar, XIMBackwardChar, - XIMForwardWord, XIMBackwardWord, - XIMCaretUp, XIMCaretDown, - XIMNextLine, XIMPreviousLine, - XIMLineStart, XIMLineEnd, - XIMAbsolutePosition, - XIMDontChange, - } XIMCaretDirection; - - These values are defined as follows: - XIMForwardChar Move the caret forward one character position. - XIMBackwardChar Move the caret backward one character position. - XIMForwardWord Move the caret forward one word. - XIMBackwardWord Move the caret backward one word. - XIMCaretUp Move the caret up one line keeping the current - horizontal offset. - XIMCaretDown Move the caret down one line keeping the current - horizontal offset. - XIMPreviousLine Move the caret to the beginning of the previous - line. - XIMNextLine Move the caret to the beginning of the next line. - XIMLineStart Move the caret to the beginning of the current - display line that contains the caret. - XIMLineEnd Move the caret to the end of the current display - line that contains the caret. - XIMAbsolutePosition The callback must move to the location - specified by the position field of the callback data, indicated - in characters, starting from the beginning of the preedit text. - Hence, a value of zero means move back to the beginning of the - preedit text. - XIMDontChange The caret position does not change. - -Status Callbacks - - An input method may communicate changes in the status of an - input context (for example, created, destroyed, or focus - changes) with three status callbacks: StatusStartCallback, - StatusDoneCallback, and StatusDrawCallback. - - When the input context is created or gains focus, the input - method calls the StatusStartCallback callback. - - void StatusStartCallback(XIC ic, XPointer client_data, XPointer - call_data); - - ic - - Specifies the input context. - - client_data - - Specifies the additional client data. - - call_data - - Not used for this callback and always passed as NULL. - - The callback should initialize appropriate data for displaying - status and for responding to StatusDrawCallback calls. Once - StatusStartCallback is called, it will not be called again - before StatusDoneCallback has been called. - - When an input context is destroyed or when it loses focus, the - input method calls StatusDoneCallback. - - void StatusDoneCallback(XIC ic, XPointer client_data, XPointer - call_data); - - ic - - Specifies the input context. - - client_data - - Specifies the additional client data. - - call_data - - Not used for this callback and always passed as NULL. - - The callback may release any data allocated on StatusStart. - - When an input context status has to be updated, the input - method calls StatusDrawCallback. - - void StatusDrawCallback(XIC ic, XPointer client_data, - XIMStatusDrawCallbackStruct *call_data); - - ic - - Specifies the input context. - - client_data - - Specifies the additional client data. - - call_data - - Specifies the status drawing information. - - The callback should update the status area by either drawing a - string or imaging a bitmap in the status area. - - The XIMStatusDataType and XIMStatusDrawCallbackStruct - structures are defined as follows: - - - -typedef enum { - XIMTextType, - XIMBitmapType, -} XIMStatusDataType; - -typedef struct _XIMStatusDrawCallbackStruct { - XIMStatusDataType type; - union { - XIMText *text; - Pixmap bitmap; - } data; -} XIMStatusDrawCallbackStruct; - - The feedback styles XIMVisibleToForward, XIMVisibleToBackword, - and XIMVisibleToCenter are not relevant and will not appear in - the XIMFeedback element of the XIMText structure. - -Event Filtering - - Xlib provides the ability for an input method to register a - filter internal to Xlib. This filter is called by a client (or - toolkit) by calling XFilterEvent after calling XNextEvent. Any - client that uses the XIM interface should call XFilterEvent to - allow input methods to process their events without knowledge - of the client's dispatching mechanism. A client's user - interface policy may determine the priority of event filters - with respect to other event-handling mechanisms (for example, - modal grabs). - - Clients may not know how many filters there are, if any, and - what they do. They may only know if an event has been filtered - on return of XFilterEvent. Clients should discard filtered - events. - - To filter an event, use XFilterEvent. - - Bool XFilterEvent(XEvent *event, Window w); - - event - - Specifies the event to filter. - - w - - Specifies the window for which the filter is to be applied. - - If the window argument is None, XFilterEvent applies the filter - to the window specified in the XEvent structure. The window - argument is provided so that layers above Xlib that do event - redirection can indicate to which window an event has been - redirected. - - If XFilterEvent returns True, then some input method has - filtered the event, and the client should discard the event. If - XFilterEvent returns False, then the client should continue - processing the event. - - If a grab has occurred in the client and XFilterEvent returns - True, the client should ungrab the keyboard. - -Getting Keyboard Input - - To get composed input from an input method, use XmbLookupString - or XwcLookupString. - - int XmbLookupString(XIC ic, XKeyPressedEvent *event, char - *buffer_return, int bytes_buffer, KeySym *keysym_return, Status - *status_return); - - int XwcLookupString(XIC ic, XKeyPressedEvent *event, wchar_t - *buffer_return, int wchars_buffer, KeySym *keysym_return, - Status *status_return); - - ic - - Specifies the input context. - - event - - Specifies the key event to be used. - - buffer_return - - Returns a multibyte string or wide character string (if any) - from the input method. - - bytes_buffer - - wchars_buffer - - Specifies space available in the return buffer. - - keysym_return - - Returns the KeySym computed from the event if this argument is - not NULL. - - status_return - - Returns a value indicating what kind of data is returned. - - The XmbLookupString and XwcLookupString functions return the - string from the input method specified in the buffer_return - argument. If no string is returned, the buffer_return argument - is unchanged. - - The KeySym into which the KeyCode from the event was mapped is - returned in the keysym_return argument if it is non-NULL and - the status_return argument indicates that a KeySym was - returned. If both a string and a KeySym are returned, the - KeySym value does not necessarily correspond to the string - returned. - - XmbLookupString returns the length of the string in bytes, and - XwcLookupString returns the length of the string in characters. - Both XmbLookupString and XwcLookupString return text in the - encoding of the locale bound to the input method of the - specified input context. - - Each string returned by XmbLookupString and XwcLookupString - begins in the initial state of the encoding of the locale (if - the encoding of the locale is state-dependent). - -Note - - To insure proper input processing, it is essential that the - client pass only KeyPress events to XmbLookupString and - XwcLookupString. Their behavior when a client passes a - KeyRelease event is undefined. - - Clients should check the status_return argument before using - the other returned values. These two functions both return a - value to status_return that indicates what has been returned in - the other arguments. The possible values returned are: - XBufferOverflow The input string to be returned is too large - for the supplied buffer_return. The required size - (XmbLookupString in bytes; XwcLookupString in characters) is - returned as the value of the function, and the contents of - buffer_return and keysym_return are not modified. The client - should recall the function with the same event and a buffer of - adequate size to obtain the string. - XLookupNone No consistent input has been composed so far. The - contents of buffer_return and keysym_return are not modified, - and the function returns zero. - XLookupChars Some input characters have been composed. They are - placed in the buffer_return argument, and the string length is - returned as the value of the function. The string is encoded in - the locale bound to the input context. The content of the - keysym_return argument is not modified. - XLookupKeySym A KeySym has been returned instead of a string - and is returned in keysym_return. The content of the - buffer_return argument is not modified, and the function - returns zero. - XLookupBoth Both a KeySym and a string are returned; - XLookupChars and XLookupKeySym occur simultaneously. - - It does not make any difference if the input context passed as - an argument to XmbLookupString and XwcLookupString is the one - currently in possession of the focus or not. Input may have - been composed within an input context before it lost the focus, - and that input may be returned on subsequent calls to - XmbLookupString or XwcLookupString even though it does not have - any more keyboard focus. - -Input Method Conventions - - The input method architecture is transparent to the client. - However, clients should respect a number of conventions in - order to work properly. Clients must also be aware of possible - effects of synchronization between input method and library in - the case of a remote input server. - -Client Conventions - - A well-behaved client (or toolkit) should first query the input - method style. If the client cannot satisfy the requirements of - the supported styles (in terms of geometry management or - callbacks), it should negotiate with the user continuation of - the program or raise an exception or error of some sort. - -Synchronization Conventions - - A KeyPress event with a KeyCode of zero is used exclusively as - a signal that an input method has composed input that can be - returned by XmbLookupString or XwcLookupString. No other use is - made of a KeyPress event with KeyCode of zero. - - Such an event may be generated by either a front-end or a - back-end input method in an implementation-dependent manner. - Some possible ways to generate this event include: - * A synthetic event sent by an input method server - * An artificial event created by a input method filter and - pushed onto a client's event queue - * A KeyPress event whose KeyCode value is modified by an - input method filter - - When callback support is specified by the client, input methods - will not take action unless they explicitly called back the - client and obtained no response (the callback is not specified - or returned invalid data). - -String Constants - - The following symbols for string constants are defined in - . Although they are shown here with particular - macro definitions, they may be implemented as macros, as global - symbols, or as a mixture of the two. The string pointer value - itself is not significant; clients must not assume that - inequality of two values implies inequality of the actual - string data. -#define XNVaNestedList "XNVaNestedList" -#define XNSeparatorofNestedList "separatorofNestedList" -#define XNQueryInputStyle "queryInputStyle" -#define XNClientWindow "clientWindow" -#define XNInputStyle "inputStyle" -#define XNFocusWindow "focusWindow" -#define XNResourceName "resourceName" -#define XNResourceClass "resourceClass" -#define XNGeometryCallback "geometryCallback" -#define XNDestroyCallback "destroyCallback" -#define XNFilterEvents "filterEvents" -#define XNPreeditStartCallback "preeditStartCallback" -#define XNPreeditDoneCallback "preeditDoneCallback" -#define XNPreeditDrawCallback "preeditDrawCallback" -#define XNPreeditCaretCallback "preeditCaretCallback" -#define XNPreeditStateNotifyCallback "preeditStateNotifyCallback -" -#define XNPreeditAttributes "preeditAttributes" -#define XNStatusStartCallback "statusStartCallback" -#define XNStatusDoneCallback "statusDoneCallback" -#define XNStatusDrawCallback "statusDrawCallback" -#define XNStatusAttributes "statusAttributes" -#define XNArea "area" -#define XNAreaNeeded "areaNeeded" -#define XNSpotLocation "spotLocation" -#define XNColormap "colorMap" -#define XNStdColormap "stdColorMap" -#define XNForeground "foreground" -#define XNBackground "background" -#define XNBackgroundPixmap "backgroundPixmap" -#define XNFontSet "fontSet" -#define XNLineSpace "lineSpace" -#define XNCursor "cursor" -#define XNQueryIMValuesList "queryIMValuesList" -#define XNQueryICValuesList "queryICValuesList" -#define XNStringConversionCallback "stringConversionCallback" -#define XNStringConversion "stringConversion" -#define XNResetState "resetState" -#define XNHotKey "hotkey" -#define XNHotKeyState "hotkeyState" -#define XNPreeditState "preeditState" -#define XNVisiblePosition "visiblePosition" -#define XNR6PreeditCallbackBehavior "r6PreeditCallback" -#define XNRequiredCharSet "requiredCharSet" -#define XNQueryOrientation "queryOrientation" -#define XNDirectionalDependentDrawing "directionalDependentDrawin -g" -#define XNContextualDrawing "contextualDrawing" -#define XNBaseFontName "baseFontName" -#define XNMissingCharSet "missingCharSet" -#define XNDefaultString "defaultString" -#define XNOrientation "orientation" -#define XNFontInfo "fontInfo" -#define XNOMAutomatic "omAutomatic" - - -Chapter 14. Inter-Client Communication Functions - - Table of Contents - - Client to Window Manager Communication - - Manipulating Top-Level Windows - Converting String Lists - Setting and Reading Text Properties - Setting and Reading the WM_NAME Property - Setting and Reading the WM_ICON_NAME Property - Setting and Reading the WM_HINTS Property - Setting and Reading the WM_NORMAL_HINTS Property - Setting and Reading the WM_CLASS Property - Setting and Reading the WM_TRANSIENT_FOR Property - Setting and Reading the WM_PROTOCOLS Property - Setting and Reading the WM_COLORMAP_WINDOWS Property - Setting and Reading the WM_ICON_SIZE Property - Using Window Manager Convenience Functions - - Client to Session Manager Communication - - Setting and Reading the WM_COMMAND Property - Setting and Reading the WM_CLIENT_MACHINE Property - - Standard Colormaps - - Standard Colormap Properties and Atoms - Setting and Obtaining Standard Colormaps - - The Inter-Client Communication Conventions Manual, hereafter - referred to as the ICCCM, details the X Consortium approved - conventions that govern inter-client communications. These - conventions ensure peer-to-peer client cooperation in the use - of selections, cut buffers, and shared resources as well as - client cooperation with window and session managers. For - further information, see the Inter-Client Communication - Conventions Manual. - - Xlib provides a number of standard properties and programming - interfaces that are ICCCM compliant. The predefined atoms for - some of these properties are defined in the - header file, where to avoid name conflicts with user symbols - their #define name has an XA_ prefix. For further information - about atoms and properties, see section 4.3. - - Xlib's selection and cut buffer mechanisms provide the primary - programming interfaces by which peer client applications - communicate with each other (see sections 4.5 and 16.6). The - functions discussed in this chapter provide the primary - programming interfaces by which client applications communicate - with their window and session managers as well as share - standard colormaps. - - The standard properties that are of special interest for - communicating with window and session managers are: - Name Type Format Description - WM_CLASS STRING 8 Set by application programs to allow window - and session managers to obtain the application's resources from - the resource database. - WM_CLIENT_MACHINE TEXT The string name of the machine on - which the client application is running. - WM_COLORMAP_WINDOWS WINDOWS 32 The list of window IDs that may - need a different colormap from that of their top-level window. - WM_COMMAND TEXT The command and arguments, null separated, - used to invoke the application. - WM_HINTS WM_HINTS 32 Additional hints set by the client for use - by the window manager. The C type of this property is XWMHints. - WM_ICON_NAME TEXT The name to be used in an icon. - WM_ICON_SIZE WM_ICON_SIZE 32 The window manager may set this - property on the root window to specify the icon sizes it - supports. The C type of this property is XIconSize. - WM_NAME TEXT The name of the application. - WM_NORMAL_HINTS WM_NORMAL_HINTS 32 Size hints for a window in - its normal state. The C type of this property is XSizeHints. - WM_PROTOCOLS ATOM 32 List of atoms that identify the - communications protocols between the client and window manager - in which the client is willing to participate. - WM_STATE WM_STATE 32 Intended for communication between window - and session managers only. - WM_TRANSIENT_FOR WINDOW 32 Set by application programs to - indicate to the window manager that a transient top-level - window, such as a dialog box. - - The remainder of this chapter discusses: - * Client to window manager communication - * Client to session manager communication - * Standard colormaps - -Client to Window Manager Communication - - This section discusses how to: - * Manipulate top-level windows - * Convert string lists - * Set and read text properties - * Set and read the WM_NAME property - * Set and read the WM_ICON_NAME property - * Set and read the WM_HINTS property - * Set and read the WM_NORMAL_HINTS property - * Set and read the WM_CLASS property - * Set and read the WM_TRANSIENT_FOR property - * Set and read the WM_PROTOCOLS property - * Set and read the WM_COLORMAP_WINDOWS property - * Set and read the WM_ICON_SIZE property - * Use window manager convenience functions - -Manipulating Top-Level Windows - - Xlib provides functions that you can use to change the - visibility or size of top-level windows (that is, those that - were created as children of the root window). Note that the - subwindows that you create are ignored by window managers. - Therefore, you should use the basic window functions described - in chapter 3 to manipulate your application's subwindows. - - To request that a top-level window be iconified, use - XIconifyWindow. - - Status XIconifyWindow(Display *display, Window w, int - screen_number); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - screen_number - - Specifies the appropriate screen number on the host server. - - The XIconifyWindow function sends a WM_CHANGE_STATE - ClientMessage event with a format of 32 and a first data - element of IconicState (as described in section 4.1.4 of the - Inter-Client Communication Conventions Manual) and a window of - w to the root window of the specified screen with an event mask - set to SubstructureNotifyMask | SubstructureRedirectMask. - Window managers may elect to receive this message and if the - window is in its normal state, may treat it as a request to - change the window's state from normal to iconic. If the - WM_CHANGE_STATE property cannot be interned, XIconifyWindow - does not send a message and returns a zero status. It returns a - nonzero status if the client message is sent successfully; - otherwise, it returns a zero status. - - To request that a top-level window be withdrawn, use - XWithdrawWindow. - - Status XWithdrawWindow(Display *display, Window w, int - screen_number); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - screen_number - - Specifies the appropriate screen number on the host server. - - The XWithdrawWindow function unmaps the specified window and - sends a synthetic UnmapNotify event to the root window of the - specified screen. Window managers may elect to receive this - message and may treat it as a request to change the window's - state to withdrawn. When a window is in the withdrawn state, - neither its normal nor its iconic representations is visible. - It returns a nonzero status if the UnmapNotify event is - successfully sent; otherwise, it returns a zero status. - - XWithdrawWindow can generate a BadWindow error. - - To request that a top-level window be reconfigured, use - XReconfigureWMWindow. - - Status XReconfigureWMWindow(Display *display, Window w, int - screen_number, unsigned int value_mask, XWindowChanges - *values); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - screen_number - - Specifies the appropriate screen number on the host server. - - value_mask - - Specifies which values are to be set using information in the - values structure. This mask is the bitwise inclusive OR of the - valid configure window values bits. - - values - - Specifies the XWindowChanges structure. - - The XReconfigureWMWindow function issues a ConfigureWindow - request on the specified top-level window. If the stacking mode - is changed and the request fails with a BadMatch error, the - error is trapped by Xlib and a synthetic ConfigureRequestEvent - containing the same configuration parameters is sent to the - root of the specified window. Window managers may elect to - receive this event and treat it as a request to reconfigure the - indicated window. It returns a nonzero status if the request or - event is successfully sent; otherwise, it returns a zero - status. - - XReconfigureWMWindow can generate BadValue and BadWindow - errors. - -Converting String Lists - - Many of the text properties allow a variety of types and - formats. Because the data stored in these properties are not - simple null-terminated strings, an XTextProperty structure is - used to describe the encoding, type, and length of the text as - well as its value. The XTextProperty structure contains: - - -typedef struct { - unsigned char *value; /* property data */ - Atom encoding; /* type of property */ - int format; /* 8, 16, or 32 */ - unsigned long nitems; /* number of items in value */ -} XTextProperty; - - Xlib provides functions to convert localized text to or from - encodings that support the inter-client communication - conventions for text. In addition, functions are provided for - converting between lists of pointers to character strings and - text properties in the STRING encoding. - - The functions for localized text return a signed integer error - status that encodes Success as zero, specific error conditions - as negative numbers, and partial conversion as a count of - unconvertible characters. - -#define #XNoMemory -1 -#define #XLocaleNotSupported -2 -#define #XConverterNotFound -3 - -typedef enum { - XStringStyle, /* STRING */ - XCompoundTextStyle, /* COMPOUND_TEXT */ - XTextStyle, /* text in owner's encoding (current loc -ale) */ - XStdICCTextStyle /* STRING, else COMPOUND_TEXT */ -} XICCEncodingStyle; - - To convert a list of text strings to an XTextProperty - structure, use XmbTextListToTextProperty or - XwcTextListToTextProperty. - - int XmbTextListToTextProperty(Display *display, char **list, - int count, XICCEncodingStyle style, XTextProperty - *text_prop_return); - - int XwcTextListToTextProperty(Display *display, wchar_t **list, - int count, XICCEncodingStyle style, XTextProperty - *text_prop_return); - - display - - Specifies the connection to the X server. - - list - - Specifies a list of null-terminated character strings. - - count - - Specifies the number of strings specified. - - style - - Specifies the manner in which the property is encoded. - - text_prop_return - - Returns the XTextProperty structure. - - The XmbTextListToTextProperty and XwcTextListToTextProperty - functions set the specified XTextProperty value to a set of - null-separated elements representing the concatenation of the - specified list of null-terminated text strings. A final - terminating null is stored at the end of the value field of - text_prop_return but is not included in the nitems member. - - The functions set the encoding field of text_prop_return to an - Atom for the specified display naming the encoding determined - by the specified style and convert the specified text list to - this encoding for storage in the text_prop_return value field. - If the style XStringStyle or XCompoundTextStyle is specified, - this encoding is ``STRING'' or ``COMPOUND_TEXT'', respectively. - If the style XTextStyle is specified, this encoding is the - encoding of the current locale. If the style XStdICCTextStyle - is specified, this encoding is ``STRING'' if the text is fully - convertible to STRING, else ``COMPOUND_TEXT''. - - If insufficient memory is available for the new value string, - the functions return XNoMemory. If the current locale is not - supported, the functions return XLocaleNotSupported. In both of - these error cases, the functions do not set text_prop_return. - - To determine if the functions are guaranteed not to return - XLocaleNotSupported, use XSupportsLocale. - - If the supplied text is not fully convertible to the specified - encoding, the functions return the number of unconvertible - characters. Each unconvertible character is converted to an - implementation-defined and encoding-specific default string. - Otherwise, the functions return Success. Note that full - convertibility to all styles except XStringStyle is guaranteed. - - To free the storage for the value field, use XFree. - - To obtain a list of text strings from an XTextProperty - structure, use XmbTextPropertyToTextList or - XwcTextPropertyToTextList. - - int XmbTextPropertyToTextList(Display *display, XTextProperty - *text_prop, char ***list_return, int *count_return); - - int XwcTextPropertyToTextList(Display *display, XTextProperty - *text_prop, wchar_t ***list_return, int *count_return); - - display - - Specifies the connection to the X server. - - text_prop - - Specifies the XTextProperty structure to be used. - - list_return - - Returns a list of null-terminated character strings. - - count_return - - Returns the number of strings. - - The XmbTextPropertyToTextList and XwcTextPropertyToTextList - functions return a list of text strings in the current locale - representing the null-separated elements of the specified - XTextProperty structure. The data in text_prop must be format - 8. - - Multiple elements of the property (for example, the strings in - a disjoint text selection) are separated by a null byte. The - contents of the property are not required to be - null-terminated; any terminating null should not be included in - text_prop.nitems. - - If insufficient memory is available for the list and its - elements, XmbTextPropertyToTextList and - XwcTextPropertyToTextList return XNoMemory. If the current - locale is not supported, the functions return - XLocaleNotSupported. Otherwise, if the encoding field of - text_prop is not convertible to the encoding of the current - locale, the functions return XConverterNotFound. For supported - locales, existence of a converter from COMPOUND_TEXT, STRING or - the encoding of the current locale is guaranteed if - XSupportsLocale returns True for the current locale (but the - actual text may contain unconvertible characters). Conversion - of other encodings is implementation-dependent. In all of these - error cases, the functions do not set any return values. - - Otherwise, XmbTextPropertyToTextList and - XwcTextPropertyToTextList return the list of null-terminated - text strings to list_return and the number of text strings to - count_return. - - If the value field of text_prop is not fully convertible to the - encoding of the current locale, the functions return the number - of unconvertible characters. Each unconvertible character is - converted to a string in the current locale that is specific to - the current locale. To obtain the value of this string, use - XDefaultString. Otherwise, XmbTextPropertyToTextList and - XwcTextPropertyToTextList return Success. - - To free the storage for the list and its contents returned by - XmbTextPropertyToTextList, use XFreeStringList. To free the - storage for the list and its contents returned by - XwcTextPropertyToTextList, use XwcFreeStringList. - - To free the in-memory data associated with the specified wide - character string list, use XwcFreeStringList. - - void XwcFreeStringList(wchar_t **list); - - list - - Specifies the list of strings to be freed. - - The XwcFreeStringList function frees memory allocated by - XwcTextPropertyToTextList. - - To obtain the default string for text conversion in the current - locale, use - - char *XDefaultString(void); - - The XDefaultString function returns the default string used by - Xlib for text conversion (for example, in - XmbTextPropertyToTextList). The default string is the string in - the current locale that is output when an unconvertible - character is found during text conversion. If the string - returned by XDefaultString is the empty string (""), no - character is output in the converted text. XDefaultString does - not return NULL. - - The string returned by XDefaultString is independent of the - default string for text drawing; see XCreateFontSet to obtain - the default string for an XFontSet. - - The behavior when an invalid codepoint is supplied to any Xlib - function is undefined. - - The returned string is null-terminated. It is owned by Xlib and - should not be modified or freed by the client. It may be freed - after the current locale is changed. Until freed, it will not - be modified by Xlib. - - To set the specified list of strings in the STRING encoding to - a XTextProperty structure, use XStringListToTextProperty. - - Status XStringListToTextProperty(char **list, int count, - XTextProperty *text_prop_return); - - list - - Specifies a list of null-terminated character strings. - - count - - Specifies the number of strings. - - text_prop_return - - Returns the XTextProperty structure. - - The XStringListToTextProperty function sets the specified - XTextProperty to be of type STRING (format 8) with a value - representing the concatenation of the specified list of - null-separated character strings. An extra null byte (which is - not included in the nitems member) is stored at the end of the - value field of text_prop_return. The strings are assumed - (without verification) to be in the STRING encoding. If - insufficient memory is available for the new value string, - XStringListToTextProperty does not set any fields in the - XTextProperty structure and returns a zero status. Otherwise, - it returns a nonzero status. To free the storage for the value - field, use XFree. - - To obtain a list of strings from a specified XTextProperty - structure in the STRING encoding, use - XTextPropertyToStringList. - - Status XTextPropertyToStringList(XTextProperty *text_prop, char - ***list_return, int *count_return); - - text_prop - - Specifies the XTextProperty structure to be used. - - list_return - - Returns a list of null-terminated character strings. - - count_return - - Returns the number of strings. - - The XTextPropertyToStringList function returns a list of - strings representing the null-separated elements of the - specified XTextProperty structure. The data in text_prop must - be of type STRING and format 8. Multiple elements of the - property (for example, the strings in a disjoint text - selection) are separated by NULL (encoding 0). The contents of - the property are not null-terminated. If insufficient memory is - available for the list and its elements, - XTextPropertyToStringList sets no return values and returns a - zero status. Otherwise, it returns a nonzero status. To free - the storage for the list and its contents, use XFreeStringList. - - To free the in-memory data associated with the specified string - list, use XFreeStringList. - - void XFreeStringList(char **list); - - list - - Specifies the list of strings to be freed. - - The XFreeStringList function releases memory allocated by - XmbTextPropertyToTextList and XTextPropertyToStringList and the - missing charset list allocated by XCreateFontSet. - -Setting and Reading Text Properties - - Xlib provides two functions that you can use to set and read - the text properties for a given window. You can use these - functions to set and read those properties of type TEXT - (WM_NAME, WM_ICON_NAME, WM_COMMAND, and WM_CLIENT_MACHINE). In - addition, Xlib provides separate convenience functions that you - can use to set each of these properties. For further - information about these convenience functions, see sections - 14.1.4, 14.1.5, 14.2.1, and 14.2.2, respectively. - - To set one of a window's text properties, use XSetTextProperty. - - void XSetTextProperty(Display *display, Window w, XTextProperty - *text_prop, Atom property); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - text_prop - - Specifies the XTextProperty structure to be used. - - property - - Specifies the property name. - - The XSetTextProperty function replaces the existing specified - property for the named window with the data, type, format, and - number of items determined by the value field, the encoding - field, the format field, and the nitems field, respectively, of - the specified XTextProperty structure. If the property does not - already exist, XSetTextProperty sets it for the specified - window. - - XSetTextProperty can generate BadAlloc, BadAtom, BadValue, and - BadWindow errors. - - To read one of a window's text properties, use - XGetTextProperty. - - Status XGetTextProperty(Display *display, Window w, - XTextProperty *text_prop_return, Atom property); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - text_prop_return - - Returns the XTextProperty structure. - - property - - Specifies the property name. - - The XGetTextProperty function reads the specified property from - the window and stores the data in the returned XTextProperty - structure. It stores the data in the value field, the type of - the data in the encoding field, the format of the data in the - format field, and the number of items of data in the nitems - field. An extra byte containing null (which is not included in - the nitems member) is stored at the end of the value field of - text_prop_return. The particular interpretation of the - property's encoding and data as text is left to the calling - application. If the specified property does not exist on the - window, XGetTextProperty sets the value field to NULL, the - encoding field to None, the format field to zero, and the - nitems field to zero. - - If it was able to read and store the data in the XTextProperty - structure, XGetTextProperty returns a nonzero status; - otherwise, it returns a zero status. - - XGetTextProperty can generate BadAtom and BadWindow errors. - -Setting and Reading the WM_NAME Property - - Xlib provides convenience functions that you can use to set and - read the WM_NAME property for a given window. - - To set a window's WM_NAME property with the supplied - convenience function, use XSetWMName. - - void XSetWMName(Display *display, Window w, XTextProperty - *text_prop); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - text_prop - - Specifies the XTextProperty structure to be used. - - The XSetWMName convenience function calls XSetTextProperty to - set the WM_NAME property. - - To read a window's WM_NAME property with the supplied - convenience function, use XGetWMName. - - Status XGetWMName(Display *display, Window w, XTextProperty - *text_prop_return); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - text_prop_return - - Returns the XTextProperty structure. - - The XGetWMName convenience function calls XGetTextProperty to - obtain the WM_NAME property. It returns a nonzero status on - success; otherwise, it returns a zero status. - - The following two functions have been superseded by XSetWMName - and XGetWMName, respectively. You can use these additional - convenience functions for window names that are encoded as - STRING properties. - - To assign a name to a window, use XStoreName. - - XStoreName(Display *display, Window w, char *window_name); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - window_name - - Specifies the window name, which should be a null-terminated - string. - - The XStoreName function assigns the name passed to window_name - to the specified window. A window manager can display the - window name in some prominent place, such as the title bar, to - allow users to identify windows easily. Some window managers - may display a window's name in the window's icon, although they - are encouraged to use the window's icon name if one is provided - by the application. If the string is not in the Host Portable - Character Encoding, the result is implementation-dependent. - - XStoreName can generate BadAlloc and BadWindow errors. - - To get the name of a window, use XFetchName. - - Status XFetchName(Display *display, Window w, char - **window_name_return); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - window_name_return - - Returns the window name, which is a null-terminated string. - - The XFetchName function returns the name of the specified - window. If it succeeds, it returns a nonzero status; otherwise, - no name has been set for the window, and it returns zero. If - the WM_NAME property has not been set for this window, - XFetchName sets window_name_return to NULL. If the data - returned by the server is in the Latin Portable Character - Encoding, then the returned string is in the Host Portable - Character Encoding. Otherwise, the result is - implementation-dependent. When finished with it, a client must - free the window name string using XFree. - - XFetchName can generate a BadWindow error. - -Setting and Reading the WM_ICON_NAME Property - - Xlib provides convenience functions that you can use to set and - read the WM_ICON_NAME property for a given window. - - To set a window's WM_ICON_NAME property, use XSetWMIconName. - - void XSetWMIconName(Display *display, Window w, XTextProperty - *text_prop); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - text_prop - - Specifies the XTextProperty structure to be used. - - The XSetWMIconName convenience function calls XSetTextProperty - to set the WM_ICON_NAME property. - - To read a window's WM_ICON_NAME property, use XGetWMIconName. - - Status XGetWMIconName(Display *display, Window w, XTextProperty - *text_prop_return); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - text_prop_return - - Returns the XTextProperty structure. - - The XGetWMIconName convenience function calls XGetTextProperty - to obtain the WM_ICON_NAME property. It returns a nonzero - status on success; otherwise, it returns a zero status. - - The next two functions have been superseded by XSetWMIconName - and XGetWMIconName, respectively. You can use these additional - convenience functions for window names that are encoded as - STRING properties. - - To set the name to be displayed in a window's icon, use - XSetIconName. - - XSetIconName(Display *display, Window w, char *icon_name); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - icon_name - - Specifies the icon name, which should be a null-terminated - string. - - If the string is not in the Host Portable Character Encoding, - the result is implementation-dependent. XSetIconName can - generate BadAlloc and BadWindow errors. - - To get the name a window wants displayed in its icon, use - XGetIconName. - - Status XGetIconName(Display *display, Window w, char - **icon_name_return); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - icon_name_return - - Returns the window's icon name, which is a null-terminated - string. - - The XGetIconName function returns the name to be displayed in - the specified window's icon. If it succeeds, it returns a - nonzero status; otherwise, if no icon name has been set for the - window, it returns zero. If you never assigned a name to the - window, XGetIconName sets icon_name_return to NULL. If the data - returned by the server is in the Latin Portable Character - Encoding, then the returned string is in the Host Portable - Character Encoding. Otherwise, the result is - implementation-dependent. When finished with it, a client must - free the icon name string using XFree. - - XGetIconName can generate a BadWindow error. - -Setting and Reading the WM_HINTS Property - - Xlib provides functions that you can use to set and read the - WM_HINTS property for a given window. These functions use the - flags and the XWMHints structure, as defined in the - header file. - - To allocate an XWMHints structure, use XAllocWMHints. - - XWMHints *XAllocWMHints(void); - - The XAllocWMHints function allocates and returns a pointer to - an XWMHints structure. Note that all fields in the XWMHints - structure are initially set to zero. If insufficient memory is - available, XAllocWMHints returns NULL. To free the memory - allocated to this structure, use XFree. - - The XWMHints structure contains: -/* Window manager hints mask bits */ - -#define InputHint (1L<<0) -#define StateHint (1L<<1) -#define IconPixmapHint (1L<<2) -#define IconWindowHint (1L<<3) -#define IconPositionHint (1L<<4) -#define IconMaskHint (1L<<5) -#define WindowGroupHint (1L<<6) -#define UrgencyHint (1L<<8) -#define AllHints (InputHint|StateHint|IconPixmapHin -t| - IconWIndowHint|IconPositionHint| - IconMaskHint|WindowGroupHint) - - -/* Values */ - -typedef struct { - long flags; /* marks which fields in this structure -are defined */ - Bool input; /* does this application rely on the win -dow manager to - get keyboard input? */ - int initial_state; /* see below */ - Pixmap icon_pixmap; /* pixmap to be used as icon */ - Window icon_window; /* window to be used as icon */ - int icon_x, icon_y; /* initial position of icon */ - Pixmap icon_mask; /* pixmap to be used as mask for icon_pi -xmap */ - XID window_group; /* id of related window group */ - /* this structure may be extended in the future */ -} XWMHints; - - The input member is used to communicate to the window manager - the input focus model used by the application. Applications - that expect input but never explicitly set focus to any of - their subwindows (that is, use the push model of focus - management), such as X Version 10 style applications that use - real-estate driven focus, should set this member to True. - Similarly, applications that set input focus to their - subwindows only when it is given to their top-level window by a - window manager should also set this member to True. - Applications that manage their own input focus by explicitly - setting focus to one of their subwindows whenever they want - keyboard input (that is, use the pull model of focus - management) should set this member to False. Applications that - never expect any keyboard input also should set this member to - False. - - Pull model window managers should make it possible for push - model applications to get input by setting input focus to the - top-level windows of applications whose input member is True. - Push model window managers should make sure that pull model - applications do not break them by resetting input focus to - PointerRoot when it is appropriate (for example, whenever an - application whose input member is False sets input focus to one - of its subwindows). - - The definitions for the initial_state flag are: -#define WithdrawnState 0 -#define NormalState 1 /* most applications start this way */ -#define IconicState 3 /* application wants to start as an icon - */ - - - The icon_mask specifies which pixels of the icon_pixmap should - be used as the icon. This allows for nonrectangular icons. Both - icon_pixmap and icon_mask must be bitmaps. The icon_window lets - an application provide a window for use as an icon for window - managers that support such use. The window_group lets you - specify that this window belongs to a group of other windows. - For example, if a single application manipulates multiple - top-level windows, this allows you to provide enough - information that a window manager can iconify all of the - windows rather than just the one window. - - The UrgencyHint flag, if set in the flags field, indicates that - the client deems the window contents to be urgent, requiring - the timely response of the user. The window manager will make - some effort to draw the user's attention to this window while - this flag is set. The client must provide some means by which - the user can cause the urgency flag to be cleared (either - mitigating the condition that made the window urgent or merely - shutting off the alarm) or the window to be withdrawn. - - To set a window's WM_HINTS property, use XSetWMHints. - - XSetWMHints(Display *display, Window w, XWMHints *wmhints); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - wmhints - - Specifies the XWMHints structure to be used. - - The XSetWMHints function sets the window manager hints that - include icon information and location, the initial state of the - window, and whether the application relies on the window - manager to get keyboard input. - - XSetWMHints can generate BadAlloc and BadWindow errors. - - To read a window's WM_HINTS property, use XGetWMHints. - - XWMHints *XGetWMHints(Display *display, Window w); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - The XGetWMHints function reads the window manager hints and - returns NULL if no WM_HINTS property was set on the window or - returns a pointer to an XWMHints structure if it succeeds. When - finished with the data, free the space used for it by calling - XFree. - - XGetWMHints can generate a BadWindow error. - -Setting and Reading the WM_NORMAL_HINTS Property - - Xlib provides functions that you can use to set or read the - WM_NORMAL_HINTS property for a given window. The functions use - the flags and the XSizeHints structure, as defined in the - header file. - - The size of the XSizeHints structure may grow in future - releases, as new components are added to support new ICCCM - features. Passing statically allocated instances of this - structure into Xlib may result in memory corruption when - running against a future release of the library. As such, it is - recommended that only dynamically allocated instances of the - structure be used. - - To allocate an XSizeHints structure, use XAllocSizeHints. - - XSizeHints *XAllocSizeHints(void); - - The XAllocSizeHints function allocates and returns a pointer to - an XSizeHints structure. Note that all fields in the XSizeHints - structure are initially set to zero. If insufficient memory is - available, XAllocSizeHints returns NULL. To free the memory - allocated to this structure, use XFree. - - The XSizeHints structure contains: -/* Size hints mask bits */ - -#define USPosition (1L<<0) /* user specified x,y */ -#define USSize (1L<<1) /* user specified width,he -ight */ -#define PPosition (1L<<2) /* program specified posis -tion */ -#define PSize (1L<<3) /* program specified size -*/ -#define PMinSize (1L<<4) /* program specified minim -um size */ -#define PMaxSize (1L<<5) /* program specified maxim -um size */ -#define PResizeInc (1L<<5) /* program specified resiz -e increments */ -#define PAspect (1L<<6) /* program specified min a -nd max aspect ratios */ -#define PBaseSize (1L<<8) -#define PWinGravity (1L<<9) -#define PAllHints (PPosition|Psize| - PMinSize|PMaxSize| - PResizeInc|PAspect) - - -/* Values */ - -typedef struct { - long flags; /* marks which fields in this structure -are defined */ - int x, y; /* Obsolete */ - int width, height; /* Obsolete */ - int min_width, min_height; - int max_width, max_height; - int width_inc, height_inc; - struct { - int x; /* numerator */ - int y; /* denominator */ - } min_aspect, max_aspect; - int base_width, base_height; - int win_gravity; - /* this structure may be extended in the future */ -} XSizeHints; - - The x, y, width, and height members are now obsolete and are - left solely for compatibility reasons. The min_width and - min_height members specify the minimum window size that still - allows the application to be useful. The max_width and - max_height members specify the maximum window size. The - width_inc and height_inc members define an arithmetic - progression of sizes (minimum to maximum) into which the window - prefers to be resized. The min_aspect and max_aspect members - are expressed as ratios of x and y, and they allow an - application to specify the range of aspect ratios it prefers. - The base_width and base_height members define the desired size - of the window. The window manager will interpret the position - of the window and its border width to position the point of the - outer rectangle of the overall window specified by the - win_gravity member. The outer rectangle of the window includes - any borders or decorations supplied by the window manager. In - other words, if the window manager decides to place the window - where the client asked, the position on the parent window's - border named by the win_gravity will be placed where the client - window would have been placed in the absence of a window - manager. - - Note that use of the PAllHints macro is highly discouraged. - - To set a window's WM_NORMAL_HINTS property, use - XSetWMNormalHints. - - void XSetWMNormalHints(Display *display, Window w, XSizeHints - *hints); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - hints - - Specifies the size hints for the window in its normal state. - - The XSetWMNormalHints function replaces the size hints for the - WM_NORMAL_HINTS property on the specified window. If the - property does not already exist, XSetWMNormalHints sets the - size hints for the WM_NORMAL_HINTS property on the specified - window. The property is stored with a type of WM_SIZE_HINTS and - a format of 32. - - XSetWMNormalHints can generate BadAlloc and BadWindow errors. - - To read a window's WM_NORMAL_HINTS property, use - XGetWMNormalHints. - - Status XGetWMNormalHints(Display *display, Window w, XSizeHints - *hints_return, long *supplied_return); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - hints_return - - Returns the size hints for the window in its normal state. - - supplied_return - - Returns the hints that were supplied by the user. - - The XGetWMNormalHints function returns the size hints stored in - the WM_NORMAL_HINTS property on the specified window. If the - property is of type WM_SIZE_HINTS, is of format 32, and is long - enough to contain either an old (pre-ICCCM) or new size hints - structure, XGetWMNormalHints sets the various fields of the - XSizeHints structure, sets the supplied_return argument to the - list of fields that were supplied by the user (whether or not - they contained defined values), and returns a nonzero status. - Otherwise, it returns a zero status. - - If XGetWMNormalHints returns successfully and a pre-ICCCM size - hints property is read, the supplied_return argument will - contain the following bits: - -(USPosition|USSize|PPosition|PSize|PMinSize| - PMaxSize|PResizeInc|PAspect) - - If the property is large enough to contain the base size and - window gravity fields as well, the supplied_return argument - will also contain the following bits: - -PBaseSize|PWinGravity - - XGetWMNormalHints can generate a BadWindow error. - - To set a window's WM_SIZE_HINTS property, use XSetWMSizeHints. - - void XSetWMSizeHints(Display *display, Window w, XSizeHints - *hints, Atom property); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - hints - - Specifies the XSizeHints structure to be used. - - property - - Specifies the property name. - - The XSetWMSizeHints function replaces the size hints for the - specified property on the named window. If the specified - property does not already exist, XSetWMSizeHints sets the size - hints for the specified property on the named window. The - property is stored with a type of WM_SIZE_HINTS and a format of - 32. To set a window's normal size hints, you can use the - XSetWMNormalHints function. - - XSetWMSizeHints can generate BadAlloc, BadAtom, and BadWindow - errors. - - To read a window's WM_SIZE_HINTS property, use XGetWMSizeHints. - - Status XGetWMSizeHints(Display *display, Window w, XSizeHints - *hints_return, long *supplied_return, Atom property); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - hints_return - - Returns the XSizeHints structure. - - supplied_return - - Returns the hints that were supplied by the user. - - property - - Specifies the property name. - - The XGetWMSizeHints function returns the size hints stored in - the specified property on the named window. If the property is - of type WM_SIZE_HINTS, is of format 32, and is long enough to - contain either an old (pre-ICCCM) or new size hints structure, - XGetWMSizeHints sets the various fields of the XSizeHints - structure, sets the supplied_return argument to the list of - fields that were supplied by the user (whether or not they - contained defined values), and returns a nonzero status. - Otherwise, it returns a zero status. To get a window's normal - size hints, you can use the XGetWMNormalHints function. - - If XGetWMSizeHints returns successfully and a pre-ICCCM size - hints property is read, the supplied_return argument will - contain the following bits: - -(USPosition|USSize|PPosition|PSize|PMinSize| - PMaxSize|PResizeInc|PAspect) - - If the property is large enough to contain the base size and - window gravity fields as well, the supplied_return argument - will also contain the following bits: - -PBaseSize|PWinGravity - - XGetWMSizeHints can generate BadAtom and BadWindow errors. - -Setting and Reading the WM_CLASS Property - - Xlib provides functions that you can use to set and get the - WM_CLASS property for a given window. These functions use the - XClassHint structure, which is defined in the - header file. - - To allocate an XClassHint structure, use XAllocClassHint. - - XClassHint *XAllocClassHint(void); - - The XAllocClassHint function allocates and returns a pointer to - an XClassHint structure. Note that the pointer fields in the - XClassHint structure are initially set to NULL. If insufficient - memory is available, XAllocClassHint returns NULL. To free the - memory allocated to this structure, use XFree. - - The XClassHint contains: - - - -typedef struct { - char *res_name; - char *res_class; -} XClassHint; - - The res_name member contains the application name, and the - res_class member contains the application class. Note that the - name set in this property may differ from the name set as - WM_NAME. That is, WM_NAME specifies what should be displayed in - the title bar and, therefore, can contain temporal information - (for example, the name of a file currently in an editor's - buffer). On the other hand, the name specified as part of - WM_CLASS is the formal name of the application that should be - used when retrieving the application's resources from the - resource database. - - To set a window's WM_CLASS property, use XSetClassHint. - - XSetClassHint(Display *display, Window w, XClassHint - *class_hints); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - class_hints - - Specifies the XClassHint structure that is to be used. - - The XSetClassHint function sets the class hint for the - specified window. If the strings are not in the Host Portable - Character Encoding, the result is implementation-dependent. - - XSetClassHint can generate BadAlloc and BadWindow errors. - - To read a window's WM_CLASS property, use XGetClassHint. - - Status XGetClassHint(Display *display, Window w, XClassHint - *class_hints_return); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - class_hints_return - - Returns the XClassHint structure. - - The XGetClassHint function returns the class hint of the - specified window to the members of the supplied structure. If - the data returned by the server is in the Latin Portable - Character Encoding, then the returned strings are in the Host - Portable Character Encoding. Otherwise, the result is - implementation-dependent. It returns a nonzero status on - success; otherwise, it returns a zero status. To free res_name - and res_class when finished with the strings, use XFree on each - individually. - - XGetClassHint can generate a BadWindow error. - -Setting and Reading the WM_TRANSIENT_FOR Property - - Xlib provides functions that you can use to set and read the - WM_TRANSIENT_FOR property for a given window. - - To set a window's WM_TRANSIENT_FOR property, use - XSetTransientForHint. - - XSetTransientForHint(Display *display, Window w, Window - prop_window); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - prop_window - - Specifies the window that the WM_TRANSIENT_FOR property is to - be set to. - - The XSetTransientForHint function sets the WM_TRANSIENT_FOR - property of the specified window to the specified prop_window. - - XSetTransientForHint can generate BadAlloc and BadWindow - errors. - - To read a window's WM_TRANSIENT_FOR property, use - XGetTransientForHint. - - Status XGetTransientForHint(Display *display, Window w, Window - *prop_window_return); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - prop_window_return - - Returns the WM_TRANSIENT_FOR property of the specified window. - - The XGetTransientForHint function returns the WM_TRANSIENT_FOR - property for the specified window. It returns a nonzero status - on success; otherwise, it returns a zero status. - - XGetTransientForHint can generate a BadWindow error. - -Setting and Reading the WM_PROTOCOLS Property - - Xlib provides functions that you can use to set and read the - WM_PROTOCOLS property for a given window. - - To set a window's WM_PROTOCOLS property, use XSetWMProtocols. - - Status XSetWMProtocols(Display *display, Window w, Atom - *protocols, int count); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - protocols - - Specifies the list of protocols. - - count - - Specifies the number of protocols in the list. - - The XSetWMProtocols function replaces the WM_PROTOCOLS property - on the specified window with the list of atoms specified by the - protocols argument. If the property does not already exist, - XSetWMProtocols sets the WM_PROTOCOLS property on the specified - window to the list of atoms specified by the protocols - argument. The property is stored with a type of ATOM and a - format of 32. If it cannot intern the WM_PROTOCOLS atom, - XSetWMProtocols returns a zero status. Otherwise, it returns a - nonzero status. - - XSetWMProtocols can generate BadAlloc and BadWindow errors. - - To read a window's WM_PROTOCOLS property, use XGetWMProtocols. - - Status XGetWMProtocols(Display *display, Window w, Atom - **protocols_return, int *count_return); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - protocols_return - - Returns the list of protocols. - - count_return - - Returns the number of protocols in the list. - - The XGetWMProtocols function returns the list of atoms stored - in the WM_PROTOCOLS property on the specified window. These - atoms describe window manager protocols in which the owner of - this window is willing to participate. If the property exists, - is of type ATOM, is of format 32, and the atom WM_PROTOCOLS can - be interned, XGetWMProtocols sets the protocols_return argument - to a list of atoms, sets the count_return argument to the - number of elements in the list, and returns a nonzero status. - Otherwise, it sets neither of the return arguments and returns - a zero status. To release the list of atoms, use XFree. - - XGetWMProtocols can generate a BadWindow error. - -Setting and Reading the WM_COLORMAP_WINDOWS Property - - Xlib provides functions that you can use to set and read the - WM_COLORMAP_WINDOWS property for a given window. - - To set a window's WM_COLORMAP_WINDOWS property, use - XSetWMColormapWindows. - - Status XSetWMColormapWindows(Display *display, Window w, Window - *colormap_windows, int count); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - colormap_windows - - Specifies the list of windows. - - count - - Specifies the number of windows in the list. - - The XSetWMColormapWindows function replaces the - WM_COLORMAP_WINDOWS property on the specified window with the - list of windows specified by the colormap_windows argument. If - the property does not already exist, XSetWMColormapWindows sets - the WM_COLORMAP_WINDOWS property on the specified window to the - list of windows specified by the colormap_windows argument. The - property is stored with a type of WINDOW and a format of 32. If - it cannot intern the WM_COLORMAP_WINDOWS atom, - XSetWMColormapWindows returns a zero status. Otherwise, it - returns a nonzero status. - - XSetWMColormapWindows can generate BadAlloc and BadWindow - errors. - - To read a window's WM_COLORMAP_WINDOWS property, use - XGetWMColormapWindows. - - Status XGetWMColormapWindows(Display *display, Window w, Window - **colormap_windows_return, int *count_return); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - colormap_windows_return - - Returns the list of windows. - - count_return - - Returns the number of windows in the list. - - The XGetWMColormapWindows function returns the list of window - identifiers stored in the WM_COLORMAP_WINDOWS property on the - specified window. These identifiers indicate the colormaps that - the window manager may need to install for this window. If the - property exists, is of type WINDOW, is of format 32, and the - atom WM_COLORMAP_WINDOWS can be interned, XGetWMColormapWindows - sets the windows_return argument to a list of window - identifiers, sets the count_return argument to the number of - elements in the list, and returns a nonzero status. Otherwise, - it sets neither of the return arguments and returns a zero - status. To release the list of window identifiers, use XFree. - - XGetWMColormapWindows can generate a BadWindow error. - -Setting and Reading the WM_ICON_SIZE Property - - Xlib provides functions that you can use to set and read the - WM_ICON_SIZE property for a given window. These functions use - the XIconSize structure, which is defined in the - header file. - - To allocate an XIconSize structure, use XAllocIconSize. - - XIconSize *XAllocIconSize(void); - - The XAllocIconSize function allocates and returns a pointer to - an XIconSize structure. Note that all fields in the XIconSize - structure are initially set to zero. If insufficient memory is - available, XAllocIconSize returns NULL. To free the memory - allocated to this structure, use XFree. - - The XIconSize structure contains: - - - -typedef struct { - int min_width, min_height; - int max_width, max_height; - int width_inc, height_inc; -} XIconSize; - - The width_inc and height_inc members define an arithmetic - progression of sizes (minimum to maximum) that represent the - supported icon sizes. - - To set a window's WM_ICON_SIZE property, use XSetIconSizes. - - XSetIconSizes(Display *display, Window w, XIconSize *size_list, - int count); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - size_list - - Specifies the size list. - - count - - Specifies the number of items in the size list. - - The XSetIconSizes function is used only by window managers to - set the supported icon sizes. - - XSetIconSizes can generate BadAlloc and BadWindow errors. - - To read a window's WM_ICON_SIZE property, use XGetIconSizes. - - Status XGetIconSizes(Display *display, Window w, XIconSize - **size_list_return, int *count_return); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - size_list_return - - Returns the size list. - - count_return - - Returns the number of items in the size list. - - The XGetIconSizes function returns zero if a window manager has - not set icon sizes; otherwise, it returns nonzero. - XGetIconSizes should be called by an application that wants to - find out what icon sizes would be most appreciated by the - window manager under which the application is running. The - application should then use XSetWMHints to supply the window - manager with an icon pixmap or window in one of the supported - sizes. To free the data allocated in size_list_return, use - XFree. - - XGetIconSizes can generate a BadWindow error. - -Using Window Manager Convenience Functions - - The XmbSetWMProperties function stores the standard set of - window manager properties, with text properties in standard - encodings for internationalized text communication. The - standard window manager properties for a given window are - WM_NAME, WM_ICON_NAME, WM_HINTS, WM_NORMAL_HINTS, WM_CLASS, - WM_COMMAND, WM_CLIENT_MACHINE, and WM_LOCALE_NAME. - - void XmbSetWMProperties(Display *display, Window w, char - *window_name, char *icon_name, char *argv[], int argc, - XSizeHints *normal_hints, XWMHints *wm_hints, XClassHint - *class_hints); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - window_name - - Specifies the window name, which should be a null-terminated - string. - - icon_name - - Specifies the icon name, which should be a null-terminated - string. - - argv - - Specifies the application's argument list. - - argc - - Specifies the number of arguments. - - hints - - Specifies the size hints for the window in its normal state. - - wm_hints - - Specifies the XWMHints structure to be used. - - class_hints - - Specifies the XClassHint structure to be used. - - The XmbSetWMProperties convenience function provides a simple - programming interface for setting those essential window - properties that are used for communicating with other clients - (particularly window and session managers). - - If the window_name argument is non-NULL, XmbSetWMProperties - sets the WM_NAME property. If the icon_name argument is - non-NULL, XmbSetWMProperties sets the WM_ICON_NAME property. - The window_name and icon_name arguments are null-terminated - strings in the encoding of the current locale. If the arguments - can be fully converted to the STRING encoding, the properties - are created with type ``STRING''; otherwise, the arguments are - converted to Compound Text, and the properties are created with - type ``COMPOUND_TEXT''. - - If the normal_hints argument is non-NULL, XmbSetWMProperties - calls XSetWMNormalHints, which sets the WM_NORMAL_HINTS - property (see section 14.1.7). If the wm_hints argument is - non-NULL, XmbSetWMProperties calls XSetWMHints, which sets the - WM_HINTS property (see section 14.1.6). - - If the argv argument is non-NULL, XmbSetWMProperties sets the - WM_COMMAND property from argv and argc. An argc of zero - indicates a zero-length command. - - The hostname of the machine is stored using XSetWMClientMachine - (see section 14.2.2). - - If the class_hints argument is non-NULL, XmbSetWMProperties - sets the WM_CLASS property. If the res_name member in the - XClassHint structure is set to the NULL pointer and the - RESOURCE_NAME environment variable is set, the value of the - environment variable is substituted for res_name. If the - res_name member is NULL, the environment variable is not set, - and argv and argv[0] are set, then the value of argv[0], - stripped of any directory prefixes, is substituted for - res_name. - - It is assumed that the supplied class_hints.res_name and argv, - the RESOURCE_NAME environment variable, and the hostname of the - machine are in the encoding of the locale announced for the - LC_CTYPE category (on POSIX-compliant systems, the LC_CTYPE, - else LANG environment variable). The corresponding WM_CLASS, - WM_COMMAND, and WM_CLIENT_MACHINE properties are typed - according to the local host locale announcer. No encoding - conversion is performed prior to storage in the properties. - - For clients that need to process the property text in a locale, - XmbSetWMProperties sets the WM_LOCALE_NAME property to be the - name of the current locale. The name is assumed to be in the - Host Portable Character Encoding and is converted to STRING for - storage in the property. - - XmbSetWMProperties can generate BadAlloc and BadWindow errors. - - To set a window's standard window manager properties with - strings in client-specified encodings, use XSetWMProperties. - The standard window manager properties for a given window are - WM_NAME, WM_ICON_NAME, WM_HINTS, WM_NORMAL_HINTS, WM_CLASS, - WM_COMMAND, and WM_CLIENT_MACHINE. - - void XSetWMProperties(Display *display, Window w, XTextProperty - *window_name, XTextProperty *icon_name, char **argv, int argc, - XSizeHints *normal_hints, XWMHints *wm_hints, XClassHint - *class_hints); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - window_name - - Specifies the window name, which should be a null-terminated - string. - - icon_name - - Specifies the icon name, which should be a null-terminated - string. - - argv - - Specifies the application's argument list. - - argc - - Specifies the number of arguments. - - normal_hints - - Specifies the size hints for the window in its normal state. - - wm_hints - - Specifies the XWMHints structure to be used. - - class_hints - - Specifies the XClassHint structure to be used. - - The XSetWMProperties convenience function provides a single - programming interface for setting those essential window - properties that are used for communicating with other clients - (particularly window and session managers). - - If the window_name argument is non-NULL, XSetWMProperties calls - XSetWMName, which, in turn, sets the WM_NAME property (see - section 14.1.4). If the icon_name argument is non-NULL, - XSetWMProperties calls XSetWMIconName, which sets the - WM_ICON_NAME property (see section 14.1.5). If the argv - argument is non-NULL, XSetWMProperties calls XSetCommand, which - sets the WM_COMMAND property (see section 14.2.1). Note that an - argc of zero is allowed to indicate a zero-length command. Note - also that the hostname of this machine is stored using - XSetWMClientMachine (see section 14.2.2). - - If the normal_hints argument is non-NULL, XSetWMProperties - calls XSetWMNormalHints, which sets the WM_NORMAL_HINTS - property (see section 14.1.7). If the wm_hints argument is - non-NULL, XSetWMProperties calls XSetWMHints, which sets the - WM_HINTS property (see section 14.1.6). - - If the class_hints argument is non-NULL, XSetWMProperties calls - XSetClassHint, which sets the WM_CLASS property (see section - 14.1.8). If the res_name member in the XClassHint structure is - set to the NULL pointer and the RESOURCE_NAME environment - variable is set, then the value of the environment variable is - substituted for res_name. If the res_name member is NULL, the - environment variable is not set, and argv and argv[0] are set, - then the value of argv[0], stripped of any directory prefixes, - is substituted for res_name. - - XSetWMProperties can generate BadAlloc and BadWindow errors. - -Client to Session Manager Communication - - This section discusses how to: - * Set and read the WM_COMMAND property - * Set and read the WM_CLIENT_MACHINE property - -Setting and Reading the WM_COMMAND Property - - Xlib provides functions that you can use to set and read the - WM_COMMAND property for a given window. - - To set a window's WM_COMMAND property, use XSetCommand. - - XSetCommand(Display *display, Window w, char **argv, int argc); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - argv - - Specifies the application's argument list. - - argc - - Specifies the number of arguments. - - The XSetCommand function sets the command and arguments used to - invoke the application. (Typically, argv is the argv array of - your main program.) If the strings are not in the Host Portable - Character Encoding, the result is implementation-dependent. - - XSetCommand can generate BadAlloc and BadWindow errors. - - To read a window's WM_COMMAND property, use XGetCommand. - - Status XGetCommand(Display *display, Window w, char - ***argv_return, int *argc_return); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - argv_return - - Returns the application's argument list. - - argc_return - - Returns the number of arguments returned. - - The XGetCommand function reads the WM_COMMAND property from the - specified window and returns a string list. If the WM_COMMAND - property exists, it is of type STRING and format 8. If - sufficient memory can be allocated to contain the string list, - XGetCommand fills in the argv_return and argc_return arguments - and returns a nonzero status. Otherwise, it returns a zero - status. If the data returned by the server is in the Latin - Portable Character Encoding, then the returned strings are in - the Host Portable Character Encoding. Otherwise, the result is - implementation-dependent. To free the memory allocated to the - string list, use XFreeStringList. - -Setting and Reading the WM_CLIENT_MACHINE Property - - Xlib provides functions that you can use to set and read the - WM_CLIENT_MACHINE property for a given window. - - To set a window's WM_CLIENT_MACHINE property, use - XSetWMClientMachine. - - void XSetWMClientMachine(Display *display, Window w, - XTextProperty *text_prop); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - text_prop - - Specifies the XTextProperty structure to be used. - - The XSetWMClientMachine convenience function calls - XSetTextProperty to set the WM_CLIENT_MACHINE property. - - To read a window's WM_CLIENT_MACHINE property, use - XGetWMClientMachine. - - Status XGetWMClientMachine(Display *display, Window w, - XTextProperty *text_prop_return); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - text_prop_return - - Returns the XTextProperty structure. - - The XGetWMClientMachine convenience function performs an - XGetTextProperty on the WM_CLIENT_MACHINE property. It returns - a nonzero status on success; otherwise, it returns a zero - status. - -Standard Colormaps - - Applications with color palettes, smooth-shaded drawings, or - digitized images demand large numbers of colors. In addition, - these applications often require an efficient mapping from - color triples to pixel values that display the appropriate - colors. - - As an example, consider a three-dimensional display program - that wants to draw a smoothly shaded sphere. At each pixel in - the image of the sphere, the program computes the intensity and - color of light reflected back to the viewer. The result of each - computation is a triple of red, green, and blue (RGB) - coefficients in the range 0.0 to 1.0. To draw the sphere, the - program needs a colormap that provides a large range of - uniformly distributed colors. The colormap should be arranged - so that the program can convert its RGB triples into pixel - values very quickly, because drawing the entire sphere requires - many such conversions. - - On many current workstations, the display is limited to 256 or - fewer colors. Applications must allocate colors carefully, not - only to make sure they cover the entire range they need but - also to make use of as many of the available colors as - possible. On a typical X display, many applications are active - at once. Most workstations have only one hardware look-up table - for colors, so only one application colormap can be installed - at a given time. The application using the installed colormap - is displayed correctly, and the other applications go - technicolor and are displayed with false colors. - - As another example, consider a user who is running an image - processing program to display earth-resources data. The image - processing program needs a colormap set up with 8 reds, 8 - greens, and 4 blues, for a total of 256 colors. Because some - colors are already in use in the default colormap, the image - processing program allocates and installs a new colormap. - - The user decides to alter some of the colors in the image by - invoking a color palette program to mix and choose colors. The - color palette program also needs a colormap with eight reds, - eight greens, and four blues, so just like the image processing - program, it must allocate and install a new colormap. - - Because only one colormap can be installed at a time, the color - palette may be displayed incorrectly whenever the image - processing program is active. Conversely, whenever the palette - program is active, the image may be displayed incorrectly. The - user can never match or compare colors in the palette and - image. Contention for colormap resources can be reduced if - applications with similar color needs share colormaps. - - The image processing program and the color palette program - could share the same colormap if there existed a convention - that described how the colormap was set up. Whenever either - program was active, both would be displayed correctly. - - The standard colormap properties define a set of commonly used - colormaps. Applications that share these colormaps and - conventions display true colors more often and provide a better - interface to the user. - - Standard colormaps allow applications to share commonly used - color resources. This allows many applications to be displayed - in true colors simultaneously, even when each application needs - an entirely filled colormap. - - Several standard colormaps are described in this section. - Usually, a window manager creates these colormaps. Applications - should use the standard colormaps if they already exist. - - To allocate an XStandardColormap structure, use - XAllocStandardColormap. - - XStandardColormap *XAllocStandardColormap(void); - - The XAllocStandardColormap function allocates and returns a - pointer to an XStandardColormap structure. Note that all fields - in the XStandardColormap structure are initially set to zero. - If insufficient memory is available, XAllocStandardColormap - returns NULL. To free the memory allocated to this structure, - use XFree. - - The XStandardColormap structure contains: -/* Hints */ - -#define ReeaseByFreeingColormap ((XID)1L) - -/* Values */ - -typedef struct { - Colormap colormap; - unsigned long red_max; - unsigned long red_mult; - unsigned long green_max; - unsigned long green_mult; - unsigned long blue_max; - unsigned long blue_mult; - unsigned long base_pixel; - VisualID visualid; - XID killid; -} XStandardColormap; - - The colormap member is the colormap created by the - XCreateColormap function. The red_max, green_max, and blue_max - members give the maximum red, green, and blue values, - respectively. Each color coefficient ranges from zero to its - max, inclusive. For example, a common colormap allocation is - 3/3/2 (3 planes for red, 3 planes for green, and 2 planes for - blue). This colormap would have red_max = 7, green_max = 7, and - blue_max = 3. An alternate allocation that uses only 216 colors - is red_max = 5, green_max = 5, and blue_max = 5. - - The red_mult, green_mult, and blue_mult members give the scale - factors used to compose a full pixel value. (See the discussion - of the base_pixel members for further information.) For a 3/3/2 - allocation, red_mult might be 32, green_mult might be 4, and - blue_mult might be 1. For a 6-colors-each allocation, red_mult - might be 36, green_mult might be 6, and blue_mult might be 1. - - The base_pixel member gives the base pixel value used to - compose a full pixel value. Usually, the base_pixel is obtained - from a call to the XAllocColorPlanes function. Given integer - red, green, and blue coefficients in their appropriate ranges, - one then can compute a corresponding pixel value by using the - following expression: - - - -(r * red_mult + g * green_mult + b * blue_mult + base_pixel) & 0xFFFFFFF -F - - For GrayScale colormaps, only the colormap, red_max, red_mult, - and base_pixel members are defined. The other members are - ignored. To compute a GrayScale pixel value, use the following - expression: - - - -(gray * red_mult + base_pixel) & 0xFFFFFFFF - - Negative multipliers can be represented by converting the 2's - complement representation of the multiplier into an unsigned - long and storing the result in the appropriate _mult field. The - step of masking by 0xFFFFFFFF effectively converts the - resulting positive multiplier into a negative one. The masking - step will take place automatically on many machine - architectures, depending on the size of the integer type used - to do the computation. - - The visualid member gives the ID number of the visual from - which the colormap was created. The killid member gives a - resource ID that indicates whether the cells held by this - standard colormap are to be released by freeing the colormap ID - or by calling the XKillClient function on the indicated - resource. (Note that this method is necessary for allocating - out of an existing colormap.) - - The properties containing the XStandardColormap information - have the type RGB_COLOR_MAP. - - The remainder of this section discusses standard colormap - properties and atoms as well as how to manipulate standard - colormaps. - -Standard Colormap Properties and Atoms - - Several standard colormaps are available. Each standard - colormap is defined by a property, and each such property is - identified by an atom. The following list names the atoms and - describes the colormap associated with each one. The - header file contains the definitions for each of - the following atoms, which are prefixed with XA_. - - RGB_DEFAULT_MAP - - This atom names a property. The value of the property is an - array of XStandardColormap structures. Each entry in the array - describes an RGB subset of the default color map for the Visual - specified by visual_id. - - Some applications only need a few RGB colors and may be able to - allocate them from the system default colormap. This is the - ideal situation because the fewer colormaps that are active in - the system the more applications are displayed with correct - colors at all times. - - A typical allocation for the RGB_DEFAULT_MAP on 8-plane - displays is 6 reds, 6 greens, and 6 blues. This gives 216 - uniformly distributed colors (6 intensities of 36 different - hues) and still leaves 40 elements of a 256-element colormap - available for special-purpose colors for text, borders, and so - on. - - RGB_BEST_MAP - - This atom names a property. The value of the property is an - XStandardColormap. - - The property defines the best RGB colormap available on the - screen. (Of course, this is a subjective evaluation.) Many - image processing and three-dimensional applications need to use - all available colormap cells and to distribute as many - perceptually distinct colors as possible over those cells. This - implies that there may be more green values available than red, - as well as more green or red than blue. - - For an 8-plane PseudoColor visual, RGB_BEST_MAP is likely to be - a 3/3/2 allocation. For a 24-plane DirectColor visual, - RGB_BEST_MAP is normally an 8/8/8 allocation. - - RGB_RED_MAP,RGB_GREEN_MAP,RGB_BLUE_MAP - - These atoms name properties. The value of each property is an - XStandardColormap. - - The properties define all-red, all-green, and all-blue - colormaps, respectively. These maps are used by applications - that want to make color-separated images. For example, a user - might generate a full-color image on an 8-plane display both by - rendering an image three times (once with high color resolution - in red, once with green, and once with blue) and by multiply - exposing a single frame in a camera. - - RGB_GRAY_MAP - - This atom names a property. The value of the property is an - XStandardColormap. - - The property describes the best GrayScale colormap available on - the screen. As previously mentioned, only the colormap, - red_max, red_mult, and base_pixel members of the - XStandardColormap structure are used for GrayScale colormaps. - -Setting and Obtaining Standard Colormaps - - Xlib provides functions that you can use to set and obtain an - XStandardColormap structure. - - To set an XStandardColormap structure, use XSetRGBColormaps. - - void XSetRGBColormaps(Display *display, Window w, - XStandardColormap *std_colormap, int count, Atom property); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - std_colormap - - Specifies the XStandardColormap structure to be used. - - count - - Specifies the number of colormaps. - - property - - Specifies the property name. - - The XSetRGBColormaps function replaces the RGB colormap - definition in the specified property on the named window. If - the property does not already exist, XSetRGBColormaps sets the - RGB colormap definition in the specified property on the named - window. The property is stored with a type of RGB_COLOR_MAP and - a format of 32. Note that it is the caller's responsibility to - honor the ICCCM restriction that only RGB_DEFAULT_MAP contain - more than one definition. - - The XSetRGBColormaps function usually is only used by window or - session managers. To create a standard colormap, follow this - procedure: - * Open a new connection to the same server. - * Grab the server. - * See if the property is on the property list of the root - window for the screen. - * If the desired property is not present: - * Create a colormap (unless you are using the default - colormap of the screen). - * Determine the color characteristics of the visual. - * Allocate cells in the colormap (or create it with - AllocAll). - * Call XStoreColors to store appropriate color values in the - colormap. - * Fill in the descriptive members in the XStandardColormap - structure. - * Attach the property to the root window. - * Use XSetCloseDownMode to make the resource permanent. - * Ungrab the server. - - XSetRGBColormaps can generate BadAlloc, BadAtom, and BadWindow - errors. - - To obtain the XStandardColormap structure associated with the - specified property, use XGetRGBColormaps. - - Status XGetRGBColormaps(Display *display, Window w, - XStandardColormap **std_colormap_return, int *count_return, - Atom property); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - std_colormap_return - - Returns the XStandardColormap structure. - - count_return - - Returns the number of colormaps. - - property - - Specifies the property name. - - The XGetRGBColormaps function returns the RGB colormap - definitions stored in the specified property on the named - window. If the property exists, is of type RGB_COLOR_MAP, is of - format 32, and is long enough to contain a colormap definition, - XGetRGBColormaps allocates and fills in space for the returned - colormaps and returns a nonzero status. If the visualid is not - present, XGetRGBColormaps assumes the default visual for the - screen on which the window is located; if the killid is not - present, None is assumed, which indicates that the resources - cannot be released. Otherwise, none of the fields are set, and - XGetRGBColormaps returns a zero status. Note that it is the - caller's responsibility to honor the ICCCM restriction that - only RGB_DEFAULT_MAP contain more than one definition. - - XGetRGBColormaps can generate BadAtom and BadWindow errors. - -Chapter 15. Resource Manager Functions - - Table of Contents - - Resource File Syntax - Resource Manager Matching Rules - Quarks - Creating and Storing Databases - Merging Resource Databases - Looking Up Resources - Storing into a Resource Database - Enumerating Database Entries - Parsing Command Line Options - - A program often needs a variety of options in the X environment - (for example, fonts, colors, icons, and cursors). Specifying - all of these options on the command line is awkward because - users may want to customize many aspects of the program and - need a convenient way to establish these customizations as the - default settings. The resource manager is provided for this - purpose. Resource specifications are usually stored in - human-readable files and in server properties. - - The resource manager is a database manager with a twist. In - most database systems, you perform a query using an imprecise - specification, and you get back a set of records. The resource - manager, however, allows you to specify a large set of values - with an imprecise specification, to query the database with a - precise specification, and to get back only a single value. - This should be used by applications that need to know what the - user prefers for colors, fonts, and other resources. It is this - use as a database for dealing with X resources that inspired - the name "Resource Manager," although the resource manager can - be and is used in other ways. - - For example, a user of your application may want to specify - that all windows should have a blue background but that all - mail-reading windows should have a red background. With - well-engineered and coordinated applications, a user can define - this information using only two lines of specifications. - - As an example of how the resource manager works, consider a - mail-reading application called xmh. Assume that it is designed - so that it uses a complex window hierarchy all the way down to - individual command buttons, which may be actual small - subwindows in some toolkits. These are often called objects or - widgets. In such toolkit systems, each user interface object - can be composed of other objects and can be assigned a name and - a class. Fully qualified names or classes can have arbitrary - numbers of component names, but a fully qualified name always - has the same number of component names as a fully qualified - class. This generally reflects the structure of the application - as composed of these objects, starting with the application - itself. - - For example, the xmh mail program has a name "xmh" and is one - of a class of "Mail" programs. By convention, the first - character of class components is capitalized, and the first - letter of name components is in lowercase. Each name and class - finally has an attribute (for example, "foreground" or "font"). - If each window is properly assigned a name and class, it is - easy for the user to specify attributes of any portion of the - application. - - At the top level, the application might consist of a paned - window (that is, a window divided into several sections) named - "toc". One pane of the paned window is a button box window - named "buttons" and is filled with command buttons. One of - these command buttons is used to incorporate new mail and has - the name "incorporate". This window has a fully qualified name, - "xmh.toc.buttons.incorporate", and a fully qualified class, - "Xmh.Paned.Box.Command". Its fully qualified name is the name - of its parent, "xmh.toc.buttons", followed by its name, - "incorporate". Its class is the class of its parent, - "Xmh.Paned.Box", followed by its particular class, "Command". - The fully qualified name of a resource is the attribute's name - appended to the object's fully qualified name, and the fully - qualified class is its class appended to the object's class. - - The incorporate button might need the following resources: - Title string, Font, Foreground color for its inactive state, - Background color for its inactive state, Foreground color for - its active state, and Background color for its active state. - Each resource is considered to be an attribute of the button - and, as such, has a name and a class. For example, the - foreground color for the button in its active state might be - named "activeForeground", and its class might be "Foreground". - - When an application looks up a resource (for example, a color), - it passes the complete name and complete class of the resource - to a look-up routine. The resource manager compares this - complete specification against the incomplete specifications of - entries in the resource database, finds the best match, and - returns the corresponding value for that entry. - - The definitions for the resource manager are contained in - . - -Resource File Syntax - - The syntax of a resource file is a sequence of resource lines - terminated by newline characters or the end of the file. The - syntax of an individual resource line is: - - - -ResourceLine = Comment | IncludeFile | ResourceSpec | -Comment = "!" {} -IncludeFile = "#" WhiteSpace "include" WhiteSpace FileName White -Space -FileName = -ResourceSpec = WhiteSpace ResourceName WhiteSpace ":" WhiteSpace - Value -ResourceName = [Binding] {Component Binding} ComponentName -Binding = "." | "*" -WhiteSpace = { | } -Component = "?" | ComponentName -ComponentName = NameChar {NameChar} -NameChar = "a"-"z" | "A"-"Z" | "0"-"9" | "_" | "-" -Value = {} - - Elements separated by vertical bar (|) are alternatives. Curly - braces ({......}) indicate zero or more repetitions of the - enclosed elements. Square brackets ([......]) indicate that the - enclosed element is optional. Quotes ("......") are used around - literal characters. - - IncludeFile lines are interpreted by replacing the line with - the contents of the specified file. The word "include" must be - in lowercase. The file name is interpreted relative to the - directory of the file in which the line occurs (for example, if - the file name contains no directory or contains a relative - directory specification). - - If a ResourceName contains a contiguous sequence of two or more - Binding characters, the sequence will be replaced with a single - ".." character if the sequence contains only ".." characters; - otherwise, the sequence will be replaced with a single "*" - character. - - A resource database never contains more than one entry for a - given ResourceName. If a resource file contains multiple lines - with the same ResourceName, the last line in the file is used. - - Any white space characters before or after the name or colon in - a ResourceSpec are ignored. To allow a Value to begin with - white space, the two-character sequence "\\space" (backslash - followed by space) is recognized and replaced by a space - character, and the two-character sequence "\\tab" (backslash - followed by horizontal tab) is recognized and replaced by a - horizontal tab character. To allow a Value to contain embedded - newline characters, the two-character sequence "\\n" is - recognized and replaced by a newline character. To allow a - Value to be broken across multiple lines in a text file, the - two-character sequence "\\newline" (backslash followed by - newline) is recognized and removed from the value. To allow a - Value to contain arbitrary character codes, the four-character - sequence "\\nnn", where each n is a digit character in the - range of "0"-"7", is recognized and replaced with a single byte - that contains the octal value specified by the sequence. - Finally, the two-character sequence "\newline" is recognized - and replaced with a single backslash. - - As an example of these sequences, the following resource line - contains a value consisting of four characters: a backslash, a - null, a "z", and a newline: -magic.values: \\000\ -z\n - -Resource Manager Matching Rules - - The algorithm for determining which resource database entry - matches a given query is the heart of the resource manager. All - queries must fully specify the name and class of the desired - resource (use of the characters "*" and "?" is not permitted). - The library supports up to 100 components in a full name or - class. Resources are stored in the database with only partially - specified names and classes, using pattern matching constructs. - An asterisk (*) is a loose binding and is used to represent any - number of intervening components, including none. A period (.) - is a tight binding and is used to separate immediately adjacent - components. A question mark (?) is used to match any single - component name or class. A database entry cannot end in a loose - binding; the final component (which cannot be the character - "?") must be specified. The lookup algorithm searches the - database for the entry that most closely matches (is most - specific for) the full name and class being queried. When more - than one database entry matches the full name and class, - precedence rules are used to select just one. - - The full name and class are scanned from left to right (from - highest level in the hierarchy to lowest), one component at a - time. At each level, the corresponding component and/or binding - of each matching entry is determined, and these matching - components and bindings are compared according to precedence - rules. Each of the rules is applied at each level before moving - to the next level, until a rule selects a single entry over all - others. The rules, in order of precedence, are: - * An entry that contains a matching component (whether name, - class, or the character "?") takes precedence over entries - that elide the level (that is, entries that match the level - in a loose binding). - * An entry with a matching name takes precedence over both - entries with a matching class and entries that match using - the character "?". An entry with a matching class takes - precedence over entries that match using the character "?". - * An entry preceded by a tight binding takes precedence over - entries preceded by a loose binding. - - To illustrate these rules, consider the following resource - database entries: - - -xmh*Paned*activeForeground: red (entry A) -*incorporate.Foreground: blue (entry B) -xmh.toc*Command*activeForeground: green (entry C) -xmh.toc*?.Foreground: white (entry D) -xmh.toc*Command.activeForeground: black (entry E) - - Consider a query for the resource: - - - -xmh.toc.messagefunctions.incorporate.activeForeground (name) -Xmh.Paned.Box.Command.Foreground (class) - - At the first level (xmh, Xmh), rule 1 eliminates entry B. At - the second level (toc, Paned), rule 2 eliminates entry A. At - the third level (messagefunctions, Box), no entries are - eliminated. At the fourth level (incorporate, Command), rule 2 - eliminates entry D. At the fifth level (activeForeground, - Foreground), rule 3 eliminates entry C. - -Quarks - - Most uses of the resource manager involve defining names, - classes, and representation types as string constants. However, - always referring to strings in the resource manager can be - slow, because it is so heavily used in some toolkits. To solve - this problem, a shorthand for a string is used in place of the - string in many of the resource manager functions. Simple - comparisons can be performed rather than string comparisons. - The shorthand name for a string is called a quark and is the - type XrmQuark. On some occasions, you may want to allocate a - quark that has no string equivalent. - - A quark is to a string what an atom is to a string in the - server, but its use is entirely local to your application. - - To allocate a new quark, use XrmUniqueQuark. - - XrmQuark XrmUniqueQuark(void); - - The XrmUniqueQuark function allocates a quark that is - guaranteed not to represent any string that is known to the - resource manager. - - Each name, class, and representation type is typedef'd as an - XrmQuark. - -typedef int XrmQuark, *XrmQuarkList; -typedef XrmQuark XrmName; -typedef XrmQuark XrmClass; -typedef XrmQuark XrmRepresentation; -#define NULLQUARK ((XrmQuark) 0) - - Lists are represented as null-terminated arrays of quarks. The - size of the array must be large enough for the number of - components used. - -typedef XrmQuarkList XrmNameList; -typedef XrmQuarkList XrmClassList; - - To convert a string to a quark, use XrmStringToQuark or - XrmPermStringToQuark. -#define XrmStringToName(string) XrmStringToQuark(string) -#define XrmStringToClass(string) XrmStringToQuark(string) -#define XrmStringToRepresentation(string) XrmStringToQuark(string) - - XrmQuark XrmStringToQuark(char *string); - - string - - Specifies the string for which a quark(Ql is to be allocated. - - These functions can be used to convert from string to quark - representation. If the string is not in the Host Portable - Character Encoding, the conversion is implementation-dependent. - The string argument to XrmStringToQuark need not be permanently - allocated storage. XrmPermStringToQuark is just like - XrmStringToQuark, except that Xlib is permitted to assume the - string argument is permanently allocated, and, hence, that it - can be used as the value to be returned by XrmQuarkToString. - - For any given quark, if XrmStringToQuark returns a non-NULL - value, all future calls will return the same value (identical - address). - - To convert a quark to a string, use XrmQuarkToString. -#define XrmNameToString(name) XrmQuarkToString(name) -#define XrmClassToString(class) XrmQuarkToString(name) -#define XrmRepresentationToString(type) XrmQuarkToString(type) - - char *XrmQuarkToString(XrmQuark quark); - - quark - - Specifies the quark for which the equivalent string is desired. - - These functions can be used to convert from quark - representation to string. The string pointed to by the return - value must not be modified or freed. The returned string is - byte-for-byte equal to the original string passed to one of the - string-to-quark routines. If no string exists for that quark, - XrmQuarkToString returns NULL. For any given quark, if - XrmQuarkToString returns a non-NULL value, all future calls - will return the same value (identical address). - - To convert a string with one or more components to a quark - list, use XrmStringToQuarkList. -#define XrmStringToNameList(str,name) XrmStringToQuarkList((str), (name -)) -#define XrmStringToClassList(str,class) XrmStringToQuarkList((str), (cl -ass)) - - void XrmStringToQuarkList(char *string, XrmQuarkList - quarks_return); - - string - - Specifies the string for which a quark list is to be allocated. - - quarks_return - - Returns the list of quarks. The caller must allocate sufficient - space for the quarks list before calling XrmStringToQuarkList. - - The XrmStringToQuarkList function converts the null-terminated - string (generally a fully qualified name) to a list of quarks. - Note that the string must be in the valid ResourceName format - (see section 15.1). If the string is not in the Host Portable - Character Encoding, the conversion is implementation-dependent. - - A binding list is a list of type XrmBindingList and indicates - if components of name or class lists are bound tightly or - loosely (that is, if wildcarding of intermediate components is - specified). - -typedef enum {XrmBindTightly, XrmBindLoosely} XrmBinding, *XrmBindingLis -t; - - XrmBindTightly indicates that a period separates the - components, and XrmBindLoosely indicates that an asterisk - separates the components. - - To convert a string with one or more components to a binding - list and a quark list, use XrmStringToBindingQuarkList. - - XrmStringToBindingQuarkList(char *string, XrmBindingList - bindings_return, XrmQuarkList quarks_return); - - string - - Specifies the string for which a quark list is to be allocated. - - bindings_return - - Returns the binding list. The caller must allocate sufficient - space for the binding list before calling - XrmStringToBindingQuarkList. - - quarks_return - - Returns the list of quarks. The caller must allocate sufficient - space for the quarks list before calling - XrmStringToBindingQuarkList. - - Component names in the list are separated by a period or an - asterisk character. The string must be in the format of a valid - ResourceName (see section 15.1). If the string does not start - with a period or an asterisk, a tight binding is assumed. For - example, the string ``*a.b*c'' becomes: - - - -quarks: a b c -bindings: loose tight loose - -Creating and Storing Databases - - A resource database is an opaque type, XrmDatabase. Each - database value is stored in an XrmValue structure. This - structure consists of a size, an address, and a representation - type. The size is specified in bytes. The representation type - is a way for you to store data tagged by some - application-defined type (for example, the strings ``font'' or - ``color''). It has nothing to do with the C data type or with - its class. The XrmValue structure is defined as: - - - -typedef struct { - unsigned int size; - XPointer addr; -} XrmValue, *XrmValuePtr; - - To initialize the resource manager, use XrmInitialize. - - void XrmInitialize(void XrmInitialize(\|)); - - To retrieve a database from disk, use XrmGetFileDatabase. - - XrmDatabase XrmGetFileDatabase(char *filename); - - filename - - Specifies the resource database file name. - - The XrmGetFileDatabase function opens the specified file, - creates a new resource database, and loads it with the - specifications read in from the specified file. The specified - file should contain a sequence of entries in valid ResourceLine - format (see section 15.1); the database that results from - reading a file with incorrect syntax is - implementation-dependent. The file is parsed in the current - locale, and the database is created in the current locale. If - it cannot open the specified file, XrmGetFileDatabase returns - NULL. - - To store a copy of a database to disk, use XrmPutFileDatabase. - - void XrmPutFileDatabase(XrmDatabase database, char *stored_db); - - database - - Specifies the database that is to be used. - - stored_db - - Specifies the file name for the stored database. - - The XrmPutFileDatabase function stores a copy of the specified - database in the specified file. Text is written to the file as - a sequence of entries in valid ResourceLine format (see section - 15.1). The file is written in the locale of the database. - Entries containing resource names that are not in the Host - Portable Character Encoding or containing values that are not - in the encoding of the database locale, are written in an - implementation-dependent manner. The order in which entries are - written is implementation-dependent. Entries with - representation types other than ``String'' are ignored. - - To obtain a pointer to the screen-independent resources of a - display, use XResourceManagerString. - - char *XResourceManagerString(Display *display); - - display - - Specifies the connection to the X server. - - The XResourceManagerString function returns the - RESOURCE_MANAGER property from the server's root window of - screen zero, which was returned when the connection was opened - using XOpenDisplay. The property is converted from type STRING - to the current locale. The conversion is identical to that - produced by XmbTextPropertyToTextList for a single element - STRING property. The returned string is owned by Xlib and - should not be freed by the client. The property value must be - in a format that is acceptable to XrmGetStringDatabase. If no - property exists, NULL is returned. - - To obtain a pointer to the screen-specific resources of a - screen, use XScreenResourceString. - - char *XScreenResourceString(Screen *screen); - - screen - - Specifies the screen. - - The XScreenResourceString function returns the SCREEN_RESOURCES - property from the root window of the specified screen. The - property is converted from type STRING to the current locale. - The conversion is identical to that produced by - XmbTextPropertyToTextList for a single element STRING property. - The property value must be in a format that is acceptable to - XrmGetStringDatabase. If no property exists, NULL is returned. - The caller is responsible for freeing the returned string by - using XFree. - - To create a database from a string, use XrmGetStringDatabase. - - XrmDatabase XrmGetStringDatabase(char *data); - - data - - Specifies the database contents using a string. - - The XrmGetStringDatabase function creates a new database and - stores the resources specified in the specified null-terminated - string. XrmGetStringDatabase is similar to XrmGetFileDatabase - except that it reads the information out of a string instead of - out of a file. The string should contain a sequence of entries - in valid ResourceLine format (see section 15.1) terminated by a - null character; the database that results from using a string - with incorrect syntax is implementation-dependent. The string - is parsed in the current locale, and the database is created in - the current locale. - - To obtain the locale name of a database, use - XrmLocaleOfDatabase. - - char *XrmLocaleOfDatabase(XrmDatabase database); - - database - - Specifies the resource database. - - The XrmLocaleOfDatabase function returns the name of the locale - bound to the specified database, as a null-terminated string. - The returned locale name string is owned by Xlib and should not - be modified or freed by the client. Xlib is not permitted to - free the string until the database is destroyed. Until the - string is freed, it will not be modified by Xlib. - - To destroy a resource database and free its allocated memory, - use XrmDestroyDatabase. - - void XrmDestroyDatabase(XrmDatabase database); - - database - - Specifies the resource database. - - If database is NULL, XrmDestroyDatabase returns immediately. - - To associate a resource database with a display, use - XrmSetDatabase. - - void XrmSetDatabase(Display *display, XrmDatabase database); - - display - - Specifies the connection to the X server. - - database - - Specifies the resource database. - - The XrmSetDatabase function associates the specified resource - database (or NULL) with the specified display. The database - previously associated with the display (if any) is not - destroyed. A client or toolkit may find this function - convenient for retaining a database once it is constructed. - - To get the resource database associated with a display, use - XrmGetDatabase. - - XrmDatabase XrmGetDatabase(Display *display); - - display - - Specifies the connection to the X server. - - The XrmGetDatabase function returns the database associated - with the specified display. It returns NULL if a database has - not yet been set. - -Merging Resource Databases - - To merge the contents of a resource file into a database, use - XrmCombineFileDatabase. - - Status XrmCombineFileDatabase(char *filename, XrmDatabase - *target_db, Bool override); - - filename - - Specifies the resource database file name. - - target_db - - Specifies the resource database into which the source database - is to be merged. - - override - - Specifies whether source entries override target ones. - - The XrmCombineFileDatabase function merges the contents of a - resource file into a database. If the same specifier is used - for an entry in both the file and the database, the entry in - the file will replace the entry in the database if override is - True; otherwise, the entry in the file is discarded. The file - is parsed in the current locale. If the file cannot be read, a - zero status is returned; otherwise, a nonzero status is - returned. If target_db contains NULL, XrmCombineFileDatabase - creates and returns a new database to it. Otherwise, the - database pointed to by target_db is not destroyed by the merge. - The database entries are merged without changing values or - types, regardless of the locale of the database. The locale of - the target database is not modified. - - To merge the contents of one database into another database, - use XrmCombineDatabase. - - void XrmCombineDatabase(XrmDatabase source_db, XrmDatabase - *target_db, Bool override); - - source_db - - Specifies the resource database that is to be merged into the - target database. - - target_db - - Specifies the resource database into which the source database - is to be merged. - - override - - Specifies whether source entries override target ones. - - The XrmCombineDatabase function merges the contents of one - database into another. If the same specifier is used for an - entry in both databases, the entry in the source_db will - replace the entry in the target_db if override is True; - otherwise, the entry in source_db is discarded. If target_db - contains NULL, XrmCombineDatabase simply stores source_db in - it. Otherwise, source_db is destroyed by the merge, but the - database pointed to by target_db is not destroyed. The database - entries are merged without changing values or types, regardless - of the locales of the databases. The locale of the target - database is not modified. - - To merge the contents of one database into another database - with override semantics, use XrmMergeDatabases. - - void XrmMergeDatabases(XrmDatabase source_db, XrmDatabase - *target_db); - - source_db - - Specifies the resource database that is to be merged into the - target database. - - target_db - - Specifies the resource database into which the source database - is to be merged. - - Calling the XrmMergeDatabases function is equivalent to calling - the XrmCombineDatabase function with an override argument of - True. - -Looking Up Resources - - To retrieve a resource from a resource database, use - XrmGetResource, XrmQGetResource, or XrmQGetSearchResource. - - Bool XrmGetResource(XrmDatabase database, char *str_name, char - *str_class, char **str_type_return, XrmValue *value_return); - - database - - Specifies the database that is to be used. - - str_name - - Specifies the fully qualified name of the value being retrieved - (as a string). - - str_class - - Specifies the fully qualified class of the value being - retrieved (as a string). - - str_type_return - - Returns the representation type of the destination (as a - string). - - value_return - - Returns the value in the database. - - Bool XrmQGetResource(XrmDatabase database, XrmNameList - quark_name, XrmClassList quark_class, XrmRepresentation - *quark_type_return, XrmValue *value_return); - - database - - Specifies the database that is to be used. - - quark_name - - Specifies the fully qualified name of the value being retrieved - (as a quark). - - quark_class - - Specifies the fully qualified class of the value being - retrieved (as a quark). - - quark_type_return - - Returns the representation type of the destination (as a - quark). - - value_return - - Returns the value in the database. - - The XrmGetResource and XrmQGetResource functions retrieve a - resource from the specified database. Both take a fully - qualified name/class pair, a destination resource - representation, and the address of a value (size/address pair). - The value and returned type point into database memory; - therefore, you must not modify the data. - - The database only frees or overwrites entries on - XrmPutResource, XrmQPutResource, or XrmMergeDatabases. A client - that is not storing new values into the database or is not - merging the database should be safe using the address passed - back at any time until it exits. If a resource was found, both - XrmGetResource and XrmQGetResource return True; otherwise, they - return False. - - Most applications and toolkits do not make random probes into a - resource database to fetch resources. The X toolkit access - pattern for a resource database is quite stylized. A series of - from 1 to 20 probes is made with only the last name/class - differing in each probe. The XrmGetResource function is at - worst a 2^n algorithm, where n is the length of the name/class - list. This can be improved upon by the application programmer - by prefetching a list of database levels that might match the - first part of a name/class list. - - To obtain a list of database levels, use XrmQGetSearchList. - - Bool XrmQGetSearchResource(XrmDatabase database, XrmNameList - names, XrmClassList classes, XrmSearchList list_return, int - list_length); - - database - - Specifies the database that is to be used. - - names - - Specifies a list of resource names. - - classes - - Specifies a list of resource classes. - - list_return - - Returns a search list for further use. The caller must allocate - sufficient space for the list before calling XrmQGetSearchList. - - list_length - - Specifies the number of entries (not the byte size) allocated - for list_return. - - The XrmQGetSearchList function takes a list of names and - classes and returns a list of database levels where a match - might occur. The returned list is in best-to-worst order and - uses the same algorithm as XrmGetResource for determining - precedence. If list_return was large enough for the search - list, XrmQGetSearchList returns True; otherwise, it returns - False. - - The size of the search list that the caller must allocate is - dependent upon the number of levels and wildcards in the - resource specifiers that are stored in the database. The worst - case length is 3^n, where n is the number of name or class - components in names or classes. - - When using XrmQGetSearchList followed by multiple probes for - resources with a common name and class prefix, only the common - prefix should be specified in the name and class list to - XrmQGetSearchList. - - To search resource database levels for a given resource, use - XrmQGetSearchResource. - - Bool XrmQGetSearchResource(XrmSearchList list, XrmName name, - XrmClass class, XrmRepresentation *type_return, XrmValue - *value_return); - - list - - Specifies the search list returned by XrmQGetSearchList. - - name - - Specifies the resource name. - - class - - Specifies the resource class. - - type_return - - Returns data representation type. - - value_return - - Returns the value in the database. - - The XrmQGetSearchResource function searches the specified - database levels for the resource that is fully identified by - the specified name and class. The search stops with the first - match. XrmQGetSearchResource returns True if the resource was - found; otherwise, it returns False. - - A call to XrmQGetSearchList with a name and class list - containing all but the last component of a resource name - followed by a call to XrmQGetSearchResource with the last - component name and class returns the same database entry as - XrmGetResource and XrmQGetResource with the fully qualified - name and class. - -Storing into a Resource Database - - To store resources into the database, use XrmPutResource or - XrmQPutResource. Both functions take a partial resource - specification, a representation type, and a value. This value - is copied into the specified database. - - void XrmPutResource(XrmDatabase *database, char *specifier, - char *type, XrmValue *value); - - database - - Specifies the resource database. - - specifier - - Specifies a complete or partial specification of the resource. - - type - - Specifies the type of the resource. - - value - - Specifies the value of the resource, which is specified as a - string. - - If database contains NULL, XrmPutResource creates a new - database and returns a pointer to it. XrmPutResource is a - convenience function that calls XrmStringToBindingQuarkList - followed by: - -XrmQPutResource(database, bindings, quarks, XrmStringToQuark(type), valu -e) - - If the specifier and type are not in the Host Portable - Character Encoding, the result is implementation-dependent. The - value is stored in the database without modification. - - void XrmQPutResource(XrmDatabase *database, XrmBindingList - bindings, XrmQuarkList quarks, XrmRepresentation type, XrmValue - *value); - - database - - Specifies the resource database. - - bindings - - Specifies a list of bindings. - - quarks - - Specifies the complete or partial name or the class list of the - resource. - - type - - Specifies the type of the resource. - - value - - Specifies the value of the resource, which is specified as a - string. - - If database contains NULL, XrmQPutResource creates a new - database and returns a pointer to it. If a resource entry with - the identical bindings and quarks already exists in the - database, the previous type and value are replaced by the new - specified type and value. The value is stored in the database - without modification. - - To add a resource that is specified as a string, use - XrmPutStringResource. - - void XrmPutStringResource(XrmDatabase *database, char - *specifier, char *value); - - database - - Specifies the resource database. - - specifier - - Specifies a complete or partial specification of the resource. - - value - - Specifies the value of the resource, which is specified as a - string. - - If database contains NULL, XrmPutStringResource creates a new - database and returns a pointer to it. XrmPutStringResource adds - a resource with the specified value to the specified database. - XrmPutStringResource is a convenience function that first calls - XrmStringToBindingQuarkList on the specifier and then calls - XrmQPutResource, using a ``String'' representation type. If the - specifier is not in the Host Portable Character Encoding, the - result is implementation-dependent. The value is stored in the - database without modification. - - To add a string resource using quarks as a specification, use - XrmQPutStringResource. - - void XrmQPutStringResource(XrmDatabase *database, - XrmBindingList bindings, XrmQuarkList quarks, char *value); - - database - - Specifies the resource database. - - bindings - - Specifies a list of bindings. - - quarks - - Specifies the complete or partial name or the class list of the - resource. - - value - - Specifies the value of the resource, which is specified as a - string. - - If database contains NULL, XrmQPutStringResource creates a new - database and returns a pointer to it. XrmQPutStringResource is - a convenience routine that constructs an XrmValue for the value - string (by calling strlen to compute the size) and then calls - XrmQPutResource, using a ``String'' representation type. The - value is stored in the database without modification. - - To add a single resource entry that is specified as a string - that contains both a name and a value, use XrmPutLineResource. - - void XrmPutLineResource(XrmDatabase *database, char *line); - - database - - Specifies the resource database. - - line - - Specifies the resource name and value pair as a single string. - - If database contains NULL, XrmPutLineResource creates a new - database and returns a pointer to it. XrmPutLineResource adds a - single resource entry to the specified database. The line - should be in valid ResourceLine format (see section 15.1) - terminated by a newline or null character; the database that - results from using a string with incorrect syntax is - implementation-dependent. The string is parsed in the locale of - the database. If the ResourceName is not in the Host Portable - Character Encoding, the result is implementation-dependent. - Note that comment lines are not stored. - -Enumerating Database Entries - - To enumerate the entries of a database, use - XrmEnumerateDatabase. -#define XrmEnumAllLevels 0 -#define XrmEnumOneLevel 0 - - Bool XrmEnumerateDatabase(XrmDatabase database, XrmNameList - name_prefix, XrmClassList class_prefix, int mode, Bool - (*proc)(), XPointer arg); - - database - - Specifies the resource database. - - name_prefix - - Specifies the resource name prefix. - - class_prefix - - Specifies the resource class prefix. - - mode - - Specifies the number of levels to enumerate. - - proc - - Specifies the procedure that is to be called for each matching - entry. - - arg - - Specifies the user-supplied argument that will be passed to the - procedure. - - The XrmEnumerateDatabase function calls the specified procedure - for each resource in the database that would match some - completion of the given name/class resource prefix. The order - in which resources are found is implementation-dependent. If - mode is XrmEnumOneLevel, a resource must match the given - name/class prefix with just a single name and class appended. - If mode is XrmEnumAllLevels, the resource must match the given - name/class prefix with one or more names and classes appended. - If the procedure returns True, the enumeration terminates and - the function returns True. If the procedure always returns - False, all matching resources are enumerated and the function - returns False. - - The procedure is called with the following arguments: - - - -(*proc)(database, bindings, quarks, type, value, arg) - XrmDatabase *database; - XrmBindingList bindings; - XrmQuarkList quarks; - XrmRepresentation *type; - XrmValue *value; - XPointer arg; - - The bindings and quarks lists are terminated by NULLQUARK. Note - that pointers to the database and type are passed, but these - values should not be modified. - - The procedure must not modify the database. If Xlib has been - initialized for threads, the procedure is called with the - database locked and the result of a call by the procedure to - any Xlib function using the same database is not defined. - -Parsing Command Line Options - - The XrmParseCommand function can be used to parse the command - line arguments to a program and modify a resource database with - selected entries from the command line. - - - -typedef enum { - XrmoptionNoArg, /* Value is specified in XrmOptionDescRec.value - */ - XrmoptionIsArg, /* Value is the option string itself */ - XrmoptionStickyArg, /* Value is characters immediately followin -g option */ - XrmoptionSepArg, /* Value is next argument in argv */ - XrmoptionResArg, /* Resource and value in next argument in argv - */ - XrmoptionSkipArg, /* Ignore this option and the next argument i -n argv */ - XrmoptionSkipLine, /* Ignore this option and the rest of argv * -/ - XrmoptionSkipNArgs /* Ignore this option and the next - \ \ \ XrmOptionDescRec.value arguments in argv */ -} XrmOptionKind; - - Note that XrmoptionSkipArg is equivalent to XrmoptionSkipNArgs - with the XrmOptionDescRec.value field containing the value one. - Note also that the value zero for XrmoptionSkipNArgs indicates - that only the option itself is to be skipped. - - - -typedef struct { - char *option; /* Option specification string in argv - */ - char *specifier; /* Binding and resource name (sans application - name) */ - XrmOptionKind argKind; /* Which style of option it is * -/ - XPointer value; /* Value to provide if XrmoptionNoArg or - \ \ \ XrmoptionSkipNArgs */ -} XrmOptionDescRec, *XrmOptionDescList; - - To load a resource database from a C command line, use - XrmParseCommand. - - void XrmParseCommand(XrmDatabase *database, XrmOptionDescList - table, int table_count, char *name, int *argc_in_out, char - **argv_in_out); - - database - - Specifies the resource database. - - table - - Specifies the table of command line arguments to be parsed. - - table_count - - Specifies the number of entries in the table. - - name - - Specifies the application name. - - argc_in_out - - Specifies the number of arguments and returns the number of - remaining arguments. - - argv_in_out - - Specifies the command line arguments and returns the remaining - arguments. - - The XrmParseCommand function parses an (argc, argv) pair - according to the specified option table, loads recognized - options into the specified database with type ``String,'' and - modifies the (argc, argv) pair to remove all recognized - options. If database contains NULL, XrmParseCommand creates a - new database and returns a pointer to it. Otherwise, entries - are added to the database specified. If a database is created, - it is created in the current locale. - - The specified table is used to parse the command line. - Recognized options in the table are removed from argv, and - entries are added to the specified resource database in the - order they occur in argv. The table entries contain information - on the option string, the option name, the style of option, and - a value to provide if the option kind is XrmoptionNoArg. The - option names are compared byte-for-byte to arguments in argv, - independent of any locale. The resource values given in the - table are stored in the resource database without modification. - All resource database entries are created using a ``String'' - representation type. The argc argument specifies the number of - arguments in argv and is set on return to the remaining number - of arguments that were not parsed. The name argument should be - the name of your application for use in building the database - entry. The name argument is prefixed to the resourceName in the - option table before storing a database entry. The name argument - is treated as a single component, even if it has embedded - periods. No separating (binding) character is inserted, so the - table must contain either a period (.) or an asterisk (*) as - the first character in each resourceName entry. To specify a - more completely qualified resource name, the resourceName entry - can contain multiple components. If the name argument and the - resourceNames are not in the Host Portable Character Encoding, - the result is implementation-dependent. - - The following provides a sample option table: - - - -static XrmOptionDescRec opTable[] = { -{"-background", "*background", XrmoptionSepArg, ( -XPointer) NULL}, -{"-bd", "*borderColor", XrmoptionSepArg, ( -XPointer) NULL}, -{"-bg", "*background", XrmoptionSepArg, ( -XPointer) NULL}, -{"-borderwidth", "*TopLevelShell.borderWidth", XrmoptionSepArg, ( -XPointer) NULL}, -{"-bordercolor", "*borderColor", XrmoptionSepArg, ( -XPointer) NULL}, -{"-bw", "*TopLevelShell.borderWidth", XrmoptionSepArg, ( -XPointer) NULL}, -{"-display", ".display", XrmoptionSepArg, ( -XPointer) NULL}, -{"-fg", "*foreground", XrmoptionSepArg, ( -XPointer) NULL}, -{"-fn", "*font", XrmoptionSepArg, ( -XPointer) NULL}, -{"-font", "*font", XrmoptionSepArg, ( -XPointer) NULL}, -{"-foreground", "*foreground", XrmoptionSepArg, ( -XPointer) NULL}, -{"-geometry", ".TopLevelShell.geometry", XrmoptionSepArg, ( -XPointer) NULL}, -{"-iconic", ".TopLevelShell.iconic", XrmoptionNoArg, ( -XPointer) "on"}, -{"-name", ".name", XrmoptionSepArg, ( -XPointer) NULL}, -{"-reverse", "*reverseVideo", XrmoptionNoArg, ( -XPointer) "on"}, -{"-rv", "*reverseVideo", XrmoptionNoArg, ( -XPointer) "on"}, -{"-synchronous", "*synchronous", XrmoptionNoArg, ( -XPointer) "on"}, -{"-title", ".TopLevelShell.title", XrmoptionSepArg, ( -XPointer) NULL}, -{"-xrm", NULL, XrmoptionResArg, ( -XPointer) NULL}, -}; - - In this table, if the -background (or -bg) option is used to - set background colors, the stored resource specifier matches - all resources of attribute background. If the -borderwidth - option is used, the stored resource specifier applies only to - border width attributes of class TopLevelShell (that is, - outer-most windows, including pop-up windows). If the -title - option is used to set a window name, only the topmost - application windows receive the resource. - - When parsing the command line, any unique unambiguous - abbreviation for an option name in the table is considered a - match for the option. Note that uppercase and lowercase matter. - -Chapter 16. Application Utility Functions - - Table of Contents - - Using Keyboard Utility Functions - - KeySym Classification Macros - - Using Latin-1 Keyboard Event Functions - Allocating Permanent Storage - Parsing the Window Geometry - Manipulating Regions - - Creating, Copying, or Destroying Regions - Moving or Shrinking Regions - Computing with Regions - Determining if Regions Are Empty or Equal - Locating a Point or a Rectangle in a Region - - Using Cut Buffers - Determining the Appropriate Visual Type - Manipulating Images - Manipulating Bitmaps - Using the Context Manager - - Once you have initialized the X system, you can use the Xlib - utility functions to: - * Use keyboard utility functions - * Use Latin-1 keyboard event functions - * Allocate permanent storage - * Parse the window geometry - * Manipulate regions - * Use cut buffers - * Determine the appropriate visual type - * Manipulate images - * Manipulate bitmaps - * Use the context manager - - As a group, the functions discussed in this chapter provide the - functionality that is frequently needed and that spans - toolkits. Many of these functions do not generate actual - protocol requests to the server. - -Using Keyboard Utility Functions - - This section discusses mapping between KeyCodes and KeySyms, - classifying KeySyms, and mapping between KeySyms and string - names. The first three functions in this section operate on a - cached copy of the server keyboard mapping. The first four - KeySyms for each KeyCode are modified according to the rules - given in section 12.7. To obtain the untransformed KeySyms - defined for a key, use the functions described in section 12.7. - - To obtain a KeySym for the KeyCode of an event, use - XLookupKeysym. - - KeySym XLookupKeysym(XKeyEvent *key_event, int index); - - key_event - - Specifies the KeyPress or KeyRelease event. - - index - - Specifies the index into the KeySyms list for the event's - KeyCode. - - The XLookupKeysym function uses a given keyboard event and the - index you specified to return the KeySym from the list that - corresponds to the KeyCode member in the XKeyPressedEvent or - XKeyReleasedEvent structure. If no KeySym is defined for the - KeyCode of the event, XLookupKeysym returns NoSymbol. - - To obtain a KeySym for a specific KeyCode, use - XKeycodeToKeysym. - - KeySym XKeycodeToKeysym(Display *display, KeyCode keycode, int - index); - - display - - Specifies the connection to the X server. - - keycode - - Specifies the KeyCode. - - index - - Specifies the element of KeyCode vector. - - The XKeycodeToKeysym function uses internal Xlib tables and - returns the KeySym defined for the specified KeyCode and the - element of the KeyCode vector. If no symbol is defined, - XKeycodeToKeysym returns NoSymbol. - - To obtain a KeyCode for a key having a specific KeySym, use - XKeysymToKeycode. - - KeyCode XKeysymToKeycode(Display *display, KeySym keysym); - - display - - Specifies the connection to the X server. - - keysym - - Specifies the KeySym that is to be searched for. - - If the specified KeySym is not defined for any KeyCode, - XKeysymToKeycode returns zero. - - The mapping between KeyCodes and KeySyms is cached internal to - Xlib. When this information is changed at the server, an Xlib - function must be called to refresh the cache. To refresh the - stored modifier and keymap information, use - XRefreshKeyboardMapping. - - XRefreshKeyboardMapping(XMappingEvent *event_map); - - event_map - - Specifies the mapping event that is to be used. - - The XRefreshKeyboardMapping function refreshes the stored - modifier and keymap information. You usually call this function - when a MappingNotify event with a request member of - MappingKeyboard or MappingModifier occurs. The result is to - update Xlib's knowledge of the keyboard. - - To obtain the uppercase and lowercase forms of a KeySym, use - XConvertCase. - - void XConvertCase(KeySym keysym, KeySym *lower_return, KeySym - *upper_return); - - keysym - - Specifies the KeySym that is to be converted. - - lower_return - - Returns the lowercase form of keysym, or keysym. - - upper_return - - Returns the uppercase form of keysym, or keysym. - - The XConvertCase function returns the uppercase and lowercase - forms of the specified Keysym, if the KeySym is subject to case - conversion; otherwise, the specified KeySym is returned to both - lower_return and upper_return. Support for conversion of other - than Latin and Cyrillic KeySyms is implementation-dependent. - - KeySyms have string names as well as numeric codes. To convert - the name of the KeySym to the KeySym code, use XStringToKeysym. - - KeySym XStringToKeysym(char *string); - - string - - Specifies the name of the KeySym that is to be converted. - - Standard KeySym names are obtained from by - removing the XK_ prefix from each name. KeySyms that are not - part of the Xlib standard also may be obtained with this - function. The set of KeySyms that are available in this manner - and the mechanisms by which Xlib obtains them is - implementation-dependent. - - If the KeySym name is not in the Host Portable Character - Encoding, the result is implementation-dependent. If the - specified string does not match a valid KeySym, XStringToKeysym - returns NoSymbol. - - To convert a KeySym code to the name of the KeySym, use - XKeysymToString. - - char *XKeysymToString(KeySym keysym); - - keysym - - Specifies the KeySym that is to be converted. - - The returned string is in a static area and must not be - modified. The returned string is in the Host Portable Character - Encoding. If the specified KeySym is not defined, - XKeysymToString returns a NULL. - -KeySym Classification Macros - - You may want to test if a KeySym is, for example, on the keypad - or on one of the function keys. You can use KeySym macros to - perform the following tests. - - IsCursorKey(keysym) - - keysym - - Specifies the KeySym that is to be tested. - - Returns True if the specified KeySym is a cursor key. - - IsFunctionKey(keysym) - - keysym - - Specifies the KeySym that is to be tested. - - Returns True if the specified KeySym is a function key. - - IsKeypadKey(keysym) - - keysym - - Specifies the KeySym that is to be tested. - - Returns True if the specified KeySym is a standard keypad key. - - IsPrivateKeypadKey(keysym) - - keysym - - Specifies the KeySym that is to be tested. - - Returns True if the specified KeySym is a vendor-private keypad - key. - - IsMiscFunctionKey(keysym) - - keysym - - Specifies the KeySym that is to be tested. - - Returns True if the specified KeySym is a miscellaneous - function key. - - IsModifierKey(keysym) - - keysym - - Specifies the KeySym that is to be tested. - - Returns True if the specified KeySym is a modifier key. - - IsPFKey(keysym) - - keysym - - Specifies the KeySym that is to be tested. - - Returns True if the specified KeySym is a PF key. - -Using Latin-1 Keyboard Event Functions - - Chapter 13 describes internationalized text input facilities, - but sometimes it is expedient to write an application that only - deals with Latin-1 characters and ASCII controls, so Xlib - provides a simple function for that purpose. XLookupString - handles the standard modifier semantics described in section - 12.7. This function does not use any of the input method - facilities described in chapter 13 and does not depend on the - current locale. - - To map a key event to an ISO Latin-1 string, use XLookupString. - - int XLookupString(XKeyEvent *event_struct, char *buffer_return, - int bytes_buffer, KeySym *keysym_return, XComposeStatus - *status_in_out); - - event_struct - - Specifies the key event structure to be used. You can pass - XKeyPressedEvent or XKeyReleasedEvent. - - buffer_return - - Returns the translated characters. - - bytes_buffer - - Specifies the length of the buffer. No more than bytes_buffer - of translation are returned. - - keysym_return - - Returns the KeySym computed from the event if this argument is - not NULL. - - status_in_out - - Specifies or returns the XComposeStatus structure or NULL. - - The XLookupString function translates a key event to a KeySym - and a string. The KeySym is obtained by using the standard - interpretation of the Shift, Lock, group, and numlock modifiers - as defined in the X Protocol specification. If the KeySym has - been rebound (see XRebindKeysym), the bound string will be - stored in the buffer. Otherwise, the KeySym is mapped, if - possible, to an ISO Latin-1 character or (if the Control - modifier is on) to an ASCII control character, and that - character is stored in the buffer. XLookupString returns the - number of characters that are stored in the buffer. - - If present (non-NULL), the XComposeStatus structure records the - state, which is private to Xlib, that needs preservation across - calls to XLookupString to implement compose processing. The - creation of XComposeStatus structures is - implementation-dependent; a portable program must pass NULL for - this argument. - - XLookupString depends on the cached keyboard information - mentioned in the previous section, so it is necessary to use - XRefreshKeyboardMapping to keep this information up-to-date. - - To rebind the meaning of a KeySym for XLookupString, use - XRebindKeysym. - - XRebindKeysym(Display *display, KeySym keysym, KeySym list[], - int mod_count, unsignedchar *string, int num_bytes); - - display - - Specifies the connection to the X server. - - keysym - - Specifies the KeySym that is to be rebound. - - list - - Specifies the KeySyms to be used as modifiers. - - mod_count - - Specifies the number of modifiers in the modifier list. - - string - - Specifies the string that is copied and will be returned by - XLookupString. - - num_bytes - - Specifies the number of bytes in the string argument. - - The XRebindKeysym function can be used to rebind the meaning of - a KeySym for the client. It does not redefine any key in the X - server but merely provides an easy way for long strings to be - attached to keys. XLookupString returns this string when the - appropriate set of modifier keys are pressed and when the - KeySym would have been used for the translation. No text - conversions are performed; the client is responsible for - supplying appropriately encoded strings. Note that you can - rebind a KeySym that may not exist. - -Allocating Permanent Storage - - To allocate some memory you will never give back, use - Xpermalloc. - - char *Xpermalloc(unsigned int size); - - The Xpermalloc function allocates storage that can never be - freed for the life of the program. The memory is allocated with - alignment for the C type double. This function may provide some - performance and space savings over the standard operating - system memory allocator. - -Parsing the Window Geometry - - To parse standard window geometry strings, use XParseGeometry. - - int XParseGeometry(char *parsestring, int *x_return, int - *y_return, unsigned int *width_return, unsigned int - *height_return); - - parsestring - - Specifies the string you want to parse. - - x_return - - y_return - - Return the x and y offsets. - - width_return - - height_return - - Return the width and height determined. - - By convention, X applications use a standard string to indicate - window size and placement. XParseGeometry makes it easier to - conform to this standard because it allows you to parse the - standard window geometry. Specifically, this function lets you - parse strings of the form: - -[=][{xX}][{+-}{+-}] - - The fields map into the arguments associated with this - function. (Items enclosed in <> are integers, items in [] are - optional, and items enclosed in {} indicate ``choose one of.'' - Note that the brackets should not appear in the actual string.) - If the string is not in the Host Portable Character Encoding, - the result is implementation-dependent. - - The XParseGeometry function returns a bitmask that indicates - which of the four values (width, height, xoffset, and yoffset) - were actually found in the string and whether the x and y - values are negative. By convention, -0 is not equal to +0, - because the user needs to be able to say ``position the window - relative to the right or bottom edge.'' For each value found, - the corresponding argument is updated. For each value not - found, the argument is left unchanged. The bits are represented - by XValue, YValue, WidthValue, HeightValue, XNegative, or - YNegative and are defined in . They will be set - whenever one of the values is defined or one of the signs is - set. - - If the function returns either the XValue or YValue flag, you - should place the window at the requested position. - - To construct a window's geometry information, use XWMGeometry. - - int XWMGeometry(Display *display, int screen, char *user_geom, - char *def_geom, unsigned int bwidth, XSizeHints *hints, int - *x_return, int *y_return, int *width_return, int - *height_return, int *gravity_return); - - display - - Specifies the connection to the X server. - - screen - - Specifies the screen. - - user_geom - - Specifies the user-specified geometry or NULL. - - def_geom - - Specifies the application's default geometry or NULL. - - bwidth - - Specifies the border width. - - hints - - Specifies the size hints for the window in its normal state. - - x_return - - y_return - - Return the x and y offsets. - - width_return - - height_return - - Return the width and height determined. - - gravity_return - - Returns the window gravity. - - The XWMGeometry function combines any geometry information - (given in the format used by XParseGeometry) specified by the - user and by the calling program with size hints (usually the - ones to be stored in WM_NORMAL_HINTS) and returns the position, - size, and gravity (NorthWestGravity, NorthEastGravity, - SouthEastGravity, or SouthWestGravity) that describe the - window. If the base size is not set in the XSizeHints - structure, the minimum size is used if set. Otherwise, a base - size of zero is assumed. If no minimum size is set in the hints - structure, the base size is used. A mask (in the form returned - by XParseGeometry) that describes which values came from the - user specification and whether or not the position coordinates - are relative to the right and bottom edges is returned. Note - that these coordinates will have already been accounted for in - the x_return and y_return values. - - Note that invalid geometry specifications can cause a width or - height of zero to be returned. The caller may pass the address - of the hints win_gravity field as gravity_return to update the - hints directly. - -Manipulating Regions - - Regions are arbitrary sets of pixel locations. Xlib provides - functions for manipulating regions. The opaque type Region is - defined in . Xlib provides functions that you can - use to manipulate regions. This section discusses how to: - * Create, copy, or destroy regions - * Move or shrink regions - * Compute with regions - * Determine if regions are empty or equal - * Locate a point or rectangle in a region - -Creating, Copying, or Destroying Regions - - To create a new empty region, use XCreateRegion. - - Region XCreateRegion(void); - - To generate a region from a polygon, use XPolygonRegion. - - Region XPolygonRegion(XPoint points[], int n, int fill_rule); - - points - - Specifies an array of points. - - n - - Specifies the number of points in the polygon. - - fill_rule - - Specifies the fill-rule you want to set for the specified GC. - You can pass EvenOddRule or WindingRule. - - The XPolygonRegion function returns a region for the polygon - defined by the points array. For an explanation of fill_rule, - see XCreateGC. - - To set the clip-mask of a GC to a region, use XSetRegion. - - XSetRegion(Display *display, GC gc, Region r); - - display - - Specifies the connection to the X server. - - gc - - Specifies the GC. - - r - - Specifies the region. - - The XSetRegion function sets the clip-mask in the GC to the - specified region. The region is specified relative to the - drawable's origin. The resulting GC clip origin is - implementation-dependent. Once it is set in the GC, the region - can be destroyed. - - To deallocate the storage associated with a specified region, - use XDestroyRegion. - - XDestroyRegion(Region r); - - r - - Specifies the region. - -Moving or Shrinking Regions - - To move a region by a specified amount, use XOffsetRegion. - - XOffsetRegion(Region r, int dx, int dy); - - r - - Specifies the region. - - dx - - dy - - Specify the x and y coordinates, which define the amount you - want to move the specified region. - - To reduce a region by a specified amount, use XShrinkRegion. - - XShrinkRegion(Region r, int dx, int dy); - - r - - Specifies the region. - - dx - - dy - - Specify the x and y coordinates, which define the amount you - want to shrink the specified region. - - Positive values shrink the size of the region, and negative - values expand the region. - -Computing with Regions - - To generate the smallest rectangle enclosing a region, use - XClipBox. - - XClipBox(Region r, XRectangle *rect_return); - - r - - Specifies the region. - - rect_return - - Returns the smallest enclosing rectangle. - - The XClipBox function returns the smallest rectangle enclosing - the specified region. - - To compute the intersection of two regions, use - XIntersectRegion. - - XIntersectRegion(Region sra, Region srb, Region dr_return); - - sra - - srb - - Specify the two regions with which you want to perform the - computation. - - dr_return - - Returns the result of the computation. - - To compute the union of two regions, use XUnionRegion. - - XUnionRegion(Region sra, Region srb, Region dr_return); - - sra - - srb - - Specify the two regions with which you want to perform the - computation. - - dr_return - - Returns the result of the computation. - - To create a union of a source region and a rectangle, use - XUnionRectWithRegion. - - XUnionRectWithRegion(XRectangle *rectangle, Region src_region, - Region dest_region_return); - - rectangle - - Specifies the rectangle. - - src_region - - Specifies the source region to be used. - - dest_region_return - - Returns the destination region. - - The XUnionRectWithRegion function updates the destination - region from a union of the specified rectangle and the - specified source region. - - To subtract two regions, use XSubtractRegion. - - XSubtractRegion(Region sra, Region srb, Region dr_return); - - sra - - srb - - Specify the two regions with which you want to perform the - computation. - - dr_return - - Returns the result of the computation. - - The XSubtractRegion function subtracts srb from sra and stores - the results in dr_return. - - To calculate the difference between the union and intersection - of two regions, use XXorRegion. - - XXorRegion(Region sra, Region srb, Region dr_return); - - sra - - srb - - Specify the two regions with which you want to perform the - computation. - - dr_return - - Returns the result of the computation. - -Determining if Regions Are Empty or Equal - - To determine if the specified region is empty, use - XEmptyRegion. - - Bool XEmptyRegion(Region r); - - r - - Specifies the region. - - The XEmptyRegion function returns True if the region is empty. - - To determine if two regions have the same offset, size, and - shape, use XEqualRegion. - - Bool XEqualRegion(Region r1, Region r2); - - r1 - - r2 - - Specify the two regions. - - The XEqualRegion function returns True if the two regions have - the same offset, size, and shape. - -Locating a Point or a Rectangle in a Region - - To determine if a specified point resides in a specified - region, use XPointInRegion. - - Bool XPointInRegion(Region r, int x, int y); - - r - - Specifies the region. - - x - - y - - Specify the x and y coordinates, which define the point. - - The XPointInRegion function returns True if the point (x, y) is - contained in the region r. - - To determine if a specified rectangle is inside a region, use - XRectInRegion. - - int XRectInRegion(Region r, int x, int y, unsigned int width, - unsigned int height); - - r - - Specifies the region. - - x - - y - - Specify the x and y coordinates, which define the coordinates - of the upper-left corner of the rectangle. - - width - - height - - Specify the width and height, which define the rectangle. - - The XRectInRegion function returns RectangleIn if the rectangle - is entirely in the specified region, RectangleOut if the - rectangle is entirely out of the specified region, and - RectanglePart if the rectangle is partially in the specified - region. - -Using Cut Buffers - - Xlib provides functions to manipulate cut buffers, a very - simple form of cut-and-paste inter-client communication. - Selections are a much more powerful and useful mechanism for - interchanging data between client (see section 4.5) and - generally should be used instead of cut buffers. - - Cut buffers are implemented as properties on the first root - window of the display. The buffers can only contain text, in - the STRING encoding. The text encoding is not changed by Xlib - when fetching or storing. Eight buffers are provided and can be - accessed as a ring or as explicit buffers (numbered 0 through - 7). - - To store data in cut buffer 0, use XStoreBytes. - - XStoreBytes(Display *display, char *bytes, int nbytes); - - display - - Specifies the connection to the X server. - - bytes - - Specifies the bytes, which are not necessarily ASCII or - null-terminated. - - nbytes - - Specifies the number of bytes to be stored. - - The data can have embedded null characters and need not be - null-terminated. The cut buffer's contents can be retrieved - later by any client calling XFetchBytes. - - XStoreBytes can generate a BadAlloc error. - - To store data in a specified cut buffer, use XStoreBuffer. - - XStoreBuffer(Display *display, char *bytes, int nbytes, int - buffer); - - display - - Specifies the connection to the X server. - - bytes - - Specifies the bytes, which are not necessarily ASCII or - null-terminated. - - nbytes - - Specifies the number of bytes to be stored. - - buffer - - Specifies the buffer in which you want to store the bytes. - - If an invalid buffer is specified, the call has no effect. The - data can have embedded null characters and need not be - null-terminated. - - XStoreBuffer can generate a BadAlloc error. - - To return data from cut buffer 0, use XFetchBytes. - - char *XFetchBytes(Display *display, int *nbytes_return); - - display - - Specifies the connection to the X server. - - nbytes_return - - Returns the number of bytes in the buffer. - - The XFetchBytes function returns the number of bytes in the - nbytes_return argument, if the buffer contains data. Otherwise, - the function returns NULL and sets nbytes to 0. The appropriate - amount of storage is allocated and the pointer returned. The - client must free this storage when finished with it by calling - XFree. - - To return data from a specified cut buffer, use XFetchBuffer. - - char *XFetchBuffer(Display *display, int *nbytes_return, int - buffer); - - display - - Specifies the connection to the X server. - - nbytes_return - - Returns the number of bytes in the buffer. - - buffer - - Specifies the buffer from which you want the stored data - returned. - - The XFetchBuffer function returns zero to the nbytes_return - argument if there is no data in the buffer or if an invalid - buffer is specified. - - To rotate the cut buffers, use XRotateBuffers. - - XRotateBuffers(Display *display, int rotate); - - display - - Specifies the connection to the X server. - - rotate - - Specifies how much to rotate the cut buffers. - - The XRotateBuffers function rotates the cut buffers, such that - buffer 0 becomes buffer n, buffer 1 becomes n + 1 mod 8, and so - on. This cut buffer numbering is global to the display. Note - that XRotateBuffers generates BadMatch errors if any of the - eight buffers have not been created. - -Determining the Appropriate Visual Type - - A single display can support multiple screens. Each screen can - have several different visual types supported at different - depths. You can use the functions described in this section to - determine which visual to use for your application. - - The functions in this section use the visual information masks - and the XVisualInfo structure, which is defined in - and contains: - -/* Visual information mask bits */ - - -#define VisualNoMask 0x0 -#define VisualIDMask 0x1 -#define VisualScreenMask 0x2 -#define VisualDepthMask 0x4 -#define VisualClassMask 0x8 -#define VisualRedMaskMask 0x10 -#define VisualGreenMaskMask 0x20 -#define VisualBlueMaskMask 0x40 -#define VisualColormapSizeMask 0x80 -#define VisualBitsPerRGBMask 0x100 -#define VisualAllMask 0x1FF - - - - -/* Values */ - -typedef struct { - Visual *visual; - VisualID visualid; - int screen; - unsigned int depth; - int class; - unsigned long red_mask; - unsigned long green_mask; - unsigned long blue_mask; - int colormap_size; - int bits_per_rgb; -} XVisualInfo; - - To obtain a list of visual information structures that match a - specified template, use XGetVisualInfo. - - XVisualInfo *XGetVisualInfo(Display *display, long vinfo_mask, - XVisualInfo *vinfo_template, int *nitems_return); - - display - - Specifies the connection to the X server. - - vinfo_mask - - Specifies the visual mask value. - - vinfo_template - - Specifies the visual attributes that are to be used in matching - the visual structures. - - nitems_return - - Returns the number of matching visual structures. - - The XGetVisualInfo function returns a list of visual structures - that have attributes equal to the attributes specified by - vinfo_template. If no visual structures match the template - using the specified vinfo_mask, XGetVisualInfo returns a NULL. - To free the data returned by this function, use XFree. - - To obtain the visual information that matches the specified - depth and class of the screen, use XMatchVisualInfo. - - Status XMatchVisualInfo(Display *display, int screen, int - depth, int class, XVisualInfo *vinfo_return); - - display - - Specifies the connection to the X server. - - screen - - Specifies the screen. - - depth - - Specifies the depth of the screen. - - class - - Specifies the class of the screen. - - vinfo_return - - Returns the matched visual information. - - The XMatchVisualInfo function returns the visual information - for a visual that matches the specified depth and class for a - screen. Because multiple visuals that match the specified depth - and class can exist, the exact visual chosen is undefined. If a - visual is found, XMatchVisualInfo returns nonzero and the - information on the visual to vinfo_return. Otherwise, when a - visual is not found, XMatchVisualInfo returns zero. - -Manipulating Images - - Xlib provides several functions that perform basic operations - on images. All operations on images are defined using an XImage - structure, as defined in . Because the number of - different types of image formats can be very large, this hides - details of image storage properly from applications. - - This section describes the functions for generic operations on - images. Manufacturers can provide very fast implementations of - these for the formats frequently encountered on their hardware. - These functions are neither sufficient nor desirable to use for - general image processing. Rather, they are here to provide - minimal functions on screen format images. The basic operations - for getting and putting images are XGetImage and XPutImage. - - Note that no functions have been defined, as yet, to read and - write images to and from disk files. - - The XImage structure describes an image as it exists in the - client's memory. The user can request that some of the members - such as height, width, and xoffset be changed when the image is - sent to the server. Note that bytes_per_line in concert with - offset can be used to extract a subset of the image. Other - members (for example, byte order, bitmap_unit, and so forth) - are characteristics of both the image and the server. If these - members differ between the image and the server, XPutImage - makes the appropriate conversions. The first byte of the first - line of plane n must be located at the address (data + (n * - height * bytes_per_line)). For a description of the XImage - structure, see section 8.7. - - To allocate an XImage structure and initialize it with image - format values from a display, use XCreateImage. - - XImage *XCreateImage(Display *display, Visual *visual, unsigned - int depth, int format, int offset, char *data, unsigned int - width, unsigned int height, int bitmap_pad, int - bytes_per_line); - - display - - Specifies the connection to the X server. - - visual - - Specifies the Visual structure. - - depth - - Specifies the depth of the image. - - format - - Specifies the format for the image. You can pass XYBitmap, - XYPixmap, or ZPixmap. - - offset - - Specifies the number of pixels to ignore at the beginning of - the scanline. - - data - - Specifies the image data. - - width - - Specifies the width of the image, in pixels. - - height - - Specifies the height of the image, in pixels. - - bitmap_pad - - Specifies the quantum of a scanline (8, 16, or 32). In other - words, the start of one scanline is separated in client memory - from the start of the next scanline by an integer multiple of - this many bits. - - bytes_per_line - - Specifies the number of bytes in the client image between the - start of one scanline and the start of the next. - - The XCreateImage function allocates the memory needed for an - XImage structure for the specified display but does not - allocate space for the image itself. Rather, it initializes the - structure byte-order, bit-order, and bitmap-unit values from - the display and returns a pointer to the XImage structure. The - red, green, and blue mask values are defined for Z format - images only and are derived from the Visual structure passed - in. Other values also are passed in. The offset permits the - rapid displaying of the image without requiring each scanline - to be shifted into position. If you pass a zero value in - bytes_per_line, Xlib assumes that the scanlines are contiguous - in memory and calculates the value of bytes_per_line itself. - - Note that when the image is created using XCreateImage, - XGetImage, or XSubImage, the destroy procedure that the - XDestroyImage function calls frees both the image structure and - the data pointed to by the image structure. - - The basic functions used to get a pixel, set a pixel, create a - subimage, and add a constant value to an image are defined in - the image object. The functions in this section are really - macro invocations of the functions in the image object and are - defined in . - - To obtain a pixel value in an image, use XGetPixel. - - unsigned long XGetPixel(XImage *ximage, int x, int y); - - ximage - - Specifies the image. - - x - - y - - Specify the x and y coordinates. - - The XGetPixel function returns the specified pixel from the - named image. The pixel value is returned in normalized format - (that is, the least significant byte of the long is the least - significant byte of the pixel). The image must contain the x - and y coordinates. - - To set a pixel value in an image, use XPutPixel. - - XPutPixel(XImage *ximage, int x, int y, unsigned long pixel); - - ximage - - Specifies the image. - - x - - y - - Specify the x and y coordinates. - - pixel - - Specifies the new pixel value. - - The XPutPixel function overwrites the pixel in the named image - with the specified pixel value. The input pixel value must be - in normalized format (that is, the least significant byte of - the long is the least significant byte of the pixel). The image - must contain the x and y coordinates. - - To create a subimage, use XSubImage. - - XImage *XSubImage(XImage *ximage, int x, int y, unsigned int - subimage_width, unsigned int subimage_height); - - ximage - - Specifies the image. - - x - - y - - Specify the x and y coordinates. - - subimage_width - - Specifies the width of the new subimage, in pixels. - - subimage_height - - Specifies the height of the new subimage, in pixels. - - The XSubImage function creates a new image that is a subsection - of an existing one. It allocates the memory necessary for the - new XImage structure and returns a pointer to the new image. - The data is copied from the source image, and the image must - contain the rectangle defined by x, y, subimage_width, and - subimage_height. - - To increment each pixel in an image by a constant value, use - XAddPixel. - - XAddPixel(XImage *ximage, long value); - - ximage - - Specifies the image. - - value - - Specifies the constant value that is to be added. - - The XAddPixel function adds a constant value to every pixel in - an image. It is useful when you have a base pixel value from - allocating color resources and need to manipulate the image to - that form. - - To deallocate the memory allocated in a previous call to - XCreateImage, use XDestroyImage. - - XDestroyImage(XImage *ximage); - - ximage - - Specifies the image. - - The XDestroyImage function deallocates the memory associated - with the XImage structure. - - Note that when the image is created using XCreateImage, - XGetImage, or XSubImage, the destroy procedure that this macro - calls frees both the image structure and the data pointed to by - the image structure. - -Manipulating Bitmaps - - Xlib provides functions that you can use to read a bitmap from - a file, save a bitmap to a file, or create a bitmap. This - section describes those functions that transfer bitmaps to and - from the client's file system, thus allowing their reuse in a - later connection (for example, from an entirely different - client or to a different display or server). - - The X version 11 bitmap file format is: - -#define name_width width -#define name_height height -#define name_x_hot x -#define name_y_hot y -static unsigned char name_bits[] = { 0xNN,... } - - The lines for the variables ending with _x_hot and _y_hot - suffixes are optional because they are present only if a - hotspot has been defined for this bitmap. The lines for the - other variables are required. The word ``unsigned'' is - optional; that is, the type of the _bits array can be ``char'' - or ``unsigned char''. The _bits array must be large enough to - contain the size bitmap. The bitmap unit is 8. - - To read a bitmap from a file and store it in a pixmap, use - XReadBitmapFile. - - int XReadBitmapFile(Display *display, Drawable d, char - *filename, unsigned int *width_return, unsigned int - *height_return, Pixmap *bitmap_return, int *x_hot_return, int - *y_hot_return); - - display - - Specifies the connection to the X server. - - d - - Specifies the drawable that indicates the screen. - - filename - - Specifies the file name to use. The format of the file name is - operating-system dependent. - - width_return - - height_return - - Return the width and height values of the read in bitmap file. - - bitmap_return - - Returns the bitmap that is created. - - x_hot_return - - y_hot_return - - Return the hotspot coordinates. - - The XReadBitmapFile function reads in a file containing a - bitmap. The file is parsed in the encoding of the current - locale. The ability to read other than the standard format is - implementation-dependent. If the file cannot be opened, - XReadBitmapFile returns BitmapOpenFailed. If the file can be - opened but does not contain valid bitmap data, it returns - BitmapFileInvalid. If insufficient working storage is - allocated, it returns BitmapNoMemory. If the file is readable - and valid, it returns BitmapSuccess. - - XReadBitmapFile returns the bitmap's height and width, as read - from the file, to width_return and height_return. It then - creates a pixmap of the appropriate size, reads the bitmap data - from the file into the pixmap, and assigns the pixmap to the - caller's variable bitmap. The caller must free the bitmap using - XFreePixmap when finished. If name_x_hot and name_y_hot exist, - XReadBitmapFile returns them to x_hot_return and y_hot_return; - otherwise, it returns -1,-1. - - XReadBitmapFile can generate BadAlloc, BadDrawable, and BadGC - errors. - - To read a bitmap from a file and return it as data, use - XReadBitmapFileData. - - int XReadBitmapFileData(char *filename, unsigned int - *width_return, unsigned int *height_return, unsignedchar - *data_return, int *x_hot_return, int *y_hot_return); - - filename - - Specifies the file name to use. The format of the file name is - operating-system dependent. - - width_return - - height_return - - Return the width and height values of the read in bitmap file. - - data_return - - Returns the bitmap data. - - x_hot_return - - y_hot_return - - Return the hotspot coordinates. - - The XReadBitmapFileData function reads in a file containing a - bitmap, in the same manner as XReadBitmapFile, but returns the - data directly rather than creating a pixmap in the server. The - bitmap data is returned in data_return; the client must free - this storage when finished with it by calling XFree. The status - and other return values are the same as for XReadBitmapFile. - - To write out a bitmap from a pixmap to a file, use - XWriteBitmapFile. - - int XWriteBitmapFile(Display *display, char *filename, Pixmap - bitmap, unsigned int width, unsigned int height, int x_hot, int - y_hot); - - display - - Specifies the connection to the X server. - - filename - - Specifies the file name to use. The format of the file name is - operating-system dependent. - - bitmap - - Specifies the bitmap. - - width - - height - - Specify the width and height. - - x_hot - - y_hot - - Specify where to place the hotspot coordinates (or -1,-1 if - none are present) in the file. - - The XWriteBitmapFile function writes a bitmap out to a file in - the X Version 11 format. The name used in the output file is - derived from the file name by deleting the directory prefix. - The file is written in the encoding of the current locale. If - the file cannot be opened for writing, it returns - BitmapOpenFailed. If insufficient memory is allocated, - XWriteBitmapFile returns BitmapNoMemory; otherwise, on no - error, it returns BitmapSuccess. If x_hot and y_hot are not -1, - -1, XWriteBitmapFile writes them out as the hotspot coordinates - for the bitmap. - - XWriteBitmapFile can generate BadDrawable and BadMatch errors. - - To create a pixmap and then store bitmap-format data into it, - use XCreatePixmapFromBitmapData. - - Pixmap XCreatePixmapFromBitmapData(Display *display, Drawable - d, char *data, unsigned int width, unsigned int height, - unsigned long fg, unsigned long bg, unsigned int depth); - - display - - Specifies the connection to the X server. - - d - - Specifies the drawable that indicates the screen. - - data - - Specifies the data in bitmap format. - - width - - height - - Specify the width and height. - - fg - - bg - - Specify the foreground and background pixel values to use. - - depth - - Specifies the depth of the pixmap. - - The XCreatePixmapFromBitmapData function creates a pixmap of - the given depth and then does a bitmap-format XPutImage of the - data into it. The depth must be supported by the screen of the - specified drawable, or a BadMatch error results. - - XCreatePixmapFromBitmapData can generate BadAlloc, BadDrawable, - BadGC, and BadValue errors. - - To include a bitmap written out by XWriteBitmapFile in a - program directly, as opposed to reading it in every time at run - time, use XCreateBitmapFromData. - - Pixmap XCreateBitmapFromData(Display *display, Drawable d, char - *data, unsigned int width, unsigned int height); - - display - - Specifies the connection to the X server. - - d - - Specifies the drawable that indicates the screen. - - data - - Specifies the location of the bitmap data. - - width - - height - - Specify the width and height. - - The XCreateBitmapFromData function allows you to include in - your C program (using #include) a bitmap file that was written - out by XWriteBitmapFile (X version 11 format only) without - reading in the bitmap file. The following example creates a - gray bitmap: - -#include "gray.bitmap" - -Pixmap bitmap; -bitmap = XCreateBitmapFromData(display, window, gray_bits, gray_width, g -ray_height); - - If insufficient working storage was allocated, - XCreateBitmapFromData returns None. It is your responsibility - to free the bitmap using XFreePixmap when finished. - - XCreateBitmapFromData can generate BadAlloc and BadGC errors. - -Using the Context Manager - - The context manager provides a way of associating data with an - X resource ID (mostly typically a window) in your program. Note - that this is local to your program; the data is not stored in - the server on a property list. Any amount of data in any number - of pieces can be associated with a resource ID, and each piece - of data has a type associated with it. The context manager - requires knowledge of the resource ID and type to store or - retrieve data. - - Essentially, the context manager can be viewed as a - two-dimensional, sparse array: one dimension is subscripted by - the X resource ID and the other by a context type field. Each - entry in the array contains a pointer to the data. Xlib - provides context management functions with which you can save - data values, get data values, delete entries, and create a - unique context type. The symbols used are in . - - To save a data value that corresponds to a resource ID and - context type, use XSaveContext. - - int XSaveContext(Display *display, XID rid, XContext context, - XPointer data); - - display - - Specifies the connection to the X server. - - rid - - Specifies the resource ID with which the data is associated. - - context - - Specifies the context type to which the data belongs. - - data - - Specifies the data to be associated with the window and type. - - If an entry with the specified resource ID and type already - exists, XSaveContext overrides it with the specified context. - The XSaveContext function returns a nonzero error code if an - error has occurred and zero otherwise. Possible errors are - XCNOMEM (out of memory). - - To get the data associated with a resource ID and type, use - XFindContext. - - int XFindContext(Display *display, XID rid, XContext context, - XPointer *data_return); - - display - - Specifies the connection to the X server. - - rid - - Specifies the resource ID with which the data is associated. - - context - - Specifies the context type to which the data belongs. - - data_return - - Returns the data. - - Because it is a return value, the data is a pointer. The - XFindContext function returns a nonzero error code if an error - has occurred and zero otherwise. Possible errors are XCNOENT - (context-not-found). - - To delete an entry for a given resource ID and type, use - XDeleteContext. - - int XDeleteContext(Display *display, XID rid, XContext - context); - - display - - Specifies the connection to the X server. - - rid - - Specifies the resource ID with which the data is associated. - - context - - Specifies the context type to which the data belongs. - - The XDeleteContext function deletes the entry for the given - resource ID and type from the data structure. This function - returns the same error codes that XFindContext returns if - called with the same arguments. XDeleteContext does not free - the data whose address was saved. - - To create a unique context type that may be used in subsequent - calls to XSaveContext and XFindContext, use XUniqueContext. - - XContext XUniqueContext(void); - -Appendix A. Xlib Functions and Protocol Requests - - This appendix provides two tables that relate to Xlib functions - and the X protocol. The following table lists each Xlib - function (in alphabetical order) and the corresponding protocol - request that it generates. - - Table A.1. Protocol requests made by each Xlib function - Xlib Function Protocol Request - XActivateScreenSaver ForceScreenSaver - XAddHost ChangeHosts - XAddHosts ChangeHosts - XAddToSaveSet ChangeSaveSet - XAllocColor AllocColor - XAllocColorCells AllocColorCells - XAllocColorPlanes AllocColorPlanes - XAllocNamedColor AllocNamedColor - XAllowEvents AllowEvents - XAutoRepeatOff ChangeKeyboardControl - XAutoRepeatOn ChangeKeyboardControl - XBell Bell - XChangeActivePointerGrab ChangeActivePointerGrab - XChangeGC ChangeGC - XChangeKeyboardControl ChangeKeyboardControl - XChangeKeyboardMapping ChangeKeyboardMapping - XChangePointerControl ChangePointerControl - XChangeProperty ChangeProperty - XChangeSaveSet ChangeSaveSet - XChangeWindowAttributes ChangeWindowAttributes - XCirculateSubwindows CirculateWindow - XCirculateSubwindowsDown CirculateWindow - XCirculateSubwindowsUp CirculateWindow - XClearArea ClearArea - XClearWindow ClearArea - XConfigureWindow ConfigureWindow - XConvertSelection ConvertSelection - XCopyArea CopyArea - XCopyColormapAndFree CopyColormapAndFree - XCopyGC CopyGC - XCopyPlane CopyPlane - XCreateBitmapFromData CreateGC - CreatePixmap - FreeGC - PutImage - XCreateColormap CreateColormap - XCreateFontCursor CreateGlyphCursor - XCreateGC CreateGC - XCreateGlyphCursor CreateGlyphCursor - XCreatePixmap CreatePixmap - XCreatePixmapCursor CreateCursor - XCreatePixmapFromData CreateGC - CreatePixmap - FreeGC - PutImage - XCreateSimpleWindow CreateWindow - XCreateWindow CreateWindow - XDefineCursor ChangeWindowAttributes - XDeleteProperty DeleteProperty - XDestroySubwindows DestroySubwindows - XDestroyWindow DestroyWindow - XDisableAccessControl SetAccessControl - XDrawArc PolyArc - XDrawArcs PolyArc - XDrawImageString ImageText8 - XDrawImageString16 ImageText16 - XDrawLine PolySegment - XDrawLines PolyLine - XDrawPoint PolyPoint - XDrawPoints PolyPoint - XDrawRectangle PolyRectangle - XDrawRectangles PolyRectangle - XDrawSegments PolySegment - XDrawString PolyText8 - XDrawString16 PolyText16 - XDrawText PolyText8 - XDrawText16 PolyText16 - XEnableAccessControl SetAccessControl - XFetchBytes GetProperty - XFetchName GetProperty - XFillArc PolyFillArc - XFillArcs PolyFillArc - XFillPolygon FillPoly - XFillRectangle PolyFillRectangle - XFillRectangles PolyFillRectangle - XForceScreenSaver ForceScreenSaver - XFreeColormap FreeColormap - XFreeColors FreeColors - XFreeCursor FreeCursor - XFreeFont CloseFont - XFreeGC FreeGC - XFreePixmap FreePixmap - XGetAtomName GetAtomName - XGetClassHint GetProperty - XGetFontPath GetFontPath - XGetGeometry GetGeometry - XGetIconName GetProperty - XGetIconSizes GetProperty - XGetImage GetImage - XGetInputFocus GetInputFocus - XGetKeyboardControl GetKeyboardControl - XGetKeyboardMapping GetKeyboardMapping - XGetModifierMapping GetModifierMapping - GetMotionEvents - XGetNormalHints GetProperty - XGetPointerControl GetPointerControl - XGetPointerMapping GetPointerMapping - XGetRGBColormaps GetProperty - XGetScreenSaver GetScreenSaver - XGetSelectionOwner GetSelectionOwner - XGetSizeHints GetProperty - XGetTextProperty GetProperty - XGetTransientForHint GetProperty - XGetWMClientMachine GetProperty - XGetWMColormapWindows GetProperty - InternAtom - XGetWMHints GetProperty - XGetWMIconName GetProperty - XGetWMName GetProperty - XGetWMNormalHints GetProperty - XGetWMProtocols GetProperty - InternAtom - XGetWMSizeHints GetProperty - XGetWindowAttributes GetWindowAttributes - GetGeometry - XGetWindowProperty GetProperty - XGetZoomHints GetProperty - XGrabButton GrabButton - XGrabKey GrabKey - XGrabKeyboard GrabKeyboard - XGrabPointer GrabPointer - XGrabServer GrabServer - XIconifyWindow InternAtom - SendEvent - XInitExtension QueryExtension - XInstallColormap InstallColormap - XInternAtom InternAtom - XKillClient KillClient - XListExtensions ListExtensions - XListFonts ListFonts - XListFontsWithInfo ListFontsWithInfo - XListHosts ListHosts - XListInstalledColormaps ListInstalledColormaps - XListProperties ListProperties - XLoadFont OpenFont - XLoadQueryFont OpenFont - QueryFont - XLookupColor LookupColor - XLowerWindow ConfigureWindow - XMapRaised ConfigureWindow - MapWindow - XMapSubwindows MapSubwindows - XMapWindow MapWindow - XMoveResizeWindow ConfigureWindow - XMoveWindow ConfigureWindow - XNoOp NoOperation - XOpenDisplay CreateGC - XParseColor LookupColor - XPutImage PutImage - XQueryBestCursor QueryBestSize - XQueryBestSize QueryBestSize - XQueryBestStipple QueryBestSize - XQueryBestTile QueryBestSize - XQueryColor QueryColors - XQueryColors QueryColors - XQueryExtension QueryExtension - XQueryFont QueryFont - XQueryKeymap QueryKeymap - XQueryPointer QueryPointer - XQueryTextExtents QueryTextExtents - XQueryTextExtents16 QueryTextExtents - XQueryTree QueryTree - XRaiseWindow ConfigureWindow - XReadBitmapFile CreateGC - CreatePixmap - FreeGC - PutImage - XRecolorCursor RecolorCursor - XReconfigureWMWindow ConfigureWindow - SendEvent - XRemoveFromSaveSet ChangeSaveSet - XRemoveHost ChangeHosts - XRemoveHosts ChangeHosts - XReparentWindow ReparentWindow - XResetScreenSaver ForceScreenSaver - XResizeWindow ConfigureWindow - XRestackWindows ConfigureWindow - XRotateBuffers RotateProperties - XRotateWindowProperties RotateProperties - XSelectInput ChangeWindowAttributes - XSendEvent SendEvent - XSetAccessControl SetAccessControl - XSetArcMode ChangeGC - XSetBackground ChangeGC - XSetClassHint ChangeProperty - XSetClipMask ChangeGC - XSetClipOrigin ChangeGC - XSetClipRectangles SetClipRectangles - XSetCloseDownMode SetCloseDownMode - XSetCommand ChangeProperty - XSetDashes SetDashes - XSetFillRule ChangeGC - XSetFillStyle ChangeGC - XSetFont ChangeGC - XSetFontPath SetFontPath - XSetForeground ChangeGC - XSetFunction ChangeGC - XSetGraphicsExposures ChangeGC - XSetIconName ChangeProperty - XSetIconSizes ChangeProperty - XSetInputFocus SetInputFocus - XSetLineAttributes ChangeGC - XSetModifierMapping SetModifierMapping - XSetNormalHints ChangeProperty - XSetPlaneMask ChangeGC - XSetPointerMapping SetPointerMapping - XSetRGBColormaps ChangeProperty - XSetScreenSaver SetScreenSaver - XSetSelectionOwner SetSelectionOwner - XSetSizeHints ChangeProperty - XSetStandardProperties ChangeProperty - XSetState ChangeGC - XSetStipple ChangeGC - XSetSubwindowMode ChangeGC - XSetTextProperty ChangeProperty - XSetTile ChangeGC - XSetTransientForHint ChangeProperty - XSetTSOrigin ChangeGC - XSetWMClientMachine ChangeProperty - XSetWMColormapWindows ChangeProperty - InternAtom - XSetWMHints ChangeProperty - XSetWMIconName ChangeProperty - XSetWMName ChangeProperty - XSetWMNormalHints ChangeProperty - XSetWMProperties ChangeProperty - XSetWMProtocols ChangeProperty - InternAtom - XSetWMSizeHints ChangeProperty - XSetWindowBackground ChangeWindowAttributes - XSetWindowBackgroundPixmap ChangeWindowAttributes - XSetWindowBorder ChangeWindowAttributes - XSetWindowBorderPixmap ChangeWindowAttributes - XSetWindowBorderWidth ConfigureWindow - XSetWindowColormap ChangeWindowAttributes - XSetZoomHints ChangeProperty - XStoreBuffer ChangeProperty - XStoreBytes ChangeProperty - XStoreColor StoreColors - XStoreColors StoreColors - XStoreName ChangeProperty - XStoreNamedColor StoreNamedColor - XSync GetInputFocus - XSynchronize GetInputFocus - XTranslateCoordinates TranslateCoordinates - XUndefineCursor ChangeWindowAttributes - XUngrabButton UngrabButton - XUngrabKey UngrabKey - XUngrabKeyboard UngrabKeyboard - XUngrabPointer UngrabPointer - XUngrabServer UngrabServer - XUninstallColormap UninstallColormap - XUnloadFont CloseFont - XUnmapSubwindows UnmapSubwindows - XUnmapWindow UnmapWindow - XWarpPointer WarpPointer - XWithdrawWindow SendEvent - UnmapWindow - - The following table lists each X protocol request (in - alphabetical order) and the Xlib functions that reference it. - - Table A.2. Xlib functions which use each Protocol Request - Protocol Request Xlib Function - AllocColor XAllocColor - AllocColorCells XAllocColorCells - AllocColorPlanes XAllocColorPlanes - AllocNamedColor XAllocNamedColor - AllowEvents XAllowEvents - Bell XBell - ChangeActivePointerGrab XChangeActivePointerGrab - ChangeGC XChangeGC - XSetArcMode - XSetBackground - XSetClipMask - XSetClipOrigin - XSetFillRule - XSetFillStyle - XSetFont - XSetForeground - XSetFunction - XSetGraphicsExposures - XSetLineAttributes - XSetPlaneMask - XSetState - XSetStipple - XSetSubwindowMode - XSetTile - XSetTSOrigin - ChangeHosts XAddHost - XAddHosts - XRemoveHost - XRemoveHosts - ChangeKeyboardControl XAutoRepeatOff - XAutoRepeatOn - XChangeKeyboardControl - ChangeKeyboardMapping XChangeKeyboardMapping - ChangePointerControl XChangePointerControl - ChangeProperty XChangeProperty - XSetClassHint - XSetCommand - XSetIconName - XSetIconSizes - XSetNormalHints - XSetRGBColormaps - XSetSizeHints - XSetStandardProperties - XSetTextProperty - XSetTransientForHint - XSetWMClientMachine - XSetWMColormapWindows - XSetWMHints - XSetWMIconName - XSetWMName - XSetWMNormalHints - XSetWMProperties - XSetWMProtocols - XSetWMSizeHints - XSetZoomHints - XStoreBuffer - XStoreBytes - XStoreName - ChangeSaveSet XAddToSaveSet - XChangeSaveSet - XRemoveFromSaveSet - ChangeWindowAttributes XChangeWindowAttributes - XDefineCursor - XSelectInput - XSetWindowBackground - XSetWindowBackgroundPixmap - XSetWindowBorder - XSetWindowBorderPixmap - XSetWindowColormap - XUndefineCursor - CirculateWindow XCirculateSubwindowsDown - XCirculateSubwindowsUp - XCirculateSubwindows - ClearArea XClearArea - XClearWindow - CloseFont XFreeFont - XUnloadFont - ConfigureWindow XConfigureWindow - XLowerWindow - XMapRaised - XMoveResizeWindow - XMoveWindow - XRaiseWindow - XReconfigureWMWindow - XResizeWindow - XRestackWindows - XSetWindowBorderWidth - ConvertSelection XConvertSelection - CopyArea XCopyArea - CopyColormapAndFree XCopyColormapAndFree - CopyGC XCopyGC - CopyPlane XCopyPlane - CreateColormap XCreateColormap - CreateCursor XCreatePixmapCursor - CreateGC XCreateGC - XCreateBitmapFromData - XCreatePixmapFromData - XOpenDisplay - XReadBitmapFile - CreateGlyphCursor XCreateFontCursor - XCreateGlyphCursor - CreatePixmap XCreatePixmap - XCreateBitmapFromData - XCreatePixmapFromData - XReadBitmapFile - CreateWindow XCreateSimpleWindow - XCreateWindow - DeleteProperty XDeleteProperty - DestroySubwindows XDestroySubwindows - DestroyWindow XDestroyWindow - FillPoly XFillPolygon - ForceScreenSaver XActivateScreenSaver - XForceScreenSaver - XResetScreenSaver - FreeColormap XFreeColormap - FreeColors XFreeColors - FreeCursor XFreeCursor - FreeGC XFreeGC - XCreateBitmapFromData - XCreatePixmapFromData - XReadBitmapFile - FreePixmap XFreePixmap - GetAtomName XGetAtomName - GetFontPath XGetFontPath - GetGeometry XGetGeometry - XGetWindowAttributes - GetImage XGetImage - GetInputFocus XGetInputFocus - XSync - XSynchronize - GetKeyboardControl XGetKeyboardControl - GetKeyboardMapping XGetKeyboardMapping - GetModifierMapping XGetModifierMapping - GetMotionEvents - GetPointerControl XGetPointerControl - GetPointerMapping XGetPointerMapping - GetProperty XFetchBytes - XFetchName - XGetClassHint - XGetIconName - XGetIconSizes - XGetNormalHints - XGetRGBColormaps - XGetSizeHints - XGetTextProperty - XGetTransientForHint - XGetWMClientMachine - XGetWMColormapWindows - XGetWMHints - XGetWMIconName - XGetWMName - XGetWMNormalHints - XGetWMProtocols - XGetWMSizeHints - XGetWindowProperty - XGetZoomHints - GetSelectionOwner XGetSelectionOwner - GetWindowAttributes XGetWindowAttributes - GrabButton XGrabButton - GrabKey XGrabKey - GrabKeyboard XGrabKeyboard - GrabPointer XGrabPointer - GrabServer XGrabServer - ImageText8 XDrawImageString - ImageText16 XDrawImageString16 - InstallColormap XInstallColormap - InternAtom XGetWMColormapWindows - XGetWMProtocols - XIconifyWindow - XInternAtom - XSetWMColormapWindows - XSetWMProtocols - KillClient XKillClient - ListExtensions XListExtensions - ListFonts XListFonts - ListFontsWithInfo XListFontsWithInfo - ListHosts XListHosts - ListInstalledColormaps XListInstalledColormaps - ListProperties XListProperties - LookupColor XLookupColor - XParseColor - MapSubwindows XMapSubwindows - MapWindow XMapRaised - XMapWindow - NoOperation XNoOp - OpenFont XLoadFont - XLoadQueryFont - PolyArc XDrawArc - XDrawArcs - PolyFillArc XFillArc - XFillArcs - PolyFillRectangle XFillRectangle - XFillRectangles - PolyLine XDrawLines - PolyPoint XDrawPoint - XDrawPoints - PolyRectangle XDrawRectangle - XDrawRectangles - PolySegment XDrawLine - XDrawSegments - PolyText8 XDrawString - XDrawText - PolyText16 XDrawString16 - XDrawText16 - PutImage XPutImage - XCreateBitmapFromData - XCreatePixmapFromData - XReadBitmapFile - QueryBestSize XQueryBestCursor - XQueryBestSize - XQueryBestStipple - XQueryBestTile - QueryColors XQueryColor - XQueryColors - QueryExtension XInitExtension - XQueryExtension - QueryFont XLoadQueryFont - XQueryFont - QueryKeymap XQueryKeymap - QueryPointer XQueryPointer - QueryTextExtents XQueryTextExtents - XQueryTextExtents16 - QueryTree XQueryTree - RecolorCursor XRecolorCursor - ReparentWindow XReparentWindow - RotateProperties XRotateBuffers - XRotateWindowProperties - SendEvent XIconifyWindow - XReconfigureWMWindow - XSendEvent - XWithdrawWindow - SetAccessControl XDisableAccessControl - XEnableAccessControl - XSetAccessControl - SetClipRectangles XSetClipRectangles - SetCloseDownMode XSetCloseDownMode - SetDashes XSetDashes - SetFontPath XSetFontPath - SetInputFocus XSetInputFocus - SetModifierMapping XSetModifierMapping - SetPointerMapping XSetPointerMapping - SetScreenSaver XGetScreenSaver - XSetScreenSaver - SetSelectionOwner XSetSelectionOwner - StoreColors XStoreColor - XStoreColors - StoreNamedColor XStoreNamedColor - TranslateCoordinates XTranslateCoordinates - UngrabButton XUngrabButton - UngrabKey XUngrabKey - UngrabKeyboard XUngrabKeyboard - UngrabPointer XUngrabPointer - UngrabServer XUngrabServer - UninstallColormap XUninstallColormap - UnmapSubwindows XUnmapSubWindows - UnmapWindow XUnmapWindow - XWithdrawWindow - WarpPointer XWarpPointer - -Appendix B. X Font Cursors - - The following are the available cursors that can be used with - XCreateFontCursor. -#define XC_X_cursor 0 #define XC_ll_angle 76 -#define XC_arrow 2 #define XC_lr_angle 78 -#define XC_based_arrow_down 4 #define XC_man 80 -#define XC_based_arrow_up 6 #define XC_middlebutton 82 -#define XC_boat 8 #define XC_mouse 84 -#define XC_bogosity 10 #define XC_pencil 86 -#define XC_bottom_left_corner 12 #define XC_pirate 88 -#define XC_bottom_right_corner 14 #define XC_plus 90 -#define XC_bottom_side 16 #define XC_question_arrow 92 -#define XC_bottom_tee 18 #define XC_right_ptr 94 -#define XC_box_spiral 20 #define XC_right_side 96 -#define XC_center_ptr 22 #define XC_right_tee 98 -#define XC_circle 24 #define XC_rightbutton 100 -#define XC_clock 26 #define XC_rtl_logo 102 -#define XC_coffee_mug 28 #define XC_sailboat 104 -#define XC_cross 30 #define XC_sb_down_arrow 106 -#define XC_cross_reverse 32 #define XC_sb_h_double_arrow 1 -08 -#define XC_crosshair 34 #define XC_sb_left_arrow 110 -#define XC_diamond_cross 36 #define XC_sb_right_arrow 112 -#define XC_dot 38 #define XC_sb_up_arrow 114 -#define XC_dot_box_mask 40 #define XC_sb_v_double_arrow 1 -16 -#define XC_double_arrow 42 #define XC_shuttle 118 -#define XC_draft_large 44 #define XC_sizing 120 -#define XC_draft_small 46 #define XC_spider 122 -#define XC_draped_box 48 #define XC_spraycan 124 -#define XC_exchange 50 #define XC_star 126 -#define XC_fleur 52 #define XC_target 128 -#define XC_gobbler 54 #define XC_tcross 130 -#define XC_gumby 56 #define XC_top_left_arrow 132 -#define XC_hand1 58 #define XC_top_left_corner 134 -#define XC_hand2 60 #define XC_top_right_corner 13 -6 -#define XC_heart 62 #define XC_top_side 138 -#define XC_icon 64 #define XC_top_tee 140 -#define XC_iron_cross 66 #define XC_trek 142 -#define XC_left_ptr 68 #define XC_ul_angle 144 -#define XC_left_side 70 #define XC_umbrella 146 -#define XC_left_tee 72 #define XC_ur_angle 148 -#define XC_leftbutton 74 #define XC_watch 150 - #define XC_xterm 152 - -Appendix C. Extensions - - Table of Contents - - Basic Protocol Support Routines - Hooking into Xlib - - Hooks into the Library - Hooks onto Xlib Data Structures - - GC Caching - Graphics Batching - Writing Extension Stubs - - Requests, Replies, and Xproto.h - Request Format - Starting to Write a Stub Procedure - Locking Data Structures - Sending the Protocol Request and Arguments - Variable Length Arguments - Replies - Synchronous Calling - Allocating and Deallocating Memory - Portability Considerations - Deriving the Correct Extension Opcode - - Because X can evolve by extensions to the core protocol, it is - important that extensions not be perceived as second-class - citizens. At some point, your favorite extensions may be - adopted as additional parts of the X Standard. - - Therefore, there should be little to distinguish the use of an - extension from that of the core protocol. To avoid having to - initialize extensions explicitly in application programs, it is - also important that extensions perform lazy evaluations, - automatically initializing themselves when called for the first - time. - - This appendix describes techniques for writing extensions to - Xlib that will run at essentially the same performance as the - core protocol requests. - -Note - - It is expected that a given extension to X consists of multiple - requests. Defining 10 new features as 10 separate extensions is - a bad practice. Rather, they should be packaged into a single - extension and should use minor opcodes to distinguish the - requests. - - The symbols and macros used for writing stubs to Xlib are - listed in . - -Basic Protocol Support Routines - - The basic protocol requests for extensions are XQueryExtension - and XListExtensions. - - Bool XQueryExtension(Display *display, char *name, int - *major_opcode_return, int *first_event_return, int - *first_error_return); - - display - - Specifies the connection to the X server. - - name - - Specifies the extension name. - - major_opcode_return - - Returns the major opcode. - - first_event_return - - Returns the first event code, if any. - - first_error_return - - Returns the first error code, if any. - - The XQueryExtension function determines if the named extension - is present. If the extension is not present, XQueryExtension - returns False; otherwise, it returns True. If the extension is - present, XQueryExtension returns the major opcode for the - extension to major_opcode_return; otherwise, it returns zero. - Any minor opcode and the request formats are specific to the - extension. If the extension involves additional event types, - XQueryExtension returns the base event type code to - first_event_return; otherwise, it returns zero. The format of - the events is specific to the extension. If the extension - involves additional error codes, XQueryExtension returns the - base error code to first_error_return; otherwise, it returns - zero. The format of additional data in the errors is specific - to the extension. - - If the extension name is not in the Host Portable Character - Encoding the result is implementation-dependent. Uppercase and - lowercase matter; the strings ``thing'', ``Thing'', and - ``thinG'' are all considered different names. - - char **XListExtensions(Display *display, int - *nextensions_return); - - display - - Specifies the connection to the X server. - - nextensions_return - - Returns the number of extensions listed. - - The XListExtensions function returns a list of all extensions - supported by the server. If the data returned by the server is - in the Latin Portable Character Encoding, then the returned - strings are in the Host Portable Character Encoding. Otherwise, - the result is implementation-dependent. - - XFreeExtensionList(char **list); - - list - - Specifies the list of extension names. - - The XFreeExtensionList function frees the memory allocated by - XListExtensions. - -Hooking into Xlib - - These functions allow you to hook into the library. They are - not normally used by application programmers but are used by - people who need to extend the core X protocol and the X library - interface. The functions, which generate protocol requests for - X, are typically called stubs. - - In extensions, stubs first should check to see if they have - initialized themselves on a connection. If they have not, they - then should call XInitExtension to attempt to initialize - themselves on the connection. - - If the extension needs to be informed of GC/font allocation or - deallocation or if the extension defines new event types, the - functions described here allow the extension to be called when - these events occur. - - The XExtCodes structure returns the information from - XInitExtension and is defined in : - -typedef struct _XExtCodes { /* public to extension, cannot be change -d */ - int extension; /* extension number */ - int major_opcode; /* major op-code assigned by server */ - int first_event; /* first event number for the extension -*/ - int first_error; /* first error number for the extension -*/ -} XExtCodes; - - XExtCodes *XInitExtension(Display *display, char *name); - - display - - Specifies the connection to the X server. - - name - - Specifies the extension name. - - The XInitExtension function determines if the named extension - exists. Then, it allocates storage for maintaining the - information about the extension on the connection, chains this - onto the extension list for the connection, and returns the - information the stub implementor will need to access the - extension. If the extension does not exist, XInitExtension - returns NULL. - - If the extension name is not in the Host Portable Character - Encoding, the result is implementation-dependent. Uppercase and - lowercase matter; the strings ``thing'', ``Thing'', and - ``thinG'' are all considered different names. - - The extension number in the XExtCodes structure is needed in - the other calls that follow. This extension number is unique - only to a single connection. - - XExtCodes *XAddExtension(Display *display); - - display - - Specifies the connection to the X server. - - For local Xlib extensions, the XAddExtension function allocates - the XExtCodes structure, bumps the extension number count, and - chains the extension onto the extension list. (This permits - extensions to Xlib without requiring server extensions.) - -Hooks into the Library - - These functions allow you to define procedures that are to be - called when various circumstances occur. The procedures include - the creation of a new GC for a connection, the copying of a GC, - the freeing of a GC, the creating and freeing of fonts, the - conversion of events defined by extensions to and from wire - format, and the handling of errors. - - All of these functions return the previous procedure defined - for this extension. - - int XESetCloseDisplay(Display *display, int extension, int - (*proc)()); - - display - - Specifies the connection to the X server. - - extension - - Specifies the extension number. - - proc - - Specifies the procedure to call when the display is closed. - - The XESetCloseDisplay function defines a procedure to be called - whenever XCloseDisplay is called. It returns any previously - defined procedure, usually NULL. - - When XCloseDisplay is called, your procedure is called with - these arguments: - - int (*proc)(Display *display, XExtCodes *codes); - - int *XESetCreateGC(Display *display, int extension, int - (*proc)()); - - display - - Specifies the connection to the X server. - - extension - - Specifies the extension number. - - proc - - Specifies the procedure to call when a GC is closed. - - The XESetCreateGC function defines a procedure to be called - whenever a new GC is created. It returns any previously defined - procedure, usually NULL. - - When a GC is created, your procedure is called with these - arguments: - - int (*proc)(Display *display, GC gc, XExtCodes *codes); - - int *XESetCopyGC(Display *display, int extension, int - (*proc)()); - - display - - Specifies the connection to the X server. - - extension - - Specifies the extension number. - - proc - - Specifies the procedure to call when GC components are copied. - - The XESetCopyGC function defines a procedure to be called - whenever a GC is copied. It returns any previously defined - procedure, usually NULL. - - When a GC is copied, your procedure is called with these - arguments: - - int (*proc)(Display *display, GC gc, XExtCodes *codes); - - int *XESetFreeGC(Display *display, int extension, int - (*proc)()); - - display - - Specifies the connection to the X server. - - extension - - Specifies the extension number. - - proc - - Specifies the procedure to call when a GC is freed. - - The XESetFreeGC function defines a procedure to be called - whenever a GC is freed. It returns any previously defined - procedure, usually NULL. - - When a GC is freed, your procedure is called with these - arguments: - - int (*proc)(Display *display, GC gc, XExtCodes *codes); - - int *XESetCreateFont(Display *display, int extension, int - (*proc)()); - - display - - Specifies the connection to the X server. - - extension - - Specifies the extension number. - - proc - - Specifies the procedure to call when a font is created. - - The XESetCreateFont function defines a procedure to be called - whenever XLoadQueryFont and XQueryFont are called. It returns - any previously defined procedure, usually NULL. - - When XLoadQueryFont or XQueryFont is called, your procedure is - called with these arguments: - - int (*proc)(Display *display, XFontStruct *fs, XExtCodes - *codes); - - int *XESetFreeFont(Display *display, int extension, int - (*proc)()); - - display - - Specifies the connection to the X server. - - extension - - Specifies the extension number. - - proc - - Specifies the procedure to call when a font is freed. - - The XESetFreeFont function defines a procedure to be called - whenever XFreeFont is called. It returns any previously defined - procedure, usually NULL. - - When XFreeFont is called, your procedure is called with these - arguments: - - int (*proc)(Display *display, XFontStruct *fs, XExtCodes - *codes); - - The XESetWireToEvent and XESetEventToWire functions allow you - to define new events to the library. An XEvent structure always - has a type code (type int) as the first component. This - uniquely identifies what kind of event it is. The second - component is always the serial number (type unsigned long) of - the last request processed by the server. The third component - is always a Boolean (type Bool) indicating whether the event - came from a SendEvent protocol request. The fourth component is - always a pointer to the display the event was read from. The - fifth component is always a resource ID of one kind or another, - usually a window, carefully selected to be useful to toolkit - dispatchers. The fifth component should always exist, even if - the event does not have a natural destination; if there is no - value from the protocol to put in this component, initialize it - to zero. There is an implementation limit such that your host - event structure size cannot be bigger than the size of the - XEvent union of structures. There also is no way to guarantee - that more than 24 elements or 96 characters in the structure - will be fully portable between machines. - - int *XESetWireToEvent(Display *display, int event_number, - Status (*proc)()); - - display - - Specifies the connection to the X server. - - event_number - - Specifies the event code. - - proc - - Specifies the procedure to call when converting an event. - - The XESetWireToEvent function defines a procedure to be called - when an event needs to be converted from wire format (xEvent) - to host format (XEvent). The event number defines which - protocol event number to install a conversion procedure for. - XESetWireToEvent returns any previously defined procedure. You - can replace a core event conversion function with one of your - own, although this is not encouraged. It would, however, allow - you to intercept a core event and modify it before being placed - in the queue or otherwise examined. When Xlib needs to convert - an event from wire format to host format, your procedure is - called with these arguments: - - int (*proc)(Display *display, XEvent *re, xEvent *event); - - Your procedure must return status to indicate if the conversion - succeeded. The re argument is a pointer to where the host - format event should be stored, and the event argument is the - 32-byte wire event structure. In the XEvent structure you are - creating, you must fill in the five required members of the - event structure. You should fill in the type member with the - type specified for the xEvent structure. You should copy all - other members from the xEvent structure (wire format) to the - XEvent structure (host format). Your conversion procedure - should return True if the event should be placed in the queue - or False if it should not be placed in the queue. - - To initialize the serial number component of the event, call - _XSetLastRequestRead with the event and use the return value. - - unsigned long_XSetLastRequestRead(Display *display, - xGenericReply *rep); - - display - - Specifies the connection to the X server. - - rep - - Specifies the wire event structure. - - The _XSetLastRequestRead function computes and returns a - complete serial number from the partial serial number in the - event. - - Status *XESetEventToWire(Display *display, int event_number, - int (*proc)()); - - display - - Specifies the connection to the X server. - - event_number - - Specifies the event code. - - proc - - Specifies the procedure to call when converting an event. - - The XESetEventToWire function defines a procedure to be called - when an event needs to be converted from host format (XEvent) - to wire format (xEvent) form. The event number defines which - protocol event number to install a conversion procedure for. - XESetEventToWire returns any previously defined procedure. It - returns zero if the conversion fails or nonzero otherwise. You - can replace a core event conversion function with one of your - own, although this is not encouraged. It would, however, allow - you to intercept a core event and modify it before being sent - to another client. When Xlib needs to convert an event from - host format to wire format, your procedure is called with these - arguments: - - int (*proc)(Display *display, XEvent *re, xEvent *event); - - The re argument is a pointer to the host format event, and the - event argument is a pointer to where the 32-byte wire event - structure should be stored. You should fill in the type with - the type from the XEvent structure. All other members then - should be copied from the host format to the xEvent structure. - - Bool *XESetWireToError(Display *display, int error_number, Bool - (*proc)()); - - display - - Specifies the connection to the X server. - - error_number - - Specifies the error code. - - proc - - Specifies the procedure to call when an error is received. - - The XESetWireToError function defines a procedure to be called - when an extension error needs to be converted from wire format - to host format. The error number defines which protocol error - code to install the conversion procedure for. XESetWireToError - returns any previously defined procedure. - - Use this function for extension errors that contain additional - error values beyond those in a core X error, when multiple wire - errors must be combined into a single Xlib error, or when it is - necessary to intercept an X error before it is otherwise - examined. - - When Xlib needs to convert an error from wire format to host - format, the procedure is called with these arguments: - - int (*proc)(Display *display, XErrorEvent *he, xError *we); - - The he argument is a pointer to where the host format error - should be stored. The structure pointed at by he is guaranteed - to be as large as an XEvent structure and so can be cast to a - type larger than an XErrorEvent to store additional values. If - the error is to be completely ignored by Xlib (for example, - several protocol error structures will be combined into one - Xlib error), then the function should return False; otherwise, - it should return True. - - int *XESetError(Display *display, int extension, int - (*proc)()); - - display - - Specifies the connection to the X server. - - extension - - Specifies the extension number. - - proc - - Specifies the procedure to call when an error is received. - - Inside Xlib, there are times that you may want to suppress the - calling of the external error handling when an error occurs. - This allows status to be returned on a call at the cost of the - call being synchronous (though most such functions are query - operations, in any case, and are typically programmed to be - synchronous). - - When Xlib detects a protocol error in _XReply, it calls your - procedure with these arguments: - - int (*proc)(Display *display, xError *err, XExtCodes *codes, - int *ret_code); - - The err argument is a pointer to the 32-byte wire format error. - The codes argument is a pointer to the extension codes - structure. The ret_code argument is the return code you may - want _XReply returned to. - - If your procedure returns a zero value, the error is not - suppressed, and the client's error handler is called. (For - further information, see section 11.8.2.) If your procedure - returns nonzero, the error is suppressed, and _XReply returns - the value of ret_code. - - char *XESetErrorString(Display *display, int extension, char - *(*proc)()); - - display - - Specifies the connection to the X server. - - extension - - Specifies the extension number. - - proc - - Specifies the procedure to call to obtain an error string. - - The XGetErrorText function returns a string to the user for an - error. XESetErrorString allows you to define a procedure to be - called that should return a pointer to the error message. The - following is an example. - - int (*proc)(Display *display, int code, XExtCodes *codes, char - *buffer, int nbytes); - - Your procedure is called with the error code for every error - detected. You should copy nbytes of a null-terminated string - containing the error message into buffer. - - void *XESetPrintErrorValues(Display *display, int extension, - void (*proc)()); - - display - - Specifies the connection to the X server. - - extension - - Specifies the extension number. - - proc - - Specifies the procedure to call when an error is printed. - - The XESetPrintErrorValues function defines a procedure to be - called when an extension error is printed, to print the error - values. Use this function for extension errors that contain - additional error values beyond those in a core X error. It - returns any previously defined procedure. - - When Xlib needs to print an error, the procedure is called with - these arguments: - - void (*proc)(Display *display, XErrorEvent *ev, void *fp); - - The structure pointed at by ev is guaranteed to be as large as - an XEvent structure and so can be cast to a type larger than an - XErrorEvent to obtain additional values set by using - XESetWireToError. The underlying type of the fp argument is - system dependent; on a POSIX-compliant system, fp should be - cast to type FILE*. - - int *XESetFlushGC(Display *display, int extension, int - *(*proc)()); - - display - - Specifies the connection to the X server. - - extension - - Specifies the extension number. - - proc - - Specifies the procedure to call when a GC is flushed. - - The procedure set by the XESetFlushGC function has the same - interface as the procedure set by the XESetCopyGC function, but - is called when a GC cache needs to be updated in the server. - - int *XESetCopyGC(Display *display, int extension, int - *(*proc)()); - - display - - Specifies the connection to the X server. - - extension - - Specifies the extension number. - - proc - - Specifies the procedure to call when a buffer is flushed. - - The XESetBeforeFlush function defines a procedure to be called - when data is about to be sent to the server. When data is about - to be sent, your procedure is called one or more times with - these arguments: - - void (*proc)(Display *display, XExtCodes *codes, char *data, - long len); - - The data argument specifies a portion of the outgoing data - buffer, and its length in bytes is specified by the len - argument. Your procedure must not alter the contents of the - data and must not do additional protocol requests to the same - display. - -Hooks onto Xlib Data Structures - - Various Xlib data structures have provisions for extension - procedures to chain extension supplied data onto a list. These - structures are GC, Visual, Screen, ScreenFormat, Display, and - XFontStruct. Because the list pointer is always the first - member in the structure, a single set of procedures can be used - to manipulate the data on these lists. - - The following structure is used in the functions in this - section and is defined in - -typedef struct _XExtData { - int number; /* number returned by XInitExtension */ - struct _XExtData *next; /* next item on list of data for structu -re */ - int (*free_private)(); /* if defined, called to free private * -/ - XPointer private_data; /* data private to this extension. */ -} XExtData; - - When any of the data structures listed above are freed, the - list is walked, and the structure's free procedure (if any) is - called. If free is NULL, then the library frees both the data - pointed to by the private_data member and the structure itself. - -union { Display *display; - GC gc; - Visual *visual; - Screen *screen; - ScreenFormat *pixmap_format; - XFontStruct *font } XEDataObject; - - XExtData **XEHeadOfExtensionList(XEDataObject object); - - object - - Specifies the object. - - The XEHeadOfExtensionList function returns a pointer to the - list of extension structures attached to the specified object. - In concert with XAddToExtensionList, XEHeadOfExtensionList - allows an extension to attach arbitrary data to any of the - structures of types contained in XEDataObject. - - XAddToExtensionList(XExtData **structure, XExtData *ext_data); - - structure - - Specifies the extension list. - - ext_data - - Specifies the extension data structure to add. - - The structure argument is a pointer to one of the data - structures enumerated above. You must initialize - ext_data->number with the extension number before calling this - function. - - XExtData *XFindOnExtensionList(struct_XExtData **structure, int - number); - - structure - - Specifies the extension list. - - number - - Specifies the extension number from XInitExtension. - - The XFindOnExtensionList function returns the first extension - data structure for the extension numbered number. It is - expected that an extension will add at most one extension data - structure to any single data structure's extension data list. - There is no way to find additional structures. - - The XAllocID macro, which allocates and returns a resource ID, - is defined in . - - XAllocID(Display *display); - - display - - Specifies the connection to the X server. - - This macro is a call through the Display structure to an - internal resource ID allocator. It returns a resource ID that - you can use when creating new resources. - - The XAllocIDs macro allocates and returns an array of resource - ID. - - XAllocIDs(Display *display, XID *ids_return, int count); - - display - - Specifies the connection to the X server. - - ids_return - - Returns the resource IDs. - - rep - - Specifies the number of resource IDs requested. - - This macro is a call through the Display structure to an - internal resource ID allocator. It returns resource IDs to the - array supplied by the caller. To correctly handle automatic - reuse of resource IDs, you must call XAllocIDs when requesting - multiple resource IDs. This call might generate protocol - requests. - -GC Caching - - GCs are cached by the library to allow merging of independent - change requests to the same GC into single protocol requests. - This is typically called a write-back cache. Any extension - procedure whose behavior depends on the contents of a GC must - flush the GC cache to make sure the server has up-to-date - contents in its GC. - - The FlushGC macro checks the dirty bits in the library's GC - structure and calls _XFlushGCCache if any elements have - changed. The FlushGC macro is defined as follows: - - FlushGC(Display *display, GC gc); - - display - - Specifies the connection to the X server. - - gc - - Specifies the GC. - - Note that if you extend the GC to add additional resource ID - components, you should ensure that the library stub sends the - change request immediately. This is because a client can free a - resource immediately after using it, so if you only stored the - value in the cache without forcing a protocol request, the - resource might be destroyed before being set into the GC. You - can use the _XFlushGCCache procedure to force the cache to be - flushed. The _XFlushGCCache procedure is defined as follows: - - _XFlushGCCache(Display *display, GC gc); - - display - - Specifies the connection to the X server. - - gc - - Specifies the GC. - -Graphics Batching - - If you extend X to add more poly graphics primitives, you may - be able to take advantage of facilities in the library to allow - back-to-back single calls to be transformed into poly requests. - This may dramatically improve performance of programs that are - not written using poly requests. A pointer to an xReq, called - last_req in the display structure, is the last request being - processed. By checking that the last request type, drawable, - gc, and other options are the same as the new one and that - there is enough space left in the buffer, you may be able to - just extend the previous graphics request by extending the - length field of the request and appending the data to the - buffer. This can improve performance by five times or more in - naive programs. For example, here is the source for the - XDrawPoint stub. (Writing extension stubs is discussed in the - next section.) -#include - -/* precompute the maximum size of batching request allowed */ - -static int size = sizeof(xPolyPointReq) + EPERBATCH * sizeof(xPoint); - -XDrawPoint(dpy, d, gc, x, y) - register Display *dpy; - Drawable d; - GC gc; - int x, y; /* INT16 */ -{ - xPoint *point; - LockDisplay(dpy); - FlushGC(dpy, gc); - { - register xPolyPointReq *req = (xPolyPointReq *) dpy->last_req; - /* if same as previous request, with same drawable, batch requests * -/ - if ( - (req->reqType == X_PolyPoint) - && (req->drawable == d) - && (req->gc == gc->gid) - && (req->coordMode == CoordModeOrigin) - && ((dpy->bufptr + sizeof (xPoint)) <= dpy->bufmax) - && (((char *)dpy->bufptr - (char *)req) < size) ) { - point = (xPoint *) dpy->bufptr; - req->length += sizeof (xPoint) >> 2; - dpy->bufptr += sizeof (xPoint); - } - - else { - GetReqExtra(PolyPoint, 4, req); /* 1 point = 4 bytes */ - req->drawable = d; - req->gc = gc->gid; - req->coordMode = CoordModeOrigin; - point = (xPoint *) (req + 1); - } - point->x = x; - point->y = y; - } - UnlockDisplay(dpy); - SyncHandle(); -} - - To keep clients from generating very long requests that may - monopolize the server, there is a symbol defined in - of EPERBATCH on the number of requests batched. - Most of the performance benefit occurs in the first few merged - requests. Note that FlushGC is called before picking up the - value of last_req, because it may modify this field. - -Writing Extension Stubs - - All X requests always contain the length of the request, - expressed as a 16-bit quantity of 32 bit words. This means that - a single request can be no more than 256K bytes in length. Some - servers may not support single requests of such a length. The - value of dpy->max_request_size contains the maximum length as - defined by the server implementation. For further information, - see X Window System Protocol. - -Requests, Replies, and Xproto.h - - The file contains three sets of definitions that - are of interest to the stub implementor: request names, request - structures, and reply structures. - - You need to generate a file equivalent to for - your extension and need to include it in your stub procedure. - Each stub procedure also must include . - - The identifiers are deliberately chosen in such a way that, if - the request is called X_DoSomething, then its request structure - is xDoSomethingReq, and its reply is xDoSomethingReply. The - GetReq family of macros, defined in , takes - advantage of this naming scheme. - - For each X request, there is a definition in - that looks similar to this: - -#define X_DoSomething 42 - - In your extension header file, this will be a minor opcode, - instead of a major opcode. - -Request Format - - Every request contains an 8-bit major opcode and a 16-bit - length field expressed in units of 4 bytes. Every request - consists of 4 bytes of header (containing the major opcode, the - length field, and a data byte) followed by zero or more - additional bytes of data. The length field defines the total - length of the request, including the header. The length field - in a request must equal the minimum length required to contain - the request. If the specified length is smaller or larger than - the required length, the server should generate a BadLength - error. Unused bytes in a request are not required to be zero. - Extensions should be designed in such a way that long protocol - requests can be split up into smaller requests, if it is - possible to exceed the maximum request size of the server. The - protocol guarantees the maximum request size to be no smaller - than 4096 units (16384 bytes). - - Major opcodes 128 through 255 are reserved for extensions. - Extensions are intended to contain multiple requests, so - extension requests typically have an additional minor opcode - encoded in the second data byte in the request header, but the - placement and interpretation of this minor opcode as well as - all other fields in extension requests are not defined by the - core protocol. Every request is implicitly assigned a sequence - number (starting with one) used in replies, errors, and events. - - Most protocol requests have a corresponding structure typedef - in , which looks like: - -typedef struct _DoSomethingReq { - CARD8 reqType; /* X_DoSomething */ - CARD8 someDatum; /* used differently in different request -s */ - CARD16 length; /* total # of bytes in request, divided -by 4 */ - ... - /* request-specific data */ - ... -} xDoSomethingReq; - - If a core protocol request has a single 32-bit argument, you - need not declare a request structure in your extension header - file. Instead, such requests use the xResourceReq structure in - . This structure is used for any request whose - single argument is a Window, Pixmap, Drawable, GContext, Font, - Cursor, Colormap, Atom, or VisualID. - -typedef struct _ResourceReq { - CARD8 reqType; /* the request type, e.g. X_DoSomething */ - BYTE pad; /* not used */ - CARD16 length; /* 2 (= total # of bytes in request, divided by -4) */ - CARD32 id; /* the Window, Drawable, Font, GContext, etc. */ -} xResourceReq; - - If convenient, you can do something similar in your extension - header file. - - In both of these structures, the reqType field identifies the - type of the request (for example, X_MapWindow or - X_CreatePixmap). The length field tells how long the request is - in units of 4-byte longwords. This length includes both the - request structure itself and any variable-length data, such as - strings or lists, that follow the request structure. Request - structures come in different sizes, but all requests are padded - to be multiples of four bytes long. - - A few protocol requests take no arguments at all. Instead, they - use the xReq structure in , which contains only a - reqType and a length (and a pad byte). - - If the protocol request requires a reply, then - also contains a reply structure typedef: - -typedef struct _DoSomethingReply { - BYTE type; /* always X_Reply */ - BYTE someDatum; /* used differently in different requests */ - CARD16 sequenceNumber; /* # of requests sent so far */ - CARD32 length; /* # of additional bytes, divided by 4 */ - ... - /* request-specific data */ - ... -} xDoSomethingReply; - - Most of these reply structures are 32 bytes long. If there are - not that many reply values, then they contain a sufficient - number of pad fields to bring them up to 32 bytes. The length - field is the total number of bytes in the request minus 32, - divided by 4. This length will be nonzero only if: - * The reply structure is followed by variable-length data, - such as a list or string. - * The reply structure is longer than 32 bytes. - - Only GetWindowAttributesl, QueryFont, QueryKeymap, and - GetKeyboardControl have reply structures longer than 32 bytes - in the core protocol. - - A few protocol requests return replies that contain no data. - does not define reply structures for these. - Instead, they use the xGenericReply structure, which contains - only a type, length, and sequence number (and sufficient - padding to make it 32 bytes long). - -Starting to Write a Stub Procedure - - An Xlib stub procedure should start like this: - -#include " - -XDoSomething (arguments, ... ) -/* argument declarations */ -{ - -register XDoSomethingReq *req; -... - - If the protocol request has a reply, then the variable - declarations should include the reply structure for the - request. The following is an example: - -xDoSomethingReply rep; - -Locking Data Structures - - To lock the display structure for systems that want to support - multithreaded access to a single display connection, each stub - will need to lock its critical section. Generally, this section - is the point from just before the appropriate GetReq call until - all arguments to the call have been stored into the buffer. The - precise instructions needed for this locking depend upon the - machine architecture. Two calls, which are generally - implemented as macros, have been provided. - - LockDisplay(Display *display); - - UnlockDisplay(Display *display); - - display - - Specifies the connection to the X server. - -Sending the Protocol Request and Arguments - - After the variable declarations, a stub procedure should call - one of four macros defined in : GetReq, - GetReqExtra, GetResReq, or GetEmptyReq. All of these macros - take, as their first argument, the name of the protocol request - as declared in except with X_ removed. Each one - declares a Display structure pointer, called dpy, and a pointer - to a request structure, called req, which is of the appropriate - type. The macro then appends the request structure to the - output buffer, fills in its type and length field, and sets req - to point to it. - - If the protocol request has no arguments (for instance, - X_GrabServer), then use GetEmptyReq. - -GetEmptyReq (DoSomething, req); - - If the protocol request has a single 32-bit argument (such as a - Pixmap, Window, Drawable, Atom, and so on), then use GetResReq. - The second argument to the macro is the 32-bit object. - X_MapWindow is a good example. - -GetResReq (DoSomething, rid, req); - - The rid argument is the Pixmap, Window, or other resource ID. - - If the protocol request takes any other argument list, then - call GetReq. After the GetReq, you need to set all the other - fields in the request structure, usually from arguments to the - stub procedure. - -GetReq (DoSomething, req); -/* fill in arguments here */ -req->arg1 = arg1; -req->arg2 = arg2; -... - - A few stub procedures (such as XCreateGC and XCreatePixmap) - return a resource ID to the caller but pass a resource ID as an - argument to the protocol request. Such procedures use the macro - XAllocID to allocate a resource ID from the range of IDs that - were assigned to this client when it opened the connection. - -rid = req->rid = XAllocID(); -... -return (rid); - - Finally, some stub procedures transmit a fixed amount of - variable-length data after the request. Typically, these - procedures (such as XMoveWindow and XSetBackground) are special - cases of more general functions like XMoveResizeWindow and - XChangeGC. These procedures use GetReqExtra, which is the same - as GetReq except that it takes an additional argument (the - number of extra bytes to allocate in the output buffer after - the request structure). This number should always be a multiple - of four. Note that it is possible for req to be set to NULL as - a defensive measure if the requested length exceeds the Xlib's - buffer size (normally 16K). - -Variable Length Arguments - - Some protocol requests take additional variable-length data - that follow the xDoSomethingReq structure. The format of this - data varies from request to request. Some requests require a - sequence of 8-bit bytes, others a sequence of 16-bit or 32-bit - entities, and still others a sequence of structures. - - It is necessary to add the length of any variable-length data - to the length field of the request structure. That length field - is in units of 32-bit longwords. If the data is a string or - other sequence of 8-bit bytes, then you must round the length - up and shift it before adding: - -req->length += (nbytes+3)>>2; - - To transmit variable-length data, use the Data macros. If the - data fits into the output buffer, then this macro copies it to - the buffer. If it does not fit, however, the Data macro calls - _XSend, which transmits first the contents of the buffer and - then your data. The Data macros take three arguments: the - display, a pointer to the beginning of the data, and the number - of bytes to be sent. - - Data(display, (char *) data, nbytes); - - Data16(display, (short *) data, nbytes); - - Data32(display, (long *) data, nbytes); - - Data, Data16, and Data32 are macros that may use their last - argument more than once, so that argument should be a variable - rather than an expression such as ``nitems*sizeof(item)''. You - should do that kind of computation in a separate statement - before calling them. Use the appropriate macro when sending - byte, short, or long data. - - If the protocol request requires a reply, then call the - procedure _XSend instead of the Data macro. _XSend takes the - same arguments, but because it sends your data immediately - instead of copying it into the output buffer (which would later - be flushed anyway by the following call on _XReply), it is - faster. - -Replies - - If the protocol request has a reply, then call _XReply after - you have finished dealing with all the fixed-length and - variable-length arguments. _XReply flushes the output buffer - and waits for an xReply packet to arrive. If any events arrive - in the meantime, _XReply places them in the queue for later - use. - - Status _XReply(Display *display, xReply *rep, int extra, Bool - discard); - - display - - Specifies the connection to the X server. - - rep - - Specifies the reply structure. - - extra - - Specifies the number of 32-bit words expected after the replay. - - discard - - Specifies if any data beyond that specified in the extra - argument should be discarded. - - The _XReply function waits for a reply packet and copies its - contents into the specified rep. _XReply handles error and - event packets that occur before the reply is received. _XReply - takes four arguments: - * A Display * structure - * A pointer to a reply structure (which must be cast to an - xReply *) - * The number of additional 32-bit words (beyond sizeof( - xReply) = 32 bytes) in the reply structure - * A Boolean that indicates whether _XReply is to discard any - additional bytes beyond those it was told to read - - Because most reply structures are 32 bytes long, the third - argument is usually 0. The only core protocol exceptions are - the replies to GetWindowAttributesl, QueryFont, QueryKeymap, - and GetKeyboardControl, which have longer replies. - - The last argument should be False if the reply structure is - followed by additional variable-length data (such as a list or - string). It should be True if there is not any variable-length - data. This last argument is provided for upward-compatibility - reasons to allow a client to communicate properly with a - hypothetical later version of the server that sends more data - than the client expected. For example, some later version of - GetWindowAttributesl might use a larger, but compatible, - xGetWindowAttributesReply that contains additional attribute - data at the end. _XReply returns True if it received a reply - successfully or False if it received any sort of error. - - For a request with a reply that is not followed by - variable-length data, you write something like: - -_XReply(display, (xReply *)&rep, 0, True); -*ret1 = rep.ret1; -*ret2 = rep.ret2; -*ret3 = rep.ret3; -... -UnlockDisplay(dpy); -SyncHandle(); -return (rep.ret4); -} - - If there is variable-length data after the reply, change the - True to False, and use the appropriate _XRead function to read - the variable-length data. - - _XRead(Display *display, char *data_return, long nbytes); - - display - - Specifies the connection to the X server. - - data_return - - Specifies the buffer. - - nbytes - - Specifies the number of bytes required. - - The _XRead function reads the specified number of bytes into - data_return. - - _XRead16(Display *display, short *data_return, long nbytes); - - display - - Specifies the connection to the X server. - - data_return - - Specifies the buffer. - - nbytes - - Specifies the number of bytes required. - - The _XRead16 function reads the specified number of bytes, - unpacking them as 16-bit quantities, into the specified array - as shorts. - - _XRead32(Display *display, long *data_return, long nbytes); - - display - - Specifies the connection to the X server. - - data_return - - Specifies the buffer. - - nbytes - - Specifies the number of bytes required. - - The _XRead32 function reads the specified number of bytes, - unpacking them as 32-bit quantities, into the specified array - as longs. - - _XRead16Pad(Display *display, short *data_return, long nbytes); - - display - - Specifies the connection to the X server. - - data_return - - Specifies the buffer. - - nbytes - - Specifies the number of bytes required. - - The _XRead16Pad function reads the specified number of bytes, - unpacking them as 16-bit quantities, into the specified array - as shorts. If the number of bytes is not a multiple of four, - _XRead16Pad reads and discards up to two additional pad bytes. - - _XReadPad(Display *display, char *data_return, long nbytes); - - display - - Specifies the connection to the X server. - - data_return - - Specifies the buffer. - - nbytes - - Specifies the number of bytes required. - - The _XReadPad function reads the specified number of bytes into - data_return. If the number of bytes is not a multiple of four, - _XReadPad reads and discards up to three additional pad bytes. - - Each protocol request is a little different. For further - information, see the Xlib sources for examples. - -Synchronous Calling - - Each procedure should have a call, just before returning to the - user, to a macro called SyncHandle. If synchronous mode is - enabled (see XSynchronize), the request is sent immediately. - The library, however, waits until any error the procedure could - generate at the server has been handled. - -Allocating and Deallocating Memory - - To support the possible reentry of these procedures, you must - observe several conventions when allocating and deallocating - memory, most often done when returning data to the user from - the window system of a size the caller could not know in - advance (for example, a list of fonts or a list of extensions). - The standard C library functions on many systems are not - protected against signals or other multithreaded uses. The - following analogies to standard I/O library functions have been - defined: - - These should be used in place of any calls you would make to - the normal C library functions. - - If you need a single scratch buffer inside a critical section - (for example, to pack and unpack data to and from the wire - protocol), the general memory allocators may be too expensive - to use (particularly in output functions, which are performance - critical). The following function returns a scratch buffer for - use within a critical section: - - char *_XAllocScratch(Display *display, unsigned long nbytes); - - display - - Specifies the connection to the X server. - - nbytes - - Specifies the number of bytes required. - - This storage must only be used inside of a critical section of - your stub. The returned pointer cannot be assumed valid after - any call that might permit another thread to execute inside - Xlib. For example, the pointer cannot be assumed valid after - any use of the GetReq or Data families of macros, after any use - of _XReply, or after any use of the _XSend or _XRead families - of functions. - - The following function returns a scratch buffer for use across - critical sections: - - char *_XAllocTemp(Display *display, unsigned long nbytes); - - display - - Specifies the connection to the X server. - - nbytes - - Specifies the number of bytes required. - - This storage can be used across calls that might permit another - thread to execute inside Xlib. The storage must be explicitly - returned to Xlib. The following function returns the storage: - - void _XFreeTemp(Display *display, char *buf, unsigned long - nbytes); - - display - - Specifies the connection to the X server. - - buf - - Specifies the buffer to return. - - nbytes - - Specifies the size of the buffer. - - You must pass back the same pointer and size that were returned - by _XAllocTemp. - -Portability Considerations - - Many machine architectures do not correctly or efficiently - access data at unaligned locations; their compilers pad out - structures to preserve this characteristic. Many other machines - capable of unaligned references pad inside of structures as - well to preserve alignment, because accessing aligned data is - usually much faster. Because the library and the server use - structures to access data at arbitrary points in a byte stream, - all data in request and reply packets must be naturally - aligned; that is, 16-bit data starts on 16-bit boundaries in - the request and 32-bit data on 32-bit boundaries. All requests - must be a multiple of 32 bits in length to preserve the natural - alignment in the data stream. You must pad structures out to - 32-bit boundaries. Pad information does not have to be zeroed - unless you want to preserve such fields for future use in your - protocol requests, but it is recommended to zero it to avoid - inadvertant data leakage and improve compressability. Floating - point varies radically between machines and should be avoided - completely if at all possible. - - This code may run on machines with 16-bit ints. So, if any - integer argument, variable, or return value either can take - only nonnegative values or is declared as a CARD16 in the - protocol, be sure to declare it as unsigned int and not as int. - (This, of course, does not apply to Booleans or enumerations.) - - Similarly, if any integer argument or return value is declared - CARD32 in the protocol, declare it as an unsigned long and not - as int or long. This also goes for any internal variables that - may take on values larger than the maximum 16-bit unsigned int. - - The library has always assumed that a char is 8 bits, a short - is 16 bits, an int is 16 or 32 bits, and a long is 32 bits. - Unfortunately, this assumption remains on machines where a long - can hold 64-bits, and many functions and structures require - unnecessarily large fields to avoid breaking compatibility with - existing code. Special care must be taken with arrays of values - that are transmitted in the protocol as CARD32 or INT32 but - have to be converted to arrays of 64-bit long when passed to or - from client applications. - - The PackData macro is a half-hearted attempt to deal with the - possibility of 32 bit shorts. However, much more work is needed - to make this work properly. - -Deriving the Correct Extension Opcode - - The remaining problem a writer of an extension stub procedure - faces that the core protocol does not face is to map from the - call to the proper major and minor opcodes. While there are a - number of strategies, the simplest and fastest is outlined - below. - * Declare an array of pointers, _NFILE long (this is normally - found in and is the number of file descriptors - supported on the system) of type XExtCodes. Make sure these - are all initialized to NULL. - * When your stub is entered, your initialization test is just - to use the display pointer passed in to access the file - descriptor and an index into the array. If the entry is - NULL, then this is the first time you are entering the - procedure for this display. Call your initialization - procedure and pass to it the display pointer. - * Once in your initialization procedure, call XInitExtension; - if it succeeds, store the pointer returned into this array. - Make sure to establish a close display handler to allow you - to zero the entry. Do whatever other initialization your - extension requires. (For example, install event handlers - and so on.) Your initialization procedure would normally - return a pointer to the XExtCodes structure for this - extension, which is what would normally be found in your - array of pointers. - * After returning from your initialization procedure, the - stub can now continue normally, because it has its major - opcode safely in its hand in the XExtCodes structure. - -Appendix D. Compatibility Functions - - Table of Contents - - X Version 11 Compatibility Functions - - Setting Standard Properties - Setting and Getting Window Sizing Hints - Getting and Setting an XStandardColormap Structure - Parsing Window Geometry - Getting the X Environment Defaults - - X Version 10 Compatibility Functions - - Drawing and Filling Polygons and Curves - Associating User Data with a Value - - The X Version 11 and X Version 10 functions discussed in this - appendix are obsolete, have been superseded by newer X Version - 11 functions, and are maintained for compatibility reasons - only. - -X Version 11 Compatibility Functions - - You can use the X Version 11 compatibility functions to: - * Set standard properties - * Set and get window sizing hints - * Set and get an XStandardColormap structure - * Parse window geometry - * Get X environment defaults - -Setting Standard Properties - - To specify a minimum set of properties describing the simplest - application, use XSetStandardProperties. This function has been - superseded by XSetWMProperties and sets all or portions of the - WM_NAME, WM_ICON_NAME, WM_HINTS, WM_COMMAND, and - WM_NORMAL_HINTS properties. - - XSetStandardProperties(Display *display, Window w, char - *window_name, char *icon_name, Pixmap icon_pixmap, char **argv, - int argc, XSizeHints *hints); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - window_name - - Specifies the window name, which should be a null-terminated - string. - - icon_name - - Specifies the icon name, which should be a null-terminated - string. - - icon_pixmap - - Specifies the bitmap that is to be used for the icon or None. - - argv - - Specifies the application's argument list. - - argc - - Specifies the number of arguments. - - hints - - Specifies a pointer to the size hints for the window in its - normal state. - - The XSetStandardProperties function provides a means by which - simple applications set the most essential properties with a - single call. XSetStandardProperties should be used to give a - window manager some information about your program's - preferences. It should not be used by applications that need to - communicate more information than is possible with - XSetStandardProperties. (Typically, argv is the argv array of - your main program.) If the strings are not in the Host Portable - Character Encoding, the result is implementation-dependent. - - XSetStandardProperties can generate BadAlloc and BadWindow - errors. - -Setting and Getting Window Sizing Hints - - Xlib provides functions that you can use to set or get window - sizing hints. The functions discussed in this section use the - flags and the XSizeHints structure, as defined in the - header file and use the WM_NORMAL_HINTS property. - - To set the size hints for a given window in its normal state, - use XSetNormalHints. This function has been superseded by - XSetWMNormalHints. - - XSetNormalHints(Display *display, Window w, XSizeHints *hints); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - hints - - Specifies a pointer to the size hints for the window in its - normal state. - - The XSetNormalHints function sets the size hints structure for - the specified window. Applications use XSetNormalHints to - inform the window manager of the size or position desirable for - that window. In addition, an application that wants to move or - resize itself should call XSetNormalHints and specify its new - desired location and size as well as making direct Xlib calls - to move or resize. This is because window managers may ignore - redirected configure requests, but they pay attention to - property changes. - - To set size hints, an application not only must assign values - to the appropriate members in the hints structure but also must - set the flags member of the structure to indicate which - information is present and where it came from. A call to - XSetNormalHints is meaningless, unless the flags member is set - to indicate which members of the structure have been assigned - values. - - XSetNormalHints can generate BadAlloc and BadWindow errors. - - To return the size hints for a window in its normal state, use - XGetNormalHints. This function has been superseded by - XGetWMNormalHints. - - Status XGetNormalHints(Display *display, Window w, XSizeHints - *hints_return); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - hints_return - - Returns the size hints for the window in its normal state. - - The XGetNormalHints function returns the size hints for a - window in its normal state. It returns a nonzero status if it - succeeds or zero if the application specified no normal size - hints for this window. - - XGetNormalHints can generate a BadWindow error. - - The next two functions set and read the WM_ZOOM_HINTS property. - - To set the zoom hints for a window, use XSetZoomHints. This - function is no longer supported by the Inter-Client - Communication Conventions Manual. - - XSetZoomHints(Display *display, Window w, XSizeHints *zhints); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - zhints - - Specifies a pointer to the zoom hints. - - Many window managers think of windows in one of three states: - iconic, normal, or zoomed. The XSetZoomHints function provides - the window manager with information for the window in the - zoomed state. - - XSetZoomHints can generate BadAlloc and BadWindow errors. - - To read the zoom hints for a window, use XGetZoomHints. This - function is no longer supported by the Inter-Client - Communication Conventions Manual. - - Status XGetZoomHints(Display *display, Window w, XSizeHints - *zhints_return); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - zhints_return - - Returns the zoom hints. - - The XGetZoomHints function returns the size hints for a window - in its zoomed state. It returns a nonzero status if it succeeds - or zero if the application specified no zoom size hints for - this window. - - XGetZoomHints can generate a BadWindow error. - - To set the value of any property of type WM_SIZE_HINTS, use - XSetSizeHints. This function has been superseded by - XSetWMSizeHints. - - XSetSizeHints(Display *display, Window w, XSizeHints *hints, - Atom property); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - hints - - Specifies a pointer to the size hints. - - property - - Specifies the property name. - - The XSetSizeHints function sets the XSizeHints structure for - the named property and the specified window. This is used by - XSetNormalHints and XSetZoomHints and can be used to set the - value of any property of type WM_SIZE_HINTS. Thus, it may be - useful if other properties of that type get defined. - - XSetSizeHints can generate BadAlloc, BadAtom, and BadWindow - errors. - - To read the value of any property of type WM_SIZE_HINTS, use - XGetSizeHints. This function has been superseded by - XGetWMSizeHints. - - Status XGetSizeHints(Display *display, Window w, XSizeHints - *hints_return, Atom property); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - hints_return - - Returns the size hints. - - property - - Specifies the property name. - - The XGetSizeHints function returns the XSizeHints structure for - the named property and the specified window. This is used by - XGetNormalHints and XGetZoomHints. It also can be used to - retrieve the value of any property of type WM_SIZE_HINTS. Thus, - it may be useful if other properties of that type get defined. - XGetSizeHints returns a nonzero status if a size hint was - defined or zero otherwise. - - XGetSizeHints can generate BadAtom and BadWindow errors. - -Getting and Setting an XStandardColormap Structure - - To get the XStandardColormap structure associated with one of - the described atoms, use XGetStandardColormap. This function - has been superseded by XGetRGBColormaps. - - Status XGetStandardColormap(Display *display, Window w, - XStandardColormap *colormap_return, Atom property); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - colormap_return - - Returns the colormap associated with the specified atom. - - property - - Specifies the property name. - - The XGetStandardColormap function returns the colormap - definition associated with the atom supplied as the property - argument. XGetStandardColormap returns a nonzero status if - successful and zero otherwise. For example, to fetch the - standard GrayScale colormap for a display, you use - XGetStandardColormap with the following syntax: -XGetStandardColormap(dpy, DefaultRootWindow(dpy), &cmap, XA_RGB_GRAY_MAP -); - - See section 14.3 for the semantics of standard colormaps. - - XGetStandardColormap can generate BadAtom and BadWindow errors. - - To set a standard colormap, use XSetStandardColormap. This - function has been superseded by XSetRGBColormaps. - - XSetStandardColormap(Display *display, Window w, - XStandardColormap *colormap, Atom property); - - display - - Specifies the connection to the X server. - - w - - Specifies the window. - - colormap - - Specifies the colormap. - - property - - Specifies the property name. - - The XSetStandardColormap function usually is only used by - window or session managers. - - XSetStandardColormap can generate BadAlloc, BadAtom, - BadDrawable, and BadWindow errors. - -Parsing Window Geometry - - To parse window geometry given a user-specified position and a - default position, use XGeometry. This function has been - superseded by XWMGeometry. - - int XGeometry(Display *display, int screen, char *position, - char *default_position, unsigned int bwidth, unsigned int - fwidth, unsigned int fheight, int xadder, int yadder, int - *x_return, int *y_return, int *width_return, int - *height_return); - - display - - Specifies the connection to the X server. - - screen - - Specifies the screen. - - position - - default_position - - Specify the geometry specifications. - - bwidth - - Specifies the border width. - - fheight - - fwidth - - Specify the font height and width in pixels (increment size). - - xadder - - yadder - - Specify additional interior padding needed in the window. - - x_return - - y_return - - Return the x and y offsets. - - width_return - - height_return - - Return the width and height determined. - - You pass in the border width (bwidth), size of the increments - fwidth and fheight (typically font width and height), and any - additional interior space (xadder and yadder) to make it easy - to compute the resulting size. The XGeometry function returns - the position the window should be placed given a position and a - default position. XGeometry determines the placement of a - window using a geometry specification as specified by - XParseGeometry and the additional information about the window. - Given a fully qualified default geometry specification and an - incomplete geometry specification, XParseGeometry returns a - bitmask value as defined above in the XParseGeometry call, by - using the position argument. - - The returned width and height will be the width and height - specified by default_position as overridden by any - user-specified position. They are not affected by fwidth, - fheight, xadder, or yadder. The x and y coordinates are - computed by using the border width, the screen width and - height, padding as specified by xadder and yadder, and the - fheight and fwidth times the width and height from the geometry - specifications. - -Getting the X Environment Defaults - - The XGetDefault function provides a primitive interface to the - resource manager facilities discussed in chapter 15. It is only - useful in very simple applications. - - char *XGetDefault(Display *display, char *program, char - *option); - - display - - Specifies the connection to the X server. - - program - - Specifies the program name for the Xlib defaults (usually - argv[0] of the main program). - - option - - Specifies the option name. - - The XGetDefault function returns the value of the resource - prog.option, where prog is the program argument with the - directory prefix removed and option must be a single component. - Note that multilevel resources cannot be used with XGetDefault. - The class "Program.Name" is always used for the resource - lookup. If the specified option name does not exist for this - program, XGetDefault returns NULL. The strings returned by - XGetDefault are owned by Xlib and should not be modified or - freed by the client. - - If a database has been set with XrmSetDatabase, that database - is used for the lookup. Otherwise, a database is created and is - set in the display (as if by calling XrmSetDatabase). The - database is created in the current locale. To create a - database, XGetDefault uses resources from the RESOURCE_MANAGER - property on the root window of screen zero. If no such property - exists, a resource file in the user's home directory is used. - On a POSIX-conformant system, this file is "$HOME/.Xdefaults". - After loading these defaults, XGetDefault merges additional - defaults specified by the XENVIRONMENT environment variable. If - XENVIRONMENT is defined, it contains a full path name for the - additional resource file. If XENVIRONMENT is not defined, - XGetDefault looks for "$HOME/.Xdefaults-name" , where name - specifies the name of the machine on which the application is - running. - -X Version 10 Compatibility Functions - - You can use the X Version 10 compatibility functions to: - * Draw and fill polygons and curves - * Associate user data with a value - -Drawing and Filling Polygons and Curves - - Xlib provides functions that you can use to draw or fill - arbitrary polygons or curves. These functions are provided - mainly for compatibility with X Version 10 and have no server - support. That is, they call other Xlib functions, not the - server directly. Thus, if you just have straight lines to draw, - using XDrawLines or XDrawSegments is much faster. - - The functions discussed here provide all the functionality of - the X Version 10 functions XDraw, XDrawFilled, XDrawPatterned, - XDrawDashed, and XDrawTiled. They are as compatible as possible - given X Version 11's new line-drawing functions. One thing to - note, however, is that VertexDrawLastPoint is no longer - supported. Also, the error status returned is the opposite of - what it was under X Version 10 (this is the X Version 11 - standard error status). XAppendVertex and XClearVertexFlag from - X Version 10 also are not supported. - - Just how the graphics context you use is set up actually - determines whether you get dashes or not, and so on. Lines are - properly joined if they connect and include the closing of a - closed figure (see XDrawLines). The functions discussed here - fail (return zero) only if they run out of memory or are passed - a Vertex list that has a Vertex with VertexStartClosed set that - is not followed by a Vertex with VertexEndClosed set. - - To achieve the effects of the X Version 10 XDraw, XDrawDashed, - and XDrawPatterned, use XDraw. - - #include - - Status XDraw(Display *display, Drawable d, GC gc, Vertex - *vlist, int vcount); - - display - - Specifies the connection to the X server. - - d - - Specifies the drawable. - - gc - - Specifies the GC. - - vlist - - Specifies a pointer to the list of vertices that indicate what - to draw. - - vcount - - Specifies how many vertices are in vlist. - - The XDraw function draws an arbitrary polygon or curve. The - figure drawn is defined by the specified list of vertices - (vlist). The points are connected by lines as specified in the - flags in the vertex structure. - - Each Vertex, as defined in , is a structure with the - following members: -typedef struct _Vertex { - short x,y; - unsigned short flags; -} Vertex; - - The x and y members are the coordinates of the vertex that are - relative to either the upper left inside corner of the drawable - (if VertexRelative is zero) or the previous vertex (if - VertexRelative is one). - - The flags, as defined in , are as follows: -VertexRelative 0x0001 /* else absolute */ -VertexDontDraw 0x0002 /* else draw */ -VertexCurved 0x0004 /* else straight */ -VertexStartClosed 0x0008 /* else not */ -VertexEndClosed 0x0010 /* else not */ - - * If VertexRelative is not set, the coordinates are absolute - (that is, relative to the drawable's origin). The first - vertex must be an absolute vertex. - * If VertexDontDraw is one, no line or curve is drawn from - the previous vertex to this one. This is analogous to - picking up the pen and moving to another place before - drawing another line. - * If VertexCurved is one, a spline algorithm is used to draw - a smooth curve from the previous vertex through this one to - the next vertex. Otherwise, a straight line is drawn from - the previous vertex to this one. It makes sense to set - VertexCurved to one only if a previous and next vertex are - both defined (either explicitly in the array or through the - definition of a closed curve). - * It is permissible for VertexDontDraw bits and VertexCurved - bits both to be one. This is useful if you want to define - the previous point for the smooth curve but do not want an - actual curve drawing to start until this point. - * If VertexStartClosed is one, then this point marks the - beginning of a closed curve. This vertex must be followed - later in the array by another vertex whose effective - coordinates are identical and that has a VertexEndClosed - bit of one. The points in between form a cycle to determine - predecessor and successor vertices for the spline - algorithm. - - This function uses these GC components: function, plane-mask, - line-width, line-style, cap-style, join-style, fill-style, - subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. It - also uses these GC mode-dependent components: foreground, - background, tile, stipple, tile-stipple-x-origin, - tile-stipple-y-origin, dash-offset, and dash-list. - - To achieve the effects of the X Version 10 XDrawTiled and - XDrawFilled, use XDrawFilled. - - #include - - Status XDrawFilled(Display *display, Drawable d, GC gc, Vertex - *vlist, int vcount); - - display - - Specifies the connection to the X server. - - d - - Specifies the drawable. - - gc - - Specifies the GC. - - vlist - - Specifies a pointer to the list of vertices that indicate what - to draw. - - vcount - - Specifies how many vertices are in vlist. - - The XDrawFilled function draws arbitrary polygons or curves and - then fills them. - - This function uses these GC components: function, plane-mask, - line-width, line-style, cap-style, join-style, fill-style, - subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. It - also uses these GC mode-dependent components: foreground, - background, tile, stipple, tile-stipple-x-origin, - tile-stipple-y-origin, dash-offset, dash-list, fill-style, and - fill-rule. - -Associating User Data with a Value - - These functions have been superseded by the context management - functions (see section 16.10). It is often necessary to - associate arbitrary information with resource IDs. Xlib - provides the XAssocTable functions that you can use to make - such an association. Application programs often need to be able - to easily refer to their own data structures when an event - arrives. The XAssocTable system provides users of the X library - with a method for associating their own data structures with X - resources (Pixmaps, Fonts, Windows, and so on). - - An XAssocTable can be used to type X resources. For example, - the user may want to have three or four types of windows, each - with different properties. This can be accomplished by - associating each X window ID with a pointer to a window - property data structure defined by the user. A generic type has - been defined in the X library for resource IDs. It is called an - XID. - - There are a few guidelines that should be observed when using - an XAssocTable : - * All XIDs are relative to the specified display. - * Because of the hashing scheme used by the association - mechanism, the following rules for determining the size of - a XAssocTable should be followed. Associations will be made - and looked up more efficiently if the table size (number of - buckets in the hashing system) is a power of two and if - there are not more than 8 XIDs per bucket. - - To return a pointer to a new XAssocTable, use - XCreateAssocTable. - - XAssocTable *XCreateAssocTable(int size); - - size - - Specifies the number of buckets in the hash system of - XAssocTable. - - The size argument specifies the number of buckets in the hash - system of XAssocTable. For reasons of efficiency the number of - buckets should be a power of two. Some size suggestions might - be: use 32 buckets per 100 objects, and a reasonable maximum - number of objects per buckets is 8. If an error allocating - memory for the XAssocTable occurs, a NULL pointer is returned. - - To create an entry in a given XAssocTable, use XMakeAssoc. - - XMakeAssoc(Display *display, XAssocTable *table, XID x_id, char - *data); - - display - - Specifies the connection to the X server. - - table - - Specifies the assoc table. - - x_id - - Specifies the X resource ID. - - data - - Specifies the data to be associated with the X resource ID. - - The XMakeAssoc function inserts data into an XAssocTable keyed - on an XID. Data is inserted into the table only once. Redundant - inserts are ignored. The queue in each association bucket is - sorted from the lowest XID to the highest XID. - - To obtain data from a given XAssocTable, use XLookUpAssoc. - - char *XLookUpAssoc(Display *display, XAssocTable *table, XID - x_id); - - display - - Specifies the connection to the X server. - - table - - Specifies the assoc table. - - x_id - - Specifies the X resource ID. - - The XLookUpAssoc function retrieves the data stored in an - XAssocTable by its XID. If an appropriately matching XID can be - found in the table, XLookUpAssoc returns the data associated - with it. If the x_id cannot be found in the table, it returns - NULL. - - To delete an entry from a given XAssocTable, use XDeleteAssoc. - - XDeleteAssoc(Display *display, XAssocTable *table, XID x_id); - - display - - Specifies the connection to the X server. - - table - - Specifies the assoc table. - - x_id - - Specifies the X resource ID. - - The XDeleteAssoc function deletes an association in an - XAssocTable keyed on its XID. Redundant deletes (and deletes of - nonexistent XIDs) are ignored. Deleting associations in no way - impairs the performance of an XAssocTable. - - To free the memory associated with a given XAssocTable, use - XDestroyAssocTable. - - XDestroyAssocTable(XAssocTable *table); - - table - - Specifies the assoc table. - -Glossary - - Access control list - X maintains a list of hosts from which client programs - can be run. By default, only programs on the local host - and hosts specified in an initial list read by the - server can use the display. This access control list can - be changed by clients on the local host. Some server - implementations can also implement other authorization - mechanisms in addition to or in place of this mechanism. - The action of this mechanism can be conditional based on - the authorization protocol name and data received by the - server at connection setup. - - Active grab - A grab is active when the pointer or keyboard is - actually owned by the single grabbing client. - - Ancestors - If W is an inferior of A, then A is an ancestor of W. - - Atom - An atom is a unique ID corresponding to a string name. - Atoms are used to identify properties, types, and - selections. - - Background - An InputOutput window can have a background, which is - defined as a pixmap. When regions of the window have - their contents lost or invalidated, the server - automatically tiles those regions with the background. - - Backing store - When a server maintains the contents of a window, the - pixels saved off-screen are known as a backing store. - - Base font name - A font name used to select a family of fonts whose - members may be encoded in various charsets. The - CharSetRegistry and CharSetEncoding fields of an XLFD - name identify the charset of the font. A base font name - may be a full XLFD name, with all fourteen '-' - delimiters, or an abbreviated XLFD name containing only - the first 12 fields of an XLFD name, up to but not - including CharSetRegistry, with or without the - thirteenth '-', or a non-XLFD name. Any XLFD fields may - contain wild cards. - - When creating an XFontSet, Xlib accepts from the client - a list of one or more base font names which select one - or more font families. They are combined with charset - names obtained from the encoding of the locale to load - the fonts required to render text. - - Bit gravity - When a window is resized, the contents of the window are - not necessarily discarded. It is possible to request - that the server relocate the previous contents to some - region of the window (though no guarantees are made). - This attraction of window contents for some location of - a window is known as bit gravity. - - Bit plane - When a pixmap or window is thought of as a stack of - bitmaps, each bitmap is called a bit plane or plane. - - Bitmap - A bitmap is a pixmap of depth one. - - Border - An InputOutput window can have a border of equal - thickness on all four sides of the window. The contents - of the border are defined by a pixmap, and the server - automatically maintains the contents of the border. - Exposure events are never generated for border regions. - - Button grabbing - Buttons on the pointer can be passively grabbed by a - client. When the button is pressed, the pointer is then - actively grabbed by the client. - - Byte order - For image (pixmap/bitmap) data, the server defines the - byte order, and clients with different native byte - ordering must swap bytes as necessary. For all other - parts of the protocol, the client defines the byte - order, and the server swaps bytes as necessary. - - Character - A member of a set of elements used for the organization, - control, or representation of text (ISO2022, as adapted - by XPG3). Note that in ISO2022 terms, a character is not - bound to a coded value until it is identified as part of - a coded character set. - - Character glyph - The abstract graphical symbol for a character. Character - glyphs may or may not map one-to-one to font glyphs, and - may be context-dependent, varying with the adjacent - characters. Multiple characters may map to a single - character glyph. - - Character set - A collection of characters. - - Charset - An encoding with a uniform, state-independent mapping - from characters to codepoints. A coded character set. - - For display in X, there can be a direct mapping from a - charset to one font, if the width of all characters in - the charset is either one or two bytes. A text string - encoded in an encoding such as Shift-JIS cannot be - passed directly to the X server, because the text - imaging requests accept only single-width charsets - (either 8 or 16 bits). Charsets which meet these - restrictions can serve as ``font charsets''. Font - charsets strictly speaking map font indices to font - glyphs, not characters to character glyphs. - - Note that a single font charset is sometimes used as the - encoding of a locale, for example, ISO8859-1. - - Children - The children of a window are its first-level subwindows. - - Class - Windows can be of different classes or types. See the - entries for InputOnly and InputOutput windows for - further information about valid window types. - - Client - An application program connects to the window system - server by some interprocess communication (IPC) path, - such as a TCP connection or a shared memory buffer. This - program is referred to as a client of the window system - server. More precisely, the client is the IPC path - itself. A program with multiple paths open to the server - is viewed as multiple clients by the protocol. Resource - lifetimes are controlled by connection lifetimes, not by - program lifetimes. - - Clipping region - In a graphics context, a bitmap or list of rectangles - can be specified to restrict output to a particular - region of the window. The image defined by the bitmap or - rectangles is called a clipping region. - - Coded character - A character bound to a codepoint. - - Coded character set - A set of unambiguous rules that establishes a character - set and the one-to-one relationship between each - character of the set and its bit representation. - (ISO2022, as adapted by XPG3) A definition of a - one-to-one mapping of a set of characters to a set of - codepoints. - - Codepoint - The coded representation of a single character in a - coded character set. - - Colormap - A colormap consists of a set of entries defining color - values. The colormap associated with a window is used to - display the contents of the window; each pixel value - indexes the colormap to produce an RGB value that drives - the guns of a monitor. Depending on hardware - limitations, one or more colormaps can be installed at - one time so that windows associated with those maps - display with true colors. - - Connection - The IPC path between the server and client program is - known as a connection. A client program typically (but - not necessarily) has one connection to the server over - which requests and events are sent. - - Containment - A window contains the pointer if the window is viewable - and the hotspot of the cursor is within a visible region - of the window or a visible region of one of its - inferiors. The border of the window is included as part - of the window for containment. The pointer is in a - window if the window contains the pointer but no - inferior contains the pointer. - - Coordinate system - The coordinate system has X horizontal and Y vertical, - with the origin [0, 0] at the upper left. Coordinates - are integral and coincide with pixel centers. Each - window and pixmap has its own coordinate system. For a - window, the origin is inside the border at the inside - upper-left corner. - - Cursor - A cursor is the visible shape of the pointer on a - screen. It consists of a hotspot, a source bitmap, a - shape bitmap, and a pair of colors. The cursor defined - for a window controls the visible appearance when the - pointer is in that window. - - Depth - The depth of a window or pixmap is the number of bits - per pixel it has. The depth of a graphics context is the - depth of the drawables it can be used in conjunction - with graphics output. - - Device - Keyboards, mice, tablets, track-balls, button boxes, and - so on are all collectively known as input devices. - Pointers can have one or more buttons (the most common - number is three). The core protocol only deals with two - devices: the keyboard and the pointer. - - DirectColor - DirectColor is a class of colormap in which a pixel - value is decomposed into three separate subfields for - indexing. The first subfield indexes an array to produce - red intensity values. The second subfield indexes a - second array to produce blue intensity values. The third - subfield indexes a third array to produce green - intensity values. The RGB (red, green, and blue) values - in the colormap entry can be changed dynamically. - - Display - A server, together with its screens and input devices, - is called a display. The Xlib Display structure contains - all information about the particular display and its - screens as well as the state that Xlib needs to - communicate with the display over a particular - connection. - - Drawable - Both windows and pixmaps can be used as sources and - destinations in graphics operations. These windows and - pixmaps are collectively known as drawables. However, an - InputOnly window cannot be used as a source or - destination in a graphics operation. - - Encoding - A set of unambiguous rules that establishes a character - set and a relationship between the characters and their - representations. The character set does not have to be - fixed to a finite pre-defined set of characters. The - representations do not have to be of uniform length. - Examples are an ISO2022 graphic set, a state-independent - or state-dependent combination of graphic sets, possibly - including control sets, and the X Compound Text - encoding. - - In X, encodings are identified by a string which appears - as: the CharSetRegistry and CharSetEncoding components - of an XLFD name; the name of a charset of the locale for - which a font could not be found; or an atom which - identifies the encoding of a text property or which - names an encoding for a text selection target type. - Encoding names should be composed of characters from the - X Portable Character Set. - - Escapement - The escapement of a string is the distance in pixels in - the primary draw direction from the drawing origin to - the origin of the next character (that is, the one - following the given string) to be drawn. - - Event - Clients are informed of information asynchronously by - means of events. These events can be either - asynchronously generated from devices or generated as - side effects of client requests. Events are grouped into - types. The server never sends an event to a client - unless the client has specifically asked to be informed - of that type of event. However, clients can force events - to be sent to other clients. Events are typically - reported relative to a window. - - Event mask - Events are requested relative to a window. The set of - event types a client requests relative to a window is - described by using an event mask. - - Event propagation - Device-related events propagate from the source window - to ancestor windows until some client has expressed - interest in handling that type of event or until the - event is discarded explicitly. - - Event source - The deepest viewable window that the pointer is in is - called the source of a device-related event. - - Event synchronization - There are certain race conditions possible when - demultiplexing device events to clients (in particular, - deciding where pointer and keyboard events should be - sent when in the middle of window management - operations). The event synchronization mechanism allows - synchronous processing of device events. - - Exposure event - Servers do not guarantee to preserve the contents of - windows when windows are obscured or reconfigured. - Exposure events are sent to clients to inform them when - contents of regions of windows have been lost. - - Extension - Named extensions to the core protocol can be defined to - extend the system. Extensions to output requests, - resources, and event types are all possible and - expected. - - Font - A font is an array of glyphs (typically characters). The - protocol does no translation or interpretation of - character sets. The client simply indicates values used - to index the glyph array. A font contains additional - metric information to determine interglyph and interline - spacing. - - Font glyph - The abstract graphical symbol for an index into a font. - - Frozen events - Clients can freeze event processing during keyboard and - pointer grabs. - - GC - GC is an abbreviation for graphics context. See Graphics - context. - - Glyph - An identified abstract graphical symbol independent of - any actual image. (ISO/IEC/DIS 9541-1) An abstract - visual representation of a graphic character, not bound - to a codepoint. - - Glyph image - An image of a glyph, as obtained from a glyph - representation displayed on a presentation surface. - (ISO/IEC/DIS 9541-1) - - Grab - Keyboard keys, the keyboard, pointer buttons, the - pointer, and the server can be grabbed for exclusive use - by a client. In general, these facilities are not - intended to be used by normal applications but are - intended for various input and window managers to - implement various styles of user interfaces. - - Graphics context - Various information for graphics output is stored in a - graphics context (GC), such as foreground pixel, - background pixel, line width, clipping region, and so - on. A graphics context can only be used with drawables - that have the same root and the same depth as the - graphics context. - - Gravity - The contents of windows and windows themselves have a - gravity, which determines how the contents move when a - window is resized. See Bit gravity and Window gravity. - - GrayScale - GrayScale can be viewed as a degenerate case of - PseudoColor, in which the red, green, and blue values in - any given colormap entry are equal and thus, produce - shades of gray. The gray values can be changed - dynamically. - - Host Portable Character Encoding - The encoding of the X Portable Character Set on the - host. The encoding itself is not defined by this - standard, but the encoding must be the same in all - locales supported by Xlib on the host. If a string is - said to be in the Host Portable Character Encoding, then - it only contains characters from the X Portable - Character Set, in the host encoding. - - Hotspot - A cursor has an associated hotspot, which defines the - point in the cursor corresponding to the coordinates - reported for the pointer. - - Identifier - An identifier is a unique value associated with a - resource that clients use to name that resource. The - identifier can be used over any connection to name the - resource. - - Inferiors - The inferiors of a window are all of the subwindows - nested below it: the children, the children's children, - and so on. - - Input focus - The input focus is usually a window defining the scope - for processing of keyboard input. If a generated - keyboard event usually would be reported to this window - or one of its inferiors, the event is reported as usual. - Otherwise, the event is reported with respect to the - focus window. The input focus also can be set such that - all keyboard events are discarded and such that the - focus window is dynamically taken to be the root window - of whatever screen the pointer is on at each keyboard - event. - - Input manager - Control over keyboard input is typically provided by an - input manager client, which usually is part of a window - manager. - - InputOnly window - An InputOnly window is a window that cannot be used for - graphics requests. InputOnly windows are invisible and - are used to control such things as cursors, input event - generation, and grabbing. InputOnly windows cannot have - InputOutput windows as inferiors. - - InputOutput window - An InputOutput window is the normal kind of window that - is used for both input and output. InputOutput windows - can have both InputOutput and InputOnly windows as - inferiors. - - Internationalization - The process of making software adaptable to the - requirements of different native languages, local - customs, and character string encodings. Making a - computer program adaptable to different locales without - program source modifications or recompilation. - - ISO2022 - ISO standard for code extension techniques for 7-bit and - 8-bit coded character sets. - - Key grabbing - Keys on the keyboard can be passively grabbed by a - client. When the key is pressed, the keyboard is then - actively grabbed by the client. - - Keyboard grabbing - A client can actively grab control of the keyboard, and - key events will be sent to that client rather than the - client the events would normally have been sent to. - - Keysym - An encoding of a symbol on a keycap on a keyboard. - - Latin-1 - The coded character set defined by the ISO8859-1 - standard. - - Latin Portable Character Encoding - The encoding of the X Portable Character Set using the - Latin-1 codepoints plus ASCII control characters. If a - string is said to be in the Latin Portable Character - Encoding, then it only contains characters from the X - Portable Character Set, not all of Latin-1. - - Locale - The international environment of a computer program - defining the ``localized'' behavior of that program at - run-time. This information can be established from one - or more sets of localization data. ANSI C defines - locale-specific processing by C system library calls. - See ANSI C and the X/Open Portability Guide - specifications for more details. In this specification, - on implementations that conform to the ANSI C library, - the ``current locale'' is the current setting of the - LC_CTYPE setlocale category. Associated with each locale - is a text encoding. When text is processed in the - context of a locale, the text must be in the encoding of - the locale. The current locale affects Xlib in its: - - + Encoding and processing of input method text - + Encoding of resource files and values - + Encoding and imaging of text strings - + Encoding and decoding for inter-client text - communication - - Locale name - The identifier used to select the desired locale for the - host C library and X library functions. On ANSI C - library compliant systems, the locale argument to the - setlocale function. - - Localization - The process of establishing information within a - computer system specific to the operation of particular - native languages, local customs and coded character - sets. (XPG3) - - Mapped - A window is said to be mapped if a map call has been - performed on it. Unmapped windows and their inferiors - are never viewable or visible. - - Modifier keys - Shift, Control, Meta, Super, Hyper, Alt, Compose, Apple, - CapsLock, ShiftLock, and similar keys are called - modifier keys. - - Monochrome - Monochrome is a special case of StaticGray in which - there are only two colormap entries. - - Multibyte - A character whose codepoint is stored in more than one - byte; any encoding which can contain multibyte - characters; text in a multibyte encoding. The ``char *'' - null-terminated string datatype in ANSI C. Note that - references in this document to multibyte strings imply - only that the strings may contain multibyte characters. - - Obscure - A window is obscured if some other window obscures it. A - window can be partially obscured and so still have - visible regions. Window A obscures window B if both are - viewable InputOutput windows, if A is higher in the - global stacking order, and if the rectangle defined by - the outside edges of A intersects the rectangle defined - by the outside edges of B. Note the distinction between - obscures and occludes. Also note that window borders are - included in the calculation. - - Occlude - A window is occluded if some other window occludes it. - Window A occludes window B if both are mapped, if A is - higher in the global stacking order, and if the - rectangle defined by the outside edges of A intersects - the rectangle defined by the outside edges of B. Note - the distinction between occludes and obscures. Also note - that window borders are included in the calculation and - that InputOnly windows never obscure other windows but - can occlude other windows. - - Padding - Some padding bytes are inserted in the data stream to - maintain alignment of the protocol requests on natural - boundaries. This increases ease of portability to some - machine architectures. - - Parent window - If C is a child of P, then P is the parent of C. - - Passive grab - Grabbing a key or button is a passive grab. The grab - activates when the key or button is actually pressed. - - Pixel value - A pixel is an N-bit value, where N is the number of bit - planes used in a particular window or pixmap (that is, - is the depth of the window or pixmap). A pixel in a - window indexes a colormap to derive an actual color to - be displayed. - - Pixmap - A pixmap is a three-dimensional array of bits. A pixmap - is normally thought of as a two-dimensional array of - pixels, where each pixel can be a value from 0 to 2^N-1, - and where N is the depth (z axis) of the pixmap. A - pixmap can also be thought of as a stack of N bitmaps. A - pixmap can only be used on the screen that it was - created in. - - Plane - When a pixmap or window is thought of as a stack of - bitmaps, each bitmap is called a plane or bit plane. - - Plane mask - Graphics operations can be restricted to only affect a - subset of bit planes of a destination. A plane mask is a - bit mask describing which planes are to be modified. The - plane mask is stored in a graphics context. - - Pointer - The pointer is the pointing device currently attached to - the cursor and tracked on the screens. - - Pointer grabbing - A client can actively grab control of the pointer. Then - button and motion events will be sent to that client - rather than the client the events would normally have - been sent to. - - Pointing device - A pointing device is typically a mouse, tablet, or some - other device with effective dimensional motion. The core - protocol defines only one visible cursor, which tracks - whatever pointing device is attached as the pointer. - - POSIX - Portable Operating System Interface, ISO/IEC 9945-1 - (IEEE Std 1003.1). - - POSIX Portable Filename Character Set - The set of 65 characters which can be used in naming - files on a POSIX-compliant host that are correctly - processed in all locales. The set is: - - a..z A..Z 0..9 ._- - - Property - Windows can have associated properties that consist of a - name, a type, a data format, and some data. The protocol - places no interpretation on properties. They are - intended as a general-purpose naming mechanism for - clients. For example, clients might use properties to - share information such as resize hints, program names, - and icon formats with a window manager. - - Property list - The property list of a window is the list of properties - that have been defined for the window. - - PseudoColor - PseudoColor is a class of colormap in which a pixel - value indexes the colormap entry to produce an - independent RGB value; that is, the colormap is viewed - as an array of triples (RGB values). The RGB values can - be changed dynamically. - - Rectangle - A rectangle specified by [x,y,w,h] has an infinitely - thin outline path with corners at [x,y], [x+w,y], - [x+w,y+h], and [x, y+h]. When a rectangle is filled, the - lower-right edges are not drawn. For example, if w=h=0, - nothing would be drawn. For w=h=1, a single pixel would - be drawn. - - Redirecting control - Window managers (or client programs) may enforce window - layout policy in various ways. When a client attempts to - change the size or position of a window, the operation - may be redirected to a specified client rather than the - operation actually being performed. - - Reply - Information requested by a client program using the X - protocol is sent back to the client with a reply. Both - events and replies are multiplexed on the same - connection. Most requests do not generate replies, but - some requests generate multiple replies. - - Request - A command to the server is called a request. It is a - single block of data sent over a connection. - - Resource - Windows, pixmaps, cursors, fonts, graphics contexts, and - colormaps are known as resources. They all have unique - identifiers associated with them for naming purposes. - The lifetime of a resource usually is bounded by the - lifetime of the connection over which the resource was - created. - - RGB values - RGB values are the red, green, and blue intensity values - that are used to define a color. These values are always - represented as 16-bit, unsigned numbers, with 0 the - minimum intensity and 65535 the maximum intensity. The X - server scales these values to match the display - hardware. - - Root - The root of a pixmap or graphics context is the same as - the root of whatever drawable was used when the pixmap - or GC was created. The root of a window is the root - window under which the window was created. - - Root window - Each screen has a root window covering it. The root - window cannot be reconfigured or unmapped, but otherwise - it acts as a full-fledged window. A root window has no - parent. - - Save set - The save set of a client is a list of other clients' - windows that, if they are inferiors of one of the - client's windows at connection close, should not be - destroyed and that should be remapped if currently - unmapped. Save sets are typically used by window - managers to avoid lost windows if the manager should - terminate abnormally. - - Scanline - A scanline is a list of pixel or bit values viewed as a - horizontal row (all values having the same y coordinate) - of an image, with the values ordered by increasing the x - coordinate. - - Scanline order - An image represented in scanline order contains - scanlines ordered by increasing the y coordinate. - - Screen - A server can provide several independent screens, which - typically have physically independent monitors. This - would be the expected configuration when there is only a - single keyboard and pointer shared among the screens. A - Screen structure contains the information about that - screen and is linked to the Display structure. - - Selection - A selection can be thought of as an indirect property - with dynamic type. That is, rather than having the - property stored in the X server, it is maintained by - some client (the owner). A selection is global and is - thought of as belonging to the user and being maintained - by clients, rather than being private to a particular - window subhierarchy or a particular set of clients. When - a client asks for the contents of a selection, it - specifies a selection target type, which can be used to - control the transmitted representation of the contents. - For example, if the selection is ``the last thing the - user clicked on,'' and that is currently an image, then - the target type might specify whether the contents of - the image should be sent in XY format or Z format. - - The target type can also be used to control the class of - contents transmitted; for example, asking for the - ``looks'' (fonts, line spacing, indentation, and so - forth) of a paragraph selection, rather than the text of - the paragraph. The target type can also be used for - other purposes. The protocol does not constrain the - semantics. - - Server - The server, which is also referred to as the X server, - provides the basic windowing mechanism. It handles IPC - connections from clients, multiplexes graphics requests - onto the screens, and demultiplexes input back to the - appropriate clients. - - Server grabbing - The server can be grabbed by a single client for - exclusive use. This prevents processing of any requests - from other client connections until the grab is - completed. This is typically only a transient state for - such things as rubber-banding, pop-up menus, or - executing requests indivisibly. - - Shift sequence - ISO2022 defines control characters and escape sequences - which temporarily (single shift) or permanently (locking - shift) cause a different character set to be in effect - (``invoking'' a character set). - - Sibling - Children of the same parent window are known as sibling - windows. - - Stacking order - Sibling windows, similar to sheets of paper on a desk, - can stack on top of each other. Windows above both - obscure and occlude lower windows. The relationship - between sibling windows is known as the stacking order. - - State-dependent encoding - An encoding in which an invocation of a charset can - apply to multiple characters in sequence. A - state-dependent encoding begins in an ``initial state'' - and enters other ``shift states'' when specific ``shift - sequences'' are encountered in the byte sequence. In - ISO2022 terms, this means use of locking shifts, not - single shifts. - - State-independent encoding - Any encoding in which the invocations of the charsets - are fixed, or span only a single character. In ISO2022 - terms, this means use of at most single shifts, not - locking shifts. - - StaticColor - StaticColor can be viewed as a degenerate case of - PseudoColor in which the RGB values are predefined and - read-only. - - StaticGray - StaticGray can be viewed as a degenerate case of - GrayScale in which the gray values are predefined and - read-only. The values are typically linear or - near-linear increasing ramps. - - Status - Many Xlib functions return a success status. If the - function does not succeed, however, its arguments are - not disturbed. - - Stipple - A stipple pattern is a bitmap that is used to tile a - region to serve as an additional clip mask for a fill - operation with the foreground color. - - STRING encoding - Latin-1, plus tab and newline. - - String Equivalence - Two ISO Latin-1 STRING8 values are considered equal if - they are the same length and if corresponding bytes are - either equal or are equivalent as follows: decimal - values 65 to 90 inclusive (characters ``A'' to ``Z'') - are pairwise equivalent to decimal values 97 to 122 - inclusive (characters ``a'' to ``z''), decimal values - 192 to 214 inclusive (characters ``A grave'' to ``O - diaeresis'') are pairwise equivalent to decimal values - 224 to 246 inclusive (characters ``a grave'' to ``o - diaeresis''), and decimal values 216 to 222 inclusive - (characters ``O oblique'' to ``THORN'') are pairwise - equivalent to decimal values 246 to 254 inclusive - (characters ``o oblique'' to ``thorn''). - - Tile - A pixmap can be replicated in two dimensions to tile a - region. The pixmap itself is also known as a tile. - - Timestamp - A timestamp is a time value expressed in milliseconds. - It is typically the time since the last server reset. - Timestamp values wrap around (after about 49.7 days). - The server, given its current time is represented by - timestamp T, always interprets timestamps from clients - by treating half of the timestamp space as being earlier - in time than T and half of the timestamp space as being - later in time than T. One timestamp value, represented - by the constant CurrentTime, is never generated by the - server. This value is reserved for use in requests to - represent the current server time. - - TrueColor - TrueColor can be viewed as a degenerate case of - DirectColor in which the subfields in the pixel value - directly encode the corresponding RGB values. That is, - the colormap has predefined read-only RGB values. The - values are typically linear or near-linear increasing - ramps. - - Type - A type is an arbitrary atom used to identify the - interpretation of property data. Types are completely - uninterpreted by the server. They are solely for the - benefit of clients. X predefines type atoms for many - frequently used types, and clients also can define new - types. - - Viewable - A window is viewable if it and all of its ancestors are - mapped. This does not imply that any portion of the - window is actually visible. Graphics requests can be - performed on a window when it is not viewable, but - output will not be retained unless the server is - maintaining backing store. - - Visible - A region of a window is visible if someone looking at - the screen can actually see it; that is, the window is - viewable and the region is not occluded by any other - window. - - Whitespace - Any spacing character. On implementations that conform - to the ANSI C library, whitespace is any character for - which isspace returns true. - - Window gravity - When windows are resized, subwindows may be repositioned - automatically relative to some position in the window. - This attraction of a subwindow to some part of its - parent is known as window gravity. - - Window manager - Manipulation of windows on the screen and much of the - user interface (policy) is typically provided by a - window manager client. - - X Portable Character Set - A basic set of 97 characters which are assumed to exist - in all locales supported by Xlib. This set contains the - following characters: - - a..z A..Z 0..9 - !"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~ - , , and - - - This is the left/lower half (also called the G0 set) of - the graphic character set of ISO8859-1 plus , - , and . It is also the set of graphic - characters in 7-bit ASCII plus the same three control - characters. The actual encoding of these characters on - the host is system dependent; see the Host Portable - Character Encoding. - - XLFD - The X Logical Font Description Conventions that define a - standard syntax for structured font names. - - XY format - The data for a pixmap is said to be in XY format if it - is organized as a set of bitmaps representing individual - bit planes with the planes appearing from - most-significant to least-significant bit order. - - Z format - The data for a pixmap is said to be in Z format if it is - organized as a set of pixel values in scanline order. - -Index - -Symbols - - _XAllocScratch, Allocating and Deallocating Memory - _XAllocTemp, Allocating and Deallocating Memory - _Xdebug, Enabling or Disabling Synchronization - _XFlushGCCache, GC Caching - _XFreeTemp, Allocating and Deallocating Memory - _XReply, Replies - _XSetLastRequestRead, Hooks into the Library - -A - - Access control list, Controlling Host Access, Glossary - Active grab, Pointer Grabbing, Glossary - Allocation, Allocating and Freeing Color Cells, Allocating and - Freeing Color Cells, Allocating and Freeing Color Cells, - Allocating and Freeing Color Cells, Allocating and - Freeing Color Cells, Allocating and Freeing Color Cells, - Allocating and Freeing Color Cells - - colormap, Allocating and Freeing Color Cells - read-only colormap cells, Allocating and Freeing Color - Cells, Allocating and Freeing Color Cells, - Allocating and Freeing Color Cells, Allocating and - Freeing Color Cells - - read/write colormap cells, Allocating and Freeing Color - Cells - - read/write colormap planes, Allocating and Freeing Color - Cells - - AllPlanes, Display Macros - Ancestors, Glossary - Arcs, Drawing Single and Multiple Arcs, Filling Single and - Multiple Arcs - - drawing, Drawing Single and Multiple Arcs - filling, Filling Single and Multiple Arcs - - Areas, Clearing Areas, Copying Areas - - clearing, Clearing Areas - copying, Copying Areas - - Atom, Properties and Atoms, Properties and Atoms, Properties - and Atoms, Properties and Atoms, Properties and Atoms, - Properties and Atoms, Properties and Atoms, Glossary - - getting name, Properties and Atoms, Properties and Atoms - interning, Properties and Atoms, Properties and Atoms - predefined, Properties and Atoms - - Authentication, Controlling Host Access - -B - - Background, Glossary - Backing store, Glossary - BadAccess, Using the Default Error Handlers - BadAlloc, Using the Default Error Handlers - BadAtom, Using the Default Error Handlers - BadColor, Using the Default Error Handlers - BadCursor, Using the Default Error Handlers - BadDrawable, Using the Default Error Handlers - BadFont, Using the Default Error Handlers - BadGC, Using the Default Error Handlers - BadIDChoice, Using the Default Error Handlers - BadImplementation, Using the Default Error Handlers - BadLength, Using the Default Error Handlers - BadMatch, Using the Default Error Handlers - BadName, Using the Default Error Handlers - BadPixmap, Using the Default Error Handlers - BadRequest, Using the Default Error Handlers - BadValue, Using the Default Error Handlers - BadWindow, Using the Default Error Handlers - Base font name, Glossary - Bit, Glossary, Glossary - - gravity, Glossary - plane, Glossary - - Bitmap, Overview of the X Window System, Glossary - BitmapBitOrder, Image Format Functions and Macros - BitmapPad, Image Format Functions and Macros - BitmapUnit, Image Format Functions and Macros - BlackPixel, Display Macros - BlackPixelOfScreen, Screen Information Macros - Bool, Generic Values and Types - Border, Glossary - Button, Pointer Grabbing, Pointer Grabbing, Glossary - - grabbing, Pointer Grabbing, Glossary - ungrabbing, Pointer Grabbing - - ButtonPress, Keyboard and Pointer Events - ButtonRelease, Keyboard and Pointer Events - Byte, Glossary - - order, Glossary - -C - - CallbackPrototype, Input Method Callback Semantics - CCC, Color Conversion Contexts and Gamut Mapping, Color - Conversion Contexts and Gamut Mapping, Color Conversion - Contexts and Gamut Mapping, Color Conversion Context - Functions, Color Conversion Context Functions, Getting - and Setting the Color Conversion Context of a Colormap, - Getting and Setting the Color Conversion Context of a - Colormap, Obtaining the Default Color Conversion - Context, Obtaining the Default Color Conversion Context, - Creating and Freeing a Color Conversion Context, - Creating and Freeing a Color Conversion Context - - creation, Creating and Freeing a Color Conversion Context - default, Color Conversion Contexts and Gamut Mapping, - Color Conversion Context Functions, Obtaining the - Default Color Conversion Context, Obtaining the - Default Color Conversion Context - - freeing, Creating and Freeing a Color Conversion Context - of colormap, Color Conversion Contexts and Gamut Mapping, - Color Conversion Context Functions, Getting and - Setting the Color Conversion Context of a - Colormap, Getting and Setting the Color Conversion - Context of a Colormap - - CellsOfScreen, Screen Information Macros - Changing, Pointer Grabbing - - pointer grab, Pointer Grabbing - - Character, Glossary - Character glyph, Glossary - Character set, Glossary - Charset, Glossary - Child window, Overview of the X Window System - Child Window, Obtaining Window Information - Children, Glossary - Chroma, TekHVC Queries, TekHVC Queries, TekHVC Queries, TekHVC - Queries, TekHVC Queries, TekHVC Queries - - maximum, TekHVC Queries, TekHVC Queries, TekHVC Queries - - CIE metric lightness, CIELab Queries, CIELab Queries, CIELab - Queries, CIELab Queries, CIELab Queries, CIELab Queries, - CIELab Queries, CIELuv Queries, CIELuv Queries, CIELuv - Queries, CIELuv Queries, CIELuv Queries, CIELuv Queries, - CIELuv Queries - - maximum, CIELab Queries, CIELab Queries, CIELuv Queries, - CIELuv Queries - - minimum, CIELab Queries, CIELuv Queries - - CirculateNotify, CirculateNotify Events - CirculateRequest, CirculateRequest Events - Class, Glossary - Clearing, Clearing Areas, Clearing Areas - - areas, Clearing Areas - windows, Clearing Areas - - Client, Glossary - Client White Point, Color Conversion Contexts and Gamut - Mapping, Modifying Attributes of a Color Conversion - Context - - of Color Conversion Context, Modifying Attributes of a - Color Conversion Context - - ClientMessage, ClientMessage Events - ClientWhitePointOfCCC, Color Conversion Context Macros - Clipping region, Glossary - Coded character, Glossary - Coded character set, Glossary - Codepoint, Glossary - Color, Color Structures, Mapping Color Names to Values, Mapping - Color Names to Values, Mapping Color Names to Values, - Allocating and Freeing Color Cells, Allocating and - Freeing Color Cells, Allocating and Freeing Color Cells, - Allocating and Freeing Color Cells, Allocating and - Freeing Color Cells, Allocating and Freeing Color Cells, - Allocating and Freeing Color Cells, Allocating and - Freeing Color Cells, Allocating and Freeing Color Cells, - Allocating and Freeing Color Cells, Modifying and - Querying Colormap Cells, Modifying and Querying Colormap - Cells, Modifying and Querying Colormap Cells, Modifying - and Querying Colormap Cells, Modifying and Querying - Colormap Cells, Modifying and Querying Colormap Cells, - Modifying and Querying Colormap Cells, Modifying and - Querying Colormap Cells, Modifying and Querying Colormap - Cells, Modifying and Querying Colormap Cells, Converting - between Color Spaces - - allocation, Allocating and Freeing Color Cells, Allocating - and Freeing Color Cells, Allocating and Freeing - Color Cells, Allocating and Freeing Color Cells, - Allocating and Freeing Color Cells, Allocating and - Freeing Color Cells, Allocating and Freeing Color - Cells - - conversion, Converting between Color Spaces - deallocation, Allocating and Freeing Color Cells - naming, Mapping Color Names to Values, Mapping Color Names - to Values, Mapping Color Names to Values, - Allocating and Freeing Color Cells, Allocating and - Freeing Color Cells, Modifying and Querying - Colormap Cells - - querying, Modifying and Querying Colormap Cells, Modifying - and Querying Colormap Cells, Modifying and - Querying Colormap Cells, Modifying and Querying - Colormap Cells - - storing, Modifying and Querying Colormap Cells, Modifying - and Querying Colormap Cells, Modifying and - Querying Colormap Cells, Modifying and Querying - Colormap Cells, Modifying and Querying Colormap - Cells - - Color Characterization Data, Creating Additional Function Sets - Color conversion, Converting between Color Spaces - Color Conversion Context, Color Conversion Contexts and Gamut - Mapping, Color Conversion Contexts and Gamut Mapping, - Color Conversion Contexts and Gamut Mapping, Color - Conversion Contexts and Gamut Mapping, Color Conversion - Context Functions, Color Conversion Context Functions, - Color Conversion Context Functions, Getting and Setting - the Color Conversion Context of a Colormap, Getting and - Setting the Color Conversion Context of a Colormap, - Obtaining the Default Color Conversion Context, - Obtaining the Default Color Conversion Context, Creating - and Freeing a Color Conversion Context, Creating and - Freeing a Color Conversion Context - - creation, Color Conversion Contexts and Gamut Mapping, - Color Conversion Context Functions, Creating and - Freeing a Color Conversion Context - - default, Color Conversion Contexts and Gamut Mapping, - Color Conversion Context Functions, Obtaining the - Default Color Conversion Context, Obtaining the - Default Color Conversion Context - - freeing, Creating and Freeing a Color Conversion Context - of colormap, Color Conversion Contexts and Gamut Mapping, - Color Conversion Context Functions, Getting and - Setting the Color Conversion Context of a - Colormap, Getting and Setting the Color Conversion - Context of a Colormap - - Color map, Color Management Functions, Allocating and Freeing - Color Cells - - Colormap, Getting and Setting the Color Conversion Context of a - Colormap, Getting and Setting the Color Conversion - Context of a Colormap, Glossary - - CCC of, Getting and Setting the Color Conversion Context - of a Colormap, Getting and Setting the Color - Conversion Context of a Colormap - - ColormapNotify, Colormap State Change Events - Colormaps, Standard Colormap Properties and Atoms - - standard, Standard Colormap Properties and Atoms - - ConfigureNotify, ConfigureNotify Events - ConfigureRequest, ConfigureRequest Events - Connection, Glossary - ConnectionNumber, Display Macros - Containment, Glossary - Coordinate system, Glossary - Copying, Copying Areas, Copying Areas - - areas, Copying Areas - planes, Copying Areas - - CreateNotify, CreateNotify Events - CurrentTime, Event Processing Overview, Pointer Grabbing - Cursor, Creating Windows, Creating, Recoloring, and Freeing - Cursors, Glossary - - Initial State, Creating Windows - limitations, Creating, Recoloring, and Freeing Cursors - - Cut Buffers, Using Cut Buffers - -D - - Debugging, Enabling or Disabling Synchronization, Using the - Default Error Handlers, Using the Default Error - Handlers, Using the Default Error Handlers, Using the - Default Error Handlers - - error event, Using the Default Error Handlers - error handlers, Using the Default Error Handlers - error message strings, Using the Default Error Handlers - error numbers, Using the Default Error Handlers - synchronous mode, Enabling or Disabling Synchronization - - Default Protection, Controlling Host Access - DefaultColormap, Display Macros - DefaultColormapOfScreen, Screen Information Macros - DefaultDepth, Display Macros - DefaultDepthOfScreen, Screen Information Macros - DefaultGC, Display Macros - DefaultGCOfScreen, Screen Information Macros - DefaultRootWindow, Display Macros - DefaultScreen, Display Macros - DefaultScreenOfDisplay, Display Macros - DefaultVisual, Display Macros - DefaultVisualOfScreen, Screen Information Macros - Depth, Glossary - Destination, Manipulating Graphics Context/State - DestroyCallback, Destroy Callback, Destroy Callback - DestroyNotify, DestroyNotify Events - Device, Glossary - Device Color Characterization, Function Sets - Device profile, Color Conversion Contexts and Gamut Mapping, - Creating Additional Function Sets - - DirectColor, Glossary - Display, Opening the Display, Obtaining Information about the - Display, Image Formats, or Screens, Glossary, Glossary, - Glossary - - data structure, Obtaining Information about the Display, - Image Formats, or Screens - - structure, Glossary, Glossary - - Display Functions, Manipulating Graphics Context/State - DisplayCells, Display Macros - DisplayHeight, Image Format Functions and Macros - DisplayHeightMM, Image Format Functions and Macros - DisplayOfCCC, Color Conversion Context Macros - DisplayOfScreen, Screen Information Macros - DisplayPlanes, Display Macros - DisplayString, Display Macros - DisplayWidth, Image Format Functions and Macros - DisplayWidthMM, Image Format Functions and Macros - DoesBackingStore, Screen Information Macros - DoesSaveUnders, Screen Information Macros - Drawable, Overview of the X Window System, Glossary - Drawing, Drawing Single and Multiple Points, Drawing Single and - Multiple Lines, Drawing Single and Multiple Lines, - Drawing Single and Multiple Rectangles, Drawing Single - and Multiple Arcs, Drawing Complex Text, Drawing Text - Characters, Drawing Image Text Characters - - arcs, Drawing Single and Multiple Arcs - image text, Drawing Image Text Characters - lines, Drawing Single and Multiple Lines - points, Drawing Single and Multiple Points - polygons, Drawing Single and Multiple Lines - rectangles, Drawing Single and Multiple Rectangles - strings, Drawing Text Characters - text items, Drawing Complex Text - -E - - Encoding, Glossary - EnterNotify, Window Entry/Exit Events - Environment, Opening the Display - - DISPLAY, Opening the Display - - Error, Errors, Using the Default Error Handlers, Using the - Default Error Handlers - - codes, Using the Default Error Handlers - handlers, Using the Default Error Handlers - handling, Errors - - Escapement, Glossary - Event, Overview of the X Window System, Event Types, Event - Types, Event Types, Selecting Events, Glossary, - Glossary, Glossary, Glossary, Glossary, Glossary - - categories, Event Types - Exposure, Glossary - mask, Glossary - propagation, Selecting Events, Glossary - source, Glossary - synchronization, Glossary - types, Event Types - - Event mask, Event Masks - EventMaskOfScreen, Screen Information Macros - Events, Keyboard and Pointer Events, Keyboard and Pointer - Events, Keyboard and Pointer Events, Keyboard and - Pointer Events, Keyboard and Pointer Events, Window - Entry/Exit Events, Window Entry/Exit Events, Input Focus - Events, Input Focus Events, Key Map State Notification - Events, Expose Events, GraphicsExpose and NoExpose - Events, GraphicsExpose and NoExpose Events, - CirculateNotify Events, ConfigureNotify Events, - CreateNotify Events, DestroyNotify Events, GravityNotify - Events, MapNotify Events, MappingNotify Events, - ReparentNotify Events, UnmapNotify Events, - VisibilityNotify Events, CirculateRequest Events, - ConfigureRequest Events, MapRequest Events, - ResizeRequest Events, Colormap State Change Events, - ClientMessage Events, PropertyNotify Events, - SelectionClear Events, SelectionRequest Events, - SelectionNotify Events - - ButtonPress, Keyboard and Pointer Events - ButtonRelease, Keyboard and Pointer Events - CirculateNotify, CirculateNotify Events - CirculateRequest, CirculateRequest Events - ClientMessage, ClientMessage Events - ColormapNotify, Colormap State Change Events - ConfigureNotify, ConfigureNotify Events - ConfigureRequest, ConfigureRequest Events - CreateNotify, CreateNotify Events - DestroyNotify, DestroyNotify Events - EnterNotify, Window Entry/Exit Events - Expose, Expose Events - FocusIn, Input Focus Events - FocusOut, Input Focus Events - GraphicsExpose, GraphicsExpose and NoExpose Events - GravityNotify, GravityNotify Events - KeymapNotify, Key Map State Notification Events - KeyPress, Keyboard and Pointer Events - KeyRelease, Keyboard and Pointer Events - LeaveNotify, Window Entry/Exit Events - MapNotify, MapNotify Events - MappingNotify, MappingNotify Events - MapRequest, MapRequest Events - MotionNotify, Keyboard and Pointer Events - NoExpose, GraphicsExpose and NoExpose Events - PropertyNotify, PropertyNotify Events - ReparentNotify, ReparentNotify Events - ResizeRequest, ResizeRequest Events - SelectionClear, SelectionClear Events - SelectionNotify, SelectionNotify Events - SelectionRequest, SelectionRequest Events - UnmapNotify, UnmapNotify Events - VisibilityNotify, VisibilityNotify Events - - Expose, Expose Events - Extension, Glossary - -F - - False, Generic Values and Types - Files, Overview of the X Window System, Standard Header Files, - Standard Header Files, Standard Header Files, Standard - Header Files, Standard Header Files, Standard Header - Files, Standard Header Files, Standard Header Files, - Standard Header Files, Standard Header Files, Standard - Header Files, Standard Header Files, Standard Header - Files, Opening the Display, Properties and Atoms, Color - Management Functions, Color Management Functions, - Manipulating Graphics Context/State, Loading and Freeing - Fonts, Controlling Host Access, Event Types, Event - Structures, Event Masks, GraphicsExpose and NoExpose - Events, Manipulating the Keyboard Encoding, Manipulating - the Keyboard Encoding, Setting and Reading the WM_HINTS - Property, Setting and Reading the WM_NORMAL_HINTS - Property, Setting and Reading the WM_CLASS Property, - Setting and Reading the WM_ICON_SIZE Property, Standard - Colormap Properties and Atoms, Resource Manager - Functions, Using Keyboard Utility Functions, Parsing the - Window Geometry, Manipulating Regions, Determining the - Appropriate Visual Type, Manipulating Images, - Manipulating Images, Using the Context Manager, Setting - and Getting Window Sizing Hints, Getting the X - Environment Defaults, Drawing and Filling Polygons and - Curves, Drawing and Filling Polygons and Curves - - $HOME/.Xdefaults, Getting the X Environment Defaults - /etc/X?.hosts, Controlling Host Access - , Standard Header Files - , Standard Header Files, Manipulating the - Keyboard Encoding - - , Standard Header Files, Manipulating the - Keyboard Encoding, Using Keyboard Utility - Functions - - , Overview of the X Window System, Standard - Header Files, Manipulating Graphics Context/State, - Event Types, Event Masks - - , Standard Header Files, Drawing and Filling - Polygons and Curves, Drawing and Filling Polygons - and Curves - - , Standard Header Files, Properties and - Atoms, Loading and Freeing Fonts, Standard - Colormap Properties and Atoms - - , Standard Header Files, Color Management - Functions - - , Standard Header Files, Opening the Display, - Color Management Functions, Event Structures, - Manipulating Images - - , Standard Header Files - , Standard Header Files, GraphicsExpose and - NoExpose Events - - , Standard Header Files - , Standard Header Files, Resource Manager - Functions - - , Standard Header Files, Setting and Reading - the WM_HINTS Property, Setting and Reading the - WM_NORMAL_HINTS Property, Setting and Reading the - WM_CLASS Property, Setting and Reading the - WM_ICON_SIZE Property, Parsing the Window - Geometry, Manipulating Regions, Determining the - Appropriate Visual Type, Manipulating Images, - Using the Context Manager, Setting and Getting - Window Sizing Hints - - Filling, Filling Single and Multiple Rectangles, Filling a - Single Polygon, Filling Single and Multiple Arcs - - arcs, Filling Single and Multiple Arcs - polygon, Filling a Single Polygon - rectangles, Filling Single and Multiple Rectangles - - FlushGC, GC Caching - FocusIn, Input Focus Events - FocusOut, Input Focus Events - Font, Font Metrics, Glossary - Font glyph, Glossary - Fonts, Loading and Freeing Fonts, Loading and Freeing Fonts, - Loading and Freeing Fonts - - freeing font information, Loading and Freeing Fonts - getting information, Loading and Freeing Fonts - unloading, Loading and Freeing Fonts - - Freeing, Window Attributes, Changing Window Attributes, - Changing Window Attributes, Allocating and Freeing Color - Cells - - colors, Allocating and Freeing Color Cells - resources, Window Attributes, Changing Window Attributes, - Changing Window Attributes - - Frozen events, Glossary - Function set, Function Sets, Function Sets - - LINEAR_RGB, Function Sets - -G - - Gamut compression, Color Conversion Contexts and Gamut Mapping, - Modifying Attributes of a Color Conversion Context, - Modifying Attributes of a Color Conversion Context, - Modifying Attributes of a Color Conversion Context - - client data, Modifying Attributes of a Color Conversion - Context - - procedure, Modifying Attributes of a Color Conversion - Context - - setting in Color Conversion Context, Modifying Attributes - of a Color Conversion Context - - Gamut handling, Color Conversion Contexts and Gamut Mapping - Gamut querying, Gamut Querying Functions - GC, Glossary - GeometryCallback, Geometry Callback - Glyph, Glossary - Glyph image, Glossary - Grab, Glossary - Grabbing, Grabbing the Server, Pointer Grabbing, Pointer - Grabbing, Keyboard Grabbing, Keyboard Grabbing - - buttons, Pointer Grabbing - keyboard, Keyboard Grabbing - keys, Keyboard Grabbing - pointer, Pointer Grabbing - server, Grabbing the Server - - Graphics context, Manipulating Graphics Context/State, Glossary - - initializing, Manipulating Graphics Context/State - - GraphicsExpose, GraphicsExpose and NoExpose Events - Gravity, Glossary - GravityNotify, GravityNotify Events - GrayScale, Glossary - -H - - Hash Lookup, Associating User Data with a Value - Headers, Overview of the X Window System, Standard Header - Files, Standard Header Files, Standard Header Files, - Standard Header Files, Standard Header Files, Standard - Header Files, Standard Header Files, Standard Header - Files, Standard Header Files, Standard Header Files, - Standard Header Files, Standard Header Files, Standard - Header Files, Standard Header Files, Opening the - Display, Properties and Atoms, Color Management - Functions, Color Management Functions, Manipulating - Graphics Context/State, Loading and Freeing Fonts, Event - Types, Event Structures, Event Masks, GraphicsExpose and - NoExpose Events, Manipulating the Keyboard Encoding, - Manipulating the Keyboard Encoding, Setting and Reading - the WM_HINTS Property, Setting and Reading the - WM_NORMAL_HINTS Property, Setting and Reading the - WM_CLASS Property, Setting and Reading the WM_ICON_SIZE - Property, Standard Colormap Properties and Atoms, - Resource Manager Functions, Using Keyboard Utility - Functions, Parsing the Window Geometry, Manipulating - Regions, Determining the Appropriate Visual Type, - Manipulating Images, Manipulating Images, Using the - Context Manager, Setting and Getting Window Sizing - Hints, Drawing and Filling Polygons and Curves, Drawing - and Filling Polygons and Curves - - , Standard Header Files - , Standard Header Files, Manipulating the - Keyboard Encoding - - , Standard Header Files, Manipulating the - Keyboard Encoding, Using Keyboard Utility - Functions - - , Overview of the X Window System, Standard - Header Files, Manipulating Graphics Context/State, - Event Types, Event Masks - - , Standard Header Files, Drawing and Filling - Polygons and Curves, Drawing and Filling Polygons - and Curves - - , Standard Header Files, Properties and - Atoms, Loading and Freeing Fonts, Standard - Colormap Properties and Atoms - - , Standard Header Files, Color Management - Functions - - , Standard Header Files, Opening the Display, - Color Management Functions, Event Structures, - Manipulating Images - - , Standard Header Files - , Standard Header Files, GraphicsExpose and - NoExpose Events - - , Standard Header Files - , Standard Header Files, Resource Manager - Functions - - , Standard Header Files, Setting and Reading - the WM_HINTS Property, Setting and Reading the - WM_NORMAL_HINTS Property, Setting and Reading the - WM_CLASS Property, Setting and Reading the - WM_ICON_SIZE Property, Parsing the Window - Geometry, Manipulating Regions, Determining the - Appropriate Visual Type, Manipulating Images, - Using the Context Manager, Setting and Getting - Window Sizing Hints - - HeightMMOfScreen, Screen Information Macros - HeightOfScreen, Screen Information Macros - Host Portable Character Encoding, Glossary - Hotspot, Glossary - -I - - Identifier, Glossary - Image text, Drawing Image Text Characters - - drawing, Drawing Image Text Characters - - ImageByteOrder, Image Format Functions and Macros - IMInstantiateCallback, Input Method Functions - Inferiors, Glossary - Input, Glossary, Glossary - - focus, Glossary - manager, Glossary - - Input Control, Event Types - Internationalization, Glossary - IsCursorKey, KeySym Classification Macros - IsFunctionKey, KeySym Classification Macros - IsKeypadKey, KeySym Classification Macros - IsMiscFunctionKey, KeySym Classification Macros - IsModifierKey, KeySym Classification Macros - ISO2022, Glossary - IsPFKey, KeySym Classification Macros - IsPrivateKeypadKey, KeySym Classification Macros - -K - - Key, Keyboard Grabbing, Keyboard Grabbing, Glossary - - grabbing, Keyboard Grabbing, Glossary - ungrabbing, Keyboard Grabbing - - Keyboard, Keyboard Grabbing, Keyboard Grabbing, Manipulating - the Keyboard and Pointer Settings, Manipulating the - Keyboard and Pointer Settings, Manipulating the Keyboard - and Pointer Settings, Glossary - - bell volume, Manipulating the Keyboard and Pointer - Settings - - bit vector, Manipulating the Keyboard and Pointer Settings - grabbing, Keyboard Grabbing, Glossary - keyclick volume, Manipulating the Keyboard and Pointer - Settings - - ungrabbing, Keyboard Grabbing - - KeymapNotify, Key Map State Notification Events - KeyPress, Keyboard and Pointer Events - KeyRelease, Keyboard and Pointer Events - Keysym, Glossary - -L - - LastKnownRequestProcessed, Display Macros - Latin Portable Character Encoding, Glossary - Latin-1, Glossary - LeaveNotify, Window Entry/Exit Events - Lines, Drawing Single and Multiple Lines - - drawing, Drawing Single and Multiple Lines - - Locale, Glossary - Locale name, Glossary - Localization, Glossary - LockDisplay, Locking Data Structures - -M - - MapNotify, MapNotify Events - Mapped window, Glossary - MappingNotify, MappingNotify Events - MapRequest, MapRequest Events - MaxCmapsOfScreen, Screen Information Macros - Menus, Grabbing the Server - MinCmapsOfScreen, Screen Information Macros - Modifier keys, Glossary - Monochrome, Glossary - MotionNotify, Keyboard and Pointer Events - Mouse, Manipulating the Keyboard and Pointer Settings - - programming, Manipulating the Keyboard and Pointer - Settings - - Multibyte, Glossary - -N - - NextRequest, Display Macros - NoExpose, GraphicsExpose and NoExpose Events - None, Generic Values and Types - -O - - Obscure, Glossary - Occlude, Glossary - Output Control, Event Types - -P - - Padding, Glossary - Parent Window, Overview of the X Window System, Obtaining - Window Information - - Passive grab, Pointer Grabbing, Glossary - Pixel value, Manipulating Graphics Context/State, Glossary - Pixmap, Overview of the X Window System, Glossary - Plane, Manipulating Graphics Context/State, Copying Areas, - Glossary, Glossary - - copying, Copying Areas - mask, Manipulating Graphics Context/State, Glossary - - PlanesOfScreen, Screen Information Macros - Pointer, Pointer Grabbing, Pointer Grabbing, Pointer Grabbing, - Glossary, Glossary - - grabbing, Pointer Grabbing, Pointer Grabbing, Glossary - ungrabbing, Pointer Grabbing - - Pointing device, Glossary - Points, Drawing Single and Multiple Points - - drawing, Drawing Single and Multiple Points - - Polygons, Drawing Single and Multiple Lines, Filling a Single - Polygon - - drawing, Drawing Single and Multiple Lines - filling, Filling a Single Polygon - - POSIX, Glossary - POSIX Portable Filename Character Set, Glossary - POSIX System Call, Display Macros - - fork, Display Macros - - PreeditCaretCallback, Preedit Caret Callback - PreeditDoneCallback, Preedit State Callbacks - PreeditDrawCallback, Preedit Draw Callback - PreeditStartCallback, Preedit State Callbacks - PreeditStateNotifyCallback, Preedit State Notify Callback - Property, Obtaining and Changing Window Properties, Obtaining - and Changing Window Properties, Obtaining and Changing - Window Properties, Obtaining and Changing Window - Properties, Obtaining and Changing Window Properties, - Obtaining and Changing Window Properties, Obtaining and - Changing Window Properties, Obtaining and Changing - Window Properties, Obtaining and Changing Window - Properties, Glossary - - appending, Obtaining and Changing Window Properties - changing, Obtaining and Changing Window Properties - deleting, Obtaining and Changing Window Properties - format, Obtaining and Changing Window Properties - getting, Obtaining and Changing Window Properties - listing, Obtaining and Changing Window Properties - prepending, Obtaining and Changing Window Properties - replacing, Obtaining and Changing Window Properties - type, Obtaining and Changing Window Properties - - Property list, Glossary - PropertyNotify, PropertyNotify Events - Protocol, Opening the Display, Opening the Display - - DECnet, Opening the Display - TCP, Opening the Display - - ProtocolRevision, Display Macros - ProtocolVersion, Display Macros - PseudoColor, Glossary - Psychometric Chroma, CIELab Queries, CIELab Queries, CIELab - Queries, CIELab Queries, CIELuv Queries, CIELuv Queries, - CIELuv Queries, CIELuv Queries - - maximum, CIELab Queries, CIELab Queries, CIELuv Queries, - CIELuv Queries - - Psychometric Hue Angle, CIELab Queries, CIELab Queries, CIELab - Queries, CIELab Queries, CIELuv Queries, CIELuv Queries, - CIELuv Queries, CIELuv Queries - -Q - - QLength, Display Macros - -R - - Read-only colormap cells, Allocating and Freeing Color Cells, - Allocating and Freeing Color Cells, Allocating and - Freeing Color Cells, Allocating and Freeing Color Cells, - Allocating and Freeing Color Cells - - allocating, Allocating and Freeing Color Cells, Allocating - and Freeing Color Cells, Allocating and Freeing - Color Cells, Allocating and Freeing Color Cells - - read-only colormap cells, Allocating and Freeing Color Cells - Read/write colormap cells, Allocating and Freeing Color Cells, - Allocating and Freeing Color Cells - - allocating, Allocating and Freeing Color Cells - - Read/write colormap planes, Allocating and Freeing Color Cells - - allocating, Allocating and Freeing Color Cells - - Rectangle, Filling Single and Multiple Rectangles, Glossary - - filling, Filling Single and Multiple Rectangles - - Rectangles, Drawing Single and Multiple Rectangles - - drawing, Drawing Single and Multiple Rectangles - - Redirecting control, Glossary - ReparentNotify, ReparentNotify Events - Reply, Glossary - Request, Glossary - ResizeRequest, ResizeRequest Events - Resource, Glossary - Resource IDs, Overview of the X Window System, Overview of the - X Window System, Overview of the X Window System, - Overview of the X Window System, Overview of the X - Window System, Overview of the X Window System, Overview - of the X Window System, Closing the Display, Window - Attributes, Changing Window Attributes, Changing Window - Attributes, Associating User Data with a Value - - Colormap, Overview of the X Window System - Cursor, Overview of the X Window System - Font, Overview of the X Window System - freeing, Window Attributes, Changing Window Attributes, - Changing Window Attributes - - GContext, Overview of the X Window System - Pixmap, Overview of the X Window System - Window, Overview of the X Window System - - RGB values, Glossary - Root, Glossary - RootWindow, Display Macros - RootWindowOfScreen, Screen Information Macros - -S - - Save set, Glossary - Save Unders, Save Under Flag - Scanline, Glossary, Glossary - - order, Glossary - - Screen, Overview of the X Window System, Opening the Display, - Glossary, Glossary - - structure, Glossary - - Screen White Point, Gamut Querying Functions - ScreenCount, Display Macros - ScreenNumberOfCCC, Color Conversion Context Macros - ScreenOfDisplay, Display Macros - ScreenWhitePointOfCCC, Color Conversion Context Macros - Selection, Selections, Selections, Selections, Selections, - Glossary - - converting, Selections - getting the owner, Selections - setting the owner, Selections - - SelectionClear, SelectionClear Events - SelectionNotify, SelectionNotify Events - SelectionRequest, SelectionRequest Events - Serial Number, Using the Default Error Handlers - Server, Grabbing the Server, Glossary, Glossary - - grabbing, Grabbing the Server, Glossary - - ServerVendor, Display Macros - Shift sequence, Glossary - Sibling, Glossary - Source, Manipulating Graphics Context/State - Stacking order, Overview of the X Window System, Glossary - Standard Colormaps, Standard Colormap Properties and Atoms - State-dependent encoding, Glossary - State-independent encoding, Glossary - StaticColor, Glossary - StaticGray, Glossary - Status, Errors, Glossary - StatusDoneCallback, Status Callbacks - StatusDrawCallback, Status Callbacks - StatusStartCallback, Status Callbacks - Stipple, Glossary - String Equivalence, Glossary - StringConversionCallback, String Conversion Callback - Strings, Drawing Text Characters - - drawing, Drawing Text Characters - -T - - Text, Drawing Complex Text - - drawing, Drawing Complex Text - - Tile, Overview of the X Window System, Window Attributes, - Window Attributes, Glossary - - mode, Window Attributes - pixmaps, Window Attributes - - Time, Pointer Grabbing - Timestamp, Glossary - True, Generic Values and Types - TrueColor, Glossary - Type, Glossary - -U - - Ungrabbing, Pointer Grabbing, Pointer Grabbing, Keyboard - Grabbing, Keyboard Grabbing - - buttons, Pointer Grabbing - keyboard, Keyboard Grabbing - keys, Keyboard Grabbing - pointer, Pointer Grabbing - - UnlockDisplay, Locking Data Structures - UnmapNotify, UnmapNotify Events - UnmapNotify Event, Unmapping Windows, Unmapping Windows - -V - - Value, TekHVC Queries, TekHVC Queries, TekHVC Queries, TekHVC - Queries, TekHVC Queries, TekHVC Queries, TekHVC Queries, - TekHVC Queries - - maximum, TekHVC Queries, TekHVC Queries, TekHVC Queries - minimum, TekHVC Queries - - VendorRelease, Display Macros - Vertex, Drawing and Filling Polygons and Curves - VertexCurved, Drawing and Filling Polygons and Curves - VertexDontDraw, Drawing and Filling Polygons and Curves - VertexEndClosed, Drawing and Filling Polygons and Curves - VertexRelative, Drawing and Filling Polygons and Curves - VertexStartClosed, Drawing and Filling Polygons and Curves - Viewable, Glossary - VisibilityNotify, VisibilityNotify Events - Visible, Glossary - Visual, Visual Types - Visual Classes, Visual Types, Visual Types, Visual Types, - Visual Types, Visual Types, Visual Types - - GrayScale, Visual Types - PseudoColor, Visual Types - StaticColor, Visual Types, Visual Types - StaticGray, Visual Types - TrueColor, Visual Types - - Visual Type, Visual Types - VisualOfCCC, Color Conversion Context Macros - -W - - White point, Color Conversion Contexts and Gamut Mapping - White point adjustment, Color Conversion Contexts and Gamut - Mapping, Modifying Attributes of a Color Conversion - Context, Modifying Attributes of a Color Conversion - Context, Modifying Attributes of a Color Conversion - Context - - client data, Modifying Attributes of a Color Conversion - Context - - procedure, Modifying Attributes of a Color Conversion - Context - - setting in Color Conversion Context, Modifying Attributes - of a Color Conversion Context - - WhitePixel, Display Macros - WhitePixelOfScreen, Screen Information Macros - Whitespace, Glossary - WidthMMOfScreen, Screen Information Macros - WidthOfScreen, Screen Information Macros - Window, Overview of the X Window System, Display Macros, - Display Macros, Window Attributes, Window Attributes, - Window Attributes, Creating Windows, Changing Window - Attributes, Changing Window Attributes, Changing Window - Attributes, Clearing Areas, Grabbing the Server, Setting - and Reading the WM_NAME Property, Setting and Reading - the WM_ICON_NAME Property, Parsing the Window Geometry, - Parsing Window Geometry, Associating User Data with a - Value, Glossary, Glossary, Glossary, Glossary, Glossary, - Glossary - - attributes, Window Attributes - background, Changing Window Attributes - clearing, Clearing Areas - defining the cursor, Changing Window Attributes - determining location, Parsing the Window Geometry, Parsing - Window Geometry - - gravity, Glossary - icon name, Setting and Reading the WM_ICON_NAME Property - IDs, Associating User Data with a Value - InputOnly, Creating Windows, Glossary - InputOutput, Glossary - manager, Glossary - managers, Grabbing the Server - mapping, Window Attributes - name, Setting and Reading the WM_NAME Property - parent, Glossary - root, Glossary - RootWindow, Display Macros - undefining the cursor, Changing Window Attributes - XRootWindow, Display Macros - -X - - X Portable Character Set, Glossary - X10 compatibility, Drawing and Filling Polygons and Curves, - Drawing and Filling Polygons and Curves, Drawing and - Filling Polygons and Curves, Drawing and Filling - Polygons and Curves, Drawing and Filling Polygons and - Curves, Drawing and Filling Polygons and Curves, Drawing - and Filling Polygons and Curves, Drawing and Filling - Polygons and Curves, Drawing and Filling Polygons and - Curves, Drawing and Filling Polygons and Curves - - XDraw, Drawing and Filling Polygons and Curves, Drawing - and Filling Polygons and Curves - - XDrawDashed, Drawing and Filling Polygons and Curves, - Drawing and Filling Polygons and Curves - - XDrawFilled, Drawing and Filling Polygons and Curves, - Drawing and Filling Polygons and Curves - - XDrawPatterned, Drawing and Filling Polygons and Curves, - Drawing and Filling Polygons and Curves - - XDrawTiled, Drawing and Filling Polygons and Curves, - Drawing and Filling Polygons and Curves - - X11/cursorfont.h, Standard Header Files - X11/keysym.h, Standard Header Files, Manipulating the Keyboard - Encoding - - X11/keysymdef.h, Standard Header Files, Manipulating the - Keyboard Encoding, Using Keyboard Utility Functions - - X11/X.h, Overview of the X Window System, Standard Header - Files, Manipulating Graphics Context/State, Event Types, - Event Masks - - X11/X10.h, Standard Header Files, Drawing and Filling Polygons - and Curves, Drawing and Filling Polygons and Curves - - X11/Xatom.h, Standard Header Files, Properties and Atoms, - Loading and Freeing Fonts, Standard Colormap Properties - and Atoms - - X11/Xcms.h, Standard Header Files, Color Management Functions - X11/Xlib.h, Standard Header Files, Opening the Display, Color - Management Functions, Event Structures, Manipulating - Images - - X11/Xlibint.h, Standard Header Files - X11/Xproto.h, Standard Header Files, GraphicsExpose and - NoExpose Events - - X11/Xprotostr.h, Standard Header Files - X11/Xresource.h, Standard Header Files, Resource Manager - Functions - - X11/Xutil.h, Standard Header Files, Setting and Reading the - WM_HINTS Property, Setting and Reading the - WM_NORMAL_HINTS Property, Setting and Reading the - WM_CLASS Property, Setting and Reading the WM_ICON_SIZE - Property, Parsing the Window Geometry, Manipulating - Regions, Determining the Appropriate Visual Type, - Manipulating Images, Using the Context Manager, Setting - and Getting Window Sizing Hints - - XActivateScreenSaver, Controlling the Screen Saver - XAddExtension, Hooking into Xlib - XAddHost, Adding, Getting, or Removing Hosts - XAddHosts, Adding, Getting, or Removing Hosts - XAddPixel, Manipulating Images - XAddToExtensionList, Hooks onto Xlib Data Structures - XAddToSaveSet, Controlling the Lifetime of a Window - XAllocClassHint, Setting and Reading the WM_CLASS Property - XAllocColor, Allocating and Freeing Color Cells, Allocating and - Freeing Color Cells - - XAllocColorCells, Allocating and Freeing Color Cells, - Allocating and Freeing Color Cells - - XAllocColorPlanes, Allocating and Freeing Color Cells, - Allocating and Freeing Color Cells - - XAllocID, Hooks onto Xlib Data Structures - XAllocIDs, Hooks onto Xlib Data Structures - XAllocNamedColor, Allocating and Freeing Color Cells, - Allocating and Freeing Color Cells - - XAllowEvents, Resuming Event Processing - XAllPlanes, Display Macros - XAnyEvent, Event Structures - XArc, Drawing Points, Lines, Rectangles, and Arcs - XAutoRepeatOff, Manipulating the Keyboard and Pointer Settings - XAutoRepeatOn, Manipulating the Keyboard and Pointer Settings - XBaseFontNameListOfFontSet, Creating and Freeing a Font Set - XBell, Manipulating the Keyboard and Pointer Settings - XBitmapBitOrder, Image Format Functions and Macros - XBitmapPad, Image Format Functions and Macros - XBitmapUnit, Image Format Functions and Macros - XBlackPixel, Display Macros - XBlackPixelOfScreen, Screen Information Macros - XCellsOfScreen, Screen Information Macros - XChangeActivePointerGrab, Pointer Grabbing - XChangeGC, Manipulating Graphics Context/State - XChangeKeyboardControl, Manipulating the Keyboard and Pointer - Settings - - XChangeKeyboardMapping, Manipulating the Keyboard Encoding - XChangePointerControl, Manipulating the Keyboard and Pointer - Settings - - XChangeProperty, Obtaining and Changing Window Properties - XChangeSaveSet, Controlling the Lifetime of a Window - XChangeWindowAttributes, Changing Window Attributes - XChar2b, Font Metrics - XCharStruct, Font Metrics - XCheckIfEvent, Selecting Events Using a Predicate Procedure - XCheckMaskEvent, Selecting Events Using a Window or Event Mask - XCheckTypedEvent, Selecting Events Using a Window or Event Mask - XCheckTypedWindowEvent, Selecting Events Using a Window or - Event Mask - - XCheckWindowEvent, Selecting Events Using a Window or Event - Mask, Selecting Events Using a Window or Event Mask - - XCirculateEvent, CirculateNotify Events - XCirculateRequestEvent, CirculateRequest Events - XCirculateSubwindows, Changing Window Stacking Order - XCirculateSubwindowsDown, Changing Window Stacking Order - XCirculateSubwindowsUp, Changing Window Stacking Order - XClassHint, Setting and Reading the WM_CLASS Property - XClearArea, Clearing Areas - XClearWindow, Clearing Areas - XClientMessageEvent, ClientMessage Events - XClipBox, Computing with Regions - XCloseDisplay, Closing the Display, Closing the Display - XCloseIM, Input Method Functions - XCloseOM, Output Method Functions - XcmsAddColorSpace, Adding Device-Independent Color Spaces - XcmsAddFunctionSet, Adding Function Sets - XcmsAllocColor, Allocating and Freeing Color Cells - XcmsAllocNamedColor, Allocating and Freeing Color Cells - XcmsCCCOfColormap, Getting and Setting the Color Conversion - Context of a Colormap - - XcmsCIELab, Color Structures - XcmsCIELabQueryMaxC, CIELab Queries - XcmsCIELabQueryMaxL, CIELab Queries - XcmsCIELabQueryMaxLC, CIELab Queries - XcmsCIELabQueryMinL, CIELab Queries - XcmsCIELuv, Color Structures - XcmsCIELuvQueryMaxC, CIELuv Queries - XcmsCIELuvQueryMaxL, CIELuv Queries - XcmsCIELuvQueryMaxLC, CIELuv Queries - XcmsCIELuvQueryMinL, CIELuv Queries - XcmsCIEuvY, Color Structures - XcmsCIExyY, Color Structures - XcmsCIEXYZ, Color Structures - XcmsClientWhitePointOfCCC, Color Conversion Context Macros - XcmsColor, Color Structures - XcmsCompressionProc, Prototype Gamut Compression Procedure - XcmsConvertColors, Converting between Color Spaces - XcmsCreateCCC, Creating and Freeing a Color Conversion Context - XcmsDefaultCCC, Obtaining the Default Color Conversion Context - XcmsDisplayOfCCC, Color Conversion Context Macros - XcmsFormatOfPrefix, Querying Color Space Format and Prefix - XcmsFreeCCC, Creating and Freeing a Color Conversion Context - XcmsLookupColor, Mapping Color Names to Values - XcmsPad, Color Structures - XcmsParseStringProc, Parse String Callback - XcmsPrefixOfFormat, Querying Color Space Format and Prefix - XcmsQueryBlack, Red, Green, and Blue Queries - XcmsQueryBlue, Red, Green, and Blue Queries - XcmsQueryColor, Modifying and Querying Colormap Cells - XcmsQueryColors, Modifying and Querying Colormap Cells - XcmsQueryGreen, Red, Green, and Blue Queries - XcmsQueryRed, Red, Green, and Blue Queries - XcmsQueryWhite, Red, Green, and Blue Queries - XcmsRGB, Color Structures - XcmsRGBi, Color Structures - XcmsScreenInitProc, Creating Additional Function Sets - XcmsScreenNumberOfCCC, Color Conversion Context Macros - XcmsScreenWhitePointOfCCC, Color Conversion Context Macros - XcmsSetCCCOfColormap, Getting and Setting the Color Conversion - Context of a Colormap - - XcmsSetCompressionProc, Modifying Attributes of a Color - Conversion Context - - XcmsSetWhiteAdjustProc, Modifying Attributes of a Color - Conversion Context - - XcmsSetWhitePoint, Modifying Attributes of a Color Conversion - Context - - XcmsStoreColor, Modifying and Querying Colormap Cells - XcmsStoreColors, Modifying and Querying Colormap Cells - XcmsTekHVC, Color Structures - XcmsTekHVCQueryMaxC, TekHVC Queries - XcmsTekHVCQueryMaxV, TekHVC Queries - XcmsTekHVCQueryMaxVC, TekHVC Queries - XcmsTekHVCQueryMaxVSamples, TekHVC Queries - XcmsTekHVCQueryMinV, TekHVC Queries - XcmsVisualOfCCC, Color Conversion Context Macros - XcmsWhiteAdjustProc, Prototype White Point Adjustment Procedure - XColor, Color Structures - XColormapEvent, Colormap State Change Events - XConfigureEvent, ConfigureNotify Events - XConfigureRequestEvent, ConfigureRequest Events - XConfigureWindow, Configuring Windows - XConnectionNumber, Display Macros - XContextDependentDrawing, Obtaining Font Set Metrics - XContextualDrawing, Obtaining Font Set Metrics - XConvertCase, Using Keyboard Utility Functions - XConvertSelection, Selections - XCopyArea, Copying Areas - XCopyColormapAndFree, Creating, Copying, and Destroying - Colormaps - - XCopyGC, Manipulating Graphics Context/State - XCopyPlane, Copying Areas - XCreateAssocTable, Associating User Data with a Value - XCreateBitmapFromData, Manipulating Bitmaps - XCreateColormap, Creating, Copying, and Destroying Colormaps - XCreateFontCursor, Creating, Recoloring, and Freeing Cursors - XCreateFontSet, Creating and Freeing a Font Set - XCreateGC, Manipulating Graphics Context/State - XCreateGlyphCursor, Creating, Recoloring, and Freeing Cursors - XCreateIC, Input Context Functions - XCreateImage, Manipulating Images - XCreateOC, Output Context Functions - XCreatePixmap, Creating and Freeing Pixmaps - XCreatePixmapCursor, Creating, Recoloring, and Freeing Cursors - XCreatePixmapFromBitmapData, Manipulating Bitmaps - XCreateSimpleWindow, Creating Windows - XCreateWindow, Creating Windows - XCreateWindowEvent, CreateNotify Events - XCrossingEvent, Window Entry/Exit Events - XDefaultColormap, Display Macros - XDefaultColormapOfScreen, Screen Information Macros - XDefaultDepth, Display Macros - XDefaultDepthOfScreen, Screen Information Macros - XDefaultGC, Display Macros - XDefaultGCOfScreen, Screen Information Macros - XDefaultRootWindow, Display Macros - XDefaultScreen, Display Macros - XDefaultScreenOfDisplay, Display Macros - XDefaultVisual, Display Macros - XDefaultVisualOfScreen, Screen Information Macros - XDefineCursor, Creating Windows, Changing Window Attributes - XDeleteAssoc, Associating User Data with a Value - XDeleteContext, Using the Context Manager - XDeleteModifiermapEntry, Manipulating the Keyboard Encoding - XDeleteProperty, Obtaining and Changing Window Properties - XDestroyAssocTable, Associating User Data with a Value - XDestroyIC, Input Context Functions - XDestroyImage, Manipulating Images - XDestroyOC, Output Context Functions - XDestroyRegion, Creating, Copying, or Destroying Regions - XDestroySubwindows, Destroying Windows - XDestroyWindow, Destroying Windows - XDestroyWindowEvent, DestroyNotify Events - XDirectionalDependentDrawing, Obtaining Font Set Metrics - XDisableAccessControl, Changing, Enabling, or Disabling Access - Control - - XDisplayCells, Display Macros - XDisplayHeight, Image Format Functions and Macros - XDisplayHeightMM, Image Format Functions and Macros - XDisplayKeycodes, Manipulating the Keyboard Encoding - XDisplayMotionBufferSize, Getting Pointer Motion History - XDisplayName, Using the Default Error Handlers - XDisplayOfIM, Input Method Functions - XDisplayOfOM, Output Method Functions - XDisplayOfScreen, Screen Information Macros - XDisplayPlanes, Display Macros - XDisplayString, Display Macros - XDisplayWidth, Image Format Functions and Macros - XDisplayWidthMM, Image Format Functions and Macros - XDoesBackingStore, Screen Information Macros - XDoesSaveUnders, Screen Information Macros - xDoSomethingReply, Request Format - xDoSomethingReq, Request Format - XDrawArc, Drawing Single and Multiple Arcs, Drawing Single and - Multiple Arcs - - XDrawArcs, Drawing Single and Multiple Arcs, Drawing Single and - Multiple Arcs - - XDrawImageString, Drawing Image Text Characters, Drawing Image - Text Characters - - XDrawImageString16, Drawing Image Text Characters, Drawing - Image Text Characters - - XDrawLine, Drawing Single and Multiple Lines, Drawing Single - and Multiple Lines - - XDrawLines, Drawing Single and Multiple Lines, Drawing Single - and Multiple Lines, Drawing and Filling Polygons and - Curves - - XDrawPoint, Drawing Single and Multiple Points, Drawing Single - and Multiple Points - - XDrawPoints, Drawing Single and Multiple Points, Drawing Single - and Multiple Points - - XDrawRectangle, Drawing Single and Multiple Rectangles, Drawing - Single and Multiple Rectangles - - XDrawRectangles, Drawing Single and Multiple Rectangles, - Drawing Single and Multiple Rectangles - - XDrawSegments, Drawing Single and Multiple Lines, Drawing - Single and Multiple Lines, Drawing and Filling Polygons - and Curves - - XDrawString, Drawing Text Characters - XDrawString16, Drawing Text Characters - XDrawText, Drawing Complex Text - XDrawText16, Drawing Complex Text - XEHeadOfExtensionList, Hooks onto Xlib Data Structures - XEmptyRegion, Determining if Regions Are Empty or Equal - XEnableAccessControl, Changing, Enabling, or Disabling Access - Control - - XEnterWindowEvent, Window Entry/Exit Events - XEqualRegion, Determining if Regions Are Empty or Equal - XErrorEvent, Using the Default Error Handlers - XESetBeforeFlush, Hooks into the Library - XESetCloseDisplay, Hooks into the Library - XESetCopyGC, Hooks into the Library - XESetCreateFont, Hooks into the Library - XESetCreateGC, Hooks into the Library - XESetError, Hooks into the Library - XESetErrorString, Hooks into the Library - XESetEventToWire, Hooks into the Library - XESetFlushGC, Hooks into the Library - XESetFreeFont, Hooks into the Library - XESetPrintErrorValues, Hooks into the Library - XESetWireToError, Hooks into the Library - XESetWireToEvent, Hooks into the Library - XEvent, Event Structures - XEventMaskOfScreen, Screen Information Macros - XEventsQueued, Event Queue Management - XExposeEvent, Expose Events - XExtCodes, Hooking into Xlib - XExtData, Hooks onto Xlib Data Structures - XExtendedMaxRequestSize, Display Macros - XExtentsOfFontSet, Obtaining Font Set Metrics - XFetchBuffer, Using Cut Buffers - XFetchBytes, Using Cut Buffers - XFetchName, Setting and Reading the WM_NAME Property - XFillArc, Filling Single and Multiple Arcs, Filling Single and - Multiple Arcs - - XFillArcs, Filling Single and Multiple Arcs - XFillPolygon, Filling a Single Polygon - XFillRectangle, Filling Single and Multiple Rectangles, Filling - Single and Multiple Rectangles - - XFillRectangles, Filling Single and Multiple Rectangles, - Filling Single and Multiple Rectangles - - XFilterEvent, Event Filtering - XFindContext, Using the Context Manager - XFindOnExtensionList, Hooks onto Xlib Data Structures - XFlush, Handling the Output Buffer - XFlushGC, Manipulating Graphics Context/State - XFocusChangeEvent, Input Focus Events - XFocusInEvent, Input Focus Events - XFocusOutEvent, Input Focus Events - XFontProp, Font Metrics - XFontSetExtents, Obtaining Font Set Metrics - XFontsOfFontSet, Creating and Freeing a Font Set - XFontStruct, Font Metrics - XForceScreenSaver, Controlling the Screen Saver - XFree, Freeing Client-Created Data - XFreeColormap, Creating, Copying, and Destroying Colormaps - XFreeColors, Allocating and Freeing Color Cells - XFreeCursor, Creating, Recoloring, and Freeing Cursors - XFreeExtensionList, Basic Protocol Support Routines - XFreeFont, Loading and Freeing Fonts - XFreeFontInfo, Obtaining and Freeing Font Names and Information - XFreeFontNames, Obtaining and Freeing Font Names and - Information - - XFreeFontPath, Setting and Retrieving the Font Search Path - XFreeFontSet, Creating and Freeing a Font Set - XFreeGC, Manipulating Graphics Context/State - XFreeModifiermap, Manipulating the Keyboard Encoding - XFreePixmap, Creating and Freeing Pixmaps - XFreeStringList, Converting String Lists - XGContextFromGC, Manipulating Graphics Context/State - XGeometry, Parsing Window Geometry - XGetAtomName, Properties and Atoms - XGetAtomNames, Properties and Atoms - XGetClassHint, Setting and Reading the WM_CLASS Property - XGetCommand, Setting and Reading the WM_COMMAND Property - XGetDefault, Getting the X Environment Defaults - XGetErrorDatabaseText, Using the Default Error Handlers - XGetErrorText, Using the Default Error Handlers - XGetFontPath, Setting and Retrieving the Font Search Path - XGetFontProperty, Loading and Freeing Fonts - XGetGCValues, Manipulating Graphics Context/State - XGetGeometry, Obtaining Window Information - XGetIconName, Setting and Reading the WM_ICON_NAME Property - XGetIconSizes, Setting and Reading the WM_ICON_SIZE Property - XGetICValues, Input Context Functions - XGetImage, Transferring Images between Client and Server - XGetIMValues, Input Method Functions - XGetInputFocus, Controlling Input Focus - XGetKeyboardControl, Manipulating the Keyboard and Pointer - Settings, Manipulating the Keyboard and Pointer Settings - - XGetKeyboardMapping, Manipulating the Keyboard Encoding - XGetModifierMapping, Manipulating the Keyboard Encoding - XGetMotionEvents, Getting Pointer Motion History - XGetNormalHints, Setting and Getting Window Sizing Hints - XGetOCValues, Output Context Functions - XGetOMValues, Output Method Functions - XGetPixel, Manipulating Images - XGetPointerControl, Manipulating the Keyboard and Pointer - Settings - - XGetPointerMapping, Manipulating the Keyboard and Pointer - Settings - - XGetRGBColormaps, Setting and Obtaining Standard Colormaps - XGetScreenSaver, Controlling the Screen Saver - XGetSelectionOwner, Selections - XGetSizeHints, Setting and Getting Window Sizing Hints - XGetStandardColormap, Getting and Setting an XStandardColormap - Structure - - XGetSubImage, Transferring Images between Client and Server - XGetTextProperty, Setting and Reading Text Properties - XGetTransientForHint, Setting and Reading the WM_TRANSIENT_FOR - Property - - XGetVisualInfo, Determining the Appropriate Visual Type - XGetWindowAttributes, Obtaining Window Information - XGetWindowProperty, Obtaining and Changing Window Properties - XGetWMClientMachine, Setting and Reading the WM_CLIENT_MACHINE - Property - - XGetWMColormapWindows, Setting and Reading the - WM_COLORMAP_WINDOWS Property - - XGetWMHints, Setting and Reading the WM_HINTS Property - XGetWMIconName, Setting and Reading the WM_ICON_NAME Property - XGetWMName, Setting and Reading the WM_NAME Property - XGetWMNormalHints, Setting and Reading the WM_NORMAL_HINTS - Property - - XGetWMProtocols, Setting and Reading the WM_PROTOCOLS Property - XGetWMSizeHints, Setting and Reading the WM_NORMAL_HINTS - Property - - XGetZoomHints, Setting and Getting Window Sizing Hints - XGrabButton, Pointer Grabbing - XGrabKey, Keyboard Grabbing - XGrabKeyboard, Keyboard Grabbing - XGrabPointer, Pointer Grabbing - XGrabServer, Grabbing the Server - XGraphicsExposeEvent, GraphicsExpose and NoExpose Events - XGravityEvent, GravityNotify Events - XHeightMMOfScreen, Screen Information Macros - XHeightOfScreen, Screen Information Macros - XHostAddress, Adding, Getting, or Removing Hosts - XIconifyWindow, Manipulating Top-Level Windows - XIconSize, Setting and Reading the WM_ICON_SIZE Property, - Setting and Reading the WM_ICON_SIZE Property - - XID, Generic Values and Types - XIfEvent, Selecting Events Using a Predicate Procedure - XIMAbsolutePosition, Preedit Caret Callback - XImage, Transferring Images between Client and Server - XImageByteOrder, Image Format Functions and Macros - XIMBackwardChar, Preedit Caret Callback - XIMBackwardWord, Preedit Caret Callback - XIMCallback, Preedit and Status Callbacks - XIMCaretDirection, Preedit Caret Callback - XIMCaretDown, Preedit Caret Callback - XIMCaretStyle, Preedit Caret Callback - XIMCaretUp, Preedit Caret Callback - XIMDontChange, Preedit Caret Callback - XIMForwardChar, Preedit Caret Callback - XIMForwardWord, Preedit Caret Callback - XIMHighlight, Preedit Draw Callback - XIMInitialState, Reset State - XIMLineEnd, Preedit Caret Callback - XIMLineStart, Preedit Caret Callback - XIMNextLine, Preedit Caret Callback - XIMOfIC, Input Context Functions - XIMPreeditArea, Query Input Style, Query Input Style - XIMPreeditCallbacks, Query Input Style, Query Input Style - XIMPreeditCaretCallbackStruct, Preedit Caret Callback - XIMPreeditDisable, Preedit State - XIMPreeditDrawCallbackStruct, Preedit Draw Callback - XIMPreeditEnable, Preedit State - XIMPreeditNone, Query Input Style, Query Input Style - XIMPreeditNothing, Query Input Style, Query Input Style - XIMPreeditPosition, Query Input Style, Query Input Style - XIMPreeditStateNotifyCallbackStruct, Preedit State Notify - Callback - - XIMPreeditUnknown, Preedit State - XIMPreviousLine, Preedit Caret Callback - XIMPrimary, Preedit Draw Callback - XIMProc, Preedit and Status Callbacks - XIMReverse, Preedit Draw Callback - XIMSecondary, Preedit Draw Callback - XIMStatusArea, Query Input Style, Query Input Style - XIMStatusCallbacks, Query Input Style, Query Input Style - XIMStatusDataType, Status Callbacks - XIMStatusDrawCallbackStruct, Status Callbacks - XIMStatusNone, Query Input Style, Query Input Style - XIMStatusNothing, Query Input Style, Query Input Style - XIMStringConversionCallbackStruct, String Conversion Callback - XIMStyle, Query Input Style - XIMStyles, Query Input Style - XIMTertiary, Preedit Draw Callback - XIMText, Preedit Draw Callback - XIMUnderline, Preedit Draw Callback - XIMVisibleToBackward, Preedit Draw Callback - XIMVisibleToCenter, Preedit Draw Callback - XIMVisibleToForward, Preedit Draw Callback - XInitExtension, Hooking into Xlib - XInitImage, Transferring Images between Client and Server - XInitThreads, Using Xlib with Threads - XINPreserveState, Reset State - XInsertModifiermapEntry, Manipulating the Keyboard Encoding - XInstallColormap, Managing Installed Colormaps - XInternalConnectionNumbers, Using Internal Connections - XInternAtom, Properties and Atoms - XInternAtoms, Properties and Atoms - XIntersectRegion, Computing with Regions - XKeyboardState, Manipulating the Keyboard and Pointer Settings - XKeycodeToKeysym, Using Keyboard Utility Functions - XKeymapEvent, Key Map State Notification Events - XKeysymToKeycode, Using Keyboard Utility Functions - XKeysymToString, Using Keyboard Utility Functions - XKillClient, Killing Clients - XLastKnownRequestProcessed, Display Macros - XLeaveWindowEvent, Window Entry/Exit Events - XLFD, Glossary - XlibSpecificationRelease, Standard Header Files - XListDepths, Display Macros - XListExtensions, Basic Protocol Support Routines - XListFonts, Obtaining and Freeing Font Names and Information - XListFontsWithInfo, Obtaining and Freeing Font Names and - Information - - XListHosts, Adding, Getting, or Removing Hosts - XListInstalledColormaps, Managing Installed Colormaps - XListPixmapFormats, Image Format Functions and Macros - XListProperties, Obtaining and Changing Window Properties - XLoadFont, Loading and Freeing Fonts - XLoadQueryFont, Loading and Freeing Fonts - XLocaleOfFontSet, Creating and Freeing a Font Set - XLocaleOfIM, Input Method Functions - XLocaleOfOM, Output Method Functions - XLockDisplay, Using Xlib with Threads - XLookUpAssoc, Associating User Data with a Value - XLookupColor, Mapping Color Names to Values - XLookupKeysym, Using Keyboard Utility Functions - XLookupString, Using Latin-1 Keyboard Event Functions - XLowerWindow, Changing Window Stacking Order - XMakeAssoc, Associating User Data with a Value - XMapEvent, MapNotify Events - XMappingEvent, MappingNotify Events - XMapRaised, Mapping Windows - XMapRequestEvent, MapRequest Events - XMapSubwindows, Mapping Windows, Mapping Windows - XMapWindow, Window Attributes, Mapping Windows, Mapping Windows - XMaskEvent, Selecting Events Using a Window or Event Mask - XMatchVisualInfo, Determining the Appropriate Visual Type - XMaxCmapsOfScreen, Screen Information Macros - XMaxRequestSize, Display Macros - XmbDrawImageString, Drawing Text Using Font Sets - XmbDrawString, Drawing Text Using Font Sets - XmbDrawText, Drawing Text Using Font Sets - XmbLookupString, Getting Keyboard Input - XmbResetIC, Input Context Functions - XmbSetWMProperties, Using Window Manager Convenience Functions - XmbTextEscapement, Obtaining Font Set Metrics - XmbTextExtents, Obtaining Font Set Metrics - XmbTextItem, Drawing Text Using Font Sets - XmbTextListToTextProperty, Converting String Lists - XmbTextPerCharExtents, Obtaining Font Set Metrics - XmbTextPropertyToTextList, Converting String Lists - XMinCmapsOfScreen, Screen Information Macros - XModifierKeymap, Manipulating the Keyboard Encoding - XMoveResizeWindow, Configuring Windows - XMoveWindow, Configuring Windows - XNArea, Area - XNAreaNeeded, Area Needed - XNBackground, Foreground and Background - XNClientWindow, Client Window - XNColormap, Colormap - XNCursor, Cursor - XNewModifiermap, Manipulating the Keyboard Encoding - XNextEvent, Handling the Output Buffer, Returning the Next - Event - - XNextRequest, Display Macros - XNFilterEvents, Filter Events - XNFocusWindow, Focus Window - XNFontSet, Font Set - XNForeground, Foreground and Background - XNGeometryCallback, Geometry Callback - XNoExposeEvent, GraphicsExpose and NoExpose Events - XNoOp, Generating a NoOperation Protocol Request - XNPreeditAttributes, Preedit and Status Attributes - XNPreeditCaretCallback, Preedit and Status Callbacks - XNPreeditDoneCallback, Preedit and Status Callbacks - XNPreeditDrawCallback, Preedit and Status Callbacks - XNPreeditStartCallback, Preedit and Status Callbacks - XNResourceClass, Resource Name and Class - XNResourceName, Resource Name and Class - XNSpotLocation, Spot Location - XNStatusAttributes, Preedit and Status Attributes - XNStatusDoneCallback, Preedit and Status Callbacks - XNStatusDrawCallback, Preedit and Status Callbacks - XNStatusStartCallback, Preedit and Status Callbacks - XNStdColormap, Colormap - XOffsetRegion, Moving or Shrinking Regions - XOMCharSetList, Required Char Set - XOMOfOC, Output Context Functions - XOpenDisplay, Opening the Display - XOpenIM, Input Method Functions - XOpenOM, Output Method Functions - XParseColor, Mapping Color Names to Values - XParseGeometry, Parsing the Window Geometry - XPeekEvent, Returning the Next Event - XPeekIfEvent, Selecting Events Using a Predicate Procedure - XPending, Handling the Output Buffer, Event Queue Management - Xpermalloc, Allocating Permanent Storage - XPixmapFormatValues, Image Format Functions and Macros - XPlanesOfScreen, Screen Information Macros - XPoint, Drawing Points, Lines, Rectangles, and Arcs - XPointer, Generic Values and Types - XPointInRegion, Locating a Point or a Rectangle in a Region - XPolygonRegion, Creating, Copying, or Destroying Regions - XProcessInternalConnection, Using Internal Connections - XPropertyEvent, PropertyNotify Events - XProtocolRevision, Display Macros - XProtocolVersion, Display Macros - XPutBackEvent, Putting an Event Back into the Queue - XPutImage, Transferring Images between Client and Server - XPutPixel, Manipulating Images - XQLength, Display Macros - XQueryBestCursor, Creating, Recoloring, and Freeing Cursors, - Creating, Recoloring, and Freeing Cursors - - XQueryBestSize, Setting the Fill Tile and Stipple - XQueryBestStipple, Setting the Fill Tile and Stipple - XQueryBestTile, Setting the Fill Tile and Stipple - XQueryColor, Modifying and Querying Colormap Cells - XQueryColors, Modifying and Querying Colormap Cells - XQueryExtension, Basic Protocol Support Routines - XQueryFont, Loading and Freeing Fonts - XQueryKeymap, Manipulating the Keyboard and Pointer Settings - XQueryPointer, Translating Screen Coordinates - XQueryTextExtents, Querying Character String Sizes - XQueryTextExtents16, Querying Character String Sizes - XQueryTree, Obtaining Window Information - XRaiseWindow, Changing Window Stacking Order - XReadBitmapFile, Manipulating Bitmaps - XReadBitmapFileData, Manipulating Bitmaps - XRebindKeysym, Using Latin-1 Keyboard Event Functions - XRecolorCursor, Creating, Recoloring, and Freeing Cursors - XReconfigureWMWindow, Manipulating Top-Level Windows - XRectangle, Drawing Points, Lines, Rectangles, and Arcs - XRectInRegion, Locating a Point or a Rectangle in a Region - XRefreshKeyboardMapping, Using Keyboard Utility Functions - XRegisterIMInstantiateCallback, Input Method Functions - XRemoveConnectionWatch, Using Internal Connections - XRemoveFromSaveSet, Controlling the Lifetime of a Window - XRemoveHost, Adding, Getting, or Removing Hosts - XRemoveHosts, Adding, Getting, or Removing Hosts - XReparentEvent, ReparentNotify Events - XReparentWindow, Changing the Parent of a Window - XResetScreenSaver, Controlling the Screen Saver - XResizeRequestEvent, ResizeRequest Events - XResizeWindow, Configuring Windows - XResourceManagerString, Creating and Storing Databases - xResourceReq, Request Format - XRestackWindows, Changing Window Stacking Order - XrmCombineDatabase, Merging Resource Databases - XrmCombineFileDatabase, Merging Resource Databases - XrmDatabase, Creating and Storing Databases - XrmDestroyDatabase, Creating and Storing Databases - XrmEnumerateDatabase, Enumerating Database Entries - XrmGetDatabase, Creating and Storing Databases - XrmGetFileDatabase, Creating and Storing Databases - XrmGetResource, Looking Up Resources - XrmGetStringDatabase, Creating and Storing Databases - XrmInitialize, Creating and Storing Databases - XrmLocaleOfDatabase, Creating and Storing Databases - XrmMergeDatabases, Merging Resource Databases - XrmOptionDescRec, Parsing Command Line Options - XrmOptionKind, Parsing Command Line Options - XrmParseCommand, Parsing Command Line Options - XrmPermStringToQuark, Quarks - XrmPutFileDatabase, Creating and Storing Databases - XrmPutLineResource, Storing into a Resource Database - XrmPutResource, Storing into a Resource Database - XrmPutStringResource, Storing into a Resource Database - XrmQGetResource, Looking Up Resources - XrmQGetSearchList, Looking Up Resources - XrmQGetSearchResource, Looking Up Resources - XrmQPutResource, Storing into a Resource Database - XrmQPutStringResource, Storing into a Resource Database - XrmQuarkToString, Quarks - XrmSetDatabase, Creating and Storing Databases - XrmStringToBindingQuarkList, Quarks - XrmStringToQuark, Quarks - XrmStringToQuarkList, Quarks - XrmUniqueQuark, Quarks - XrmValue, Creating and Storing Databases - XRootWindow, Display Macros - XRootWindowOfScreen, Screen Information Macros - XRotateBuffers, Using Cut Buffers - XRotateWindowProperties, Obtaining and Changing Window - Properties - - XSaveContext, Using the Context Manager - XScreenCount, Display Macros - XScreenNumberOfScreen, Screen Information Macros - XScreenOfDisplay, Display Macros - XScreenResourceString, Creating and Storing Databases - XSegment, Drawing Points, Lines, Rectangles, and Arcs - XSelectInput, Selecting Events - XSelectionClearEvent, SelectionClear Events - XSelectionEvent, SelectionNotify Events - XSelectionRequestEvent, SelectionRequest Events - XSendEvent, Sending Events to Other Applications, Sending - Events to Other Applications - - XServerInterpretedAddress, Adding, Getting, or Removing Hosts - XServerVendor, Display Macros - XSetAccessControl, Changing, Enabling, or Disabling Access - Control - - XSetAfterFunction, Enabling or Disabling Synchronization - XSetArcMode, Setting the Arc Mode, Subwindow Mode, and Graphics - Exposure - - XSetBackground, Setting the Foreground, Background, Function, - or Plane Mask - - XSetClassHint, Setting and Reading the WM_CLASS Property - XSetClipMask, Setting the Clip Region - XSetClipOrigin, Setting the Clip Region - XSetClipRectangles, Setting the Clip Region - XSetCloseDownMode, Closing the Display - XSetCommand, Setting and Reading the WM_COMMAND Property - XSetDashes, Setting the Line Attributes and Dashes - XSetErrorHandler, Using the Default Error Handlers - XSetFillRule, Setting the Fill Style and Fill Rule - XSetFillStyle, Setting the Fill Style and Fill Rule - XSetFont, Setting the Current Font - XSetFontPath, Setting and Retrieving the Font Search Path - XSetForeground, Setting the Foreground, Background, Function, - or Plane Mask - - XSetFunction, Setting the Foreground, Background, Function, or - Plane Mask - - XSetGraphicsExposures, Setting the Arc Mode, Subwindow Mode, - and Graphics Exposure - - XSetICFocus, Input Context Functions - XSetIconName, Setting and Reading the WM_ICON_NAME Property - XSetIconSizes, Setting and Reading the WM_ICON_SIZE Property - XSetICValues, Input Context Functions - XSetIMValues, Input Method Functions - XSetInputFocus, Controlling Input Focus - XSetIOErrorHandler, Using the Default Error Handlers - XSetLineAttributes, Setting the Line Attributes and Dashes - XSetLocaleModifiers, X Locale Management - XSetModifierMapping, Manipulating the Keyboard Encoding - XSetNormalHints, Setting and Getting Window Sizing Hints - XSetOCValues, Output Context Functions - XSetOMValues, Output Method Functions - XSetPlaneMask, Setting the Foreground, Background, Function, or - Plane Mask - - XSetPointerMapping, Manipulating the Keyboard and Pointer - Settings - - XSetRegion, Creating, Copying, or Destroying Regions - XSetRGBColormaps, Setting and Obtaining Standard Colormaps - XSetScreenSaver, Controlling the Screen Saver - XSetSelectionOwner, Selections - XSetSizeHints, Setting and Getting Window Sizing Hints - XSetStandardColormap, Getting and Setting an XStandardColormap - Structure - - XSetStandardProperties, Setting Standard Properties - XSetState, Setting the Foreground, Background, Function, or - Plane Mask - - XSetStipple, Setting the Fill Tile and Stipple - XSetSubwindowMode, Setting the Arc Mode, Subwindow Mode, and - Graphics Exposure - - XSetTextProperty, Setting and Reading Text Properties - XSetTile, Setting the Fill Tile and Stipple - XSetTransientForHint, Setting and Reading the WM_TRANSIENT_FOR - Property - - XSetTSOrigin, Setting the Fill Tile and Stipple - XSetWindowAttributes, Window Attributes - XSetWindowBackground, Changing Window Attributes - XSetWindowBackgroundPixmap, Changing Window Attributes - XSetWindowBorder, Changing Window Attributes - XSetWindowBorderPixmap, Changing Window Attributes - XSetWindowBorderWidth, Configuring Windows - XSetWindowColormap, Changing Window Attributes - XSetWMClientMachine, Setting and Reading the WM_CLIENT_MACHINE - Property - - XSetWMColormapWindows, Setting and Reading the - WM_COLORMAP_WINDOWS Property - - XSetWMHints, Setting and Reading the WM_HINTS Property - XSetWMIconName, Setting and Reading the WM_ICON_NAME Property - XSetWMName, Setting and Reading the WM_NAME Property - XSetWMNormalHints, Setting and Reading the WM_NORMAL_HINTS - Property - - XSetWMProperties, Using Window Manager Convenience Functions - XSetWMProtocols, Setting and Reading the WM_PROTOCOLS Property - XSetWMSizeHints, Setting and Reading the WM_NORMAL_HINTS - Property - - XSetZoomHints, Setting and Getting Window Sizing Hints - XShrinkRegion, Moving or Shrinking Regions - XStoreBuffer, Using Cut Buffers - XStoreBytes, Using Cut Buffers - XStoreColor, Modifying and Querying Colormap Cells - XStoreColors, Modifying and Querying Colormap Cells - XStoreName, Setting and Reading the WM_NAME Property - XStoreNamedColor, Modifying and Querying Colormap Cells - XStringListToTextProperty, Converting String Lists - XStringToKeysym, Using Keyboard Utility Functions - XSubImage, Manipulating Images - XSubtractRegion, Computing with Regions - XSync, Overview of the X Window System, Overview of the X - Window System, Handling the Output Buffer - - XSynchronize, Enabling or Disabling Synchronization - XTextExtents, Computing Logical Extents - XTextExtents16, Computing Logical Extents - XTextItem, Drawing Text - XTextItem16, Drawing Text - XTextProperty, Converting String Lists - XTextPropertyToStringList, Converting String Lists - XTextWidth, Computing Character String Sizes, Computing - Character String Sizes - - XTextWidth16, Computing Character String Sizes, Computing - Character String Sizes - - XTimeCoord, Getting Pointer Motion History - XTranslateCoordinates, Translating Screen Coordinates - XUndefineCursor, Changing Window Attributes - XUngrabButton, Pointer Grabbing - XUngrabKey, Keyboard Grabbing - XUngrabKeyboard, Keyboard Grabbing - XUngrabPointer, Pointer Grabbing - XUngrabServer, Grabbing the Server - XUninstallColormap, Managing Installed Colormaps - XUnionRectWithRegion, Computing with Regions - XUnionRegion, Computing with Regions - XUnloadFont, Loading and Freeing Fonts - XUnlockDisplay, Using Xlib with Threads - XUnmapEvent, UnmapNotify Events - XUnmapSubwindows, Unmapping Windows - XUnmapWindow, Unmapping Windows, Unmapping Windows - XUnregisterIMInstantiateCallback, Input Method Functions - XUnsetICFocus, Input Context Functions - XVaCreateNestedList, Variable Argument Lists - XVendorRelease, Display Macros - XVisibilityEvent, VisibilityNotify Events - XVisualIDFromVisual, Visual Types - XWarpPointer, Moving the Pointer - XwcDrawImageString, Drawing Text Using Font Sets - XwcDrawString, Drawing Text Using Font Sets - XwcDrawText, Drawing Text Using Font Sets - XwcFreeStringList, Converting String Lists - XwcLookupString, Getting Keyboard Input - XwcResetIC, Input Context Functions - XwcTextEscapement, Obtaining Font Set Metrics - XwcTextExtents, Obtaining Font Set Metrics - XwcTextItem, Drawing Text Using Font Sets - XwcTextListToTextProperty, Converting String Lists - XwcTextPerCharExtents, Obtaining Font Set Metrics - XwcTextPropertyToTextList, Converting String Lists - XWhitePixel, Display Macros - XWhitePixelOfScreen, Screen Information Macros - XWidthMMOfScreen, Screen Information Macros - XWidthOfScreen, Screen Information Macros - XWindowAttributes, Obtaining Window Information - XWindowChanges, Configuring Windows - XWindowEvent, Handling the Output Buffer, Selecting Events - Using a Window or Event Mask - - XWithdrawWindow, Manipulating Top-Level Windows - XWMGeometry, Parsing the Window Geometry - XWriteBitmapFile, Manipulating Bitmaps, Manipulating Bitmaps - XXorRegion, Computing with Regions - XY format, Glossary - -Z - - Z format, Glossary -- cgit 1.4.1-21-gabe81