Xlib - C Language X Interface
X Consortium Standard
James Gettys
Digital Equipment Corporation
Cambridge Research Laboratory
Robert W. Scheifler
Massachusetts Institute of Technology
Laboratory for Computer Science
Chuck Adams
Tektronix, Inc.
Vania Joloboff
Open Software Foundation
Hideki Hiura
Sun Microsystems, Inc.
Bill McMahon
Hewlett-Packard Company
Ron Newman
Massachusetts Institute of Technology
Al Tabayoyon
Tektronix, Inc.
Glenn Widener
Tektronix, Inc.
Shigeru Yamada
Fujitsu OSSI
X Version 11, Release 7.7
Copyright © 1985, 1986, 1987, 1988, 1989, 1991, 1994, 1996, 2002 The Open Group
Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Except as contained in this notice, the name of The Open Group shall not be
used in advertising or otherwise to promote the sale, use or other dealings in
this Software without prior written authorization from The Open Group.
Copyright © 1985, 1986, 1987, 1988, 1989, 1991 Digital Equipment Corporation
Permission to use, copy, modify and distribute this documentation for any
purpose and without fee is hereby granted, provided that the above copyright
notice appears in all copies and that both that copyright notice and this
permission notice appear in supporting documentation, and that the names of
Digital and Tetronix not be used in in advertising or publicity pertaining to
distribution of the software without specific, written prior permission.
Digital and Tetronix make no representations about the suitability of the
software described herein for any purpose. It is provided “as is” without
express or implied warranty.
TekHVC is a trademark of Tektronix, Inc.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Table of Contents
Acknowledgments
1. Introduction to Xlib
Overview of the X Window System
Errors
Standard Header Files
Generic Values and Types
Naming and Argument Conventions within Xlib
Programming Considerations
Character Sets and Encodings
Formatting Conventions
2. Display Functions
Opening the Display
Obtaining Information about the Display, Image Formats, or Screens
Display Macros
Image Format Functions and Macros
Screen Information Macros
Generating a NoOperation Protocol Request
Freeing Client-Created Data
Closing the Display
Using X Server Connection Close Operations
Using Xlib with Threads
Using Internal Connections
3. Window Functions
Visual Types
Window Attributes
Background Attribute
Border Attribute
Gravity Attributes
Backing Store Attribute
Save Under Flag
Backing Planes and Backing Pixel Attributes
Event Mask and Do Not Propagate Mask Attributes
Override Redirect Flag
Colormap Attribute
Cursor Attribute
Creating Windows
Destroying Windows
Mapping Windows
Unmapping Windows
Configuring Windows
Changing Window Stacking Order
Changing Window Attributes
4. Window Information Functions
Obtaining Window Information
Translating Screen Coordinates
Properties and Atoms
Obtaining and Changing Window Properties
Selections
5. Pixmap and Cursor Functions
Creating and Freeing Pixmaps
Creating, Recoloring, and Freeing Cursors
6. Color Management Functions
Color Structures
Color Strings
RGB Device String Specification
RGB Intensity String Specification
Device-Independent String Specifications
Color Conversion Contexts and Gamut Mapping
Creating, Copying, and Destroying Colormaps
Mapping Color Names to Values
Allocating and Freeing Color Cells
Modifying and Querying Colormap Cells
Color Conversion Context Functions
Getting and Setting the Color Conversion Context of a Colormap
Obtaining the Default Color Conversion Context
Color Conversion Context Macros
Modifying Attributes of a Color Conversion Context
Creating and Freeing a Color Conversion Context
Converting between Color Spaces
Callback Functions
Prototype Gamut Compression Procedure
Supplied Gamut Compression Procedures
Prototype White Point Adjustment Procedure
Supplied White Point Adjustment Procedures
Gamut Querying Functions
Red, Green, and Blue Queries
CIELab Queries
CIELuv Queries
TekHVC Queries
Color Management Extensions
Color Spaces
Adding Device-Independent Color Spaces
Querying Color Space Format and Prefix
Creating Additional Color Spaces
Parse String Callback
Color Specification Conversion Callback
Function Sets
Adding Function Sets
Creating Additional Function Sets
7. Graphics Context Functions
Manipulating Graphics Context/State
Using Graphics Context Convenience Routines
Setting the Foreground, Background, Function, or Plane Mask
Setting the Line Attributes and Dashes
Setting the Fill Style and Fill Rule
Setting the Fill Tile and Stipple
Setting the Current Font
Setting the Clip Region
Setting the Arc Mode, Subwindow Mode, and Graphics Exposure
8. Graphics Functions
Clearing Areas
Copying Areas
Drawing Points, Lines, Rectangles, and Arcs
Drawing Single and Multiple Points
Drawing Single and Multiple Lines
Drawing Single and Multiple Rectangles
Drawing Single and Multiple Arcs
Filling Areas
Filling Single and Multiple Rectangles
Filling a Single Polygon
Filling Single and Multiple Arcs
Font Metrics
Loading and Freeing Fonts
Obtaining and Freeing Font Names and Information
Computing Character String Sizes
Computing Logical Extents
Querying Character String Sizes
Drawing Text
Drawing Complex Text
Drawing Text Characters
Drawing Image Text Characters
Transferring Images between Client and Server
9. Window and Session Manager Functions
Changing the Parent of a Window
Controlling the Lifetime of a Window
Managing Installed Colormaps
Setting and Retrieving the Font Search Path
Grabbing the Server
Killing Clients
Controlling the Screen Saver
Controlling Host Access
Adding, Getting, or Removing Hosts
Changing, Enabling, or Disabling Access Control
10. Events
Event Types
Event Structures
Event Masks
Event Processing Overview
Keyboard and Pointer Events
Pointer Button Events
Keyboard and Pointer Events
Window Entry/Exit Events
Normal Entry/Exit Events
Grab and Ungrab Entry/Exit Events
Input Focus Events
Normal Focus Events and Focus Events While Grabbed
Focus Events Generated by Grabs
Key Map State Notification Events
Exposure Events
Expose Events
GraphicsExpose and NoExpose Events
Window State Change Events
CirculateNotify Events
ConfigureNotify Events
CreateNotify Events
DestroyNotify Events
GravityNotify Events
MapNotify Events
MappingNotify Events
ReparentNotify Events
UnmapNotify Events
VisibilityNotify Events
Structure Control Events
CirculateRequest Events
ConfigureRequest Events
MapRequest Events
ResizeRequest Events
Colormap State Change Events
Client Communication Events
ClientMessage Events
PropertyNotify Events
SelectionClear Events
SelectionRequest Events
SelectionNotify Events
11. Event Handling Functions
Selecting Events
Handling the Output Buffer
Event Queue Management
Manipulating the Event Queue
Returning the Next Event
Selecting Events Using a Predicate Procedure
Selecting Events Using a Window or Event Mask
Putting an Event Back into the Queue
Sending Events to Other Applications
Getting Pointer Motion History
Handling Protocol Errors
Enabling or Disabling Synchronization
Using the Default Error Handlers
12. Input Device Functions
Pointer Grabbing
Keyboard Grabbing
Resuming Event Processing
Moving the Pointer
Controlling Input Focus
Manipulating the Keyboard and Pointer Settings
Manipulating the Keyboard Encoding
13. Locales and Internationalized Text Functions
X Locale Management
Locale and Modifier Dependencies
Variable Argument Lists
Output Methods
Output Method Overview
Output Method Functions
X Output Method Values
Output Context Functions
Output Context Values
Creating and Freeing a Font Set
Obtaining Font Set Metrics
Drawing Text Using Font Sets
Input Methods
Input Method Overview
Input Method Management
Input Method Functions
Input Method Values
Input Context Functions
Input Context Values
Input Method Callback Semantics
Event Filtering
Getting Keyboard Input
Input Method Conventions
String Constants
14. Inter-Client Communication Functions
Client to Window Manager Communication
Manipulating Top-Level Windows
Converting String Lists
Setting and Reading Text Properties
Setting and Reading the WM_NAME Property
Setting and Reading the WM_ICON_NAME Property
Setting and Reading the WM_HINTS Property
Setting and Reading the WM_NORMAL_HINTS Property
Setting and Reading the WM_CLASS Property
Setting and Reading the WM_TRANSIENT_FOR Property
Setting and Reading the WM_PROTOCOLS Property
Setting and Reading the WM_COLORMAP_WINDOWS Property
Setting and Reading the WM_ICON_SIZE Property
Using Window Manager Convenience Functions
Client to Session Manager Communication
Setting and Reading the WM_COMMAND Property
Setting and Reading the WM_CLIENT_MACHINE Property
Standard Colormaps
Standard Colormap Properties and Atoms
Setting and Obtaining Standard Colormaps
15. Resource Manager Functions
Resource File Syntax
Resource Manager Matching Rules
Quarks
Creating and Storing Databases
Merging Resource Databases
Looking Up Resources
Storing into a Resource Database
Enumerating Database Entries
Parsing Command Line Options
16. Application Utility Functions
Using Keyboard Utility Functions
KeySym Classification Macros
Using Latin-1 Keyboard Event Functions
Allocating Permanent Storage
Parsing the Window Geometry
Manipulating Regions
Creating, Copying, or Destroying Regions
Moving or Shrinking Regions
Computing with Regions
Determining if Regions Are Empty or Equal
Locating a Point or a Rectangle in a Region
Using Cut Buffers
Determining the Appropriate Visual Type
Manipulating Images
Manipulating Bitmaps
Using the Context Manager
A. Xlib Functions and Protocol Requests
B. X Font Cursors
C. Extensions
Basic Protocol Support Routines
Hooking into Xlib
Hooks into the Library
Hooks onto Xlib Data Structures
GC Caching
Graphics Batching
Writing Extension Stubs
Requests, Replies, and Xproto.h
Request Format
Starting to Write a Stub Procedure
Locking Data Structures
Sending the Protocol Request and Arguments
Variable Length Arguments
Replies
Synchronous Calling
Allocating and Deallocating Memory
Portability Considerations
Deriving the Correct Extension Opcode
D. Compatibility Functions
X Version 11 Compatibility Functions
Setting Standard Properties
Setting and Getting Window Sizing Hints
Getting and Setting an XStandardColormap Structure
Parsing Window Geometry
Getting the X Environment Defaults
X Version 10 Compatibility Functions
Drawing and Filling Polygons and Curves
Associating User Data with a Value
Glossary
Index
List of Tables
A.1. Protocol requests made by each Xlib function
A.2. Xlib functions which use each Protocol Request
Acknowledgments
The design and implementation of the first 10 versions of X were primarily the
work of three individuals: Robert Scheifler of the MIT Laboratory for Computer
Science and Jim Gettys of Digital Equipment Corporation and Ron Newman of MIT,
both at MIT Project Athena. X version 11, however, is the result of the efforts
of dozens of individuals at almost as many locations and organizations. At the
risk of offending some of the players by exclusion, we would like to
acknowledge some of the people who deserve special credit and recognition for
their work on Xlib. Our apologies to anyone inadvertently overlooked.
Release 1
Our thanks does to Ron Newman (MIT Project Athena), who contributed
substantially to the design and implementation of the Version 11 Xlib
interface.
Our thanks also goes to Ralph Swick (Project Athena and Digital) who kept it
all together for us during the early releases. He handled literally thousands
of requests from people everywhere and saved the sanity of at least one of us.
His calm good cheer was a foundation on which we could build.
Our thanks also goes to Todd Brunhoff (Tektronix) who was ``loaned'' to Project
Athena at exactly the right moment to provide very capable and much-needed
assistance during the alpha and beta releases. He was responsible for the
successful integration of sources from multiple sites; we would not have had a
release without him.
Our thanks also goes to Al Mento and Al Wojtas of Digital's ULTRIX
Documentation Group. With good humor and cheer, they took a rough draft and
made it an infinitely better and more useful document. The work they have done
will help many everywhere. We also would like to thank Hal Murray (Digital SRC)
and Peter George (Digital VMS) who contributed much by proofreading the early
drafts of this document.
Our thanks also goes to Jeff Dike (Digital UEG), Tom Benson, Jackie Granfield,
and Vince Orgovan (Digital VMS) who helped with the library utilities
implementation; to Hania Gajewska (Digital UEG-WSL) who, along with Ellis Cohen
(CMU and Siemens), was instrumental in the semantic design of the window
manager properties; and to Dave Rosenthal (Sun Microsystems) who also
contributed to the protocol and provided the sample generic color frame buffer
device-dependent code.
The alpha and beta test participants deserve special recognition and thanks as
well. It is significant that the bug reports (and many fixes) during alpha and
beta test came almost exclusively from just a few of the alpha testers, mostly
hardware vendors working on product implementations of X. The continued public
contribution of vendors and universities is certainly to the benefit of the
entire X community.
Our special thanks must go to Sam Fuller, Vice-President of Corporate Research
at Digital, who has remained committed to the widest public availability of X
and who made it possible to greatly supplement MIT's resources with the Digital
staff in order to make version 11 a reality. Many of the people mentioned here
are part of the Western Software Laboratory (Digital UEG-WSL) of the ULTRIX
Engineering group and work for Smokey Wallace, who has been vital to the
project's success. Others not mentioned here worked on the toolkit and are
acknowledged in the X Toolkit documentation.
Of course, we must particularly thank Paul Asente, formerly of Stanford
University and now of Digital UEG-WSL, who wrote W, the predecessor to X, and
Brian Reid, formerly of Stanford University and now of Digital WRL, who had
much to do with W's design.
Finally, our thanks goes to MIT, Digital Equipment Corporation, and IBM for
providing the environment where it could happen.
Release 4
Our thanks go to Jim Fulton (MIT X Consortium) for designing and specifying the
new Xlib functions for Inter-Client Communication Conventions (ICCCM) support.
We also thank Al Mento of Digital for his continued effort in maintaining this
document and Jim Fulton and Donna Converse (MIT X Consortium) for their
much-appreciated efforts in reviewing the changes.
Release 5
The principal authors of the Input Method facilities are Vania Joloboff (Open
Software Foundation) and Bill McMahon (Hewlett-Packard). The principal author
of the rest of the internationalization facilities is Glenn Widener
(Tektronix). Our thanks to them for keeping their sense of humor through a long
and sometimes difficult design process. Although the words and much of the
design are due to them, many others have contributed substantially to the
design and implementation. Tom McFarland (HP) and Frank Rojas (IBM) deserve
particular recognition for their contributions. Other contributors were: Tim
Anderson (Motorola), Alka Badshah (OSF), Gabe Beged-Dov (HP), Chih-Chung Ko
(III), Vera Cheng (III), Michael Collins (Digital), Walt Daniels (IBM),
Noritoshi Demizu (OMRON), Keisuke Fukui (Fujitsu), Hitoshoi Fukumoto (Nihon
Sun), Tim Greenwood (Digital), John Harvey (IBM), Hideki Hiura (Sun), Fred
Horman (AT&T), Norikazu Kaiya (Fujitsu), Yuji Kamata (IBM), Yutaka Kataoka
(Waseda University), Ranee Khubchandani (Sun), Akira Kon (NEC), Hiroshi
Kuribayashi (OMRON), Teruhiko Kurosaka (Sun), Seiji Kuwari (OMRON), Sandra
Martin (OSF), Narita Masahiko (Fujitsu), Masato Morisaki (NTT), Nelson Ng
(Sun), Takashi Nishimura (NTT America), Makato Nishino (IBM), Akira Ohsone
(Nihon Sun), Chris Peterson (MIT), Sam Shteingart (AT&T), Manish Sheth (AT&T),
Muneiyoshi Suzuki (NTT), Cori Mehring (Digital), Shoji Sugiyama (IBM), and Eiji
Tosa (IBM).
We are deeply indebted to Tatsuya Kato (NTT), Hiroshi Kuribayashi (OMRON),
Seiji Kuwari (OMRON), Muneiyoshi Suzuki (NTT), and Li Yuhong (OMRON) for
producing one of the first complete sample implementation of the
internationalization facilities, and Hiromu Inukai (Nihon Sun), Takashi
Fujiwara (Fujitsu), Hideki Hiura (Sun), Yasuhiro Kawai (Oki Technosystems
Laboratory), Kazunori Nishihara (Fuji Xerox), Masaki Takeuchi (Sony), Katsuhisa
Yano (Toshiba), Makoto Wakamatsu (Sony Corporation) for producing the another
complete sample implementation of the internationalization facilities.
The principal authors (design and implementation) of the Xcms color management
facilities are Al Tabayoyon (Tektronix) and Chuck Adams (Tektronix). Joann
Taylor (Tektronix), Bob Toole (Tektronix), and Keith Packard (MIT X Consortium)
also contributed significantly to the design. Others who contributed are:
Harold Boll (Kodak), Ken Bronstein (HP), Nancy Cam (SGI), Donna Converse (MIT X
Consortium), Elias Israel (ISC), Deron Johnson (Sun), Jim King (Adobe), Ricardo
Motta (HP), Chuck Peek (IBM), Wil Plouffe (IBM), Dave Sternlicht (MIT X
Consortium), Kumar Talluri (AT&T), and Richard Verberg (IBM).
We also once again thank Al Mento of Digital for his work in formatting and
reformatting text for this manual, and for producing man pages. Thanks also to
Clive Feather (IXI) for proof-reading and finding a number of small errors.
Release 6
Stephen Gildea (X Consortium) authored the threads support. Ovais Ashraf (Sun)
and Greg Olsen (Sun) contributed substantially by testing the facilities and
reporting bugs in a timely fashion.
The principal authors of the internationalization facilities, including Input
and Output Methods, are Hideki Hiura (SunSoft) and Shigeru Yamada (Fujitsu
OSSI). Although the words and much of the design are due to them, many others
have contributed substantially to the design and implementation. They are:
Takashi Fujiwara (Fujitsu), Yoshio Horiuchi (IBM), Makoto Inada (Digital),
Hiromu Inukai (Nihon SunSoft), Song JaeKyung (KAIST), Franky Ling (Digital),
Tom McFarland (HP), Hiroyuki Miyamoto (Digital), Masahiko Narita (Fujitsu),
Frank Rojas (IBM), Hidetoshi Tajima (HP), Masaki Takeuchi (Sony), Makoto
Wakamatsu (Sony), Masaki Wakao (IBM), Katsuhisa Yano(Toshiba) and Jinsoo Yoon
(KAIST).
The principal producers of the sample implementation of the
internationalization facilities are: Jeffrey Bloomfield (Fujitsu OSSI), Takashi
Fujiwara (Fujitsu), Hideki Hiura (SunSoft), Yoshio Horiuchi (IBM), Makoto Inada
(Digital), Hiromu Inukai (Nihon SunSoft), Song JaeKyung (KAIST), Riki Kawaguchi
(Fujitsu), Franky Ling (Digital), Hiroyuki Miyamoto (Digital), Hidetoshi Tajima
(HP), Toshimitsu Terazono (Fujitsu), Makoto Wakamatsu (Sony), Masaki Wakao
(IBM), Shigeru Yamada (Fujitsu OSSI) and Katsuhisa Yano (Toshiba).
The coordinators of the integration, testing, and release of this
implementation of the internationalization facilities are Nobuyuki Tanaka
(Sony) and Makoto Wakamatsu (Sony).
Others who have contributed to the architectural design or testing of the
sample implementation of the internationalization facilities are: Hector Chan
(Digital), Michael Kung (IBM), Joseph Kwok (Digital), Hiroyuki Machida (Sony),
Nelson Ng (SunSoft), Frank Rojas (IBM), Yoshiyuki Segawa (Fujitsu OSSI), Makiko
Shimamura (Fujitsu), Shoji Sugiyama (IBM), Lining Sun (SGI), Masaki Takeuchi
(Sony), Jinsoo Yoon (KAIST) and Akiyasu Zen (HP).
Jim Gettys
Cambridge Research Laboratory
Digital Equipment Corporation
Robert W. Scheifler
Laboratory for Computer Science
Massachusetts Institute of Technology
Release 7
This document is made available to you in modern formats such as HTML and PDF
thanks to the efforts of Matt Dew, who converted the original troff sources to
DocBook/XML and edited them into shape; along with Gaetan Nadon and Alan
Coopersmith, who set up the formatting machinery in the libX11 builds and
performed further editing of the DocBook markup.
Chapter 1. Introduction to Xlib
Table of Contents
Overview of the X Window System
Errors
Standard Header Files
Generic Values and Types
Naming and Argument Conventions within Xlib
Programming Considerations
Character Sets and Encodings
Formatting Conventions
The X Window System is a network-transparent window system that was designed at
MIT. X display servers run on computers with either monochrome or color bitmap
display hardware. The server distributes user input to and accepts output
requests from various client programs located either on the same machine or
elsewhere in the network. Xlib is a C subroutine library that application
programs (clients) use to interface with the window system by means of a stream
connection. Although a client usually runs on the same machine as the X server
it is talking to, this need not be the case.
Xlib − C Language X Interface is a reference guide to the low-level C language
interface to the X Window System protocol. It is neither a tutorial nor a
user’s guide to programming the X Window System. Rather, it provides a detailed
description of each function in the library as well as a discussion of the
related background information. Xlib − C Language X Interface assumes a basic
understanding of a graphics window system and of the C programming language.
Other higher-level abstractions (for example, those provided by the toolkits
for X) are built on top of the Xlib library. For further information about
these higher-level libraries, see the appropriate toolkit documentation. The X
Window System Protocol provides the definitive word on the behavior of X.
Although additional information appears here, the protocol document is the
ruling document.
To provide an introduction to X programming, this chapter discusses:
• Overview of the X Window System
• Errors
• Standard header files
• Generic values and types
• Naming and argument conventions within Xlib
• Programming considerations
• Character sets and encodings
• Formatting conventions
Overview of the X Window System
Some of the terms used in this book are unique to X, and other terms that are
common to other window systems have different meanings in X. You may find it
helpful to refer to the glossary, which is located at the end of the book.
The X Window System supports one or more screens containing overlapping windows
or subwindows. A screen is a physical monitor and hardware that can be color,
grayscale, or monochrome. There can be multiple screens for each display or
workstation. A single X server can provide display services for any number of
screens. A set of screens for a single user with one keyboard and one pointer
(usually a mouse) is called a display.
All the windows in an X server are arranged in strict hierarchies. At the top
of each hierarchy is a root window, which covers each of the display screens.
Each root window is partially or completely covered by child windows. All
windows, except for root windows, have parents. There is usually at least one
window for each application program. Child windows may in turn have their own
children. In this way, an application program can create an arbitrarily deep
tree on each screen. X provides graphics, text, and raster operations for
windows.
A child window can be larger than its parent. That is, part or all of the child
window can extend beyond the boundaries of the parent, but all output to a
window is clipped by its parent. If several children of a window have
overlapping locations, one of the children is considered to be on top of or
raised over the others, thus obscuring them. Output to areas covered by other
windows is suppressed by the window system unless the window has backing store.
If a window is obscured by a second window, the second window obscures only
those ancestors of the second window that are also ancestors of the first
window.
A window has a border zero or more pixels in width, which can be any pattern
(pixmap) or solid color you like. A window usually but not always has a
background pattern, which will be repainted by the window system when
uncovered. Child windows obscure their parents, and graphic operations in the
parent window usually are clipped by the children.
Each window and pixmap has its own coordinate system. The coordinate system has
the X axis horizontal and the Y axis vertical with the origin [0, 0] at the
upper-left corner. Coordinates are integral, in terms of pixels, and coincide
with pixel centers. For a window, the origin is inside the border at the
inside, upper-left corner.
X does not guarantee to preserve the contents of windows. When part or all of a
window is hidden and then brought back onto the screen, its contents may be
lost. The server then sends the client program an Expose event to notify it
that part or all of the window needs to be repainted. Programs must be prepared
to regenerate the contents of windows on demand.
X also provides off-screen storage of graphics objects, called pixmaps. Single
plane (depth 1) pixmaps are sometimes referred to as bitmaps. Pixmaps can be
used in most graphics functions interchangeably with windows and are used in
various graphics operations to define patterns or tiles. Windows and pixmaps
together are referred to as drawables.
Most of the functions in Xlib just add requests to an output buffer. These
requests later execute asynchronously on the X server. Functions that return
values of information stored in the server do not return (that is, they block)
until an explicit reply is received or an error occurs. You can provide an
error handler, which will be called when the error is reported.
If a client does not want a request to execute asynchronously, it can follow
the request with a call to XSync, which blocks until all previously buffered
asynchronous events have been sent and acted on. As an important side effect,
the output buffer in Xlib is always flushed by a call to any function that
returns a value from the server or waits for input.
Many Xlib functions will return an integer resource ID, which allows you to
refer to objects stored on the X server. These can be of type Window, Font,
Pixmap, Colormap, Cursor, and GContext, as defined in the file <X11/X.h>. These
resources are created by requests and are destroyed (or freed) by requests or
when connections are closed. Most of these resources are potentially shareable
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
<X11/Xlib.h> 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
<X11/X.h> are to be used by applications. It is included automatically from
<X11/Xlib.h> so application code should never need to reference
this file directly.
This file contains symbols for much of the color management
facilities described in chapter 6. All functions, types, and
<X11/Xcms.h> symbols with the prefix "Xcms", plus the Color Conversion
Contexts macros, are declared in this file. <X11/Xlib.h> must be
included before including this file.
This file declares various functions, types, and symbols used for
<X11/Xutil.h> inter-client communication and application utility functions,
which are described in chapters 14 and 16. <X11/Xlib.h> must be
included before including this file.
<X11/ This file declares all functions, types, and symbols for the
Xresource.h> resource manager facilities, which are described in chapter 15.
<X11/Xlib.h> must be included before including this file.
<X11/Xatom.h> This file declares all predefined atoms, which are symbols with
the prefix "XA_".
<X11/ This file declares the cursor symbols for the standard cursor
cursorfont.h> 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
<X11/ preprocessor symbol must be defined prior to inclusion of the
keysymdef.h> file to obtain the associated values. The preprocessor symbols
are XK_MISCELLANY, XK_XKB_KEYS, XK_3270, XK_LATIN1, XK_LATIN2,
XK_LATIN3, XK_LATIN4, XK_KATAKANA, XK_ARABIC, XK_CYRILLIC,
XK_GREEK, XK_TECHNICAL, XK_SPECIAL, XK_PUBLISHING, XK_APL,
XK_HEBREW, XK_THAI, and XK_KOREAN.
<X11/ This file defines the preprocessor symbols XK_MISCELLANY,
keysym.h> XK_XKB_KEYS, XK_LATIN1, XK_LATIN2, XK_LATIN3, XK_LATIN4, and
XK_GREEK and then includes <X11/keysymdef.h>.
<X11/ This file declares all the functions, types, and symbols used for
Xlibint.h> extensions, which are described in Appendix C. This file
automatically includes <X11/Xlib.h>.
This file declares types and symbols for the basic X protocol,
<X11/ for use in implementing extensions. It is included automatically
Xproto.h> from <X11/Xlibint.h>, so application and extension code should
never need to reference this file directly.
This file declares types and symbols for the basic X protocol,
<X11/ for use in implementing extensions. It is included automatically
Xprotostr.h> from <X11/Xproto.h>, so application and extension code should
never need to reference this file directly.
This file declares all the functions, types, and symbols used for
<X11/X10.h> 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:
A basic set of 97 characters, which are assumed to exist in all
locales supported by Xlib. This set contains the following
characters:
X Portable a..z A..Z 0..9 !"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~ <space>,
Character <tab>, and <newline>
Set
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.
The encoding of the X Portable Character Set on the host. The
Host encoding itself is not defined by this standard, but the encoding
Portable must be the same in all locales supported by Xlib on the host. If
Character a string is said to be in the Host Portable Character Encoding,
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 The encoding of the X Portable Character Set using the Latin-1
Portable codepoints plus ASCII control characters. If a string is said to
Character be in the Latin Portable Character Encoding, then it only contains
Encoding characters from the X Portable Character Set, not all of Latin-1.
STRING Latin-1, plus tab and newline.
Encoding
POSIX The set of 65 characters, which can be used in naming files on a
Portable POSIX-compliant host, that are correctly processed in all locales.
Filename The set is:
Character
Set
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);
Specifies the hardware display name, which determines the display
display_name 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
Specifies a protocol family or an alias for a protocol family.
protocol 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.
Specifies the name of the host machine on which the display is
hostname physically attached. You follow the hostname with either a single
colon (:) or a double colon (::).
Specifies the number of the display server on that host machine.
number 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.
Specifies the screen to be used on that server. Multiple screens
can be controlled by a single X server. The screen_number sets an
screen_number internal variable that can be accessed by using the DefaultScreen
macro or the XDefaultScreen function if you are using languages
other than C (see section 2.2.1).
For example, the following would specify screen 1 of display 0 on the machine
named ``dual-headed'':
dual-headed:0.1
The XOpenDisplay function returns a Display structure that serves as the
connection to the X server and that contains all the information about that X
server. XOpenDisplay connects your application to the X server through TCP or
DECnet communications protocols, or through some local inter-process
communication protocol. If the protocol is specified as "tcp", "inet", or
"inet6", or if no protocol is specified and the hostname is a host machine name
and a single colon (:) separates the hostname and display number, XOpenDisplay
connects using TCP streams. (If the protocol is specified as "inet", TCP over
IPv4 is used. If the protocol is specified as "inet6", TCP over IPv6 is used.
Otherwise, the implementation determines which IP version is used.) If the
hostname and protocol are both not specified, Xlib uses whatever it believes is
the fastest transport. If the hostname is a host machine name and a double
colon (::) separates the hostname and display number, XOpenDisplay connects
using DECnet. A single X server can support any or all of these transport
mechanisms simultaneously. A particular Xlib implementation can support many
more of these transport mechanisms.
If successful, XOpenDisplay returns a pointer to a Display structure, which is
defined in <X11/Xlib.h>. If XOpenDisplay does not succeed, it returns NULL.
After a successful call to XOpenDisplay, all of the screens in the display can
be used by the client. The screen number specified in the display_name argument
is returned by the DefaultScreen macro (or the XDefaultScreen function). You
can access elements of the Display and Screen structures only by using the
information macros or functions. For information about using macros and
functions to obtain information from the Display structure, see section 2.2.1.
X servers may implement various types of access control mechanisms (see section
9.8).
Obtaining Information about the Display, Image Formats, or Screens
The Xlib library provides a number of useful macros and corresponding functions
that return data from the Display structure. The macros are used for C
programming, and their corresponding function equivalents are for other
language bindings. This section discusses the:
• Display macros
• Image format functions and macros
• Screen information macros
All other members of the Display structure (that is, those for which no macros
are defined) are private to Xlib and must not be used. Applications must never
directly modify or inspect these private members of the Display structure. The
XDisplayWidth, XDisplayHeight, XDisplayCells, XDisplayPlanes, XDisplayWidthMM,
and XDisplayHeightMM functions in the next sections are misnamed. These
functions really should be named Screenwhatever and XScreenwhatever, not
Displaywhatever or XDisplaywhatever. Our apologies for the resulting confusion.
Display Macros
Applications should not directly modify any part of the Display and Screen
structures. The members should be considered read-only, although they may
change as the result of other operations on the display.
The following lists the C language macros, their corresponding function
equivalents that are for other language bindings, and what data both can
return.
AllPlanes
unsigned long XAllPlanes(void);
Both return a value with all bits set to 1 suitable for use in a plane argument
to a procedure.
Both BlackPixel and WhitePixel can be used in implementing a monochrome
application. These pixel values are for permanently allocated entries in the
default colormap. The actual RGB (red, green, and blue) values are settable on
some screens and, in any case, may not actually be black or white. The names
are intended to convey the expected relative intensity of the colors.
BlackPixel(display, screen_number);
unsigned long XBlackPixel(Display *display, int screen_number);
display Specifies the connection to the X server.
screen_number Specifies the appropriate screen number on the host server.
Both return the black pixel value for the specified screen.
WhitePixel(display, screen_number);
unsigned long XWhitePixel(Display *display, int screen_number);
display Specifies the connection to the X server.
screen_number Specifies the appropriate screen number on the host server.
Both return the white pixel value for the specified screen.
ConnectionNumber(display);
int XConnectionNumber(Display *display);
display Specifies the connection to the X server.
Both return a connection number for the specified display. On a POSIX
-conformant system, this is the file descriptor of the connection.
DefaultColormap(display, screen_number);
Colormap XDefaultColormap(Display *display, int screen_number);
display Specifies the connection to the X server.
screen_number Specifies the appropriate screen number on the host server.
Both return the default colormap ID for allocation on the specified screen.
Most routine allocations of color should be made out of this colormap.
DefaultDepth(display, screen_number);
int XDefaultDepth(Display *display, int screen_number);
display Specifies the connection to the X server.
screen_number Specifies the appropriate screen number on the host server.
Both return the depth (number of planes) of the default root window for the
specified screen. Other depths may also be supported on this screen (see
XMatchVisualInfo).
To determine the number of depths that are available on a given screen, use
XListDepths.
int *XListDepths(Display *display, int screen_number, int *count_return);
display Specifies the connection to the X server.
screen_number Specifies the appropriate screen number on the host server.
count_return Returns the number of depths.
The XListDepths function returns the array of depths that are available on the
specified screen. If the specified screen_number is valid and sufficient memory
for the array can be allocated, XListDepths sets count_return to the number of
available depths. Otherwise, it does not set count_return and returns NULL. To
release the memory allocated for the array of depths, use XFree.
DefaultGC(display, screen_number);
GC XDefaultGC(Display *display, int screen_number);
display Specifies the connection to the X server.
screen_number Specifies the appropriate screen number on the host server.
Both return the default graphics context for the root window of the specified
screen. This GC is created for the convenience of simple applications and
contains the default GC components with the foreground and background pixel
values initialized to the black and white pixels for the screen, respectively.
You can modify its contents freely because it is not used in any Xlib function.
This GC should never be freed.
DefaultRootWindow(display);
Window XDefaultRootWindow(Display *display);
display Specifies the connection to the X server.
Both return the root window for the default screen.
DefaultScreenOfDisplay(display);
Screen *XDefaultScreenOfDisplay(Display *display);
display Specifies the connection to the X server.
Both return a pointer to the default screen.
ScreenOfDisplay(display, screen_number);
Screen *XScreenOfDisplay(Display *display, int screen_number);
display Specifies the connection to the X server.
screen_number Specifies the appropriate screen number on the host server.
Both return a pointer to the indicated screen.
DefaultScreen(display);
int XDefaultScreen(Display *display);
display Specifies the connection to the X server.
Both return the default screen number referenced by the XOpenDisplay function.
This macro or function should be used to retrieve the screen number in
applications that will use only a single screen.
DefaultVisual(display, screen_number);
Visual *XDefaultVisual(Display *display, int screen_number);
display Specifies the connection to the X server.
screen_number Specifies the appropriate screen number on the host server.
Both return the default visual type for the specified screen. For further
information about visual types, see section 3.1.
DisplayCells(display, screen_number);
int XDisplayCells(Display *display, int screen_number);
display Specifies the connection to the X server.
screen_number Specifies the appropriate screen number on the host server.
Both return the number of entries in the default colormap.
DisplayPlanes(display, screen_number);
int XDisplayPlanes(Display *display, int screen_number);
display Specifies the connection to the X server.
screen_number Specifies the appropriate screen number on the host server.
Both return the depth of the root window of the specified screen. For an
explanation of depth, see the glossary.
DisplayString(display);
char *XDisplayString(Display *display);
display Specifies the connection to the X server.
Both return the string that was passed to XOpenDisplay when the current display
was opened. On POSIX-conformant systems, if the passed string was NULL, these
return the value of the DISPLAY environment variable when the current display
was opened. These are useful to applications that invoke the fork system call
and want to open a new connection to the same display from the child process as
well as for printing error messages.
long XExtendedMaxRequestSize(Display *display);
display Specifies the connection to the X server.
The XExtendedMaxRequestSize function returns zero if the specified display does
not support an extended-length protocol encoding; otherwise, it returns the
maximum request size (in 4-byte units) supported by the server using the
extended-length encoding. The Xlib functions XDrawLines, XDrawArcs,
XFillPolygon, XChangeProperty, XSetClipRectangles, and XSetRegion will use the
extended-length encoding as necessary, if supported by the server. Use of the
extended-length encoding in other Xlib functions (for example, XDrawPoints,
XDrawRectangles, XDrawSegments, XFillArcs, XFillRectangles, XPutImage) is
permitted but not required; an Xlib implementation may choose to split the data
across multiple smaller requests instead.
long XMaxRequestSize(Display *display);
display Specifies the connection to the X server.
The XMaxRequestSize function returns the maximum request size (in 4-byte units)
supported by the server without using an extended-length protocol encoding.
Single protocol requests to the server can be no larger than this size unless
an extended-length protocol encoding is supported by the server. The protocol
guarantees the size to be no smaller than 4096 units (16384 bytes). Xlib
automatically breaks data up into multiple protocol requests as necessary for
the following functions: XDrawPoints, XDrawRectangles, XDrawSegments, XFillArcs
, XFillRectangles, and XPutImage.
LastKnownRequestProcessed(display);
unsigned long XLastKnownRequestProcessed(Display *display);
display Specifies the connection to the X server.
Both extract the full serial number of the last request known by Xlib to have
been processed by the X server. Xlib automatically sets this number when
replies, events, and errors are received.
NextRequest(display);
unsigned long XNextRequest(Display *display);
display Specifies the connection to the X server.
Both extract the full serial number that is to be used for the next request.
Serial numbers are maintained separately for each display connection.
ProtocolVersion(display);
int XProtocolVersion(Display *display);
display Specifies the connection to the X server.
Both return the major version number (11) of the X protocol associated with the
connected display.
ProtocolRevision(display);
int XProtocolRevision(Display *display);
display Specifies the connection to the X server.
Both return the minor protocol revision number of the X server.
QLength(display);
int XQLength(Display *display);
display Specifies the connection to the X server.
Both return the length of the event queue for the connected display. Note that
there may be more events that have not been read into the queue yet (see
XEventsQueued).
RootWindow(display, screen_number);
Window XRootWindow(Display *display, int screen_number);
display Specifies the connection to the X server.
screen_number Specifies the appropriate screen number on the host server.
Both return the root window. These are useful with functions that need a
drawable of a particular screen and for creating top-level windows.
ScreenCount(display);
int XScreenCount(Display *display);
display Specifies the connection to the X server.
Both return the number of available screens.
ServerVendor(display);
char *XServerVendor(Display *display);
display Specifies the connection to the X server.
Both return a pointer to a null-terminated string that provides some
identification of the owner of the X server implementation. If the data
returned by the server is in the Latin Portable Character Encoding, then the
string is in the Host Portable Character Encoding. Otherwise, the contents of
the string are implementation-dependent.
VendorRelease(display);
int XVendorRelease(Display *display);
display Specifies the connection to the X server.
Both return a number related to a vendor's release of the X server.
Image Format Functions and Macros
Applications are required to present data to the X server in a format that the
server demands. To help simplify applications, most of the work required to
convert the data is provided by Xlib (see sections 8.7 and 16.8).
The XPixmapFormatValues structure provides an interface to the pixmap format
information that is returned at the time of a connection setup. It contains:
typedef struct {
int depth;
int bits_per_pixel;
int scanline_pad;
} XPixmapFormatValues;
To obtain the pixmap format information for a given display, use
XListPixmapFormats.
XPixmapFormatValues *XListPixmapFormats(Display *display, int *count_return);
display Specifies the connection to the X server.
count_return Returns the number of pixmap formats that are supported by the
display.
The XListPixmapFormats function returns an array of XPixmapFormatValues
structures that describe the types of Z format images supported by the
specified display. If insufficient memory is available, XListPixmapFormats
returns NULL. To free the allocated storage for the XPixmapFormatValues
structures, use XFree.
The following lists the C language macros, their corresponding function
equivalents that are for other language bindings, and what data they both
return for the specified server and screen. These are often used by toolkits as
well as by simple applications.
ImageByteOrder(display);
int XImageByteOrder(Display *display);
display Specifies the connection to the X server.
Both specify the required byte order for images for each scanline unit in XY
format (bitmap) or for each pixel value in Z format. The macro or function can
return either LSBFirst or MSBFirst.
XBitmapUnit(display);
int XBitmapUnit(Display *display);
display Specifies the connection to the X server.
Both return the size of a bitmap's scanline unit in bits. The scanline is
calculated in multiples of this value.
BitmapBitOrder(display);
int XBitmapBitOrder(Display *display);
display Specifies the connection to the X server.
Within each bitmap unit, the left-most bit in the bitmap as displayed on the
screen is either the least significant or most significant bit in the unit.
This macro or function can return LSBFirst or MSBFirst.
BitmapPad(display);
int XBitmapPad(Display *display);
display Specifies the connection to the X server.
Each scanline must be padded to a multiple of bits returned by this macro or
function.
DisplayHeight(display, screen_number);
int XDisplayHeight(Display *display, int screen_number);
display Specifies the connection to the X server.
screen_number Specifies the appropriate screen number on the host server.
Both return an integer that describes the height of the screen in pixels.
DisplayHeightMM(display, screen_number);
int XDisplayHeightMM(Display *display, int screen_number);
display Specifies the connection to the X server.
screen_number Specifies the appropriate screen number on the host server.
Both return the height of the specified screen in millimeters.
DisplayWidth(display, screen_number);
int XDisplayWidth(Display *display, int screen_number);
display Specifies the connection to the X server.
screen_number Specifies the appropriate screen number on the host server.
Both return the width of the screen in pixels.
DisplayWidthMM(display, screen_number);
int XDisplayWidthMM(Display *display, int screen_number);
display Specifies the connection to the X server.
screen_number Specifies the appropriate screen number on the host server.
Both return the width of the specified screen in millimeters.
Screen Information Macros
The following lists the C language macros, their corresponding function
equivalents that are for other language bindings, and what data they both can
return. These macros or functions all take a pointer to the appropriate screen
structure.
BlackPixelOfScreen(screen);
unsigned long XBlackPixelOfScreen(Screen *screen);
screen Specifies the appropriate Screen structure.
Both return the black pixel value of the specified screen.
XWhitePixelOfScreen(screen);
unsigned long XWhitePixelOfScreen(Screen *screen);
screen Specifies the appropriate Screen structure.
Both return the white pixel value of the specified screen.
CellsOfScreen(screen);
int XCellsOfScreen(Screen *screen);
screen Specifies the appropriate Screen structure.
Both return the number of colormap cells in the default colormap of the
specified screen.
DefaultColormapOfScreen(screen);
Colormap XDefaultColormapOfScreen(Screen *screen);
screen Specifies the appropriate Screen structure.
Both return the default colormap of the specified screen.
DefaultDepthOfScreen(screen);
int XDefaultDepthOfScreen(Screen *screen);
screen Specifies the appropriate Screen structure.
Both return the depth of the root window.
DefaultGCOfScreen(screen);
GC XDefaultGCOfScreen(Screen *screen);
screen Specifies the appropriate Screen structure.
Both return a default graphics context (GC) of the specified screen, which has
the same depth as the root window of the screen. The GC must never be freed.
XDefaultVisualOfScreen(screen);
Visual *XDefaultVisualOfScreen(Screen *screen);
screen Specifies the appropriate Screen structure.
Both return the default visual of the specified screen. For information on
visual types, see section 3.1.
DoesBackingStore(screen);
int XDoesBackingStore(Screen *screen);
screen Specifies the appropriate Screen structure.
Both return a value indicating whether the screen supports backing stores. The
value returned can be one of WhenMapped, NotUseful, or Always (see section
3.2.4).
DoesSaveUnders(screen);
Bool XDoesSaveUnders(Screen *screen);
screen Specifies the appropriate Screen structure.
Both return a Boolean value indicating whether the screen supports save unders.
If True, the screen supports save unders. If False, the screen does not support
save unders (see section 3.2.5).
DisplayOfScreen(screen);
Display *XDisplayOfScreen(Screen *screen);
screen Specifies the appropriate Screen structure.
Both return the display of the specified screen.
ScreenNumberOfScreen(screen);
long XScreenNumberOfScreen(Screen *screen);
screen Specifies the appropriate Screen structure.
The XScreenNumberOfScreen function returns the screen index number of the
specified screen.
EventMaskOfScreen(screen);
long XEventMaskOfScreen(Screen *screen);
screen Specifies the appropriate Screen structure.
Both return the event mask of the root window for the specified screen at
connection setup time.
WidthOfScreen(screen);
int XWidthOfScreen(Screen *screen);
screen Specifies the appropriate Screen structure.
Both return the width of the specified screen in pixels.
HeightOfScreen(screen);
int XHeightOfScreen(Screen *screen);
screen Specifies the appropriate Screen structure.
Both return the height of the specified screen in pixels.
WidthMMOfScreen(screen);
int XWidthMMOfScreen(Screen *screen);
screen Specifies the appropriate Screen structure.
Both return the width of the specified screen in millimeters.
HeightMMOfScreen(screen);
int XHeightMMOfScreen(Screen *screen);
screen Specifies the appropriate Screen structure.
Both return the height of the specified screen in millimeters.
MaxCmapsOfScreen(screen);
int XMaxCmapsOfScreen(Screen *screen);
screen Specifies the appropriate Screen structure.
Both return the maximum number of installed colormaps supported by the
specified screen (see section 9.3).
MinCmapsOfScreen(screen);
int XMinCmapsOfScreen(Screen *screen);
screen Specifies the appropriate Screen structure.
Both return the minimum number of installed colormaps supported by the
specified screen (see section 9.3).
PlanesOfScreen(screen);
int XPlanesOfScreen(Screen *screen);
screen Specifies the appropriate Screen structure.
Both return the depth of the root window.
RootWindowOfScreen(screen);
Window XRootWindowOfScreen(Screen *screen);
screen Specifies the appropriate Screen structure.
Both return the root window of the specified screen.
Generating a NoOperation Protocol Request
To execute a NoOperation protocol request, use XNoOp.
XNoOp(Display *display);
display Specifies the connection to the X server.
The XNoOp function sends a NoOperation protocol request to the X server,
thereby exercising the connection.
Freeing Client-Created Data
To free in-memory data that was created by an Xlib function, use XFree.
XFree(void *data);
data Specifies the data that is to be freed.
The XFree function is a general-purpose Xlib routine that frees the specified
data. You must use it to free any objects that were allocated by Xlib, unless
an alternate function is explicitly specified for the object. A NULL pointer
cannot be passed to this function.
Closing the Display
To close a display or disconnect from the X server, use XCloseDisplay.
XCloseDisplay(Display *display);
display Specifies the connection to the X server.
The XCloseDisplay function closes the connection to the X server for the
display specified in the Display structure and destroys all windows, resource
IDs (Window, Font, Pixmap, Colormap, Cursor, and GContext), or other resources
that the client has created on this display, unless the close-down mode of the
client has been changed (see XSetCloseDownMode). Therefore, these windows,
resource IDs, and other resources should never be referenced again or an error
will be generated. Before exiting, you should call XCloseDisplay explicitly so
that any pending errors are reported as XCloseDisplay performs a final XSync
operation.
XCloseDisplay can generate a BadGC error.
Xlib provides a function to permit the resources owned by a client to survive
after the client's connection is closed. To change a client's close-down mode,
use XSetCloseDownMode.
XSetCloseDownMode(Display *display, int close_mode);
display Specifies the connection to the X server.
close_mode Specifies the client close-down mode. You can pass DestroyAll,
RetainPermanent, or RetainTemporary.
The XSetCloseDownMode function defines what will happen to the client's
resources at connection close. A connection starts in DestroyAll mode. For
information on what happens to the client's resources when the close_mode
argument is RetainPermanent or RetainTemporary, see section 2.6.
XSetCloseDownMode can generate a BadValue error.
Using X Server Connection Close Operations
When the X server's connection to a client is closed either by an explicit call
to XCloseDisplay or by a process that exits, the X server performs the
following automatic operations:
• It disowns all selections owned by the client (see XSetSelectionOwner).
• It performs an XUngrabPointer and XUngrabKeyboard if the client has
actively grabbed the pointer or the keyboard.
• It performs an XUngrabServer if the client has grabbed the server.
• It releases all passive grabs made by the client.
• It marks all resources (including colormap entries) allocated by the client
either as permanent or temporary, depending on whether the close-down mode
is RetainPermanent or RetainTemporary. However, this does not prevent other
client applications from explicitly destroying the resources (see
XSetCloseDownMode).
When the close-down mode is DestroyAll, the X server destroys all of a client's
resources as follows:
• It examines each window in the client's save-set to determine if it is an
inferior (subwindow) of a window created by the client. (The save-set is a
list of other clients' windows that are referred to as save-set windows.)
If so, the X server reparents the save-set window to the closest ancestor
so that the save-set window is not an inferior of a window created by the
client. The reparenting leaves unchanged the absolute coordinates (with
respect to the root window) of the upper-left outer corner of the save-set
window.
• It performs a MapWindow request on the save-set window if the save-set
window is unmapped. The X server does this even if the save-set window was
not an inferior of a window created by the client.
• It destroys all windows created by the client.
• It performs the appropriate free request on each nonwindow resource created
by the client in the server (for example, Font, Pixmap, Cursor, Colormap,
and GContext).
• It frees all colors and colormap entries allocated by a client application.
Additional processing occurs when the last connection to the X server closes.
An X server goes through a cycle of having no connections and having some
connections. When the last connection to the X server closes as a result of a
connection closing with the close_mode of DestroyAll, the X server does the
following:
• It resets its state as if it had just been started. The X server begins by
destroying all lingering resources from clients that have terminated in
RetainPermanent or RetainTemporary mode.
• It deletes all but the predefined atom identifiers.
• It deletes all properties on all root windows (see section 4.3).
• It resets all device maps and attributes (for example, key click, bell
volume, and acceleration) as well as the access control list.
• It restores the standard root tiles and cursors.
• It restores the default font path.
• It restores the input focus to state PointerRoot.
However, the X server does not reset if you close a connection with a
close-down mode set to RetainPermanent or RetainTemporary.
Using Xlib with Threads
On systems that have threads, support may be provided to permit multiple
threads to use Xlib concurrently.
To initialize support for concurrent threads, use XInitThreads.
Status XInitThreads(void);
The XInitThreads function initializes Xlib support for concurrent threads. This
function must be the first Xlib function a multi-threaded program calls, and it
must complete before any other Xlib call is made. This function returns a
nonzero status if initialization was successful; otherwise, it returns zero. On
systems that do not support threads, this function always returns zero.
It is only necessary to call this function if multiple threads might use Xlib
concurrently. If all calls to Xlib functions are protected by some other access
mechanism (for example, a mutual exclusion lock in a toolkit or through
explicit client programming), Xlib thread initialization is not required. It is
recommended that single-threaded programs not call this function.
To lock a display across several Xlib calls, use XLockDisplay.
XLockDisplay(Display *display);
display Specifies the connection to the X server.
The XLockDisplay function locks out all other threads from using the specified
display. Other threads attempting to use the display will block until the
display is unlocked by this thread. Nested calls to XLockDisplay work
correctly; the display will not actually be unlocked until XUnlockDisplay has
been called the same number of times as XLockDisplay. This function has no
effect unless Xlib was successfully initialized for threads using XInitThreads.
To unlock a display, use XUnlockDisplay.
XUnlockDisplay(Display *display);
display Specifies the connection to the X server.
The XUnlockDisplay function allows other threads to use the specified display
again. Any threads that have blocked on the display are allowed to continue.
Nested locking works correctly; if XLockDisplay has been called multiple times
by a thread, then XUnlockDisplay must be called an equal number of times before
the display is actually unlocked. This function has no effect unless Xlib was
successfully initialized for threads using XInitThreads.
Using Internal Connections
In addition to the connection to the X server, an Xlib implementation may
require connections to other kinds of servers (for example, to input method
servers as described in chapter 13). Toolkits and clients that use multiple
displays, or that use displays in combination with other inputs, need to obtain
these additional connections to correctly block until input is available and
need to process that input when it is available. Simple clients that use a
single display and block for input in an Xlib event function do not need to use
these facilities.
To track internal connections for a display, use XAddConnectionWatch.
typedef void (*XConnectionWatchProc)(Display *display, XPointer client_data,
int fd, Bool opening, XPointer *watch_data);
Status XAddConnectionWatch(Display *display, XConnectionWatchProc procedure,
XPointer client_data);
display Specifies the connection to the X server.
procedure Specifies the procedure to be called.
client_data Specifies the additional client data.
The XAddConnectionWatch function registers a procedure to be called each time
Xlib opens or closes an internal connection for the specified display. The
procedure is passed the display, the specified client_data, the file descriptor
for the connection, a Boolean indicating whether the connection is being opened
or closed, and a pointer to a location for private watch data. If opening is
True, the procedure can store a pointer to private data in the location pointed
to by watch_data; when the procedure is later called for this same connection
and opening is False, the location pointed to by watch_data will hold this same
private data pointer.
This function can be called at any time after a display is opened. If internal
connections already exist, the registered procedure will immediately be called
for each of them, before XAddConnectionWatch returns. XAddConnectionWatch
returns a nonzero status if the procedure is successfully registered;
otherwise, it returns zero.
The registered procedure should not call any Xlib functions. If the procedure
directly or indirectly causes the state of internal connections or watch
procedures to change, the result is not defined. If Xlib has been initialized
for threads, the procedure is called with the display locked and the result of
a call by the procedure to any Xlib function that locks the display is not
defined unless the executing thread has externally locked the display using
XLockDisplay.
To stop tracking internal connections for a display, use
XRemoveConnectionWatch.
Status XRemoveConnectionWatch(Display *display, XConnectionWatchProc procedure,
XPointer client_data);
display Specifies the connection to the X server.
procedure Specifies the procedure to be called.
client_data Specifies the additional client data.
The XRemoveConnectionWatch function removes a previously registered connection
watch procedure. The client_data must match the client_data used when the
procedure was initially registered.
To process input on an internal connection, use XProcessInternalConnection.
void XProcessInternalConnection(Display *display, int fd);
display Specifies the connection to the X server.
fd Specifies the file descriptor.
The XProcessInternalConnection function processes input available on an
internal connection. This function should be called for an internal connection
only after an operating system facility (for example, select or poll) has
indicated that input is available; otherwise, the effect is not defined.
To obtain all of the current internal connections for a display, use
XInternalConnectionNumbers.
Status XInternalConnectionNumbers(Display *display, int ** fd, int *
count_return);
display Specifies the connection to the X server.
fd_return Returns the file descriptors.
count_return Returns the number of file descriptors.
The XInternalConnectionNumbers function returns a list of the file descriptors
for all internal connections currently open for the specified display. When the
allocated list is no longer needed, free it by using XFree. This functions
returns a nonzero status if the list is successfully allocated; otherwise, it
returns zero.
Chapter 3. Window Functions
Table of Contents
Visual Types
Window Attributes
Background Attribute
Border Attribute
Gravity Attributes
Backing Store Attribute
Save Under Flag
Backing Planes and Backing Pixel Attributes
Event Mask and Do Not Propagate Mask Attributes
Override Redirect Flag
Colormap Attribute
Cursor Attribute
Creating Windows
Destroying Windows
Mapping Windows
Unmapping Windows
Configuring Windows
Changing Window Stacking Order
Changing Window Attributes
Visual Types
On some display hardware, it may be possible to deal with color resources in
more than one way. For example, you may be able to deal with a screen of either
12-bit depth with arbitrary mapping of pixel to color (pseudo-color) or 24-bit
depth with 8 bits of the pixel dedicated to each of red, green, and blue. These
different ways of dealing with the visual aspects of the screen are called
visuals. For each screen of the display, there may be a list of valid visual
types supported at different depths of the screen. Because default windows and
visual types are defined for each screen, most simple applications need not
deal with this complexity. Xlib provides macros and functions that return the
default root window, the default depth of the default root window, and the
default visual type (see sections 2.2.1 and 16.7).
Xlib uses an opaque Visual structure that contains information about the
possible color mapping. The visual utility functions (see section 16.7) use an
XVisualInfo structure to return this information to an application. The members
of this structure pertinent to this discussion are class, red_mask, green_mask,
blue_mask, bits_per_rgb, and colormap_size. The class member specifies one of
the possible visual classes of the screen and can be StaticGray, StaticColor,
TrueColor, GrayScale, PseudoColor, or DirectColor.
The following concepts may serve to make the explanation of visual types
clearer. The screen can be color or grayscale, can have a colormap that is
writable or read-only, and can also have a colormap whose indices are
decomposed into separate RGB pieces, provided one is not on a grayscale screen.
This leads to the following diagram:
Color Gray-Scale
R/O R/W R/O R/W
----------------------------------------------
Undecomposed Static Pseudo Static Gray
Colormap Color Color Gray Scale
Decomposed True Direct
Colormap Color Color
----------------------------------------------
Conceptually, as each pixel is read out of video memory for display on the
screen, it goes through a look-up stage by indexing into a colormap. Colormaps
can be manipulated arbitrarily on some hardware, in limited ways on other
hardware, and not at all on other hardware. The visual types affect the
colormap and the RGB values in the following ways:
• For PseudoColor, a pixel value indexes a colormap to produce independent
RGB values, and the RGB values can be changed dynamically.
• GrayScale is treated the same way as PseudoColor except that the primary
that drives the screen is undefined. Thus, the client should always store
the same value for red, green, and blue in the colormaps.
• For DirectColor, a pixel value is decomposed into separate RGB subfields,
and each subfield separately indexes the colormap for the corresponding
value. The RGB values can be changed dynamically.
• TrueColor is treated the same way as DirectColor except that the colormap
has predefined, read-only RGB values. These RGB values are server dependent
but provide linear or near-linear ramps in each primary.
• StaticColor is treated the same way as PseudoColor except that the colormap
has predefined, read-only, server-dependent RGB values.
• StaticGray is treated the same way as StaticColor except that the RGB
values are equal for any single pixel value, thus resulting in shades of
gray. StaticGray with a two-entry colormap can be thought of as monochrome.
The red_mask, green_mask, and blue_mask members are only defined for
DirectColor and TrueColor. Each has one contiguous set of bits with no
intersections. The bits_per_rgb member specifies the log base 2 of the number
of distinct color values (individually) of red, green, and blue. Actual RGB
values are unsigned 16-bit numbers. The colormap_size member defines the number
of available colormap entries in a newly created colormap. For DirectColor and
TrueColor, this is the size of an individual pixel subfield.
To obtain the visual ID from a Visual, use XVisualIDFromVisual.
VisualID XVisualIDFromVisual(Visual *visual);
visual Specifies the visual type.
The XVisualIDFromVisual function returns the visual ID for the specified visual
type.
Window Attributes
All InputOutput windows have a border width of zero or more pixels, an optional
background, an event suppression mask (which suppresses propagation of events
from children), and a property list (see section 4.3). The window border and
background can be a solid color or a pattern, called a tile. All windows except
the root have a parent and are clipped by their parent. If a window is stacked
on top of another window, it obscures that other window for the purpose of
input. If a window has a background (almost all do), it obscures the other
window for purposes of output. Attempts to output to the obscured area do
nothing, and no input events (for example, pointer motion) are generated for
the obscured area.
Windows also have associated property lists (see section 4.3).
Both InputOutput and InputOnly windows have the following common attributes,
which are the only attributes of an InputOnly window:
• win-gravity
• event-mask
• do-not-propagate-mask
• override-redirect
• cursor
If you specify any other attributes for an InputOnly window, a BadMatch error
results.
InputOnly windows are used for controlling input events in situations where
InputOutput windows are unnecessary. InputOnly windows are invisible; can only
be used to control such things as cursors, input event generation, and
grabbing; and cannot be used in any graphics requests. Note that InputOnly
windows cannot have InputOutput windows as inferiors.
Windows have borders of a programmable width and pattern as well as a
background pattern or tile. Pixel values can be used for solid colors. The
background and border pixmaps can be destroyed immediately after creating the
window if no further explicit references to them are to be made. The pattern
can either be relative to the parent or absolute. If ParentRelative, the
parent's background is used.
When windows are first created, they are not visible (not mapped) on the
screen. Any output to a window that is not visible on the screen and that does
not have backing store will be discarded. An application may wish to create a
window long before it is mapped to the screen. When a window is eventually
mapped to the screen (using XMapWindow), the X server generates an Expose event
for the window if backing store has not been maintained.
A window manager can override your choice of size, border width, and position
for a top-level window. Your program must be prepared to use the actual size
and position of the top window. It is not acceptable for a client application
to resize itself unless in direct response to a human command to do so.
Instead, either your program should use the space given to it, or if the space
is too small for any useful work, your program might ask the user to resize the
window. The border of your top-level window is considered fair game for window
managers.
To set an attribute of a window, set the appropriate member of the
XSetWindowAttributes structure and OR in the corresponding value bitmask in
your subsequent calls to XCreateWindow and XChangeWindowAttributes, or use one
of the other convenience functions that set the appropriate attribute. The
symbols for the value mask bits and the XSetWindowAttributes structure are:
/* Window attribute value mask bits */
/* Window attribute value mask bits */
#define CWBackPixmap (1L<<0)
#define CWBackPixel (1L<<1)
#define CWBorderPixmap (1L<<2)
#define CWBorderPixel (1L<<3)
#define CWBitGravity (1L<<4)
#define CWWinGravity (1L<<5)
#define CWBackingStore (1L<<6)
#define CWBackingPlanes (1L<<7)
#define CWBackingPixel (1L<<8)
#define CWOverrideRedirect (1L<<9)
#define CWSaveUnder (1L<<10)
#define CWEventMask (1L<<11)
#define CWDontPropagate (1L<<12)
#define CWColormap (1L<<13)
#define CWCursor (1L<<14)
/* Values */
typedef struct {
Pixmap background_pixmap; /* background, None, or ParentRelative */
unsigned long background_pixel; /* background pixel */
Pixmap border_pixmap; /* border of the window or CopyFromParent */
unsigned long border_pixel; /* border pixel value */
int bit_gravity; /* one of bit gravity values */
int win_gravity; /* one of the window gravity values */
int backing_store; /* NotUseful, WhenMapped, Always */
unsigned long backing_planes; /* planes to be preserved if possible */
unsigned long backing_pixel; /* value to use in restoring planes */
Bool save_under; /* should bits under be saved? (popups) */
long event_mask; /* set of events that should be saved */
long do_not_propagate_mask; /* set of events that should not propagate */
Bool override_redirect; /* boolean value for override_redirect */
Colormap colormap; /* color map to be associated with window */
Cursor cursor; /* cursor to be displayed (or None) */
} XSetWindowAttributes;
The following lists the defaults for each window attribute and indicates
whether the attribute is applicable to 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
Specify the x and y coordinates, which are the top-left outside
y corner of the created window's borders and are relative to the
inside of the parent window's borders.
width
Specify the width and height, which are the created window's
height 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.
Specifies the created window's class. You can pass InputOutput,
class 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.
Specifies which window attributes are defined in the attributes
valuemask 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.
Specifies the structure from which the values (as specified by the
attributes 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
Specify the x and y coordinates, which are the top-left outside
y corner of the new window's borders and are relative to the inside
of the parent window's borders.
width
Specify the width and height, which are the created window's
height 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.
If the sibling occludes the window, the window is placed at the top of
Opposite 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.
If any sibling occludes the window, the window is placed at the top of
Opposite 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.
Specifies which values are to be set using information in the values
value_mask 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
Specify the x and y coordinates, which define the new location of the
y 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.
Specifies which window attributes are defined in the attributes
argument. This mask is the bitwise inclusive OR of the valid
valuemask 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.
Specifies the structure from which the values (as specified by the
attributes 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 planes */
Bool save_under; /* boolean, should bits under be saved? */
Colormap colormap; /* color map to be associated with window */
Bool map_installed; /* boolean, is color map currently installed*/
int map_state; /* IsUnmapped, IsUnviewable, IsViewable */
long all_event_masks; /* set of events all people have interest in*/
long your_event_mask; /* my event mask */
long do_not_propagate_mask; /* set of events that should not propagate */
Bool override_redirect; /* boolean value for override-redirect */
Screen *screen; /* back pointer to correct screen */
} XWindowAttributes;
The x and y members are set to the upper-left outer corner relative to the
parent 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
Return the x and y coordinates that define the location of
y_return 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
Return the drawable's dimensions (width and height). For a
height_return window, these dimensions specify the inside size, not
including the border.
border_width_return Returns the border width in pixels. If the drawable is a
pixmap, it returns zero.
depth_return Returns the depth of the drawable (bits per pixel for the
object).
The XGetGeometry function returns the root window and the current geometry of
the drawable. The geometry of the drawable includes the x and y coordinates,
width and height, border width, and depth. These are described in the argument
list. It is legal to pass to this function a window whose class is InputOnly.
XGetGeometry can generate a BadDrawable error.
Translating Screen Coordinates
Applications sometimes need to perform a coordinate transformation from the
coordinate space of one window to another window or need to determine which
window the pointing device is in. XTranslateCoordinates and XQueryPointer
fulfill these needs (and avoid any race conditions) by asking the X server to
perform these operations.
To translate a coordinate in one window to the coordinate space of another
window, use XTranslateCoordinates.
Bool XTranslateCoordinates(Display *display, Window src_w, Window dest_w, int
src_x, int src_y, int *dest_x_return, int *dest_y_return, Window
*child_return);
display Specifies the connection to the X server.
src_w Specifies the source window.
dest_w Specifies the destination window.
src_x
src_y Specify the x and y coordinates within the source window.
dest_x_return
dest_y_return Return the x and y coordinates within the destination window.
child_return Returns the child if the coordinates are contained in a mapped
child of the destination window.
If XTranslateCoordinates returns True, it takes the src_x and src_y coordinates
relative to the source window's origin and returns these coordinates to
dest_x_return and dest_y_return relative to the destination window's origin. If
XTranslateCoordinates returns False, src_w and dest_w are on different screens,
and dest_x_return and dest_y_return are zero. If the coordinates are contained
in a mapped child of dest_w, that child is returned to child_return. Otherwise,
child_return is set to None.
XTranslateCoordinates can generate a BadWindow error.
To obtain the screen coordinates of the pointer or to determine the pointer
coordinates relative to a specified window, use XQueryPointer.
Bool XQueryPointer(Display *display, Window w, Window *root_return, Window
*child_return, int *root_x_return, int *root_y_return, int *win_x_return, int
*win_y_return, unsigned int *mask_return);
display Specifies the connection to the X server.
w Specifies the window.
root_return Returns the root window that the pointer is in.
child_return Returns the child window that the pointer is located in, if any.
root_x_return
root_y_return Return the pointer coordinates relative to the root window's
origin.
win_x_return
win_y_return Return the pointer coordinates relative to the specified window.
mask_return Returns the current state of the modifier keys and pointer
buttons.
The XQueryPointer function returns the root window the pointer is logically on
and the pointer coordinates relative to the root window's origin. If
XQueryPointer returns False, the pointer is not on the same screen as the
specified window, and XQueryPointer returns None to child_return and zero to
win_x_return and win_y_return. If XQueryPointer returns True, the pointer
coordinates returned to win_x_return and win_y_return are relative to the
origin of the specified window. In this case, XQueryPointer returns the child
that contains the pointer, if any, or else None to child_return.
XQueryPointer returns the current logical state of the keyboard buttons and the
modifier keys in mask_return. It sets mask_return to the bitwise inclusive OR
of one or more of the button or modifier key bitmasks to match the current
state of the mouse buttons and the modifier keys.
Note that the logical state of a device (as seen through Xlib) may lag the
physical state if device event processing is frozen (see section 12.1).
XQueryPointer can generate a BadWindow error.
Properties and Atoms
A property is a collection of named, typed data. The window system has a set of
predefined properties (for example, the name of a window, size hints, and so
on), and users can define any other arbitrary information and associate it with
windows. Each property has a name, which is an ISO Latin-1 string. For each
named property, a unique identifier (atom) is associated with it. A property
also has a type, for example, string or integer. These types are also indicated
using atoms, so arbitrary new types can be defined. Data of only one type may
be associated with a single property name. Clients can store and retrieve
properties associated with windows. For efficiency reasons, an atom is used
rather than a character string. XInternAtom can be used to obtain the atom for
property names.
A property is also stored in one of several possible formats. The X server can
store the information as 8-bit quantities, 16-bit quantities, or 32-bit
quantities. This permits the X server to present the data in the byte order
that the client expects. If you define further properties of complex type, you
must encode and decode them yourself. These functions must be carefully written
if they are to be portable. For further information about how to write a
library extension, see appendix C. The type of a property is defined by an
atom, which allows for arbitrary extension in this type scheme.
Certain property names are predefined in the server for commonly used
functions. The atoms for these properties are defined in <X11/Xatom.h>. To
avoid name clashes with user symbols, the #define name for each atom has the
XA_ prefix. For an explanation of the functions that let you get and set much
of the information stored in these predefined properties, see chapter 14.
The core protocol imposes no semantics on these property names, but semantics
are specified in other X Consortium standards, such as the Inter-Client
Communication Conventions Manual and the X Logical Font Description Conventions
.
You can use properties to communicate other information between applications.
The functions described in this section let you define new properties and get
the unique atom IDs in your applications.
Although any particular atom can have some client interpretation within each of
the name spaces, atoms occur in five distinct name spaces within the protocol:
• Selections
• Property names
• Property types
• Font properties
• Type of a ClientMessage event (none are built into the X server)
The built-in selection property names are:
PRIMARY SECONDARY
The built-in property names are:
CUT_BUFFER0 RESOURCE_MANAGER
CUT_BUFFER1 WM_CLASS
CUT_BUFFER2 WM_CLIENT_MACHINE
CUT_BUFFER3 WM_COLORMAP_WINDOWS
CUT_BUFFER4 WM_COMMAND
CUT_BUFFER5 WM_HINTS
CUT_BUFFER6 WM_ICON_NAME
CUT_BUFFER7 WM_ICON_SIZE
RGB_BEST_MAP WM_NAME
RGB_BLUE_MAP WM_NORMAL_HINTS
RGB_DEFAULT_MAP WM_PROTOCOLS
RGB_GRAY_MAP WM_STATE
RGB_GREEN_MAP WM_TRANSIENT_FOR
RGB_RED_MAP WM_ZOOM_HINTS
The built-in property types are:
ARC PIXMAP
ATOM POINT
BITMAP RGB_COLOR_MAP
CARDINAL RECTANGLE
COLORMAP STRING
CURSOR VISUALID
DRAWABLE WINDOW
FONT WM_HINTS
INTEGER WM_SIZE_HINTS
The built-in font property names are:
MIN_SPACE STRIKEOUT_DESCENT
NORM_SPACE STRIKEOUT_ASCENT
MAX_SPACE ITALIC_ANGLE
END_SPACE X_HEIGHT
SUPERSCRIPT_X QUAD_WIDTH
SUPERSCRIPT_Y WEIGHT
SUBSCRIPT_X POINT_SIZE
SUBSCRIPT_Y RESOLUTION
UNDERLINE_POSITION COPYRIGHT
UNDERLINE_THICKNESS NOTICE
FONT_NAME FAMILY_NAME
FULL_NAME CAP_HEIGHT
For further information about font properties, see section 8.5.
To return an atom for a given name, use XInternAtom.
Atom XInternAtom(Display *display, char *atom_name, Bool only_if_exists);
display Specifies the connection to the X server.
atom_name Specifies the name associated with the atom you want returned.
only_if_exists Specifies a Boolean value that indicates whether the atom must
be created.
The XInternAtom function returns the atom identifier associated with the
specified atom_name string. If only_if_exists is False, the atom is created if
it does not exist. Therefore, XInternAtom can return None. If the atom name is
not in the Host Portable Character Encoding, the result is
implementation-dependent. Uppercase and lowercase matter; the strings
``thing'', ``Thing'', and ``thinG'' all designate different atoms. The atom
will remain defined even after the client's connection closes. It will become
undefined only when the last connection to the X server closes.
XInternAtom can generate BadAlloc and BadValue errors.
To return atoms for an array of names, use XInternAtoms.
Status XInternAtoms(Display *display, char **names, int count, Bool
only_if_exists, Atom *atoms_return);
display Specifies the connection to the X server.
names Specifies the array of atom names.
count Specifies the number of atom names in the array.
only_if_exists Specifies a Boolean value that indicates whether the atom must
be created.
atoms_return Returns the atoms.
The XInternAtoms function returns the atom identifiers associated with the
specified names. The atoms are stored in the atoms_return array supplied by the
caller. Calling this function is equivalent to calling XInternAtom for each of
the names in turn with the specified value of only_if_exists, but this function
minimizes the number of round-trip protocol exchanges between the client and
the X server.
This function returns a nonzero status if atoms are returned for all of the
names; otherwise, it returns zero.
XInternAtoms can generate BadAlloc and BadValue errors.
To return a name for a given atom identifier, use XGetAtomName.
char *XGetAtomName(Display *display, Atom atom);
display Specifies the connection to the X server.
atom Specifies the atom for the property name you want returned.
The XGetAtomName function returns the name associated with the specified atom.
If the data returned by the server is in the Latin Portable Character Encoding,
then the returned string is in the Host Portable Character Encoding. Otherwise,
the result is implementation-dependent. To free the resulting string, call
XFree.
XGetAtomName can generate a BadAtom error.
To return the names for an array of atom identifiers, use XGetAtomNames.
Status XGetAtomNames(Display *display, Atom *atoms, int count, char
**names_return);
display Specifies the connection to the X server.
atoms Specifies the array of atoms.
count Specifies the number of atoms in the array.
names_return Returns the atom names.
The XGetAtomNames function returns the names associated with the specified
atoms. The names are stored in the names_return array supplied by the caller.
Calling this function is equivalent to calling XGetAtomName for each of the
atoms in turn, but this function minimizes the number of round-trip protocol
exchanges between the client and the X server.
This function returns a nonzero status if names are returned for all of the
atoms; otherwise, it returns zero.
XGetAtomNames can generate a BadAtom error.
Obtaining and Changing Window Properties
You can attach a property list to every window. Each property has a name, a
type, and a value (see section 4.3). The value is an array of 8-bit, 16-bit, or
32-bit quantities, whose interpretation is left to the clients. The type char
is used to represent 8-bit quantities, the type short is used to represent
16-bit quantities, and the type long is used to represent 32-bit quantities.
Xlib provides functions that you can use to obtain, change, update, or
interchange window properties. In addition, Xlib provides other utility
functions for inter-client communication (see chapter 14).
To obtain the type, format, and value of a property of a given window, use
XGetWindowProperty.
int XGetWindowProperty(Display *display, Window w, Atom property, long
long_offset, long long_length, Bool delete, Atom req_type, Atom
*actual_type_return, int *actual_format_return, unsigned long *nitems_return,
unsigned long *bytes_after_return, unsigned char **prop_return);
display Specifies the connection to the X server.
w Specifies the window whose property you want to obtain.
property Specifies the property name.
long_offset Specifies the offset in the specified property (in 32-bit
quantities) where the data is to be retrieved.
long_length Specifies the length in 32-bit multiples of the data to be
retrieved.
delete Specifies a Boolean value that determines whether the
property is deleted.
req_type Specifies the atom identifier associated with the property
type or AnyPropertyType.
actual_type_return Returns the atom identifier that defines the actual type
of the property.
actual_format_return Returns the actual format of the property.
nitems_return Returns the actual number of 8-bit, 16-bit, or 32-bit
items stored in the prop_return data.
bytes_after_return Returns the number of bytes remaining to be read in the
property if a partial read was performed.
prop_return Returns the data in the specified format.
The XGetWindowProperty function returns the actual type of the property; the
actual format of the property; the number of 8-bit, 16-bit, or 32-bit items
transferred; the number of bytes remaining to be read in the property; and a
pointer to the data actually returned. XGetWindowProperty sets the return
arguments as follows:
• If the specified property does not exist for the specified window,
XGetWindowProperty returns None to actual_type_return and the value zero to
actual_format_return and bytes_after_return. The nitems_return argument is
empty. In this case, the delete argument is ignored.
• If the specified property exists but its type does not match the specified
type, XGetWindowProperty returns the actual property type to
actual_type_return, the actual property format (never zero) to
actual_format_return, and the property length in bytes (even if the
actual_format_return is 16 or 32) to bytes_after_return. It also ignores
the delete argument. The nitems_return argument is empty.
• If the specified property exists and either you assign AnyPropertyType to
the req_type argument or the specified type matches the actual property
type, XGetWindowProperty returns the actual property type to
actual_type_return and the actual property format (never zero) to
actual_format_return. It also returns a value to bytes_after_return and
nitems_return, by defining the following values:
• N = actual length of the stored property in bytes (even if the format is 16
or 32) I = 4 * long_offset T = N - I L = MINIMUM(T, 4 * long_length) A = N
- (I + L)
• The returned value starts at byte index I in the property (indexing from
zero), and its length in bytes is L. If the value for long_offset causes L
to be negative, a BadValue error results. The value of bytes_after_return
is A, giving the number of trailing unread bytes in the stored property.
If the returned format is 8, the returned data is represented as a char array.
If the returned format is 16, the returned data is represented as a short array
and should be cast to that type to obtain the elements. If the returned format
is 32, the returned data is represented as a long array and should be cast to
that type to obtain the elements.
XGetWindowProperty always allocates one extra byte in prop_return (even if the
property is zero length) and sets it to zero so that simple properties
consisting of characters do not have to be copied into yet another string
before use.
If delete is True and bytes_after_return is zero, XGetWindowProperty deletes
the property from the window and generates a PropertyNotify event on the
window.
The function returns Success if it executes successfully. To free the resulting
data, use XFree.
XGetWindowProperty can generate BadAtom, BadValue, and BadWindow errors.
To obtain a given window's property list, use XListProperties.
Atom *XListProperties(Display *display, Window w, int *num_prop_return);
display Specifies the connection to the X server.
w Specifies the window whose property list you want to obtain.
num_prop_return Returns the length of the properties array.
The XListProperties function returns a pointer to an array of atom properties
that are defined for the specified window or returns NULL if no properties were
found. To free the memory allocated by this function, use XFree.
XListProperties can generate a BadWindow error.
To change a property of a given window, use XChangeProperty.
XChangeProperty(Display *display, Window w, Atom property, Atom type, int
format, int mode, unsignedchar *data, int nelements);
display Specifies the connection to the X server.
w Specifies the window whose property you want to change.
property Specifies the property name.
Specifies the type of the property. The X server does not interpret
type the type but simply passes it back to an application that later calls
XGetWindowProperty.
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
format information allows the X server to correctly perform byte-swap
operations as necessary. If the format is 16-bit or 32-bit, you must
explicitly cast your data pointer to an (unsigned char *) in the call
to XChangeProperty.
mode Specifies the mode of the operation. You can pass PropModeReplace,
PropModePrepend, or PropModeAppend.
data Specifies the property data.
nelements Specifies the number of elements of the specified data format.
The XChangeProperty function alters the property for the specified window and
causes the X server to generate a PropertyNotify event on that window.
XChangeProperty performs the following:
• If mode is PropModeReplace, XChangeProperty discards the previous property
value and stores the new data.
• If mode is PropModePrepend or PropModeAppend, XChangeProperty inserts the
specified data before the beginning of the existing data or onto the end of
the existing data, respectively. The type and format must match the
existing property value, or a BadMatch error results. If the property is
undefined, it is treated as defined with the correct type and format with
zero-length data.
If the specified format is 8, the property data must be a char array. If the
specified format is 16, the property data must be a short array. If the
specified format is 32, the property data must be a long array.
The lifetime of a property is not tied to the storing client. Properties remain
until explicitly deleted, until the window is destroyed, or until the server
resets. For a discussion of what happens when the connection to the X server is
closed, see section 2.6. The maximum size of a property is server dependent and
can vary dynamically depending on the amount of memory the server has
available. (If there is insufficient space, a BadAlloc error results.)
XChangeProperty can generate BadAlloc, BadAtom, BadMatch, BadValue, and
BadWindow errors.
To rotate a window's property list, use XRotateWindowProperties.
XRotateWindowProperties(Display *display, Window w, Atom properties[], int
num_prop, int npositions);
display Specifies the connection to the X server.
w Specifies the window.
properties Specifies the array of properties that are to be rotated.
num_prop Specifies the length of the properties array.
npositions Specifies the rotation amount.
The XRotateWindowProperties function allows you to rotate properties on a
window and causes the X server to generate PropertyNotify events. If the
property names in the properties array are viewed as being numbered starting
from zero and if there are num_prop property names in the list, then the value
associated with property name I becomes the value associated with property name
(I + npositions) mod N for all I from zero to N − 1. The effect is to rotate
the states by npositions places around the virtual ring of property names
(right for positive npositions, left for negative npositions). If npositions
mod N is nonzero, the X server generates a PropertyNotify event for each
property in the order that they are listed in the array. If an atom occurs more
than once in the list or no property with that name is defined for the window,
a BadMatch error results. If a BadAtom or BadMatch error results, no properties
are changed.
XRotateWindowProperties can generate BadAtom, BadMatch, and BadWindow errors.
To delete a property on a given window, use XDeleteProperty.
XDeleteProperty(Display *display, Window w, Atom property);
display Specifies the connection to the X server.
w Specifies the window whose property you want to delete.
property Specifies the property name.
The XDeleteProperty function deletes the specified property only if the
property was defined on the specified window and causes the X server to
generate a PropertyNotify event on the window unless the property does not
exist.
XDeleteProperty can generate BadAtom and BadWindow errors.
Selections
Selections are one method used by applications to exchange data. By using the
property mechanism, applications can exchange data of arbitrary types and can
negotiate the type of the data. A selection can be thought of as an indirect
property with a dynamic type. That is, rather than having the property stored
in the X server, the property is maintained by some client (the owner). A
selection is global in nature (considered to belong to the user but be
maintained by clients) rather than being private to a particular window
subhierarchy or a particular set of clients.
Xlib provides functions that you can use to set, get, or request conversion of
selections. This allows applications to implement the notion of current
selection, which requires that notification be sent to applications when they
no longer own the selection. Applications that support selection often
highlight the current selection and so must be informed when another
application has acquired the selection so that they can unhighlight the
selection.
When a client asks for the contents of a selection, it specifies a selection
target type. This target type can be used to control the transmitted
representation of the contents. For example, if the selection is ``the last
thing the user clicked on'' and that is currently an image, then the target
type might specify whether the contents of the image should be sent in XY
format or Z format.
The target type can also be used to control the class of contents transmitted,
for example, asking for the ``looks'' (fonts, line spacing, indentation, and so
forth) of a paragraph selection, not the text of the paragraph. The target type
can also be used for other purposes. The protocol does not constrain the
semantics.
To set the selection owner, use XSetSelectionOwner.
XSetSelectionOwner(Display *display, Atom selection, Window owner, Time time);
display Specifies the connection to the X server.
selection Specifies the selection atom.
owner Specifies the owner of the specified selection atom. You can pass a
window or None.
time Specifies the time. You can pass either a timestamp or CurrentTime.
The XSetSelectionOwner function changes the owner and last-change time for the
specified selection and has no effect if the specified time is earlier than the
current last-change time of the specified selection or is later than the
current X server time. Otherwise, the last-change time is set to the specified
time, with CurrentTime replaced by the current server time. If the owner window
is specified as None, then the owner of the selection becomes None (that is, no
owner). Otherwise, the owner of the selection becomes the client executing the
request.
If the new owner (whether a client or None) is not the same as the current
owner of the selection and the current owner is not None, the current owner is
sent a SelectionClear event. If the client that is the owner of a selection is
later terminated (that is, its connection is closed) or if the owner window it
has specified in the request is later destroyed, the owner of the selection
automatically reverts to None, but the last-change time is not affected. The
selection atom is uninterpreted by the X server. XGetSelectionOwner returns the
owner window, which is reported in SelectionRequest and SelectionClear events.
Selections are global to the X server.
XSetSelectionOwner can generate BadAtom and BadWindow errors.
To return the selection owner, use XGetSelectionOwner.
Window XGetSelectionOwner(Display *display, Atom selection);
display Specifies the connection to the X server.
selection Specifies the selection atom whose owner you want returned.
The XGetSelectionOwner function returns the window ID associated with the
window that currently owns the specified selection. If no selection was
specified, the function returns the constant None. If None is returned, there
is no owner for the selection.
XGetSelectionOwner can generate a BadAtom error.
To request conversion of a selection, use XConvertSelection.
XConvertSelection(Display *display, Atom selection, Atom target, Atom property,
Window requestor, Time time);
display Specifies the connection to the X server.
selection Specifies the selection atom.
target Specifies the target atom.
property Specifies the property name. You also can pass None.
requestor Specifies the requestor.
time Specifies the time. You can pass either a timestamp or CurrentTime.
XConvertSelection requests that the specified selection be converted to the
specified target type:
• If the specified selection has an owner, the X server sends a
SelectionRequest event to that owner.
• If no owner for the specified selection exists, the X server generates a
SelectionNotify event to the requestor with property None.
The arguments are passed on unchanged in either of the events. There are two
predefined selection atoms: PRIMARY and SECONDARY.
XConvertSelection can generate BadAtom and BadWindow errors.
Chapter 5. Pixmap and Cursor Functions
Table of Contents
Creating and Freeing Pixmaps
Creating, Recoloring, and Freeing Cursors
Creating and Freeing Pixmaps
Pixmaps can only be used on the screen on which they were created. Pixmaps are
off-screen resources that are used for various operations, such as defining
cursors as tiling patterns or as the source for certain raster operations. Most
graphics requests can operate either on a window or on a pixmap. A bitmap is a
single bit-plane pixmap.
To create a pixmap of a given size, use XCreatePixmap.
Pixmap XCreatePixmap(Display *display, Drawable d, unsigned int width, unsigned
int height, unsigned int depth);
display Specifies the connection to the X server.
d Specifies which screen the pixmap is created on.
width
height Specify the width and height, which define the dimensions of the
pixmap.
depth Specifies the depth of the pixmap.
The XCreatePixmap function creates a pixmap of the width, height, and depth you
specified and returns a pixmap ID that identifies it. It is valid to pass an
InputOnly window to the drawable argument. The width and height arguments must
be nonzero, or a BadValue error results. The depth argument must be one of the
depths supported by the screen of the specified drawable, or a BadValue error
results.
The server uses the specified drawable to determine on which screen to create
the pixmap. The pixmap can be used only on this screen and only with other
drawables of the same depth (see XCopyPlane for an exception to this rule). The
initial contents of the pixmap are undefined.
XCreatePixmap can generate BadAlloc, BadDrawable, and BadValue errors.
To free all storage associated with a specified pixmap, use XFreePixmap.
XFreePixmap(Display *display, Pixmap pixmap);
display Specifies the connection to the X server.
pixmap Specifies the pixmap.
The XFreePixmap function first deletes the association between the pixmap ID
and the pixmap. Then, the X server frees the pixmap storage when there are no
references to it. The pixmap should never be referenced again.
XFreePixmap can generate a BadPixmap error.
Creating, Recoloring, and Freeing Cursors
Each window can have a different cursor defined for it. Whenever the pointer is
in a visible window, it is set to the cursor defined for that window. If no
cursor was defined for that window, the cursor is the one defined for the
parent window.
From X's perspective, a cursor consists of a cursor source, mask, colors, and a
hotspot. The mask pixmap determines the shape of the cursor and must be a depth
of one. The source pixmap must have a depth of one, and the colors determine
the colors of the source. The hotspot defines the point on the cursor that is
reported when a pointer event occurs. There may be limitations imposed by the
hardware on cursors as to size and whether a mask is implemented.
XQueryBestCursor can be used to find out what sizes are possible. There is a
standard font for creating cursors, but Xlib provides functions that you can
use to create cursors from an arbitrary font or from bitmaps.
To create a cursor from the standard cursor font, use XCreateFontCursor.
#include <X11/cursorfont.h>
Cursor XCreateFontCursor(Display *display, unsigned int shape);
display Specifies the connection to the X server.
shape Specifies the shape of the cursor.
X provides a set of standard cursor shapes in a special font named cursor.
Applications are encouraged to use this interface for their cursors because the
font can be customized for the individual display type. The shape argument
specifies which glyph of the standard fonts to use.
The hotspot comes from the information stored in the cursor font. The initial
colors of a cursor are a black foreground and a white background (see
XRecolorCursor). For further information about cursor shapes, see appendix B.
XCreateFontCursor can generate BadAlloc and BadValue errors.
To create a cursor from font glyphs, use XCreateGlyphCursor.
Cursor XCreateGlyphCursor(Display *display, Font source_font, Font mask_font,
unsigned int source_char, unsigned int mask_char, XColor *foreground_color,
XColor *background_color);
display Specifies the connection to the X server.
source_font Specifies the font for the source glyph.
mask_font Specifies the font for the mask glyph or None.
source_char Specifies the character glyph for the source.
mask_char Specifies the glyph character for the mask.
foreground_color Specifies the RGB values for the foreground of the source.
background_color Specifies the RGB values for the background of the source.
The XCreateGlyphCursor function is similar to XCreatePixmapCursor except that
the source and mask bitmaps are obtained from the specified font glyphs. The
source_char must be a defined glyph in source_font, or a BadValue error
results. If mask_font is given, mask_char must be a defined glyph in mask_font,
or a BadValue error results. The mask_font and character are optional. The
origins of the source_char and mask_char (if defined) glyphs are positioned
coincidently and define the hotspot. The source_char and mask_char need not
have the same bounding box metrics, and there is no restriction on the
placement of the hotspot relative to the bounding boxes. If no mask_char is
given, all pixels of the source are displayed. You can free the fonts
immediately by calling XFreeFont if no further explicit references to them are
to be made.
For 2-byte matrix fonts, the 16-bit value should be formed with the byte1
member in the most significant byte and the byte2 member in the least
significant byte.
XCreateGlyphCursor can generate BadAlloc, BadFont, and BadValue errors.
To create a cursor from two bitmaps, use XCreatePixmapCursor.
Cursor XCreatePixmapCursor(Display *display, Pixmap source, Pixmap mask, XColor
*foreground_color, XColor *background_color, unsigned int x, unsigned int y);
display Specifies the connection to the X server.
source Specifies the shape of the source cursor.
mask Specifies the cursor's source bits to be displayed or None.
foreground_color Specifies the RGB values for the foreground of the source.
background_color Specifies the RGB values for the background of the source.
x
y Specify the x and y coordinates, which indicate the hotspot
relative to the source's origin.
The XCreatePixmapCursor function creates a cursor and returns the cursor ID
associated with it. The foreground and background RGB values must be specified
using foreground_color and background_color, even if the X server only has a
StaticGray or GrayScale screen. The foreground color is used for the pixels set
to 1 in the source, and the background color is used for the pixels set to 0.
Both source and mask, if specified, must have depth one (or a BadMatch error
results) but can have any root. The mask argument defines the shape of the
cursor. The pixels set to 1 in the mask define which source pixels are
displayed, and the pixels set to 0 define which pixels are ignored. If no mask
is given, all pixels of the source are displayed. The mask, if present, must be
the same size as the pixmap defined by the source argument, or a BadMatch error
results. The hotspot must be a point within the source, or a BadMatch error
results.
The components of the cursor can be transformed arbitrarily to meet display
limitations. The pixmaps can be freed immediately if no further explicit
references to them are to be made. Subsequent drawing in the source or mask
pixmap has an undefined effect on the cursor. The X server might or might not
make a copy of the pixmap.
XCreatePixmapCursor can generate BadAlloc and BadPixmap errors.
To determine useful cursor sizes, use XQueryBestCursor.
Status XQueryBestCursor(Display *display, Drawable d, unsigned int width,
unsigned int height, unsigned int *width_return, unsigned int *height_return);
display Specifies the connection to the X server.
d Specifies the drawable, which indicates the screen.
width
height Specify the width and height of the cursor that you want the size
information for.
width_return
height_return Return the best width and height that is closest to the specified
width and height.
Some displays allow larger cursors than other displays. The XQueryBestCursor
function provides a way to find out what size cursors are actually possible on
the display. It returns the largest size that can be displayed. Applications
should be prepared to use smaller cursors on displays that cannot support large
ones.
XQueryBestCursor can generate a BadDrawable error.
To change the color of a given cursor, use XRecolorCursor.
XRecolorCursor(Display *display, Cursor cursor, XColor *foreground_color,
XColor *background_color);
display Specifies the connection to the X server.
cursor Specifies the cursor.
foreground_color Specifies the RGB values for the foreground of the source.
background_color Specifies the RGB values for the background of the source.
The XRecolorCursor function changes the color of the specified cursor, and if
the cursor is being displayed on a screen, the change is visible immediately.
The pixel members of the XColor structures are ignored; only the RGB values are
used.
XRecolorCursor can generate a BadCursor error.
To free (destroy) a given cursor, use XFreeCursor.
XFreeCursor(Display *display, Cursor cursor);
display Specifies the connection to the X server.
cursor Specifies the cursor.
The XFreeCursor function deletes the association between the cursor resource ID
and the specified cursor. The cursor storage is freed when no other resource
references it. The specified cursor ID should not be referred to again.
XFreeCursor can generate a BadCursor error.
Chapter 6. Color Management Functions
Table of Contents
Color Structures
Color Strings
RGB Device String Specification
RGB Intensity String Specification
Device-Independent String Specifications
Color Conversion Contexts and Gamut Mapping
Creating, Copying, and Destroying Colormaps
Mapping Color Names to Values
Allocating and Freeing Color Cells
Modifying and Querying Colormap Cells
Color Conversion Context Functions
Getting and Setting the Color Conversion Context of a Colormap
Obtaining the Default Color Conversion Context
Color Conversion Context Macros
Modifying Attributes of a Color Conversion Context
Creating and Freeing a Color Conversion Context
Converting between Color Spaces
Callback Functions
Prototype Gamut Compression Procedure
Supplied Gamut Compression Procedures
Prototype White Point Adjustment Procedure
Supplied White Point Adjustment Procedures
Gamut Querying Functions
Red, Green, and Blue Queries
CIELab Queries
CIELuv Queries
TekHVC Queries
Color Management Extensions
Color Spaces
Adding Device-Independent Color Spaces
Querying Color Space Format and Prefix
Creating Additional Color Spaces
Parse String Callback
Color Specification Conversion Callback
Function Sets
Adding Function Sets
Creating Additional Function Sets
Each X window always has an associated colormap that provides a level of
indirection between pixel values and colors displayed on the screen. Xlib
provides functions that you can use to manipulate a colormap. The X protocol
defines colors using values in the RGB color space. The RGB color space is
device dependent; rendering an RGB value on differing output devices typically
results in different colors. Xlib also provides a means for clients to specify
color using device-independent color spaces for consistent results across
devices. Xlib supports device-independent color spaces derivable from the CIE
XYZ color space. This includes the CIE XYZ, xyY, L*u*v*, and L*a*b* color
spaces as well as the TekHVC color space.
This chapter discusses how to:
• Create, copy, and destroy a colormap
• Specify colors by name or value
• Allocate, modify, and free color cells
• Read entries in a colormap
• Convert between color spaces
• Control aspects of color conversion
• Query the color gamut of a screen
• Add new color spaces
All functions, types, and symbols in this chapter with the prefix ``Xcms'' are
defined in <X11/Xcms.h>. The remaining functions and types are defined in <X11/
Xlib.h>.
Functions in this chapter manipulate the representation of color on the screen.
For each possible value that a pixel can take in a window, there is a color
cell in the colormap. For example, if a window is 4 bits deep, pixel values 0
through 15 are defined. A colormap is a collection of color cells. A color cell
consists of a triple of red, green, and blue (RGB) values. The hardware imposes
limits on the number of significant bits in these values. As each pixel is read
out of display memory, the pixel is looked up in a colormap. The RGB value of
the cell determines what color is displayed on the screen. On a grayscale
display with a black-and-white monitor, the values are combined to determine
the brightness on the screen.
Typically, an application allocates color cells or sets of color cells to
obtain the desired colors. The client can allocate read-only cells. In which
case, the pixel values for these colors can be shared among multiple
applications, and the RGB value of the cell cannot be changed. If the client
allocates read/write cells, they are exclusively owned by the client, and the
color associated with the pixel value can be changed at will. Cells must be
allocated (and, if read/write, initialized with an RGB value) by a client to
obtain desired colors. The use of pixel value for an unallocated cell results
in an undefined color.
Because colormaps are associated with windows, X supports displays with
multiple colormaps and, indeed, different types of colormaps. If there are
insufficient colormap resources in the display, some windows will display in
their true colors, and others will display with incorrect colors. A window
manager usually controls which windows are displayed in their true colors if
more than one colormap is required for the color resources the applications are
using. At any time, there is a set of installed colormaps for a screen. Windows
using one of the installed colormaps display with true colors, and windows
using other colormaps generally display with incorrect colors. You can control
the set of installed colormaps by using XInstallColormap and XUninstallColormap
.
Colormaps are local to a particular screen. Screens always have a default
colormap, and programs typically allocate cells out of this colormap.
Generally, you should not write applications that monopolize color resources.
Although some hardware supports multiple colormaps installed at one time, many
of the hardware displays built today support only a single installed colormap,
so the primitives are written to encourage sharing of colormap entries between
applications.
The DefaultColormap macro returns the default colormap. The DefaultVisual macro
returns the default visual type for the specified screen. Possible visual types
are StaticGray, GrayScale, StaticColor, PseudoColor, TrueColor, or DirectColor
(see section 3.1).
Color Structures
Functions that operate only on RGB color space values use an XColor structure,
which contains:
typedef struct {
unsigned long pixel; /* pixel value */
unsigned short red, green, blue; /* rgb values */
char flags; /* DoRed, DoGreen, DoBlue */
char pad;
} XColor;
The red, green, and blue values are always in the range 0 to 65535 inclusive,
independent of the number of bits actually used in the display hardware. The
server scales these values down to the range used by the hardware. Black is
represented by (0,0,0), and white is represented by (65535,65535,65535). In
some functions, the flags member controls which of the red, green, and blue
members is used and can be the inclusive OR of zero or more of DoRed, DoGreen,
and DoBlue.
Functions that operate on all color space values use an XcmsColor structure.
This structure contains a union of substructures, each supporting color
specification encoding for a particular color space. Like the XColor structure,
the XcmsColor structure contains pixel and color specification information (the
spec member in the XcmsColor structure).
typedef unsigned long XcmsColorFormat; /* Color Specification Format */
typedef struct {
union {
XcmsRGB RGB;
XcmsRGBi RGBi;
XcmsCIEXYZ CIEXYZ;
XcmsCIEuvY CIEuvY;
XcmsCIExyY CIExyY;
XcmsCIELab CIELab;
XcmsCIELuv CIELuv;
XcmsTekHVC TekHVC;
XcmsPad Pad;
} spec;
unsigned long pixel;
XcmsColorFormat format;
} XcmsColor; /* Xcms Color Structure */
Because the color specification can be encoded for the various color spaces,
encoding for the spec member is identified by the format member, which is of
type XcmsColorFormat. The following macros define standard formats.
#define XcmsUndefinedFormat 0x00000000
#define XcmsCIEXYZFormat 0x00000001 /* CIE XYZ */
#define XcmsCIEuvYFormat 0x00000002 /* CIE u'v'Y */
#define XcmsCIExyYFormat 0x00000003 /* CIE xyY */
#define XcmsCIELabFormat 0x00000004 /* CIE L*a*b* */
#define XcmsCIELuvFormat 0x00000005 /* CIE L*u*v* */
#define XcmsTekHVCFormat 0x00000006 /* TekHVC */
#define XcmsRGBFormat 0x80000000 /* RGB Device */
#define XcmsRGBiFormat 0x80000001 /* RGB Intensity */
Formats for device-independent color spaces are distinguishable from those for
device-dependent spaces by the 32nd bit. If this bit is set, it indicates that
the color specification is in a device-dependent form; otherwise, it is in a
device-independent form. If the 31st bit is set, this indicates that the color
space has been added to Xlib at run time (see section 6.12.4). The format value
for a color space added at run time may be different each time the program is
executed. If references to such a color space must be made outside the client
(for example, storing a color specification in a file), then reference should
be made by color space string prefix (see XcmsFormatOfPrefix and
XcmsPrefixOfFormat).
Data types that describe the color specification encoding for the various color
spaces are defined as follows:
typedef double XcmsFloat;
typedef struct {
unsigned short red; /* 0x0000 to 0xffff */
unsigned short green; /* 0x0000 to 0xffff */
unsigned short blue; /* 0x0000 to 0xffff */
} XcmsRGB; /* RGB Device */
typedef struct {
XcmsFloat red; /* 0.0 to 1.0 */
XcmsFloat green; /* 0.0 to 1.0 */
XcmsFloat blue; /* 0.0 to 1.0 */
} XcmsRGBi; /* RGB Intensity */
typedef struct {
XcmsFloat X;
XcmsFloat Y; /* 0.0 to 1.0 */
XcmsFloat Z;
} XcmsCIEXYZ; /* CIE XYZ */
typedef struct {
XcmsFloat u_prime; /* 0.0 to ~0.6 */
XcmsFloat v_prime; /* 0.0 to ~0.6 */
XcmsFloat Y; /* 0.0 to 1.0 */
} XcmsCIEuvY; /* CIE u'v'Y */
typedef struct {
XcmsFloat x; /* 0.0 to ~.75 */
XcmsFloat y; /* 0.0 to ~.85 */
XcmsFloat Y; /* 0.0 to 1.0 */
} XcmsCIExyY; /* CIE xyY */
typedef struct {
XcmsFloat L_star; /* 0.0 to 100.0 */
XcmsFloat a_star;
XcmsFloat b_star;
} XcmsCIELab; /* CIE L*a*b* */
typedef struct {
XcmsFloat L_star; /* 0.0 to 100.0 */
XcmsFloat u_star;
XcmsFloat v_star;
} XcmsCIELuv; /* CIE L*u*v* */
typedef struct {
XcmsFloat H; /* 0.0 to 360.0 */
XcmsFloat V; /* 0.0 to 100.0 */
XcmsFloat C; /* 0.0 to 100.0 */
} XcmsTekHVC; /* TekHVC */
typedef struct {
XcmsFloat pad0;
XcmsFloat pad1;
XcmsFloat pad2;
XcmsFloat pad3;
} XcmsPad; /* four doubles */
The device-dependent formats provided allow color specification in:
• RGB Intensity (XcmsRGBi)
• Red, green, and blue linear intensity values, floating-point values from
0.0 to 1.0, where 1.0 indicates full intensity, 0.5 half intensity, and so
on.
• RGB Device (XcmsRGB)
• Red, green, and blue values appropriate for the specified output device.
XcmsRGB values are of type unsigned short, scaled from 0 to 65535
inclusive, and are interchangeable with the red, green, and blue values in
an XColor structure.
It is important to note that RGB Intensity values are not gamma corrected
values. In contrast, RGB Device values generated as a result of converting
color specifications are always gamma corrected, and RGB Device values acquired
as a result of querying a colormap or passed in by the client are assumed by
Xlib to be gamma corrected. The term RGB value in this manual always refers to
an RGB Device value.
Color Strings
Xlib provides a mechanism for using string names for colors. A color string may
either contain an abstract color name or a numerical color specification. Color
strings are case-insensitive.
Color strings are used in the following functions:
• XAllocNamedColor
• XcmsAllocNamedColor
• XLookupColor
• XcmsLookupColor
• XParseColor
• XStoreNamedColor
Xlib supports the use of abstract color names, for example, red or blue. A
value for this abstract name is obtained by searching one or more color name
databases. Xlib first searches zero or more client-side databases; the number,
location, and content of these databases is implementation-dependent and might
depend on the current locale. If the name is not found, Xlib then looks for the
color in the X server's database. If the color name is not in the Host Portable
Character Encoding, the result is implementation-dependent.
A numerical color specification consists of a color space name and a set of
values in the following syntax:
<color_space_name>:<value>/.../<value>
The following are examples of valid color strings.
"CIEXYZ:0.3227/0.28133/0.2493"
"RGBi:1.0/0.0/0.0"
"rgb:00/ff/00"
"CIELuv:50.0/0.0/0.0"
The syntax and semantics of numerical specifications are given for each
standard color space in the following sections.
RGB Device String Specification
An RGB Device specification is identified by the prefix ``rgb:'' and conforms
to the following syntax:
rgb:<red>/<green>/<blue>
<red>, <green>, <blue> := h | hh | hhh | hhhh
h := single hexadecimal digits (case insignificant)
Note that h indicates the value scaled in 4 bits, hh the value scaled in 8
bits, hhh the value scaled in 12 bits, and hhhh the value scaled in 16 bits,
respectively.
Typical examples are the strings ``rgb:ea/75/52'' and ``rgb:ccc/320/320'', but
mixed numbers of hexadecimal digit strings (``rgb:ff/a5/0'' and ``rgb:ccc/32/
0'') are also allowed.
For backward compatibility, an older syntax for RGB Device is supported, but
its continued use is not encouraged. The syntax is an initial sharp sign
character followed by a numeric specification, in one of the following formats:
#RGB (4 bits each)
#RRGGBB (8 bits each)
#RRRGGGBBB (12 bits each)
#RRRRGGGGBBBB (16 bits each)
The R, G, and B represent single hexadecimal digits. When fewer than 16 bits
each are specified, they represent the most significant bits of the value
(unlike the ``rgb:'' syntax, in which values are scaled). For example, the
string ``#3a7'' is the same as ``#3000a0007000''.
RGB Intensity String Specification
An RGB intensity specification is identified by the prefix ``rgbi:'' and
conforms to the following syntax:
rgbi:<red>/<green>/<blue>
Note that red, green, and blue are floating-point values between 0.0 and 1.0,
inclusive. The input format for these values is an optional sign, a string of
numbers possibly containing a decimal point, and an optional exponent field
containing an E or e followed by a possibly signed integer string.
Device-Independent String Specifications
The standard device-independent string specifications have the following
syntax:
CIEXYZ:<X>/<Y>/<Z>
CIEuvY:<u>/<v>/<Y>
CIExyY:<x>/<y>/<Y>
CIELab:<L>/<a>/<b>
CIELuv:<L>/<u>/<v>
TekHVC:<H>/<V>/<C>
All of the values (C, H, V, X, Y, Z, a, b, u, v, y, x) are floating-point
values. The syntax for these values is an optional plus or minus sign, a string
of digits possibly containing a decimal point, and an optional exponent field
consisting of an ``E'' or ``e'' followed by an optional plus or minus followed
by a string of digits.
Color Conversion Contexts and Gamut Mapping
When Xlib converts device-independent color specifications into
device-dependent specifications and vice versa, it uses knowledge about the
color limitations of the screen hardware. This information, typically called
the device profile, is available in a Color Conversion Context (CCC).
Because a specified color may be outside the color gamut of the target screen
and the white point associated with the color specification may differ from the
white point inherent to the screen, Xlib applies gamut mapping when it
encounters certain conditions:
• Gamut compression occurs when conversion of device-independent color
specifications to device-dependent color specifications results in a color
out of the target screen's gamut.
• White adjustment occurs when the inherent white point of the screen differs
from the white point assumed by the client.
Gamut handling methods are stored as callbacks in the CCC, which in turn are
used by the color space conversion routines. Client data is also stored in the
CCC for each callback. The CCC also contains the white point the client assumes
to be associated with color specifications (that is, the Client White Point).
The client can specify the gamut handling callbacks and client data as well as
the Client White Point. Xlib does not preclude the X client from performing
other forms of gamut handling (for example, gamut expansion); however, Xlib
does not provide direct support for gamut handling other than white adjustment
and gamut compression.
Associated with each colormap is an initial CCC transparently generated by
Xlib. Therefore, when you specify a colormap as an argument to an Xlib
function, you are indirectly specifying a CCC. There is a default CCC
associated with each screen. Newly created CCCs inherit attributes from the
default CCC, so the default CCC attributes can be modified to affect new CCCs.
Xcms functions in which gamut mapping can occur return Status and have specific
status values defined for them, as follows:
• XcmsFailure indicates that the function failed.
• XcmsSuccess indicates that the function succeeded. In addition, if the
function performed any color conversion, the colors did not need to be
compressed.
• XcmsSuccessWithCompression indicates the function performed color
conversion and at least one of the colors needed to be compressed. The
gamut compression method is determined by the gamut compression procedure
in the CCC that is specified directly as a function argument or in the CCC
indirectly specified by means of the colormap argument.
Creating, Copying, and Destroying Colormaps
To create a colormap for a screen, use XCreateColormap.
Colormap XCreateColormap(Display *display, Window w, Visual *visual, int
alloc);
display Specifies the connection to the X server.
w Specifies the window on whose screen you want to create a colormap.
visual Specifies a visual type supported on the screen. If the visual type is
not one supported by the screen, a BadMatch error results.
alloc Specifies the colormap entries to be allocated. You can pass AllocNone
or AllocAll.
The XCreateColormap function creates a colormap of the specified visual type
for the screen on which the specified window resides and returns the colormap
ID associated with it. Note that the specified window is only used to determine
the screen.
The initial values of the colormap entries are undefined for the visual classes
GrayScale, PseudoColor, and DirectColor. For StaticGray, StaticColor, and
TrueColor, the entries have defined values, but those values are specific to
the visual and are not defined by X. For StaticGray, StaticColor, and TrueColor
, alloc must be AllocNone, or a BadMatch error results. For the other visual
classes, if alloc is AllocNone, the colormap initially has no allocated
entries, and clients can allocate them. For information about the visual types,
see section 3.1.
If alloc is AllocAll, the entire colormap is allocated writable. The initial
values of all allocated entries are undefined. For GrayScale and PseudoColor,
the effect is as if an XAllocColorCells call returned all pixel values from
zero to N - 1, where N is the colormap entries value in the specified visual.
For DirectColor, the effect is as if an XAllocColorPlanes call returned a pixel
value of zero and red_mask, green_mask, and blue_mask values containing the
same bits as the corresponding masks in the specified visual. However, in all
cases, none of these entries can be freed by using XFreeColors.
XCreateColormap can generate BadAlloc, BadMatch, BadValue, and BadWindow
errors.
To create a new colormap when the allocation out of a previously shared
colormap has failed because of resource exhaustion, use XCopyColormapAndFree.
Colormap XCopyColormapAndFree(Display *display, Colormap colormap);
display Specifies the connection to the X server.
colormap Specifies the colormap.
The XCopyColormapAndFree function creates a colormap of the same visual type
and for the same screen as the specified colormap and returns the new colormap
ID. It also moves all of the client's existing allocation from the specified
colormap to the new colormap with their color values intact and their read-only
or writable characteristics intact and frees those entries in the specified
colormap. Color values in other entries in the new colormap are undefined. If
the specified colormap was created by the client with alloc set to AllocAll,
the new colormap is also created with AllocAll, all color values for all
entries are copied from the specified colormap, and then all entries in the
specified colormap are freed. If the specified colormap was not created by the
client with AllocAll, the allocations to be moved are all those pixels and
planes that have been allocated by the client using XAllocColor,
XAllocNamedColor, XAllocColorCells, or XAllocColorPlanes and that have not been
freed since they were allocated.
XCopyColormapAndFree can generate BadAlloc and BadColor errors.
To destroy a colormap, use XFreeColormap.
XFreeColormap(Display *display, Colormap colormap);
display Specifies the connection to the X server.
colormap Specifies the colormap that you want to destroy.
The XFreeColormap function deletes the association between the colormap
resource ID and the colormap and frees the colormap storage. However, this
function has no effect on the default colormap for a screen. If the specified
colormap is an installed map for a screen, it is uninstalled (see
XUninstallColormap). If the specified colormap is defined as the colormap for a
window (by XCreateWindow, XSetWindowColormap, or XChangeWindowAttributes),
XFreeColormap changes the colormap associated with the window to None and
generates a ColormapNotify event. X does not define the colors displayed for a
window with a colormap of None.
XFreeColormap can generate a BadColor error.
Mapping Color Names to Values
To map a color name to an RGB value, use XLookupColor.
Status XLookupColor(Display *display, Colormap colormap, char *color_name,
XColor *exact_def_return, XColor *screen_def_return);
display Specifies the connection to the X server.
colormap Specifies the colormap.
color_name Specifies the color name string (for example, red) whose
color definition structure you want returned.
exact_def_return Returns the exact RGB values.
screen_def_return Returns the closest RGB values provided by the hardware.
The XLookupColor function looks up the string name of a color with respect to
the screen associated with the specified colormap. It returns both the exact
color values and the closest values provided by the screen with respect to the
visual type of the specified colormap. If the color name is not in the Host
Portable Character Encoding, the result is implementation-dependent. Use of
uppercase or lowercase does not matter. XLookupColor returns nonzero if the
name is resolved; otherwise, it returns zero.
XLookupColor can generate a BadColor error.
To map a color name to the exact RGB value, use XParseColor.
Status XParseColor(Display *display, Colormap colormap, char *spec, XColor
*exact_def_return);
display Specifies the connection to the X server.
colormap Specifies the colormap.
spec Specifies the color name string; case is ignored.
exact_def_return Returns the exact color value for later use and sets the DoRed
, DoGreen, and DoBlue flags.
The XParseColor function looks up the string name of a color with respect to
the screen associated with the specified colormap. It returns the exact color
value. If the color name is not in the Host Portable Character Encoding, the
result is implementation-dependent. Use of uppercase or lowercase does not
matter. XParseColor returns nonzero if the name is resolved; otherwise, it
returns zero.
XParseColor can generate a BadColor error.
To map a color name to a value in an arbitrary color space, use XcmsLookupColor
.
Status XcmsLookupColor(Display *display, Colormap colormap, char *color_string,
XcmsColor *color_exact_return, XcmsColor *color_screen_return, XcmsColorFormat
result_format);
display Specifies the connection to the X server.
colormap Specifies the colormap.
color_string Specifies the color string(St.
Returns the color specification parsed from the color
color_exact_return 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.
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
result_format 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.
Returns the color specification parsed from the color
color_exact_return string or parsed from the corresponding string found in a
color-name database.
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
result_format 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.
Specifies the color specification array of XcmsColor
colors 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.
Returns an array of Boolean values indicating
compression status. If a non-NULL pointer is supplied,
compression_flags_return 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.
Specifies the pixel member that indicates the color cell to
color_in_out 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.
Specifies an array of XcmsColor structures, each pixel member
colors_in_out 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.
Specifies the gamut compression procedure that is to be
applied when a color lies outside the screen's color gamut. If
compression_proc 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.
Specifies the Client White Point. If NULL is
client_white_point 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.
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
compression_proc 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.
Specifies the white adjustment procedure that is to be
white_adjust_proc 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[]);
Specifies the CCC. If conversion is between
ccc 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.
Returns an array of Boolean values indicating
compression status. If a non-NULL pointer is supplied,
compression_flags_return 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.
Specifies an array of color specifications. Pixel
colors_in_out members should be ignored and must remain unchanged
upon return.
ncolors Specifies the number of XcmsColor structures in the
color-specification array.
Specifies the index into the array of XcmsColor
index 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.
Returns an array of Boolean values for indicating
compression status. If a non-NULL pointer is supplied
compression_flags_return 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.
Specifies an array of color specifications. Pixel
colors_in_out members should be ignored and must remain unchanged
upon return.
ncolors Specifies the number of XcmsColor structures in the
color-specification array.
Returns an array of Boolean values for indicating
compression status. If a non-NULL pointer is supplied
compression_flags_return and a color at a given index is compressed, then True
should be stored at the corresponding index in this
array; otherwise, the array should not be modified.
Supplied White Point Adjustment Procedures
White point adjustment procedures provided by Xlib are as follows:
• XcmsCIELabWhiteShiftColors
• This uses the CIE L*a*b* color space for adjusting the chromatic character
of colors to compensate for the chromatic differences between the source
and destination white points. This procedure simply converts the color
specifications to XcmsCIELab using the source white point and then converts
to the target specification format using the destination's white point. No
client data is necessary.
• XcmsCIELuvWhiteShiftColors
• This uses the CIE L*u*v* color space for adjusting the chromatic character
of colors to compensate for the chromatic differences between the source
and destination white points. This procedure simply converts the color
specifications to XcmsCIELuv using the source white point and then converts
to the target specification format using the destination's white point. No
client data is necessary.
• XcmsTekHVCWhiteShiftColors
• This uses the TekHVC color space for adjusting the chromatic character of
colors to compensate for the chromatic differences between the source and
destination white points. This procedure simply converts the color
specifications to XcmsTekHVC using the source white point and then converts
to the target specification format using the destination's white point. An
advantage of this procedure over those previously described is an attempt
to minimize hue shift. No client data is necessary.
From an implementation point of view, these white point adjustment procedures
convert the color specifications to a device-independent but
white-point-dependent color space (for example, CIE L*u*v*, CIE L*a*b*, TekHVC)
using one white point and then converting those specifications to the target
color space using another white point. In other words, the specification goes
in the color space with one white point but comes out with another white point,
resulting in a chromatic shift based on the chromatic displacement between the
initial white point and target white point. The CIE color spaces that are
assumed to be white-point-independent are CIE u'v'Y, CIE XYZ, and CIE xyY. When
developing a custom white point adjustment procedure that uses a
device-independent color space not initially accessible for use in the color
management system, use XcmsAddColorSpace to ensure that it is added.
As an example, if the CCC specifies a white point adjustment procedure and if
the Client White Point and Screen White Point differ, the XcmsAllocColor
function will use the white point adjustment procedure twice:
• Once to convert to XcmsRGB
• A second time to convert from XcmsRGB
For example, assume the specification is in XcmsCIEuvY and the adjustment
procedure is XcmsCIELuvWhiteShiftColors. During conversion to XcmsRGB, the call
to XcmsAllocColor results in the following series of color specification
conversions:
• From XcmsCIEuvY to XcmsCIELuv using the Client White Point
• From XcmsCIELuv to XcmsCIEuvY using the Screen White Point
• From XcmsCIEuvY to XcmsCIEXYZ (CIE u'v'Y and XYZ are
white-point-independent color spaces)
• From XcmsCIEXYZ to XcmsRGBi
• From XcmsRGBi to XcmsRGB
The resulting RGB specification is passed to XAllocColor, and the RGB
specification returned by XAllocColor is converted back to XcmsCIEuvY by
reversing the color conversion sequence.
Gamut Querying Functions
This section describes the gamut querying functions that Xlib provides. These
functions allow the client to query the boundary of the screen's color gamut in
terms of the CIE L*a*b*, CIE L*u*v*, and TekHVC color spaces. Functions are
also provided that allow you to query the color specification of:
• White (full-intensity red, green, and blue)
• Red (full-intensity red while green and blue are zero)
• Green (full-intensity green while red and blue are zero)
• Blue (full-intensity blue while red and green are zero)
• Black (zero-intensity red, green, and blue)
The white point associated with color specifications passed to and returned
from these gamut querying functions is assumed to be the Screen White Point.
This is a reasonable assumption, because the client is trying to query the
screen's color gamut.
The following naming convention is used for the Max and Min functions:
Xcms<color_space>QueryMax<dimensions>
Xcms<color_space>QueryMin<dimensions>
The <dimensions> consists of a letter or letters that identify the dimensions
of the color space that are not fixed. For example, XcmsTekHVCQueryMaxC is
given a fixed Hue and Value for which maximum Chroma is found.
Red, Green, and Blue Queries
To obtain the color specification for black (zero-intensity red, green, and
blue), use XcmsQueryBlack.
Status XcmsQueryBlack(XcmsCCC ccc, XcmsColorFormat target_format, XcmsColor
*color_return);
ccc Specifies the CCC. The CCC's Client White Point and white point
adjustment procedures are ignored.
target_format Specifies the target color specification format.
Returns the color specification in the specified target format
color_return 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.
Returns the color specification in the specified target format
for full-intensity blue while red and green are zero. The white
color_return 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.
Returns the color specification in the specified target format
for full-intensity green while red and blue are zero. The white
color_return 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.
Returns the color specification in the specified target format
for full-intensity red while green and blue are zero. The white
color_return 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.
Returns the color specification in the specified target format
color_return 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.
Returns the CIE L*a*b* coordinates of maximum chroma displayable
by the screen for the given hue angle and lightness. The white
color_return 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.
Returns the CIE L*a*b* coordinates of maximum lightness
displayable by the screen for the given hue angle and chroma. The
color_return 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.
Returns the CIE L*a*b* coordinates of maximum chroma displayable
color_return 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.
Returns the CIE L*a*b* coordinates of minimum lightness
displayable by the screen for the given hue angle and chroma. The
color_return 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.
Returns the CIE L*u*v* coordinates of maximum chroma displayable
by the screen for the given hue angle and lightness. The white
color_return 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.
Returns the CIE L*u*v* coordinates of maximum lightness
displayable by the screen for the given hue angle and chroma. The
color_return 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.
Returns the CIE L*u*v* coordinates of maximum chroma displayable
color_return 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.
Returns the CIE L*u*v* coordinates of minimum lightness
displayable by the screen for the given hue angle and chroma. The
color_return 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.
Returns the maximum Chroma along with the actual Hue and Value at
color_return 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.
Returns the maximum Value along with the Hue and Chroma at which
color_return 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.
Returns the color specification in XcmsTekHVC for the maximum
Chroma, the Value at which that maximum Chroma is reached, and the
color_return 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.
Returns nsamples of color specifications in XcmsTekHVC such that
the Chroma is the maximum attainable for the Value and Hue. The
colors_return 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.
Returns the minimum Value and the actual Hue and Chroma at which
color_return 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.
Specifies the white point associated with color specifications.
white_point 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.
Specifies an array of color specifications. Pixel
colors_in_out members should be ignored and must remain unchanged
upon return.
ncolors Specifies the number of XcmsColor structures in the
color-specification array.
Returns an array of Boolean values for indicating
compression status. If a non-NULL pointer is supplied
compression_flags_return 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, LineDoubleDash */
int cap_style; /* CapNotLast, CapButt, CapRound, CapProjecting */
int join_style; /* JoinMiter, JoinRound, JoinBevel */
int fill_style; /* FillSolid, FillTiled, FillStippled FillOpaqueStippled*/
int fill_rule; /* EvenOddRule, WindingRule */
int arc_mode; /* ArcChord, ArcPieSlice */
Pixmap tile; /* tile pixmap for tiling operations */
Pixmap stipple; /* stipple 1 plane pixmap for stippling */
int ts_x_origin; /* offset for tile or stipple operations */
int ts_y_origin
Font font; /* default text font for text operations */
int subwindow_mode; /* ClipByChildren, IncludeInferiors */
Bool graphics_exposures; /* boolean, should exposures be generated */
int clip_x_origin; /* origin for clipping */
int clip_y_origin;
Pixmap clip_mask; /* bitmap clipping; other calls for rects */
int dash_offset; /* patterned/dashed line information */
char dashes;
} 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 │
├──────────────────┼──────────────────────────────────────────────────────────┤
│ │Pixmap of unspecified size filled with foreground pixel │
│ │ │
│tile │(that is, client specified pixel if any, else 0) │
│ │ │
│ │(subsequent changes to foreground do not affect this │
│ │pixmap) │
├──────────────────┼──────────────────────────────────────────────────────────┤
│stipple │Pixmap of unspecified size filled with ones │
├──────────────────┼──────────────────────────────────────────────────────────┤
│ts_x_origin │0 │
├──────────────────┼──────────────────────────────────────────────────────────┤
│ts_y_origin │0 │
├──────────────────┼──────────────────────────────────────────────────────────┤
│font │<implementation dependent> │
├──────────────────┼──────────────────────────────────────────────────────────┤
│subwindow_mode │ClipByChildren │
├──────────────────┼──────────────────────────────────────────────────────────┤
│graphics_exposures│True │
├──────────────────┼──────────────────────────────────────────────────────────┤
│clip_x_origin │0 │
├──────────────────┼──────────────────────────────────────────────────────────┤
│clip_y_origin │0 │
├──────────────────┼──────────────────────────────────────────────────────────┤
│clip_mask │None │
├──────────────────┼──────────────────────────────────────────────────────────┤
│dash_offset │0 │
├──────────────────┼──────────────────────────────────────────────────────────┤
│dashes │4 (that is, the list [4, 4]) │
└──────────────────┴──────────────────────────────────────────────────────────┘
Note that foreground and background are not set to any values likely to be
useful in a window.
The function attributes of a GC are used when you update a section of a
drawable (the destination) with bits from somewhere else (the source). The
function in a GC defines how the new destination bits are to be computed from
the source bits and the old destination bits. GXcopy is typically the most
useful because it will work on a color display, but special applications may
use other functions, particularly in concert with particular planes of a color
display. The 16 GC functions, defined in <X11/X.h>, are:
┌──────────────┬─────┬───────────────────────┐
│Function Name │Value│Operation │
├──────────────┼─────┼───────────────────────┤
│GXclear │0x0 │0 │
├──────────────┼─────┼───────────────────────┤
│GXand │0x1 │src AND dst │
├──────────────┼─────┼───────────────────────┤
│GXandReverse │0x2 │src AND NOT dst │
├──────────────┼─────┼───────────────────────┤
│GXcopy │0x3 │src │
├──────────────┼─────┼───────────────────────┤
│GXandInverted │0x4 │(NOT src) AND dst │
├──────────────┼─────┼───────────────────────┤
│GXnoop │0x5 │dst │
├──────────────┼─────┼───────────────────────┤
│GXxor │0x6 │src XOR dst │
├──────────────┼─────┼───────────────────────┤
│GXor │0x7 │src OR dst │
├──────────────┼─────┼───────────────────────┤
│GXnor │0x8 │(NOT src) AND (NOT dst)│
├──────────────┼─────┼───────────────────────┤
│GXequiv │0x9 │(NOT src) XOR dst │
├──────────────┼─────┼───────────────────────┤
│GXinvert │0xa │NOT dst │
├──────────────┼─────┼───────────────────────┤
│GXorReverse │0xb │src OR (NOT dst) │
├──────────────┼─────┼───────────────────────┤
│GXcopyInverted│0xc │NOT src │
├──────────────┼─────┼───────────────────────┤
│GXorInverted │0xd │(NOT src) OR dst │
├──────────────┼─────┼───────────────────────┤
│GXnand │0xe │(NOT src) OR (NOT dst) │
├──────────────┼─────┼───────────────────────┤
│GXset │0xf │1 │
└──────────────┴─────┴───────────────────────┘
Many graphics operations depend on either pixel values or planes in a GC. The
planes attribute is of type long, and it specifies which planes of the
destination are to be modified, one bit per plane. A monochrome display has
only one plane and will be the least significant bit of the word. As planes are
added to the display hardware, they will occupy more significant bits in the
plane mask.
In graphics operations, given a source and destination pixel, the result is
computed bitwise on corresponding bits of the pixels. That is, a Boolean
operation is performed in each bit plane. The plane_mask restricts the
operation to a subset of planes. A macro constant AllPlanes can be used to
refer to all planes of the screen simultaneously. The result is computed by the
following:
((src FUNC dst) AND plane-mask) OR (dst AND (NOT plane-mask))
Range checking is not performed on the values for foreground, background, or
plane_mask. They are simply truncated to the appropriate number of bits. The
line-width is measured in pixels and either can be greater than or equal to one
(wide line) or can be the special value zero (thin line).
Wide lines are drawn centered on the path described by the graphics request.
Unless otherwise specified by the join-style or cap-style, the bounding box of
a wide line with endpoints [x1, y1], [x2, y2] and width w is a rectangle with
vertices at the following real coordinates:
[x1-(w*sn/2), y1+(w*cs/2)], [x1+(w*sn/2), y1-(w*cs/2)],
[x2-(w*sn/2), y2+(w*cs/2)], [x2+(w*sn/2), y2-(w*cs/2)]
Here sn is the sine of the angle of the line, and cs is the cosine of the angle
of the line. A pixel is part of the line and so is drawn if the center of the
pixel is fully inside the bounding box (which is viewed as having infinitely
thin edges). If the center of the pixel is exactly on the bounding box, it is
part of the line if and only if the interior is immediately to its right (x
increasing direction). Pixels with centers on a horizontal edge are a special
case and are part of the line if and only if the interior or the boundary is
immediately below (y increasing direction) and the interior or the boundary is
immediately to the right (x increasing direction).
Thin lines (zero line-width) are one-pixel-wide lines drawn using an
unspecified, device-dependent algorithm. There are only two constraints on this
algorithm.
• If a line is drawn unclipped from [x1,y1] to [x2,y2] and if another line is
drawn unclipped from [x1+dx,y1+dy] to [x2+dx,y2+dy], a point [x,y] is
touched by drawing the first line if and only if the point [x+dx,y+dy] is
touched by drawing the second line.
• The effective set of points comprising a line cannot be affected by
clipping. That is, a point is touched in a clipped line if and only if the
point lies inside the clipping region and the point would be touched by the
line when drawn unclipped.
A wide line drawn from [x1,y1] to [x2,y2] always draws the same pixels as a
wide line drawn from [x2,y2] to [x1,y1], not counting cap-style and join-style.
It is recommended that this property be true for thin lines, but this is not
required. A line-width of zero may differ from a line-width of one in which
pixels are drawn. This permits the use of many manufacturers' line drawing
hardware, which may run many times faster than the more precisely specified
wide lines.
In general, drawing a thin line will be faster than drawing a wide line of
width one. However, because of their different drawing algorithms, thin lines
may not mix well aesthetically with wide lines. If it is desirable to obtain
precise and uniform results across all displays, a client should always use a
line-width of one rather than a line-width of zero.
The line-style defines which sections of a line are drawn:
LineSolid The full path of the line is drawn.
The full path of the line is drawn, but the even dashes are
LineDoubleDash filled differently from the odd dashes (see fill-style) with
CapButt style used where even and odd dashes meet.
Only the even dashes are drawn, and cap-style applies to all
LineOnOffDash 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.
The line has a circular arc with the diameter equal to the
CapRound line-width, centered on the endpoint. (This is equivalent to
CapButt for line-width of zero).
The line is square at the end, but the path continues beyond the
CapProjecting 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:
The outer edges of two lines extend to meet at an angle. However, if
JoinMiter 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.
The closed path is a square, aligned with the coordinate
CapProjecting wide 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
A tile with the same width and height as stipple, but with
FillOpaqueStippled 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.
Specifies which components in the GC are to be set using the
valuemask 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.
Specifies which components in the GC are to be copied to the
valuemask 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.
Specifies which components in the GC are to be changed using
valuemask 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.
Specifies which components in the GC are to be returned in the
valuemask 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.
Specifies the line-style and cap-style you want to set for the
cap_style 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.
Specifies a Boolean value that indicates whether you want
graphics_exposures 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
Specify the x and y coordinates, which are relative to the origin of
y 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
Specify the x and y coordinates, which are relative to the origin of
y 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 data */
Font fid; /* Font id for this font */
unsigned direction; /* hint about the direction font is painted */
unsigned min_char_or_byte2; /* first character */
unsigned max_char_or_byte2; /* last character */
unsigned min_byte1; /* first row that exists */
unsigned max_byte1; /* last row that exists */
Bool all_chars_exist; /* flag if all characters have nonzero size */
unsigned default_char; /* char to print for undefined character */
int n_properties; /* how many properties there are */
XFontProp *properties; /* pointer to array of additional properties */
XCharStruct min_bounds; /* minimum bounds over all existing char */
XCharStruct max_bounds; /* maximum bounds over all existing char */
XCharStruct *per_char; /* first_char to last_char information */
int ascent; /* logical extent above baseline for spacing */
int descent; /* logical descent below baseline for spacing */
} XFontStruct;
X supports single byte/character, two bytes/character matrix, and 16-bit
character text operations. Note that any of these forms can be used with a
font, but a single byte/character text request can only specify a single byte
(that is, the first row of a 2-byte font). You should view 2-byte fonts as a
two-dimensional matrix of defined characters: byte1 specifies the range of
defined rows and byte2 defines the range of defined columns of the font. Single
byte/character fonts have one row defined, and the byte2 range specified in the
structure defines a range of characters.
The bounding box of a character is defined by the XCharStruct of that
character. When characters are absent from a font, the default_char is used.
When fonts have all characters of the same size, only the information in the
XFontStruct min and max bounds are used.
The members of the XFontStruct have the following semantics:
• The direction member can be either FontLeftToRight or FontRightToLeft. It
is just a hint as to whether most XCharStruct elements have a positive (
FontLeftToRight) or a negative (FontRightToLeft) character width metric.
The core protocol defines no support for vertical text.
• If the min_byte1 and max_byte1 members are both zero, min_char_or_byte2
specifies the linear character index corresponding to the first element of
the per_char array, and max_char_or_byte2 specifies the linear character
index of the last element.
• If either min_byte1 or max_byte1 are nonzero, both min_char_or_byte2 and
max_char_or_byte2 are less than 256, and the 2-byte character index values
corresponding to the per_char array element N (counting from 0) are:
• byte1 = N/D + min_byte1 byte2 = N\\D + min_char_or_byte2
• where:
• D = max_char_or_byte2 - min_char_or_byte2 + 1 / = integer division \\ =
integer modulus
• If the per_char pointer is NULL, all glyphs between the first and last
character indexes inclusive have the same information, as given by both
min_bounds and max_bounds.
• If all_chars_exist is True, all characters in the per_char array have
nonzero bounding boxes.
• The default_char member specifies the character that will be used when an
undefined or nonexistent character is printed. The default_char is a 16-bit
character (not a 2-byte character). For a font using 2-byte matrix format,
the default_char has byte1 in the most-significant byte and byte2 in the
least significant byte. If the default_char itself specifies an undefined
or nonexistent character, no printing is performed for an undefined or
nonexistent character.
• The min_bounds and max_bounds members contain the most extreme values of
each individual XCharStruct component over all elements of this array (and
ignore nonexistent characters). The bounding box of the font (the smallest
rectangle enclosing the shape obtained by superimposing all of the
characters at the same origin [x,y]) has its upper-left coordinate at:
[x + min_bounds.lbearing, y - max_bounds.ascent]
• Its width is:
max_bounds.rbearing - min_bounds.lbearing
• Its height is:
max_bounds.ascent + max_bounds.descent
• The ascent member is the logical extent of the font above the baseline that
is used for determining line spacing. Specific characters may extend beyond
this.
• The descent member is the logical extent of the font at or below the
baseline that is used for determining line spacing. Specific characters may
extend beyond this.
• If the baseline is at Y-coordinate y, the logical extent of the font is
inclusive between the Y-coordinate values (y - font.ascent) and (y +
font.descent - 1). Typically, the minimum interline spacing between rows of
text is given by ascent + descent.
For a character origin at [x,y], the bounding box of a character (that is, the
smallest rectangle that encloses the character's shape) described in terms of
XCharStruct components is a rectangle with its upper-left corner at:
[x + lbearing, y - ascent]
Its width is:
rbearing - lbearing
Its height is:
ascent + descent
The origin for the next character is defined to be:
[x + width, y]
The lbearing member defines the extent of the left edge of the character ink
from the origin. The rbearing member defines the extent of the right edge of
the character ink from the origin. The ascent member defines the extent of the
top edge of the character ink from the origin. The descent member defines the
extent of the bottom edge of the character ink from the origin. The width
member defines the logical width of the character.
Note that the baseline (the y position of the character origin) is logically
viewed as being the scanline just below nondescending characters. When descent
is zero, only pixels with Y-coordinates less than y are drawn, and the origin
is logically viewed as being coincident with the left edge of a nonkerned
character. When lbearing is zero, no pixels with X-coordinate less than x are
drawn. Any of the XCharStruct metric members could be negative. If the width is
negative, the next character will be placed to the left of the current origin.
The X protocol does not define the interpretation of the attributes member in
the XCharStruct structure. A nonexistent character is represented with all
members of its XCharStruct set to zero.
A font is not guaranteed to have any properties. The interpretation of the
property value (for example, long or unsigned long) must be derived from a
priori knowledge of the property. A basic set of font properties is specified
in the X Consortium standard X Logical Font Description Conventions.
Loading and Freeing Fonts
Xlib provides functions that you can use to load fonts, get font information,
unload fonts, and free font information. A few font functions use a GContext
resource ID or a font ID interchangeably.
To load a given font, use XLoadFont.
Font XLoadFont(Display *display, char *name);
display Specifies the connection to the X server.
name Specifies the name of the font, which is a null-terminated string.
The XLoadFont function loads the specified font and returns its associated font
ID. If the font name is not in the Host Portable Character Encoding, the result
is implementation-dependent. Use of uppercase or lowercase does not matter.
When the characters ``?'' and ``*'' are used in a font name, a pattern match is
performed and any matching font is used. In the pattern, the ``?'' character
will match any single character, and the ``*'' character will match any number
of characters. A structured format for font names is specified in the X
Consortium standard X Logical Font Description Conventions. If XLoadFont was
unsuccessful at loading the specified font, a BadName error results. Fonts are
not associated with a particular screen and can be stored as a component of any
GC. When the font is no longer needed, call XUnloadFont.
XLoadFont can generate BadAlloc and BadName errors.
To return information about an available font, use XQueryFont.
XFontStruct *XQueryFont(Display *display, XID font_ID);
display Specifies the connection to the X server.
font_ID Specifies the font ID or the GContext ID.
The XQueryFont function returns a pointer to the XFontStruct structure, which
contains information associated with the font. You can query a font or the font
stored in a GC. The font ID stored in the XFontStruct structure will be the
GContext ID, and you need to be careful when using this ID in other functions
(see XGContextFromGC). If the font does not exist, XQueryFont returns NULL. To
free this data, use XFreeFontInfo.
To perform a XLoadFont and XQueryFont in a single operation, use XLoadQueryFont
.
XFontStruct *XLoadQueryFont(Display *display, char *name);
display Specifies the connection to the X server.
name Specifies the name of the font, which is a null-terminated string.
The XLoadQueryFont function provides the most common way for accessing a font.
XLoadQueryFont both opens (loads) the specified font and returns a pointer to
the appropriate XFontStruct structure. If the font name is not in the Host
Portable Character Encoding, the result is implementation-dependent. If the
font does not exist, XLoadQueryFont returns NULL.
XLoadQueryFont can generate a BadAlloc error.
To unload the font and free the storage used by the font structure that was
allocated by XQueryFont or XLoadQueryFont, use XFreeFont.
XFreeFont(Display *display, XFontStruct *font_struct);
display Specifies the connection to the X server.
font_struct Specifies the storage associated with the font.
The XFreeFont function deletes the association between the font resource ID and
the specified font and frees the XFontStruct structure. The font itself will be
freed when no other resource references it. The data and the font should not be
referenced again.
XFreeFont can generate a BadFont error.
To return a given font property, use XGetFontProperty.
Bool XGetFontProperty(XFontStruct *font_struct, Atom atom, unsigned long
*value_return);
font_struct Specifies the storage associated with the font.
atom Specifies the atom for the property name you want returned.
value_return Returns the value of the font property.
Given the atom for that property, the XGetFontProperty function returns the
value of the specified font property. XGetFontProperty also returns False if
the property was not defined or True if it was defined. A set of predefined
atoms exists for font properties, which can be found in <X11/Xatom.h>. This set
contains the standard properties associated with a font. Although it is not
guaranteed, it is likely that the predefined font properties will be present.
To unload a font that was loaded by XLoadFont, use XUnloadFont.
XUnloadFont(Display *display, Font font);
display Specifies the connection to the X server.
font Specifies the font.
The XUnloadFont function deletes the association between the font resource ID
and the specified font. The font itself will be freed when no other resource
references it. The font should not be referenced again.
XUnloadFont can generate a BadFont error.
Obtaining and Freeing Font Names and Information
You obtain font names and information by matching a wildcard specification when
querying a font type for a list of available sizes and so on.
To return a list of the available font names, use XListFonts.
char **XListFonts(Display *display, char *pattern, int maxnames, int
*actual_count_return);
display Specifies the connection to the X server.
pattern Specifies the null-terminated pattern string that can
contain wildcard characters.
maxnames Specifies the maximum number of names to be returned.
actual_count_return Returns the actual number of font names.
The XListFonts function returns an array of available font names (as controlled
by the font search path; see XSetFontPath) that match the string you passed to
the pattern argument. The pattern string can contain any characters, but each
asterisk (*) is a wildcard for any number of characters, and each question mark
(?) is a wildcard for a single character. If the pattern string is not in the
Host Portable Character Encoding, the result is implementation-dependent. Use
of uppercase or lowercase does not matter. Each returned string is
null-terminated. If the data returned by the server is in the Latin Portable
Character Encoding, then the returned strings are in the Host Portable
Character Encoding. Otherwise, the result is implementation-dependent. If there
are no matching font names, XListFonts returns NULL. The client should call
XFreeFontNames when finished with the result to free the memory.
To free a font name array, use XFreeFontNames.
XFreeFontNames(char *list[]);
list Specifies the array of strings you want to free.
The XFreeFontNames function frees the array and strings returned by XListFonts
or XListFontsWithInfo.
To obtain the names and information about available fonts, use
XListFontsWithInfo.
char **XListFontsWithInfo(Display *display, char *pattern, int maxnames, int
*count_return, XFontStruct **info_return);
display Specifies the connection to the X server.
pattern Specifies the null-terminated pattern string that can contain
wildcard characters.
maxnames Specifies the maximum number of names to be returned.
count_return Returns the actual number of matched font names.
info_return Returns the font information.
The XListFontsWithInfo function returns a list of font names that match the
specified pattern and their associated font information. The list of names is
limited to size specified by maxnames. The information returned for each font
is identical to what XLoadQueryFont would return except that the per-character
metrics are not returned. The pattern string can contain any characters, but
each asterisk (*) is a wildcard for any number of characters, and each question
mark (?) is a wildcard for a single character. If the pattern string is not in
the Host Portable Character Encoding, the result is implementation-dependent.
Use of uppercase or lowercase does not matter. Each returned string is
null-terminated. If the data returned by the server is in the Latin Portable
Character Encoding, then the returned strings are in the Host Portable
Character Encoding. Otherwise, the result is implementation-dependent. If there
are no matching font names, XListFontsWithInfo returns NULL.
To free only the allocated name array, the client should call XFreeFontNames.
To free both the name array and the font information array or to free just the
font information array, the client should call XFreeFontInfo.
To free font structures and font names, use XFreeFontInfo.
XFreeFontInfo(char **names, XFontStruct *free_info, int actual_count);
names Specifies the list of font names.
free_info Specifies the font information.
actual_count Specifies the actual number of font names.
The XFreeFontInfo function frees a font structure or an array of font
structures and optionally an array of font names. If NULL is passed for names,
no font names are freed. If a font structure for an open font (returned by
XLoadQueryFont) is passed, the structure is freed, but the font is not closed;
use XUnloadFont to close the font.
Computing Character String Sizes
Xlib provides functions that you can use to compute the width, the logical
extents, and the server information about 8-bit and 2-byte text strings. The
width is computed by adding the character widths of all the characters. It does
not matter if the font is an 8-bit or 2-byte font. These functions return the
sum of the character metrics in pixels.
To determine the width of an 8-bit character string, use XTextWidth.
int XTextWidth(XFontStruct *font_struct, char *string, int count);
font_struct Specifies the font used for the width computation.
string Specifies the character string.
count Specifies the character count in the specified string.
To determine the width of a 2-byte character string, use XTextWidth16.
int XTextWidth16(XFontStruct *font_struct, XChar2b *string, int count);
font_struct Specifies the font used for the width computation.
string Specifies the character string.
count Specifies the character count in the specified string.
Computing Logical Extents
To compute the bounding box of an 8-bit character string in a given font, use
XTextExtents.
XTextExtents(XFontStruct *font_struct, char *string, int nchars, int
*direction_return, int *font_ascent_return, int *font_descent_return,
XCharStruct *overall_return);
font_struct Specifies the XFontStruct structure.
string Specifies the character string.
nchars Specifies the number of characters in the character string.
direction_return Returns the value of the direction hint (FontLeftToRight or
FontRightToLeft).
font_ascent_return Returns the font ascent.
font_descent_return Returns the font descent.
overall_return Returns the overall size in the specified XCharStruct
structure.
To compute the bounding box of a 2-byte character string in a given font, use
XTextExtents16.
XTextExtents16(XFontStruct *font_struct, XChar2b *string, int nchars, int
*direction_return, int *font_ascent_return, int *font_descent_return,
XCharStruct *overall_return);
font_struct Specifies the XFontStruct structure.
string Specifies the character string.
nchars Specifies the number of characters in the character string.
direction_return Returns the value of the direction hint (FontLeftToRight or
FontRightToLeft).
font_ascent_return Returns the font ascent.
font_descent_return Returns the font descent.
overall_return Returns the overall size in the specified XCharStruct
structure.
The XTextExtents and XTextExtents16 functions perform the size computation
locally and, thereby, avoid the round-trip overhead of XQueryTextExtents and
XQueryTextExtents16. Both functions return an XCharStruct structure, whose
members are set to the values as follows.
The ascent member is set to the maximum of the ascent metrics of all characters
in the string. The descent member is set to the maximum of the descent metrics.
The width member is set to the sum of the character-width metrics of all
characters in the string. For each character in the string, let W be the sum of
the character-width metrics of all characters preceding it in the string. Let L
be the left-side-bearing metric of the character plus W. Let R be the
right-side-bearing metric of the character plus W. The lbearing member is set
to the minimum L of all characters in the string. The rbearing member is set to
the maximum R.
For fonts defined with linear indexing rather than 2-byte matrix indexing, each
XChar2b structure is interpreted as a 16-bit number with byte1 as the most
significant byte. If the font has no defined default character, undefined
characters in the string are taken to have all zero metrics.
Querying Character String Sizes
To query the server for the bounding box of an 8-bit character string in a
given font, use XQueryTextExtents.
XQueryTextExtents(Display *display, XID font_ID, char *string, int nchars, int
*direction_return, int *font_ascent_return, int *font_descent_return,
XCharStruct *overall_return);
display Specifies the connection to the X server.
font_ID Specifies either the font ID or the GContext ID that
contains the font.
string Specifies the character string.
nchars Specifies the number of characters in the character string.
direction_return Returns the value of the direction hint (FontLeftToRight or
FontRightToLeft).
font_ascent_return Returns the font ascent.
font_descent_return Returns the font descent.
overall_return Returns the overall size in the specified XCharStruct
structure.
To query the server for the bounding box of a 2-byte character string in a
given font, use XQueryTextExtents16.
XQueryTextExtents16(Display *display, XID font_ID, XChar2b *string, int nchars,
int *direction_return, int *font_ascent_return, int *font_descent_return,
XCharStruct *overall_return);
display Specifies the connection to the X server.
font_ID Specifies either the font ID or the GContext ID that
contains the font.
string Specifies the character string.
nchars Specifies the number of characters in the character string.
direction_return Returns the value of the direction hint (FontLeftToRight or
FontRightToLeft).
font_ascent_return Returns the font ascent.
font_descent_return Returns the font descent.
overall_return Returns the overall size in the specified XCharStruct
structure.
The XQueryTextExtents and XQueryTextExtents16 functions return the bounding box
of the specified 8-bit and 16-bit character string in the specified font or the
font contained in the specified GC. These functions query the X server and,
therefore, suffer the round-trip overhead that is avoided by XTextExtents and
XTextExtents16. Both functions return a XCharStruct structure, whose members
are set to the values as follows.
The ascent member is set to the maximum of the ascent metrics of all characters
in the string. The descent member is set to the maximum of the descent metrics.
The width member is set to the sum of the character-width metrics of all
characters in the string. For each character in the string, let W be the sum of
the character-width metrics of all characters preceding it in the string. Let L
be the left-side-bearing metric of the character plus W. Let R be the
right-side-bearing metric of the character plus W. The lbearing member is set
to the minimum L of all characters in the string. The rbearing member is set to
the maximum R.
For fonts defined with linear indexing rather than 2-byte matrix indexing, each
XChar2b structure is interpreted as a 16-bit number with byte1 as the most
significant byte. If the font has no defined default character, undefined
characters in the string are taken to have all zero metrics.
Characters with all zero metrics are ignored. If the font has no defined
default_char, the undefined characters in the string are also ignored.
XQueryTextExtents and XQueryTextExtents16 can generate BadFont and BadGC
errors.
Drawing Text
This section discusses how to draw:
• Complex text
• Text characters
• Image text characters
The fundamental text functions XDrawText and XDrawText16 use the following
structures:
typedef struct {
char *chars; /* pointer to string */
int nchars; /* number of characters */
int delta; /* delta between strings */
Font font; /* Font to print it in, None don't change */
} XTextItem;
typedef struct {
XChar2b *chars; /* pointer to two-byte characters */
int nchars; /* number of characters */
int delta; /* delta between strings */
Font font; /* font to print it in, None don't change */
} XTextItem16;
If the font member is not None, the font is changed before printing and also is
stored in the GC. If an error was generated during text drawing, the previous
items may have been drawn. The baseline of the characters are drawn starting at
the x and y coordinates that you pass in the text drawing functions.
For example, consider the background rectangle drawn by XDrawImageString. If
you want the upper-left corner of the background rectangle to be at pixel
coordinate (x,y), pass the (x,y + ascent) as the baseline origin coordinates to
the text functions. The ascent is the font ascent, as given in the XFontStruct
structure. If you want the lower-left corner of the background rectangle to be
at pixel coordinate (x,y), pass the (x,y - descent + 1) as the baseline origin
coordinates to the text functions. The descent is the font descent, as given in
the XFontStruct structure.
Drawing Complex Text
To draw 8-bit characters in a given drawable, use XDrawText.
XDrawText(Display *display, Drawable d, GC gc, int x, int y, XTextItem *items,
int nitems);
display Specifies the connection to the X server.
d Specifies the drawable.
gc Specifies the GC.
x
y Specify the x and y coordinates, which are relative to the origin of
the specified drawable and define the origin of the first character.
items Specifies an array of text items.
nitems Specifies the number of text items in the array.
To draw 2-byte characters in a given drawable, use XDrawText16.
XDrawText16(Display *display, Drawable d, GC gc, int x, int y, XTextItem16
*items, int nitems);
display Specifies the connection to the X server.
d Specifies the drawable.
gc Specifies the GC.
x
y Specify the x and y coordinates, which are relative to the origin of
the specified drawable and define the origin of the first character.
items Specifies an array of text items.
nitems Specifies the number of text items in the array.
The XDrawText16 function is similar to XDrawText except that it uses 2-byte or
16-bit characters. Both functions allow complex spacing and font shifts between
counted strings.
Each text item is processed in turn. A font member other than None in an item
causes the font to be stored in the GC and used for subsequent text. A text
element delta specifies an additional change in the position along the x axis
before the string is drawn. The delta is always added to the character origin
and is not dependent on any characteristics of the font. Each character image,
as defined by the font in the GC, is treated as an additional mask for a fill
operation on the drawable. The drawable is modified only where the font
character has a bit set to 1. If a text item generates a BadFont error, the
previous text items may have been drawn.
For fonts defined with linear indexing rather than 2-byte matrix indexing, each
XChar2b structure is interpreted as a 16-bit number with byte1 as the most
significant byte.
Both functions use these GC components: function, plane-mask, fill-style, font,
subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. They also use
these GC mode-dependent components: foreground, background, tile, stipple,
tile-stipple-x-origin, and tile-stipple-y-origin.
XDrawText and XDrawText16 can generate BadDrawable, BadFont, BadGC, and
BadMatch errors.
Drawing Text Characters
To draw 8-bit characters in a given drawable, use XDrawString.
XDrawString(Display *display, Drawable d, GC gc, int x, int y, char *string,
int length);
display Specifies the connection to the X server.
d Specifies the drawable.
gc Specifies the GC.
x
y Specify the x and y coordinates, which are relative to the origin of
the specified drawable and define the origin of the first character.
string Specifies the character string.
length Specifies the number of characters in the string argument.
To draw 2-byte characters in a given drawable, use XDrawString16.
XDrawString16(Display *display, Drawable d, GC gc, int x, int y, XChar2b
*string, int length);
display Specifies the connection to the X server.
d Specifies the drawable.
gc Specifies the GC.
x
y Specify the x and y coordinates, which are relative to the origin of
the specified drawable and define the origin of the first character.
string Specifies the character string.
length Specifies the number of characters in the string argument.
Each character image, as defined by the font in the GC, is treated as an
additional mask for a fill operation on the drawable. The drawable is modified
only where the font character has a bit set to 1. For fonts defined with 2-byte
matrix indexing and used with XDrawString16, each byte is used as a byte2 with
a byte1 of zero.
Both functions use these GC components: function, plane-mask, fill-style, font,
subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. They also use
these GC mode-dependent components: foreground, background, tile, stipple,
tile-stipple-x-origin, and tile-stipple-y-origin.
XDrawString and XDrawString16 can generate BadDrawable, BadGC, and BadMatch
errors.
Drawing Image Text Characters
Some applications, in particular terminal emulators, need to print image text
in which both the foreground and background bits of each character are painted.
This prevents annoying flicker on many displays.
To draw 8-bit image text characters in a given drawable, use XDrawImageString.
XDrawImageString(Display *display, Drawable d, GC gc, int x, int y, char
*string, int length);
display Specifies the connection to the X server.
d Specifies the drawable.
gc Specifies the GC.
x
y Specify the x and y coordinates, which are relative to the origin of
the specified drawable and define the origin of the first character.
string Specifies the character string.
length Specifies the number of characters in the string argument.
To draw 2-byte image text characters in a given drawable, use
XDrawImageString16.
XDrawImageString16(Display *display, Drawable d, GC gc, int x, int y, XChar2b
*string, int length);
display Specifies the connection to the X server.
d Specifies the drawable.
gc Specifies the GC.
x
y Specify the x and y coordinates, which are relative to the origin of
the specified drawable and define the origin of the first character.
string Specifies the character string.
length Specifies the number of characters in the string argument.
The XDrawImageString16 function is similar to XDrawImageString except that it
uses 2-byte or 16-bit characters. Both functions also use both the foreground
and background pixels of the GC in the destination.
The effect is first to fill a destination rectangle with the background pixel
defined in the GC and then to paint the text with the foreground pixel. The
upper-left corner of the filled rectangle is at:
[x, y - font-ascent]
The width is:
overall-width
The height is:
font-ascent + font-descent
The overall-width, font-ascent, and font-descent are as would be returned by
XQueryTextExtents using gc and string. The function and fill-style defined in
the GC are ignored for these functions. The effective function is GXcopy, and
the effective fill-style is FillSolid.
For fonts defined with 2-byte matrix indexing and used with XDrawImageString,
each byte is used as a byte2 with a byte1 of zero.
Both functions use these GC components: plane-mask, foreground, background,
font, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask.
XDrawImageString and XDrawImageString16 can generate BadDrawable, BadGC, and
BadMatch errors.
Transferring Images between Client and Server
Xlib provides functions that you can use to transfer images between a client
and the server. Because the server may require diverse data formats, Xlib
provides an image object that fully describes the data in memory and that
provides for basic operations on that data. You should reference the data
through the image object rather than referencing the data directly. However,
some implementations of the Xlib library may efficiently deal with frequently
used data formats by replacing functions in the procedure vector with special
case functions. Supported operations include destroying the image, getting a
pixel, storing a pixel, extracting a subimage of an image, and adding a
constant to an image (see section 16.8).
All the image manipulation functions discussed in this section make use of the
XImage structure, which describes an image as it exists in the client's memory.
typedef struct _XImage {
int width, height; /* size of image */
int xoffset; /* number of pixels offset in X direction */
int format; /* XYBitmap, XYPixmap, ZPixmap */
char *data; /* pointer to image data */
int byte_order; /* data byte order, LSBFirst, MSBFirst */
int bitmap_unit; /* quant. of scanline 8, 16, 32 */
int bitmap_bit_order; /* LSBFirst, MSBFirst */
int bitmap_pad; /* 8, 16, 32 either XY or ZPixmap */
int depth; /* depth of image */
int bytes_per_line; /* accelerator to next scanline */
int bits_per_pixel; /* bits per pixel (ZPixmap) */
unsigned long red_mask; /* bits in z arrangement */
unsigned long green_mask;
unsigned long blue_mask;
XPointer obdata; /* hook for the object routines to hang on */
struct funcs { /* image manipulation routines */
struct _XImage *(*create_image)();
int (*destroy_image)();
unsigned long (*get_pixel)();
int (*put_pixel)();
struct _XImage *(*sub_image)();
int (*add_pixel)();
} f;
} XImage;
To initialize the image manipulation routines of an image structure, use
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
Specify the x and y coordinates, which are relative to the origin of
dest_y 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.
Specifies the directory path used to look for a font. Setting the
directories 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).
Returns the current screen save control value (
allow_exposures_return DontAllowExposures, AllowExposures, or DefaultExposures
).
Controlling Host Access
This section discusses how to:
• Add, get, or remove hosts from the access control list
• Change, enable, or disable access
X does not provide any protection on a per-window basis. If you find out the
resource ID of a resource, you can manipulate it. To provide some minimal level
of protection, however, connections are permitted only from machines you trust.
This is adequate on single-user workstations but obviously breaks down on
timesharing machines. Although provisions exist in the X protocol for proper
connection authentication, the lack of a standard authentication server leaves
host-level access control as the only common mechanism.
The initial set of hosts allowed to open connections typically consists of:
• The host the window system is running on.
• On POSIX-conformant systems, each host listed in the /etc/X?.hosts file.
The ? indicates the number of the display. This file should consist of host
names separated by newlines. DECnet nodes must terminate in :: to
distinguish them from Internet hosts.
If a host is not in the access control list when the access control mechanism
is enabled and if the host attempts to establish a connection, the server
refuses the connection. To change the access list, the client must reside on
the same host as the server and/or must have been granted permission in the
initial authorization at connection setup.
Servers also can implement other access control policies in addition to or in
place of this host access facility. For further information about other access
control implementations, see X Window System Protocol.
Adding, Getting, or Removing Hosts
Xlib provides functions that you can use to add, get, or remove hosts from the
access control list. All the host access control functions use the XHostAddress
structure, which contains:
typedef struct {
int family; /* for example FamilyInternet */
int length; /* length of address, in bytes */
char *address; /* pointer to where to find the address */
} XHostAddress;
The family member specifies which protocol address family to use (for example,
TCP/IP or DECnet) and can be FamilyInternet, FamilyInternet6,
FamilyServerInterpreted, FamilyDECnet, or FamilyChaos. The length member
specifies the length of the address in bytes. The address member specifies a
pointer to the address.
For TCP/IP, the address should be in network byte order. For IP version 4
addresses, the family should be FamilyInternet and the length should be 4
bytes. For IP version 6 addresses, the family should be FamilyInternet6 and the
length should be 16 bytes.
For the DECnet family, the server performs no automatic swapping on the address
bytes. A Phase IV address is 2 bytes long. The first byte contains the least
significant 8 bits of the node number. The second byte contains the most
significant 2 bits of the node number in the least significant 2 bits of the
byte and the area in the most significant 6 bits of the byte.
For the ServerInterpreted family, the length is ignored and the address member
is a pointer to a XServerInterpretedAddress structure, which contains:
typedef struct {
int typelength; /* length of type string, in bytes */
int valuelength; /* length of value string, in bytes */
char *type; /* pointer to where to find the type string */
char *value; /* pointer to where to find the address */
} XServerInterpretedAddress;
The type and value members point to strings representing the type and value of
the server interpreted entry. These strings may not be NULL-terminated so care
should be used when accessing them. The typelength and valuelength members
specify the length in byte of the type and value strings.
To add a single host, use XAddHost.
XAddHost(Display *display, XHostAddress *host);
display Specifies the connection to the X server.
host Specifies the host that is to be added.
The XAddHost function adds the specified host to the access control list for
that display. The server must be on the same host as the client issuing the
command, or a BadAccess error results.
XAddHost can generate BadAccess and BadValue errors.
To add multiple hosts at one time, use XAddHosts.
XAddHosts(Display *display, XHostAddress *hosts, int num_hosts);
display Specifies the connection to the X server.
hosts Specifies each host that is to be added.
num_hosts Specifies the number of hosts.
The XAddHosts function adds each specified host to the access control list for
that display. The server must be on the same host as the client issuing the
command, or a BadAccess error results.
XAddHosts can generate BadAccess and BadValue errors.
To obtain a host list, use XListHosts.
XHostAddress *XListHosts(Display *display, int *nhosts_return, Bool
*state_return);
display Specifies the connection to the X server.
nhosts_return Returns the number of hosts currently in the access control list.
state_return Returns the state of the access control.
The XListHosts function returns the current access control list as well as
whether the use of the list at connection setup was enabled or disabled.
XListHosts allows a program to find out what machines can make connections. It
also returns a pointer to a list of host structures that were allocated by the
function. When no longer needed, this memory should be freed by calling XFree.
To remove a single host, use XRemoveHost.
XRemoveHost(Display *display, XHostAddress *host);
display Specifies the connection to the X server.
host Specifies the host that is to be removed.
The XRemoveHost function removes the specified host from the access control
list for that display. The server must be on the same host as the client
process, or a BadAccess error results. If you remove your machine from the
access list, you can no longer connect to that server, and this operation
cannot be reversed unless you reset the server.
XRemoveHost can generate BadAccess and BadValue errors.
To remove multiple hosts at one time, use XRemoveHosts.
XRemoveHosts(Display *display, XHostAddress *hosts, int num_hosts);
display Specifies the connection to the X server.
hosts Specifies each host that is to be removed.
num_hosts Specifies the number of hosts.
The XRemoveHosts function removes each specified host from the access control
list for that display. The X server must be on the same host as the client
process, or a BadAccess error results. If you remove your machine from the
access list, you can no longer connect to that server, and this operation
cannot be reversed unless you reset the server.
XRemoveHosts can generate BadAccess and BadValue errors.
Changing, Enabling, or Disabling Access Control
Xlib provides functions that you can use to enable, disable, or change access
control.
For these functions to execute successfully, the client application must reside
on the same host as the X server and/or have been given permission in the
initial authorization at connection setup.
To change access control, use XSetAccessControl.
XSetAccessControl(Display *display, int mode);
display Specifies the connection to the X server.
mode Specifies the mode. You can pass EnableAccess or DisableAccess.
The XSetAccessControl function either enables or disables the use of the access
control list at each connection setup.
XSetAccessControl can generate BadAccess and BadValue errors.
To enable access control, use XEnableAccessControl.
XEnableAccessControl(Display *display);
display Specifies the connection to the X server.
The XEnableAccessControl function enables the use of the access control list at
each connection setup.
XEnableAccessControl can generate a BadAccess error.
To disable access control, use XDisableAccessControl.
XDisableAccessControl(Display *display);
display Specifies the connection to the X server.
The XDisableAccessControl function disables the use of the access control list
at each connection setup.
XDisableAccessControl can generate a BadAccess error.
Chapter 10. Events
Table of Contents
Event Types
Event Structures
Event Masks
Event Processing Overview
Keyboard and Pointer Events
Pointer Button Events
Keyboard and Pointer Events
Window Entry/Exit Events
Normal Entry/Exit Events
Grab and Ungrab Entry/Exit Events
Input Focus Events
Normal Focus Events and Focus Events While Grabbed
Focus Events Generated by Grabs
Key Map State Notification Events
Exposure Events
Expose Events
GraphicsExpose and NoExpose Events
Window State Change Events
CirculateNotify Events
ConfigureNotify Events
CreateNotify Events
DestroyNotify Events
GravityNotify Events
MapNotify Events
MappingNotify Events
ReparentNotify Events
UnmapNotify Events
VisibilityNotify Events
Structure Control Events
CirculateRequest Events
ConfigureRequest Events
MapRequest Events
ResizeRequest Events
Colormap State Change Events
Client Communication Events
ClientMessage Events
PropertyNotify Events
SelectionClear Events
SelectionRequest Events
SelectionNotify Events
A client application communicates with the X server through the connection you
establish with the XOpenDisplay function. A client application sends requests
to the X server over this connection. These requests are made by the Xlib
functions that are called in the client application. Many Xlib functions cause
the X server to generate events, and the user’s typing or moving the pointer
can generate events asynchronously. The X server returns events to the client
on the same connection.
This chapter discusses the following topics associated with events:
• Event types
• Event structures
• Event masks
• Event processing
Functions for handling events are dealt with in the next chapter.
Event Types
An event is data generated asynchronously by the X server as a result of some
device activity or as side effects of a request sent by an Xlib function.
Device-related events propagate from the source window to ancestor windows
until some client application has selected that event type or until the event
is explicitly discarded. The X server generally sends an event to a client
application only if the client has specifically asked to be informed of that
event type, typically by setting the event-mask attribute of the window. The
mask can also be set when you create a window or by changing the window's
event-mask. You can also mask out events that would propagate to ancestor
windows by manipulating the do-not-propagate mask of the window's attributes.
However, MappingNotify events are always sent to all clients.
An event type describes a specific event generated by the X server. For each
event type, a corresponding constant name is defined in <X11/X.h>, which is
used when referring to an event type. The following table lists the event
category and its associated event type or types. The processing associated with
these events is discussed in section 10.5.
┌───────────────┬─────────────────────────────────────────────────────────────┐
│Event Category │Event Type │
├───────────────┼─────────────────────────────────────────────────────────────┤
│Keyboard events│KeyPress, KeyRelease │
├───────────────┼─────────────────────────────────────────────────────────────┤
│Pointer events │ButtonPress, ButtonRelease, MotionNotify │
├───────────────┼─────────────────────────────────────────────────────────────┤
│Window crossing│EnterNotify, LeaveNotify │
│events │ │
├───────────────┼─────────────────────────────────────────────────────────────┤
│Input focus │FocusIn, FocusOut │
│events │ │
├───────────────┼─────────────────────────────────────────────────────────────┤
│Keymap state │ │
│notification │KeymapNotify │
│event │ │
├───────────────┼─────────────────────────────────────────────────────────────┤
│Exposure events│Expose, GraphicsExpose, NoExpose │
├───────────────┼─────────────────────────────────────────────────────────────┤
│Structure │CirculateRequest, ConfigureRequest, MapRequest, ResizeRequest│
│control events │ │
├───────────────┼─────────────────────────────────────────────────────────────┤
│Window state │CirculateNotify, ConfigureNotify, CreateNotify, DestroyNotify│
│notification │, GravityNotify, MapNotify, MappingNotify, ReparentNotify, │
│events │UnmapNotify, VisibilityNotify │
├───────────────┼─────────────────────────────────────────────────────────────┤
│Colormap state │ │
│notification │ColormapNotify │
│event │ │
├───────────────┼─────────────────────────────────────────────────────────────┤
│Client │ClientMessage, PropertyNotify, SelectionClear, │
│communication │SelectionNotify, SelectionRequest │
│events │ │
└───────────────┴─────────────────────────────────────────────────────────────┘
Event Structures
For each event type, a corresponding structure is declared in <X11/Xlib.h>. All
the event structures have the following common members:
typedef struct {
int type;
unsigned long serial; /* # of last request processed by server */
Bool send_event; /* true if this came from a SendEvent request */
Display *display; /* Display the event was read from */
Window window;
} XAnyEvent;
The type member is set to the event type constant name that uniquely identifies
it. For example, when the X server reports a 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 changed */
XAnyEvent xany;
XKeyEvent xkey;
XButtonEvent xbutton;
XMotionEvent xmotion;
XCrossingEvent xcrossing;
XFocusChangeEvent xfocus;
XExposeEvent xexpose;
XGraphicsExposeEvent xgraphicsexpose;
XNoExposeEvent xnoexpose;
XVisibilityEvent xvisibility;
XCreateWindowEvent xcreatewindow;
XDestroyWindowEvent xdestroywindow;
XUnmapEvent xunmap;
XMapEvent xmap;
XMapRequestEvent xmaprequest;
XReparentEvent xreparent;
XConfigureEvent xconfigure;
XGravityEvent xgravity;
XResizeRequestEvent xresizerequest;
XConfigureRequestEvent xconfigurerequest;
XCirculateEvent xcirculate;
XCirculateRequestEvent xcirculaterequest;
XPropertyEvent xproperty;
XSelectionClearEvent xselectionclear;
XSelectionRequestEvent xselectionrequest;
XSelectionEvent xselection;
XColormapEvent xcolormap;
XClientMessageEvent xclient;
XMappingEvent xmapping;
XErrorEvent xerror;
XKeymapEvent xkeymap;
long pad[24];
} XEvent;
An XEvent structure's first entry always is the type member, which is set to
the event type. The second member always is the serial number of the protocol
request that generated the event. The third member always is send_event, which
is a Bool that indicates if the event was sent by a different client. The
fourth member always is a display, which is the display that the event was read
from. Except for keymap events, the fifth member always is a window, which has
been carefully selected to be useful to toolkit dispatchers. To avoid breaking
toolkits, the order of these first five entries is not to change. Most events
also contain a time member, which is the time at which an event occurred. In
addition, a pointer to the generic event must be cast before it is used to
access any other information in the structure.
Event Masks
Clients select event reporting of most events relative to a window. To do this,
pass an event mask to an Xlib event-handling function that takes an event_mask
argument. The bits of the event mask are defined in <X11/X.h>. Each bit in the
event mask maps to an event mask name, which describes the event or events you
want the X server to return to a client application.
Unless the client has specifically asked for them, most events are not reported
to clients when they are generated. Unless the client suppresses them by
setting graphics-exposures in the GC to False, GraphicsExpose and NoExpose are
reported by default as a result of XCopyPlane and XCopyArea. SelectionClear,
SelectionRequest, SelectionNotify, or ClientMessage cannot be masked.
Selection-related events are only sent to clients cooperating with selections
(see section 4.5). When the keyboard or pointer mapping is changed,
MappingNotify is always sent to clients.
The following table lists the event mask constants you can pass to the
event_mask argument and the circumstances in which you would want to specify
the event mask:
┌────────────────────────┬────────────────────────────────────────────────────┐
│Event Mask │Circumstances │
├────────────────────────┼────────────────────────────────────────────────────┤
│NoEventMask │No events wanted │
├────────────────────────┼────────────────────────────────────────────────────┤
│KeyPressMask │Keyboard down events wanted │
├────────────────────────┼────────────────────────────────────────────────────┤
│KeyReleaseMask │Keyboard up events wanted │
├────────────────────────┼────────────────────────────────────────────────────┤
│ButtonPressMask │Pointer button down events wanted │
├────────────────────────┼────────────────────────────────────────────────────┤
│ButtonReleaseMask │Pointer button up events wanted │
├────────────────────────┼────────────────────────────────────────────────────┤
│EnterWindowMask │Pointer window entry events wanted │
├────────────────────────┼────────────────────────────────────────────────────┤
│LeaveWindowMask │Pointer window leave events wanted │
├────────────────────────┼────────────────────────────────────────────────────┤
│PointerMotionMask │Pointer motion events wanted │
├────────────────────────┼────────────────────────────────────────────────────┤
│PointerMotionHintMask │Pointer motion hints wanted │
├────────────────────────┼────────────────────────────────────────────────────┤
│Button1MotionMask │Pointer motion while button 1 down │
├────────────────────────┼────────────────────────────────────────────────────┤
│Button2MotionMask │Pointer motion while button 2 down │
├────────────────────────┼────────────────────────────────────────────────────┤
│Button3MotionMask │Pointer motion while button 3 down │
├────────────────────────┼────────────────────────────────────────────────────┤
│Button4MotionMask │Pointer motion while button 4 down │
├────────────────────────┼────────────────────────────────────────────────────┤
│Button5MotionMask │Pointer motion while button 5 down │
├────────────────────────┼────────────────────────────────────────────────────┤
│ButtonMotionMask │Pointer motion while any button down │
├────────────────────────┼────────────────────────────────────────────────────┤
│KeymapStateMask │Keyboard state wanted at window entry and focus in │
├────────────────────────┼────────────────────────────────────────────────────┤
│ExposureMask │Any exposure wanted │
├────────────────────────┼────────────────────────────────────────────────────┤
│VisibilityChangeMask │Any change in visibility wanted │
├────────────────────────┼────────────────────────────────────────────────────┤
│StructureNotifyMask │Any change in window structure wanted │
├────────────────────────┼────────────────────────────────────────────────────┤
│ResizeRedirectMask │Redirect resize of this window │
├────────────────────────┼────────────────────────────────────────────────────┤
│SubstructureNotifyMask │Substructure notification wanted │
├────────────────────────┼────────────────────────────────────────────────────┤
│SubstructureRedirectMask│Redirect structure requests on children │
├────────────────────────┼────────────────────────────────────────────────────┤
│FocusChangeMask │Any change in input focus wanted │
├────────────────────────┼────────────────────────────────────────────────────┤
│PropertyChangeMask │Any change in property wanted │
├────────────────────────┼────────────────────────────────────────────────────┤
│ColormapChangeMask │Any change in colormap wanted │
├────────────────────────┼────────────────────────────────────────────────────┤
│OwnerGrabButtonMask │Automatic grabs should activate with owner_events │
│ │set to True │
└────────────────────────┴────────────────────────────────────────────────────┘
Event Processing Overview
The event reported to a client application during event processing depends on
which event masks you provide as the event-mask attribute for a window. For
some event masks, there is a one-to-one correspondence between the event mask
constant and the event type constant. For example, if you pass the event mask
ButtonPressMask, the X server sends back only ButtonPress events. Most events
contain a time member, which is the time at which an event occurred.
In other cases, one event mask constant can map to several event type
constants. For example, if you pass the event mask SubstructureNotifyMask, the
X server can send back CirculateNotify, ConfigureNotify, CreateNotify,
DestroyNotify, GravityNotify, MapNotify, ReparentNotify, or UnmapNotify events.
In another case, two event masks can map to one event type. For example, if you
pass either PointerMotionMask or ButtonMotionMask, the X server sends back a
MotionNotify event.
The following table lists the event mask, its associated event type or types,
and the structure name associated with the event type. Some of these structures
actually are typedefs to a generic structure that is shared between two event
types. Note that N.A. appears in columns for which the information is not
applicable.
┌────────────────────────┬────────────────┬──────────────────────┬─────────────────┐
│Event Mask │Event Type │Structure │Generic Structure│
├────────────────────────┼────────────────┼──────────────────────┼─────────────────┤
│ButtonMotionMask │ │ │ │
│ │ │ │ │
│Button1MotionMask │ │ │ │
│ │ │ │ │
│Button2MotionMask │ │ │ │
│ │MotionNotify │XPointerMovedEvent │XMotionEvent │
│Button3MotionMask │ │ │ │
│ │ │ │ │
│Button4MotionMask │ │ │ │
│ │ │ │ │
│Button5MotionMask │ │ │ │
├────────────────────────┼────────────────┼──────────────────────┼─────────────────┤
│ButtonPressMask │ButtonPress │XButtonPressedEvent │XButtonEvent │
├────────────────────────┼────────────────┼──────────────────────┼─────────────────┤
│ButtonReleaseMask │ButtonRelease │XButtonReleasedEvent │XButtonEvent │
├────────────────────────┼────────────────┼──────────────────────┼─────────────────┤
│ColormapChangeMask │ColormapNotify │XColormapEvent │ │
├────────────────────────┼────────────────┼──────────────────────┼─────────────────┤
│EnterWindowMask │EnterNotify │XEnterWindowEvent │XCrossingEvent │
├────────────────────────┼────────────────┼──────────────────────┼─────────────────┤
│LeaveWindowMask │LeaveNotify │XLeaveWindowEvent │XCrossingEvent │
├────────────────────────┼────────────────┼──────────────────────┼─────────────────┤
│ExposureMask │Expose │XExposeEvent │ │
├────────────────────────┼────────────────┼──────────────────────┼─────────────────┤
│GCGraphicsExposures in │GraphicsExpose │XGraphicsExposeEvent │ │
│GC ├────────────────┼──────────────────────┼─────────────────┤
│ │NoExpose │XNoExposeEvent │ │
├────────────────────────┼────────────────┼──────────────────────┼─────────────────┤
│ │FocusIn │XFocusInEvent │XFocusChangeEvent│
│FocusChangeMask ├────────────────┼──────────────────────┼─────────────────┤
│ │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 │ │
├────────────────────────┼────────────────┼──────────────────────┼─────────────────┤
│ │CirculateNotify │XCirculateEvent │ │
│ ├────────────────┼──────────────────────┼─────────────────┤
│ │ConfigureNotify │XConfigureEvent │ │
│ ├────────────────┼──────────────────────┼─────────────────┤
│ │DestroyNotify │XDestroyWindowEvent │ │
│ ├────────────────┼──────────────────────┼─────────────────┤
│StructureNotifyMask │GravityNotify │XGravityEvent │ │
│ ├────────────────┼──────────────────────┼─────────────────┤
│ │MapNotify │XMapEvent │ │
│ ├────────────────┼──────────────────────┼─────────────────┤
│ │ReparentNotify │XReparentEvent │ │
│ ├────────────────┼──────────────────────┼─────────────────┤
│ │UnmapNotify │XUnmapEvent │ │
├────────────────────────┼────────────────┼──────────────────────┼─────────────────┤
│ │CirculateNotify │XCirculateEvent │ │
│ ├────────────────┼──────────────────────┼─────────────────┤
│ │ConfigureNotify │XConfigureEvent │ │
│ ├────────────────┼──────────────────────┼─────────────────┤
│ │CreateNotify │XCreateWindowEvent │ │
│ ├────────────────┼──────────────────────┼─────────────────┤
│ │DestroyNotify │XDestroyWindowEvent │ │
│SubstructureNotifyMask ├────────────────┼──────────────────────┼─────────────────┤
│ │GravityNotify │XGravityEvent │ │
│ ├────────────────┼──────────────────────┼─────────────────┤
│ │MapNotify │XMapEvent │ │
│ ├────────────────┼──────────────────────┼─────────────────┤
│ │ReparentNotify │XReparentEvent │ │
│ ├────────────────┼──────────────────────┼─────────────────┤
│ │UnmapNotify │XUnmapEvent │ │
├────────────────────────┼────────────────┼──────────────────────┼─────────────────┤
│ │CirculateRequest│XCirculateRequestEvent│ │
│ ├────────────────┼──────────────────────┼─────────────────┤
│SubstructureRedirectMask│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 server */
Bool send_event; /* true if this came from a SendEvent request */
Display *display; /* Display the event was read from */
Window window; /* ``event'' window it is reported relative to */
Window root; /* root window that the event occurred on */
Window subwindow; /* child window */
Time time; /* milliseconds */
int x, y; /* pointer x, y coordinates in event window */
int x_root, y_root; /* coordinates relative to root */
unsigned int state; /* key or button mask */
unsigned int button; /* detail */
Bool same_screen; /* same screen flag */
} XButtonEvent;
typedef XButtonEvent XButtonPressedEvent;
typedef XButtonEvent XButtonReleasedEvent;
typedef struct {
int type; /* KeyPress or KeyRelease */
unsigned long serial; /* # of last request processed by server */
Bool send_event; /* true if this came from a SendEvent request */
Display *display; /* Display the event was read from */
Window window; /* ``event'' window it is reported relative to */
Window root; /* root window that the event occurred on */
Window subwindow; /* child window */
Time time; /* milliseconds */
int x, y; /* pointer x, y coordinates in event window */
int x_root, y_root; /* coordinates relative to root */
unsigned int state; /* key or button mask */
unsigned int keycode; /* detail */
Bool same_screen; /* same screen flag */
} XKeyEvent;
typedef XKeyEvent XKeyPressedEvent;
typedef XKeyEvent XKeyReleasedEvent;
typedef struct {
int type; /* MotionNotify */
unsigned long serial; /* # of last request processed by server */
Bool send_event; /* true if this came from a SendEvent request */
Display *display; /* Display the event was read from */
Window window; /* ``event'' window reported relative to */
Window root; /* root window that the event occurred on */
Window subwindow; /* child window */
Time time; /* milliseconds */
int x, y; /* pointer x, y coordinates in event window */
int x_root, y_root; /* coordinates relative to root */
unsigned int state; /* key or button mask */
char is_hint; /* detail */
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 server */
Bool send_event; /* true if this came from a SendEvent request */
Display *display; /* Display the event was read from */
Window window; /* ``event'' window reported relative to */
Window root; /* root window that the event occurred on */
Window subwindow; /* child window */
Time time; /* milliseconds */
int x, y; /* pointer x, y coordinates in event window */
int x_root, y_root; /* coordinates relative to root */
int mode; /* NotifyNormal, NotifyGrab, NotifyUngrab */
int detail;
/*
* NotifyAncestor, NotifyVirtual, NotifyInferior,
* NotifyNonlinear,NotifyNonlinearVirtual
*/
Bool same_screen; /* same screen flag */
Bool focus; /* boolean focus */
unsigned int state; /* key or button mask */
} XCrossingEvent;
typedef XCrossingEvent XEnterWindowEvent;
typedef XCrossingEvent XLeaveWindowEvent;
The window member is set to the window on which the 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 request */
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, NotifyPointer,
* 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 server */
Bool send_event; /* true if this came from a SendEvent 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 server */
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 more */
} 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 server */
Bool send_event; /* true if this came from a SendEvent 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 more */
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 server */
Bool send_event; /* true if this came from a SendEvent request */
Display *display; /* Display the event was read from */
Drawable drawable;
int major_code; /* core is CopyArea or CopyPlane */
int minor_code; /* not defined in the core */
} XNoExposeEvent;
Both structures have these common members: drawable, major_code, and
minor_code. The drawable member is set to the drawable of the destination
region on which the graphics request was to be performed. The major_code member
is set to the graphics request initiated by the client and can be either
X_CopyArea or X_CopyPlane. If it is X_CopyArea, a call to XCopyArea initiated
the request. If it is X_CopyPlane, a call to XCopyPlane initiated the request.
These constants are defined in <X11/Xproto.h>. The minor_code member, like the
major_code member, indicates which graphics request was initiated by the
client. However, the minor_code member is not defined by the core X protocol
and will be zero in these cases, although it may be used by an extension.
The XGraphicsExposeEvent structure has these additional members: x, y, width,
height, and count. The x and y members are set to the coordinates relative to
the drawable's origin and indicate the upper-left corner of the rectangle. The
width and height members are set to the size (extent) of the rectangle. The
count member is set to the number of GraphicsExpose events to follow. If count
is zero, no more GraphicsExpose events follow for this window. However, if
count is nonzero, at least that number of GraphicsExpose events (and possibly
more) are to follow for this window.
Window State Change Events
The following sections discuss:
• CirculateNotify events
• ConfigureNotify events
• CreateNotify events
• DestroyNotify events
• GravityNotify events
• MapNotify events
• MappingNotify events
• ReparentNotify events
• UnmapNotify events
• VisibilityNotify events
CirculateNotify Events
The X server can report CirculateNotify events to clients wanting information
about when a window changes its position in the stack. The X server generates
this event type whenever a window is actually restacked as a result of a client
application calling XCirculateSubwindows, XCirculateSubwindowsUp, or
XCirculateSubwindowsDown.
To receive CirculateNotify events, set the StructureNotifyMask bit in the
event-mask attribute of the window or the SubstructureNotifyMask bit in the
event-mask attribute of the parent window (in which case, circulating any child
generates an event).
The structure for this event type contains:
typedef struct {
int type; /* CirculateNotify */
unsigned long serial; /* # of last request processed by server */
Bool send_event; /* true if this came from a SendEvent request */
Display *display; /* Display the event was read from */
Window event;
Window window;
int place; /* PlaceOnTop, PlaceOnBottom */
} XCirculateEvent;
The event member is set either to the restacked window or to its parent,
depending on whether StructureNotify or SubstructureNotify was selected. The
window member is set to the window that was restacked. The place member is set
to the window's position after the restack occurs and is either PlaceOnTop or
PlaceOnBottom. If it is PlaceOnTop, the window is now on top of all siblings.
If it is PlaceOnBottom, the window is now below all siblings.
ConfigureNotify Events
The X server can report ConfigureNotify events to clients wanting information
about actual changes to a window's state, such as size, position, border, and
stacking order. The X server generates this event type whenever one of the
following configure window requests made by a client application actually
completes:
• A window's size, position, border, and/or stacking order is reconfigured by
calling XConfigureWindow.
• The window's position in the stacking order is changed by calling
XLowerWindow, XRaiseWindow, or XRestackWindows.
• A window is moved by calling XMoveWindow.
• A window's size is changed by calling XResizeWindow.
• A window's size and location is changed by calling XMoveResizeWindow.
• A window is mapped and its position in the stacking order is changed by
calling XMapRaised.
• A window's border width is changed by calling XSetWindowBorderWidth.
To receive ConfigureNotify events, set the StructureNotifyMask bit in the
event-mask attribute of the window or the SubstructureNotifyMask bit in the
event-mask attribute of the parent window (in which case, configuring any child
generates an event).
The structure for this event type contains:
typedef struct {
int type; /* ConfigureNotify */
unsigned long serial; /* # of last request processed by server */
Bool send_event; /* true if this came from a SendEvent request */
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 SendEvent request */
Display *display; /* Display the event was read from */
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 request */
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 request */
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 SendEvent 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 server */
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, MappingKeyboard,
MappingPointer */
int first_keycode; /* first keycode */
int count; /* defines range of change w. first_keycode*/
} 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 request */
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 request */
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 request */
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 request */
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 server */
Bool send_event; /* true if this came from a SendEvent request */
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, Opposite */
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 request */
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 request */
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 request */
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 server */
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 request */
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 request */
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 request */
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 request */
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
Specify the time interval in which the events are returned from
stop 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 request */
unsigned char error_code; /* error code of failed request */
unsigned char request_code; /* Major op-code of failed request */
unsigned char minor_code; /* Minor op-code of failed request */
XID resourceid; /* resource id */
} XErrorEvent;
The serial member is the number of requests, starting from one, sent over the
network connection since it was opened. It is the number that was the value of
NextRequest immediately before the failing call was made. The request_code
member is a protocol request of the procedure that failed, as defined in <X11/
Xproto.h>. The following error codes can be returned by the functions described
in this chapter:
┌─────────────────┬───────────────────────────────────────────────────────────┐
│Error Code │Description │
├─────────────────┼───────────────────────────────────────────────────────────┤
│ │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. │
│ │ │
│BadAccess │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. │
├─────────────────┼───────────────────────────────────────────────────────────┤
│ │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 │
│BadAlloc │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. │
├─────────────────┼───────────────────────────────────────────────────────────┤
│ │The value chosen for a resource identifier either is not │
│BadIDChoice │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. │
├─────────────────┼───────────────────────────────────────────────────────────┤
│ │The server does not implement some aspect of the request. A│
│ │server that generates this error for a core request is │
│BadImplementation│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. │
├─────────────────┼───────────────────────────────────────────────────────────┤
│ │The length of a request is shorter or longer than that │
│ │required to contain the arguments. This is an internal Xlib│
│BadLength │or server error. │
│ │ │
│ │The length of a request exceeds the maximum length accepted│
│ │by the server. │
├─────────────────┼───────────────────────────────────────────────────────────┤
│ │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. │
│BadMatch │ │
│ │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. │
├─────────────────┼───────────────────────────────────────────────────────────┤
│ │Some numeric value falls outside of the range of values │
│ │accepted by the request. Unless a specific range is │
│BadValue │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.
For a core protocol request, the major request protocol number is
used for the message argument. For an extension request, the
XRequest 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.
Specifies a Boolean value that indicates whether the pointer
owner_events events are to be reported as usual or reported with respect to
the grab window if selected by the event mask.
Specifies which pointer events are reported to the client. The
event_mask 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.
Specifies a Boolean value that indicates whether the pointer
owner_events events are to be reported as usual or reported with respect to
the grab window if selected by the event mask.
Specifies which pointer events are reported to the client. The
event_mask 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.
Specifies the event mode. You can pass AsyncPointer, SyncPointer,
event_mode 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:
If the pointer is frozen by the client, pointer event processing
continues as usual. If the pointer is frozen twice by the client
AsyncPointer 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.
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
SyncPointer 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.
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
ReplayPointer ), 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.
If the keyboard is frozen by the client, keyboard event
processing continues as usual. If the keyboard is frozen twice
AsyncKeyboard 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.
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
SyncKeyboard 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.
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
ReplayKeyboard 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.
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
SyncBoth 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).
If the pointer and the keyboard are frozen by the client, event
processing for both devices continues as usual. If a device is
AsyncBoth 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.
Specifies where the input focus reverts to if the window becomes not
revert_to viewable. You can pass RevertToParent, RevertToPointerRoot, or
RevertToNone.
time Specifies the time. You can pass either a timestamp or CurrentTime.
The XSetInputFocus function changes the input focus and the last-focus-change
time. It has no effect if the specified time is earlier than the current
last-focus-change time or is later than the current X server time. Otherwise,
the last-focus-change time is set to the specified time (CurrentTime is
replaced by the current X server time). XSetInputFocus causes the X server to
generate FocusIn and FocusOut events.
Depending on the focus argument, the following occurs:
• If focus is None, all keyboard events are discarded until a new focus
window is set, and the revert_to argument is ignored.
• If focus is a window, it becomes the keyboard's focus window. If a
generated keyboard event would normally be reported to this window or one
of its inferiors, the event is reported as usual. Otherwise, the event is
reported relative to the focus window.
• If focus is PointerRoot, the focus window is dynamically taken to be the
root window of whatever screen the pointer is on at each keyboard event. In
this case, the revert_to argument is ignored.
The specified focus window must be viewable at the time XSetInputFocus is
called, or a BadMatch error results. If the focus window later becomes not
viewable, the X server evaluates the revert_to argument to determine the new
focus window as follows:
• If revert_to is RevertToParent, the focus reverts to the parent (or the
closest viewable ancestor), and the new revert_to value is taken to be
RevertToNone.
• If revert_to is RevertToPointerRoot or RevertToNone, the focus reverts to
PointerRoot or None, respectively. When the focus reverts, the X server
generates FocusIn and FocusOut events, but the last-focus-change time is
not affected.
XSetInputFocus can generate BadMatch, BadValue, and BadWindow errors.
To obtain the current input focus, use XGetInputFocus.
XGetInputFocus(Display *display, Window *focus_return, int *revert_to_return);
display Specifies the connection to the X server.
focus_return Returns the focus window, PointerRoot, or None.
revert_to_return Returns the current focus state (RevertToParent,
RevertToPointerRoot, or RevertToNone).
The XGetInputFocus function returns the focus window and the current focus
state.
Manipulating the Keyboard and Pointer Settings
Xlib provides functions that you can use to change the keyboard control, obtain
a list of the auto-repeat keys, turn keyboard auto-repeat on or off, ring the
bell, set or obtain the pointer button or keyboard mapping, and obtain a bit
vector for the keyboard.
This section discusses the user-preference options of bell, key click, pointer
behavior, and so on. The default values for many of these options are server
dependent. Not all implementations will actually be able to control all of
these parameters.
The XChangeKeyboardControl function changes control of a keyboard and operates
on a XKeyboardControl structure:
/* Mask bits for ChangeKeyboardControl */
#define KBBellPercent (1L<<0)
#define KBBellPitch (1L<<1)
#define KBBellDuration (1L<<2)
#define KBLed (1L<<3)
#define KBLedMode (1L<<4)
#define KBKey (1L<<5)
#define KBAutoRepeatMode (1L<<6)
/* Values */
typedef struct {
int key_click_percent;
int bell_percent;
int bell_pitch;
int bell_duration;
int led;
int led_mode; /* LedModeOn, LedModeOff */
int key;
int auto_repeat_mode; /* AutoRepeatModeOff, AutoRepeatModeOn,
AutoRepeatModeDefault */
} XKeyboardControl;
The key_click_percent member sets the volume for key clicks between 0 (off) and
100 (loud) inclusive, if possible. A setting of -1 restores the default. Other
negative values generate a BadValue error.
The bell_percent sets the base volume for the bell between 0 (off) and 100
(loud) inclusive, if possible. A setting of -1 restores the default. Other
negative values generate a BadValue error. The bell_pitch member sets the pitch
(specified in Hz) of the bell, if possible. A setting of -1 restores the
default. Other negative values generate a BadValue error. The bell_duration
member sets the duration of the bell specified in milliseconds, if possible. A
setting of -1 restores the default. Other negative values generate a BadValue
error.
If both the led_mode and led members are specified, the state of that LED is
changed, if possible. The led_mode member can be set to LedModeOn or LedModeOff
. If only led_mode is specified, the state of all LEDs are changed, if
possible. At most 32 LEDs numbered from one are supported. No standard
interpretation of LEDs is defined. If led is specified without led_mode, a
BadMatch error results.
If both the auto_repeat_mode and key members are specified, the
auto_repeat_mode of that key is changed (according to AutoRepeatModeOn,
AutoRepeatModeOff, or AutoRepeatModeDefault), if possible. If only
auto_repeat_mode is specified, the global auto_repeat_mode for the entire
keyboard is changed, if possible, and does not affect the per-key settings. If
a key is specified without an auto_repeat_mode, a BadMatch error results. Each
key has an individual mode of whether or not it should auto-repeat and a
default setting for the mode. In addition, there is a global mode of whether
auto-repeat should be enabled or not and a default setting for that mode. When
global mode is AutoRepeatModeOn, keys should obey their individual auto-repeat
modes. When global mode is AutoRepeatModeOff, no keys should auto-repeat. An
auto-repeating key generates alternating KeyPress and KeyRelease events. When a
key is used as a modifier, it is desirable for the key not to auto-repeat,
regardless of its auto-repeat setting.
A bell generator connected with the console but not directly on a keyboard is
treated as if it were part of the keyboard. The order in which controls are
verified and altered is server-dependent. If an error is generated, a subset of
the controls may have been altered.
XChangeKeyboardControl(Display *display, unsigned long value_mask,
XKeyboardControl *values);
display Specifies the connection to the X server.
value_mask Specifies which controls to change. This mask is the bitwise
inclusive OR of the valid control mask bits.
values Specifies one value for each bit set to 1 in the mask.
The XChangeKeyboardControl function controls the keyboard characteristics
defined by the XKeyboardControl structure. The value_mask argument specifies
which values are to be changed.
XChangeKeyboardControl can generate BadMatch and BadValue errors.
To obtain the current control values for the keyboard, use XGetKeyboardControl.
XGetKeyboardControl(Display *display, XKeyboardState *values_return);
display Specifies the connection to the X server.
values_return Returns the current keyboard controls in the specified
XKeyboardState structure.
The XGetKeyboardControl function returns the current control values for the
keyboard to the XKeyboardState structure.
typedef struct {
int key_click_percent;
int bell_percent;
unsigned int bell_pitch, bell_duration;
unsigned long led_mask;
int global_auto_repeat;
char auto_repeats[32];
} XKeyboardState;
For the LEDs, the least significant bit of led_mask corresponds to LED one, and
each bit set to 1 in led_mask indicates an LED that is lit. The
global_auto_repeat member can be set to AutoRepeatModeOn or AutoRepeatModeOff.
The auto_repeats member is a bit vector. Each bit set to 1 indicates that
auto-repeat is enabled for the corresponding key. The vector is represented as
32 bytes. Byte N (from 0) contains the bits for keys 8N to 8N + 7 with the
least significant bit in the byte representing key 8N.
To turn on keyboard auto-repeat, use XAutoRepeatOn.
XAutoRepeatOn(Display *display);
display Specifies the connection to the X server.
The XAutoRepeatOn function turns on auto-repeat for the keyboard on the
specified display.
To turn off keyboard auto-repeat, use XAutoRepeatOff.
XAutoRepeatOff(Display *display);
display Specifies the connection to the X server.
The XAutoRepeatOff function turns off auto-repeat for the keyboard on the
specified display.
To ring the bell, use XBell.
XBell(Display *display, int percent);
display Specifies the connection to the X server.
percent Specifies the volume for the bell, which can range from -100 to 100
inclusive.
The XBell function rings the bell on the keyboard on the specified display, if
possible. The specified volume is relative to the base volume for the keyboard.
If the value for the percent argument is not in the range -100 to 100
inclusive, a BadValue error results. The volume at which the bell rings when
the percent argument is nonnegative is:
• base - [(base * percent) / 100] + percent
The volume at which the bell rings when the percent argument is negative is:
• base + [(base * percent) / 100]
To change the base volume of the bell, use XChangeKeyboardControl.
XBell can generate a BadValue error.
To obtain a bit vector that describes the state of the keyboard, use
XQueryKeymap.
XQueryKeymap(Display *display, char keys_return[32]);
display Specifies the connection to the X server.
keys_return Returns an array of bytes that identifies which keys are pressed
down. Each bit represents one key of the keyboard.
The XQueryKeymap function returns a bit vector for the logical state of the
keyboard, where each bit set to 1 indicates that the corresponding key is
currently pressed down. The vector is represented as 32 bytes. Byte N (from 0)
contains the bits for keys 8N to 8N + 7 with the least significant bit in the
byte representing key 8N.
Note that the logical state of a device (as seen by client applications) may
lag the physical state if device event processing is frozen.
To set the mapping of the pointer buttons, use XSetPointerMapping.
int XSetPointerMapping(Display *display, unsignedchar map[], int nmap);
display Specifies the connection to the X server.
map Specifies the mapping list.
nmap Specifies the number of items in the mapping list.
The XSetPointerMapping function sets the mapping of the pointer. If it
succeeds, the X server generates a MappingNotify event, and XSetPointerMapping
returns MappingSuccess. Element map[i] defines the logical button number for
the physical button i+1. The length of the list must be the same as
XGetPointerMapping would return, or a BadValue error results. A zero element
disables a button, and elements are not restricted in value by the number of
physical buttons. However, no two elements can have the same nonzero value, or
a BadValue error results. If any of the buttons to be altered are logically in
the down state, XSetPointerMapping returns MappingBusy, and the mapping is not
changed.
XSetPointerMapping can generate a BadValue error.
To get the pointer mapping, use XGetPointerMapping.
int XGetPointerMapping(Display *display, unsignedchar map_return[], int nmap);
display Specifies the connection to the X server.
map_return Returns the mapping list.
nmap Specifies the number of items in the mapping list.
The XGetPointerMapping function returns the current mapping of the pointer.
Pointer buttons are numbered starting from one. XGetPointerMapping returns the
number of physical buttons actually on the pointer. The nominal mapping for a
pointer is map[i]=i+1. The nmap argument specifies the length of the array
where the pointer mapping is returned, and only the first nmap elements are
returned in map_return.
To control the pointer's interactive feel, use XChangePointerControl.
XChangePointerControl(Display *display, Bool do_accel, Bool do_threshold, int
accel_numerator, int accel_denominator, int threshold);
display Specifies the connection to the X server.
do_accel Specifies a Boolean value that controls whether the values
for the accel_numerator or accel_denominator are used.
do_threshold Specifies a Boolean value that controls whether the value for
the threshold is used.
accel_numerator Specifies the numerator for the acceleration multiplier.
accel_denominator Specifies the denominator for the acceleration multiplier.
threshold Specifies the acceleration threshold.
The XChangePointerControl function defines how the pointing device moves. The
acceleration, expressed as a fraction, is a multiplier for movement. For
example, specifying 3/1 means the pointer moves three times as fast as normal.
The fraction may be rounded arbitrarily by the X server. Acceleration only
takes effect if the pointer moves more than threshold pixels at once and only
applies to the amount beyond the value in the threshold argument. Setting a
value to -1 restores the default. The values of the do_accel and do_threshold
arguments must be True for the pointer values to be set, or the parameters are
unchanged. Negative values (other than -1) generate a BadValue error, as does a
zero value for the accel_denominator argument.
XChangePointerControl can generate a BadValue error.
To get the current pointer parameters, use XGetPointerControl.
XGetPointerControl(Display *display, int *accel_numerator_return, int
*accel_denominator_return, int *threshold_return);
display Specifies the connection to the X server.
accel_numerator_return Returns the numerator for the acceleration multiplier.
accel_denominator_return Returns the denominator for the acceleration
multiplier.
threshold_return Returns the acceleration threshold.
The XGetPointerControl function returns the pointer's current acceleration
multiplier and acceleration threshold.
Manipulating the Keyboard Encoding
A KeyCode represents a physical (or logical) key. KeyCodes lie in the inclusive
range [8,255]. A KeyCode value carries no intrinsic information, although
server implementors may attempt to encode geometry (for example, matrix)
information in some fashion so that it can be interpreted in a server-dependent
fashion. The mapping between keys and KeyCodes cannot be changed.
A KeySym is an encoding of a symbol on the cap of a key. The set of defined
KeySyms includes the ISO Latin character sets (1-4), Katakana, Arabic,
Cyrillic, Greek, Technical, Special, Publishing, APL, Hebrew, Thai, Korean and
a miscellany of keys found on keyboards (Return, Help, Tab, and so on). To the
extent possible, these sets are derived from international standards. In areas
where no standards exist, some of these sets are derived from Digital Equipment
Corporation standards. The list of defined symbols can be found in <X11/
keysymdef.h>. Unfortunately, some C preprocessors have limits on the number of
defined symbols. If you must use KeySyms not in the Latin 1-4, Greek, and
miscellaneous classes, you may have to define a symbol for those sets. Most
applications usually only include <X11/keysym.h>, which defines symbols for ISO
Latin 1-4, Greek, and miscellaneous.
A list of KeySyms is associated with each KeyCode. The list is intended to
convey the set of symbols on the corresponding key. If the list (ignoring
trailing NoSymbol entries) is a single KeySym ``K'', then the list is treated
as if it were the list ``K NoSymbol K NoSymbol''. If the list (ignoring
trailing NoSymbol entries) is a pair of KeySyms ``K1 K2'', then the list is
treated as if it were the list ``K1 K2 K1 K2''. If the list (ignoring trailing
NoSymbol entries) is a triple of KeySyms ``K1 K2 K3'', then the list is treated
as if it were the list ``K1 K2 K3 NoSymbol''. When an explicit ``void'' element
is desired in the list, the value VoidSymbol can be used.
The first four elements of the list are split into two groups of KeySyms. Group
1 contains the first and second KeySyms; Group 2 contains the third and fourth
KeySyms. Within each group, if the second element of the group is NoSymbol,
then the group should be treated as if the second element were the same as the
first element, except when the first element is an alphabetic KeySym ``K'' for
which both lowercase and uppercase forms are defined. In that case, the group
should be treated as if the first element were the lowercase form of ``K'' and
the second element were the uppercase form of ``K''.
The standard rules for obtaining a KeySym from a KeyPress event make use of
only the Group 1 and Group 2 KeySyms; no interpretation of other KeySyms in the
list is given. Which group to use is determined by the modifier state.
Switching between groups is controlled by the KeySym named MODE SWITCH, by
attaching that KeySym to some KeyCode and attaching that KeyCode to any one of
the modifiers Mod1 through Mod5. This modifier is called the group modifier.
For any KeyCode, Group 1 is used when the group modifier is off, and Group 2 is
used when the group modifier is on.
The Lock modifier is interpreted as CapsLock when the KeySym named XK_Caps_Lock
is attached to some KeyCode and that KeyCode is attached to the Lock modifier.
The Lock modifier is interpreted as ShiftLock when the KeySym named
XK_Shift_Lock is attached to some KeyCode and that KeyCode is attached to the
Lock modifier. If the Lock modifier could be interpreted as both CapsLock and
ShiftLock, the CapsLock interpretation is used.
The operation of keypad keys is controlled by the KeySym named XK_Num_Lock, by
attaching that KeySym to some KeyCode and attaching that KeyCode to any one of
the modifiers Mod1 through Mod5. This modifier is called the numlock modifier.
The standard KeySyms with the prefix ``XK_KP_'' in their name are called keypad
KeySyms; these are KeySyms with numeric value in the hexadecimal range 0xFF80
to 0xFFBD inclusive. In addition, vendor-specific KeySyms in the hexadecimal
range 0x11000000 to 0x1100FFFF are also keypad KeySyms.
Within a group, the choice of KeySym is determined by applying the first rule
that is satisfied from the following list:
• The numlock modifier is on and the second KeySym is a keypad KeySym. In
this case, if the Shift modifier is on, or if the Lock modifier is on and
is interpreted as ShiftLock, then the first KeySym is used, otherwise the
second KeySym is used.
• The Shift and Lock modifiers are both off. In this case, the first KeySym
is used.
• The Shift modifier is off, and the Lock modifier is on and is interpreted
as CapsLock. In this case, the first KeySym is used, but if that KeySym is
lowercase alphabetic, then the corresponding uppercase KeySym is used
instead.
• The Shift modifier is on, and the Lock modifier is on and is interpreted as
CapsLock. In this case, the second KeySym is used, but if that KeySym is
lowercase alphabetic, then the corresponding uppercase KeySym is used
instead.
• The Shift modifier is on, or the Lock modifier is on and is interpreted as
ShiftLock, or both. In this case, the second KeySym is used.
No spatial geometry of the symbols on the key is defined by their order in the
KeySym list, although a geometry might be defined on a server-specific basis.
The X server does not use the mapping between KeyCodes and KeySyms. Rather, it
merely stores it for reading and writing by clients.
To obtain the legal KeyCodes for a display, use XDisplayKeycodes.
XDisplayKeycodes(Display *display, int *min_keycodes_return, int
*max_keycodes_return);
display Specifies the connection to the X server.
min_keycodes_return Returns the minimum number of KeyCodes.
max_keycodes_return Returns the maximum number of KeyCodes.
The XDisplayKeycodes function returns the min-keycodes and max-keycodes
supported by the specified display. The minimum number of KeyCodes returned is
never less than 8, and the maximum number of KeyCodes returned is never greater
than 255. Not all KeyCodes in this range are required to have corresponding
keys.
To obtain the symbols for the specified KeyCodes, use XGetKeyboardMapping.
KeySym *XGetKeyboardMapping(Display *display, KeyCode first_keycode, int
keycode_count, int *keysyms_per_keycode_return);
display Specifies the connection to the X server.
first_keycode Specifies the first KeyCode that is to be returned.
keycode_count Specifies the number of KeyCodes that are to be
returned.
keysyms_per_keycode_return Returns the number of KeySyms per KeyCode.
The XGetKeyboardMapping function returns the symbols for the specified number
of KeyCodes starting with first_keycode. The value specified in first_keycode
must be greater than or equal to min_keycode as returned by XDisplayKeycodes,
or a BadValue error results. In addition, the following expression must be less
than or equal to max_keycode as returned by XDisplayKeycodes:
first_keycode + keycode_count - 1
If this is not the case, a BadValue error results. The number of elements in
the KeySyms list is:
keycode_count * keysyms_per_keycode_return
KeySym number N, counting from zero, for KeyCode K has the following index in
the list, counting from zero:
(K - first_code) * keysyms_per_code_return + N
The X server arbitrarily chooses the keysyms_per_keycode_return value to be
large enough to report all requested symbols. A special KeySym value of
NoSymbol is used to fill in unused elements for individual KeyCodes. To free
the storage returned by XGetKeyboardMapping, use XFree.
XGetKeyboardMapping can generate a BadValue error.
To change the keyboard mapping, use XChangeKeyboardMapping.
XChangeKeyboardMapping(Display *display, int first_keycode, int
keysyms_per_keycode, KeySym *keysyms, int num_codes);
display Specifies the connection to the X server.
first_keycode Specifies the first KeyCode that is to be changed.
keysyms_per_keycode Specifies the number of KeySyms per KeyCode.
keysyms Specifies an array of KeySyms.
num_codes Specifies the number of KeyCodes that are to be changed.
The XChangeKeyboardMapping function defines the symbols for the specified
number of KeyCodes starting with first_keycode. The symbols for KeyCodes
outside this range remain unchanged. The number of elements in keysyms must be:
num_codes * keysyms_per_keycode
The specified first_keycode must be greater than or equal to min_keycode
returned by XDisplayKeycodes, or a BadValue error results. In addition, the
following expression must be less than or equal to max_keycode as returned by
XDisplayKeycodes, or a BadValue error results:
first_keycode + num_codes - 1
KeySym number N, counting from zero, for KeyCode K has the following index in
keysyms, counting from zero:
(K - first_keycode) * keysyms_per_keycode + N
The specified keysyms_per_keycode can be chosen arbitrarily by the client to be
large enough to hold all desired symbols. A special KeySym value of NoSymbol
should be used to fill in unused elements for individual KeyCodes. It is legal
for NoSymbol to appear in nontrailing positions of the effective list for a
KeyCode. XChangeKeyboardMapping generates a MappingNotify event.
There is no requirement that the X server interpret this mapping. It is merely
stored for reading and writing by clients.
XChangeKeyboardMapping can generate BadAlloc and BadValue errors.
The next six functions make use of the XModifierKeymap data structure, which
contains:
typedef struct {
int max_keypermod; /* This server's max number of keys per modifier */
KeyCode *modifiermap; /* An 8 by max_keypermod array of the modifiers */
} 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
• 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: │
├───────────┬────────────────────────────────┬────────────────────────────────┤
│ │XSupportsLocale │Locale queried │
│setlocale ├────────────────────────────────┼────────────────────────────────┤
│ │XSetLocaleModifiers │Locale modified │
├───────────┴────────────────────────────────┴────────────────────────────────┤
│Resources: │
├───────────┬────────────────────────────────┬────────────────────────────────┤
│ │XrmGetFileDatabase │ │
│setlocale │ │Locale of XrmDatabase │
│ │XrmGetStringDatabase │ │
├───────────┼────────────────────────────────┼────────────────────────────────┤
│ │XrmPutFileDatabase │ │
│XrmDatabase│ │Locale of XrmDatabase │
│ │XrmLocaleOfDatabase │ │
├───────────┴────────────────────────────────┴────────────────────────────────┤
│Setting Standard Properties: │
├───────────┬────────────────────────────────┬────────────────────────────────┤
│ │ │Encoding of supplied/returned │
│setlocale │XmbSetWMProperties │text (some WM_ property text in │
│ │ │environment locale) │
├───────────┼────────────────────────────────┼────────────────────────────────┤
│ │XmbTextPropertyToTextList │ │
│ │ │ │
│ │XwcTextPropertyToTextList │Encoding of supplied/returned │
│setlocale │ │text │
│ │XmbTextListToTextProperty │ │
│ │ │ │
│ │XwcTextListToTextProperty │ │
├───────────┴────────────────────────────────┴────────────────────────────────┤
│Text Input: │
├───────────┬────────────────────────────────┬────────────────────────────────┤
│ │XOpenIM │XIM input method selection │
│ ├────────────────────────────────┼────────────────────────────────┤
│setlocale │XRegisterIMInstantiateCallback │XIM selection │
│ ├────────────────────────────────┼────────────────────────────────┤
│ │XUnregisterIMInstantiateCallback│XIM selection │
├───────────┼────────────────────────────────┼────────────────────────────────┤
│ │XCreateIC │XIC input method configuration │
│XIM ├────────────────────────────────┼────────────────────────────────┤
│ │XLocaleOfIM, and so on │Queried locale │
├───────────┼────────────────────────────────┼────────────────────────────────┤
│ │XmbLookupString │Keyboard layout │
│XIC ├────────────────────────────────┼────────────────────────────────┤
│ │XwcLookupString │Encoding of returned text │
├───────────┴────────────────────────────────┴────────────────────────────────┤
│Text Drawing: │
├───────────┬────────────────────────────────┬────────────────────────────────┤
│ │XOpenOM │XOM output method selection │
│setlocale ├────────────────────────────────┼────────────────────────────────┤
│ │XCreateFontSet │Charsets of fonts in XFontSet │
├───────────┼────────────────────────────────┼────────────────────────────────┤
│ │XCreateOC │XOC output method configuration │
│XOM ├────────────────────────────────┼────────────────────────────────┤
│ │XLocaleOfOM, and so on │Queried locale │
├───────────┼────────────────────────────────┼────────────────────────────────┤
│ │XmbDrawText, │Locale of supplied text │
│ ├────────────────────────────────┼────────────────────────────────┤
│ │XwcDrawText, and so on │Locale of supplied text │
│ ├────────────────────────────────┼────────────────────────────────┤
│XFontSet │XExtentsOfFontSet, and so on │ │
│ │ │ │
│ │XmbTextExtents, │Locale-dependent metrics │
│ │ │ │
│ │XwcTextExtents, and so on │ │
├───────────┴────────────────────────────────┴────────────────────────────────┤
│Xlib Errors: │
├───────────┬────────────────────────────────┬────────────────────────────────┤
│ │XGetErrorDatabaseText, │ │
│setlocale │ │Locale of error message │
│ │XGetErrorText, and so on │ │
└───────────┴────────────────────────────────┴────────────────────────────────┘
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.
Specifies the size of ink_array_return and
array_size 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, similar 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:
This function allows clients to register a
XRegisterIMInstantiateCallback 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.
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
XSetIMValues, XSetICValues 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.
If chosen, the input method would require the client to
XIMPreeditArea provide some area values for it to do its preediting. Refer
to XIC values XNArea and XNAreaNeeded.
If chosen, the input method would require the client to
XIMPreeditPosition provide positional values. Refer to XIC values
XNSpotLocation and XNFocusWindow.
If chosen, the input method would require the client to
XIMPreeditCallbacks 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.
The input method does not provide any preedit feedback. Any
XIMPreeditNone 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.
The input method requires the client to provide some area
XIMStatusArea values for it to do its status feedback. See XNArea and
XNAreaNeeded.
The input method requires the client to define the set of
XIMStatusCallbacks status callbacks, XNStatusStartCallback,
XNStatusDoneCallback, and XNStatusDrawCallback.
XIMStatusNothing The input method can function without any status values.
The input method does not provide any status feedback. If
XIMStatusNone 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 │Preedit │Preedit │Input Style │Preedit │Preedit│
│ │Management│Callback│Position│Preedit Area │Nothing │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 │ │Ignored │Ignored │D-S-G │Ignored │Ignored│
│Callback │ │ │ │ │ │ │
├────────────────┼──────────┼────────┼────────┼─────────────┼────────┼───────┤
│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 │ │S-G │S-G │S-G │S-G │S-G │
│Callback │ │ │ │ │ │ │
├────────────────┼──────────┼────────┼────────┼─────────────┼────────┼───────┤
│String │ │D-S-G │D-S-G │D-S-G │D-S-G │D-S-G │
│Conversion │ │ │ │ │ │ │
├────────────────┼──────────┼────────┼────────┼─────────────┼────────┼───────┤
│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 │ │Ignored │D-S-G │D-S-G │D-S-G │Ignored│
│Pixmap │ │ │ │ │ │ │
├────────────────┼──────────┼────────┼────────┼─────────────┼────────┼───────┤
│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 │ │S-G │S-G │S-G │S-G │Ignored│
│Notify Callback │ │ │ │ │ │ │
├────────────────┼──────────┼────────┼────────┼─────────────┼────────┼───────┤
│Preedit │ │C-S-G │Ignored │Ignored │Ignored │Ignored│
│Callbacks │ │ │ │ │ │ │
└────────────────┴──────────┴────────┴────────┴─────────────┴────────┴───────┘
┌──────────────┬────────────────┬────────────┬─────────┬────────────┬─────────┐
│XIC Value │Geomentry │Status │Status │Status │Status │
│ │Management │Callback │Area │Nothing │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 │ │Ignored │D-S-G │Ignored │Ignored │
│Callback │ │ │ │ │ │
├──────────────┼────────────────┼────────────┼─────────┼────────────┼─────────┤
│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 │ │Ignored │D-S-G │D-S-G │Ignored │
│Pixmap │ │ │ │ │ │
├──────────────┼────────────────┼────────────┼─────────┼────────────┼─────────┤
│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 │ │C-S-G │Ignored │Ignored │Ignored │
│Callbacks │ │ │ │ │ │
└──────────────┴────────────────┴────────────┴─────────┴────────────┴─────────┘
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. Some Xlib implementations will
allow this to be set when XNInputStyle is set to XIMPreeditCallbacks. Behavior
in that case is implementation defined.
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 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.
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.
The callback must move to the location specified by the
position field of the callback data, indicated in
XIMAbsolutePosition 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:
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
XBufferOverflow 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.
No consistent input has been composed so far. The contents of
XLookupNone buffer_return and keysym_return are not modified, and the
function returns zero.
Some input characters have been composed. They are placed in
the buffer_return argument, and the string length is returned
XLookupChars 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.
A KeySym has been returned instead of a string and is returned
XLookupKeySym in keysym_return. The content of the buffer_return argument is
not modified, and the function returns zero.
XLookupBoth Both a KeySym and a string are returned; XLookupChars and
XLookupKeySym occur simultaneously.
It does not make any difference if the input context passed as an argument to
XmbLookupString and XwcLookupString is the one currently in possession of the
focus or not. Input may have been composed within an input context before it
lost the focus, and that input may be returned on subsequent calls to
XmbLookupString or XwcLookupString even though it does not have any more
keyboard focus.
Input Method Conventions
The input method architecture is transparent to the client. However, clients
should respect a number of conventions in order to work properly. Clients must
also be aware of possible effects of synchronization between input method and
library in the case of a remote input server.
Client Conventions
A well-behaved client (or toolkit) should first query the input method style.
If the client cannot satisfy the requirements of the supported styles (in terms
of geometry management or callbacks), it should negotiate with the user
continuation of the program or raise an exception or error of some sort.
Synchronization Conventions
A KeyPress event with a KeyCode of zero is used exclusively as a signal that an
input method has composed input that can be returned by XmbLookupString or
XwcLookupString. No other use is made of a KeyPress event with KeyCode of zero.
Such an event may be generated by either a front-end or a back-end input method
in an implementation-dependent manner. Some possible ways to generate this
event include:
• A synthetic event sent by an input method server
• An artificial event created by a input method filter and pushed onto a
client's event queue
• A KeyPress event whose KeyCode value is modified by an input method filter
When callback support is specified by the client, input methods will not take
action unless they explicitly called back the client and obtained no response
(the callback is not specified or returned invalid data).
String Constants
The following symbols for string constants are defined in <X11/Xlib.h>.
Although they are shown here with particular macro definitions, they may be
implemented as macros, as global symbols, or as a mixture of the two. The
string pointer value itself is not significant; clients must not assume that
inequality of two values implies inequality of the actual string data.
#define XNVaNestedList "XNVaNestedList"
#define XNSeparatorofNestedList "separatorofNestedList"
#define XNQueryInputStyle "queryInputStyle"
#define XNClientWindow "clientWindow"
#define XNInputStyle "inputStyle"
#define XNFocusWindow "focusWindow"
#define XNResourceName "resourceName"
#define XNResourceClass "resourceClass"
#define XNGeometryCallback "geometryCallback"
#define XNDestroyCallback "destroyCallback"
#define XNFilterEvents "filterEvents"
#define XNPreeditStartCallback "preeditStartCallback"
#define XNPreeditDoneCallback "preeditDoneCallback"
#define XNPreeditDrawCallback "preeditDrawCallback"
#define XNPreeditCaretCallback "preeditCaretCallback"
#define XNPreeditStateNotifyCallback "preeditStateNotifyCallback"
#define XNPreeditAttributes "preeditAttributes"
#define XNStatusStartCallback "statusStartCallback"
#define XNStatusDoneCallback "statusDoneCallback"
#define XNStatusDrawCallback "statusDrawCallback"
#define XNStatusAttributes "statusAttributes"
#define XNArea "area"
#define XNAreaNeeded "areaNeeded"
#define XNSpotLocation "spotLocation"
#define XNColormap "colorMap"
#define XNStdColormap "stdColorMap"
#define XNForeground "foreground"
#define XNBackground "background"
#define XNBackgroundPixmap "backgroundPixmap"
#define XNFontSet "fontSet"
#define XNLineSpace "lineSpace"
#define XNCursor "cursor"
#define XNQueryIMValuesList "queryIMValuesList"
#define XNQueryICValuesList "queryICValuesList"
#define XNStringConversionCallback "stringConversionCallback"
#define XNStringConversion "stringConversion"
#define XNResetState "resetState"
#define XNHotKey "hotkey"
#define XNHotKeyState "hotkeyState"
#define XNPreeditState "preeditState"
#define XNVisiblePosition "visiblePosition"
#define XNR6PreeditCallbackBehavior "r6PreeditCallback"
#define XNRequiredCharSet "requiredCharSet"
#define XNQueryOrientation "queryOrientation"
#define XNDirectionalDependentDrawing "directionalDependentDrawing"
#define XNContextualDrawing "contextualDrawing"
#define XNBaseFontName "baseFontName"
#define XNMissingCharSet "missingCharSet"
#define XNDefaultString "defaultString"
#define XNOrientation "orientation"
#define XNFontInfo "fontInfo"
#define XNOMAutomatic "omAutomatic"
Chapter 14. Inter-Client Communication Functions
Table of Contents
Client to Window Manager Communication
Manipulating Top-Level Windows
Converting String Lists
Setting and Reading Text Properties
Setting and Reading the WM_NAME Property
Setting and Reading the WM_ICON_NAME Property
Setting and Reading the WM_HINTS Property
Setting and Reading the WM_NORMAL_HINTS Property
Setting and Reading the WM_CLASS Property
Setting and Reading the WM_TRANSIENT_FOR Property
Setting and Reading the WM_PROTOCOLS Property
Setting and Reading the WM_COLORMAP_WINDOWS Property
Setting and Reading the WM_ICON_SIZE Property
Using Window Manager Convenience Functions
Client to Session Manager Communication
Setting and Reading the WM_COMMAND Property
Setting and Reading the WM_CLIENT_MACHINE Property
Standard Colormaps
Standard Colormap Properties and Atoms
Setting and Obtaining Standard Colormaps
The Inter-Client Communication Conventions Manual, hereafter referred to as the
ICCCM, details the X Consortium approved conventions that govern inter-client
communications. These conventions ensure peer-to-peer client cooperation in the
use of selections, cut buffers, and shared resources as well as client
cooperation with window and session managers. For further information, see the
Inter-Client Communication Conventions Manual.
Xlib provides a number of standard properties and programming interfaces that
are ICCCM compliant. The predefined atoms for some of these properties are
defined in the <X11/Xatom.h> header file, where to avoid name conflicts with
user symbols their #define name has an XA_ prefix. For further information
about atoms and properties, see section 4.3.
Xlib’s selection and cut buffer mechanisms provide the primary programming
interfaces by which peer client applications communicate with each other (see
sections 4.5 and 16.6). The functions discussed in this chapter provide the
primary programming interfaces by which client applications communicate with
their window and session managers as well as share standard colormaps.
The standard properties that are of special interest for communicating with
window and session managers are:
┌───────────────────┬───────────────┬──────┬──────────────────────────────────┐
│Name │Type │Format│Description │
├───────────────────┼───────────────┼──────┼──────────────────────────────────┤
│ │ │ │Set by application programs to │
│ │ │ │allow window and session managers │
│WM_CLASS │STRING │8 │to obtain the application’s │
│ │ │ │resources from the resource │
│ │ │ │database. │
├───────────────────┼───────────────┼──────┼──────────────────────────────────┤
│ │ │ │The string name of the machine on │
│WM_CLIENT_MACHINE │TEXT │ │which the client application is │
│ │ │ │running. │
├───────────────────┼───────────────┼──────┼──────────────────────────────────┤
│ │ │ │The list of window IDs that may │
│WM_COLORMAP_WINDOWS│WINDOWS │32 │need a different colormap from │
│ │ │ │that of their top-level window. │
├───────────────────┼───────────────┼──────┼──────────────────────────────────┤
│ │ │ │The command and arguments, null │
│WM_COMMAND │TEXT │ │separated, used to invoke the │
│ │ │ │application. │
├───────────────────┼───────────────┼──────┼──────────────────────────────────┤
│ │ │ │Additional hints set by the client│
│WM_HINTS │WM_HINTS │32 │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. │
├───────────────────┼───────────────┼──────┼──────────────────────────────────┤
│ │ │ │The window manager may set this │
│ │ │ │property on the root window to │
│WM_ICON_SIZE │WM_ICON_SIZE │32 │specify the icon sizes it │
│ │ │ │supports. The C type of this │
│ │ │ │property is XIconSize. │
├───────────────────┼───────────────┼──────┼──────────────────────────────────┤
│WM_NAME │TEXT │ │The name of the application. │
├───────────────────┼───────────────┼──────┼──────────────────────────────────┤
│ │ │ │Size hints for a window in its │
│WM_NORMAL_HINTS │WM_NORMAL_HINTS│32 │normal state. The C type of this │
│ │ │ │property is XSizeHints. │
├───────────────────┼───────────────┼──────┼──────────────────────────────────┤
│ │ │ │List of atoms that identify the │
│ │ │ │communications protocols between │
│WM_PROTOCOLS │ATOM │32 │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. │
├───────────────────┼───────────────┼──────┼──────────────────────────────────┤
│ │ │ │Set by application programs to │
│WM_TRANSIENT_FOR │WINDOW │32 │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.
Specifies which values are to be set using information in the
value_mask 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 locale) */
XStdICCTextStyle /* STRING, else COMPOUND_TEXT */
} XICCEncodingStyle;
To convert a list of text strings to an XTextProperty structure, use
XmbTextListToTextProperty or XwcTextListToTextProperty.
int XmbTextListToTextProperty(Display *display, char **list, int count,
XICCEncodingStyle style, XTextProperty *text_prop_return);
int XwcTextListToTextProperty(Display *display, wchar_t **list, int count,
XICCEncodingStyle style, XTextProperty *text_prop_return);
display Specifies the connection to the X server.
list Specifies a list of null-terminated character strings.
count Specifies the number of strings specified.
style Specifies the manner in which the property is encoded.
text_prop_return Returns the XTextProperty structure.
The XmbTextListToTextProperty and XwcTextListToTextProperty functions set the
specified XTextProperty value to a set of null-separated elements representing
the concatenation of the specified list of null-terminated text strings. A
final terminating null is stored at the end of the value field of
text_prop_return but is not included in the nitems member.
The functions set the encoding field of text_prop_return to an Atom for the
specified display naming the encoding determined by the specified style and
convert the specified text list to this encoding for storage in the
text_prop_return value field. If the style XStringStyle or XCompoundTextStyle
is specified, this encoding is ``STRING'' or ``COMPOUND_TEXT'', respectively.
If the style XTextStyle is specified, this encoding is the encoding of the
current locale. If the style XStdICCTextStyle is specified, this encoding is
``STRING'' if the text is fully convertible to STRING, else ``COMPOUND_TEXT''.
If insufficient memory is available for the new value string, the functions
return XNoMemory. If the current locale is not supported, the functions return
XLocaleNotSupported. In both of these error cases, the functions do not set
text_prop_return.
To determine if the functions are guaranteed not to return XLocaleNotSupported,
use XSupportsLocale.
If the supplied text is not fully convertible to the specified encoding, the
functions return the number of unconvertible characters. Each unconvertible
character is converted to an implementation-defined and encoding-specific
default string. Otherwise, the functions return Success. Note that full
convertibility to all styles except XStringStyle is guaranteed.
To free the storage for the value field, use XFree.
To obtain a list of text strings from an XTextProperty structure, use
XmbTextPropertyToTextList or XwcTextPropertyToTextList.
int XmbTextPropertyToTextList(Display *display, XTextProperty *text_prop, char
***list_return, int *count_return);
int XwcTextPropertyToTextList(Display *display, XTextProperty *text_prop,
wchar_t ***list_return, int *count_return);
display Specifies the connection to the X server.
text_prop Specifies the XTextProperty structure to be used.
list_return Returns a list of null-terminated character strings.
count_return Returns the number of strings.
The XmbTextPropertyToTextList and XwcTextPropertyToTextList functions return a
list of text strings in the current locale representing the null-separated
elements of the specified XTextProperty structure. The data in text_prop must
be format 8.
Multiple elements of the property (for example, the strings in a disjoint text
selection) are separated by a null byte. The contents of the property are not
required to be null-terminated; any terminating null should not be included in
text_prop.nitems.
If insufficient memory is available for the list and its elements,
XmbTextPropertyToTextList and XwcTextPropertyToTextList return XNoMemory. If
the current locale is not supported, the functions return XLocaleNotSupported.
Otherwise, if the encoding field of text_prop is not convertible to the
encoding of the current locale, the functions return XConverterNotFound. For
supported locales, existence of a converter from COMPOUND_TEXT, STRING or the
encoding of the current locale is guaranteed if XSupportsLocale returns True
for the current locale (but the actual text may contain unconvertible
characters). Conversion of other encodings is implementation-dependent. In all
of these error cases, the functions do not set any return values.
Otherwise, XmbTextPropertyToTextList and XwcTextPropertyToTextList return the
list of null-terminated text strings to list_return and the number of text
strings to count_return.
If the value field of text_prop is not fully convertible to the encoding of the
current locale, the functions return the number of unconvertible characters.
Each unconvertible character is converted to a string in the current locale
that is specific to the current locale. To obtain the value of this string, use
XDefaultString. Otherwise, XmbTextPropertyToTextList and
XwcTextPropertyToTextList return Success.
To free the storage for the list and its contents returned by
XmbTextPropertyToTextList, use XFreeStringList. To free the storage for the
list and its contents returned by XwcTextPropertyToTextList, use
XwcFreeStringList.
To free the in-memory data associated with the specified wide character string
list, use XwcFreeStringList.
void XwcFreeStringList(wchar_t **list);
list Specifies the list of strings to be freed.
The XwcFreeStringList function frees memory allocated by
XwcTextPropertyToTextList.
To obtain the default string for text conversion in the current locale, use
char *XDefaultString(void);
The XDefaultString function returns the default string used by Xlib for text
conversion (for example, in XmbTextPropertyToTextList). The default string is
the string in the current locale that is output when an unconvertible character
is found during text conversion. If the string returned by XDefaultString is
the empty string (""), no character is output in the converted text.
XDefaultString does not return NULL.
The string returned by XDefaultString is independent of the default string for
text drawing; see XCreateFontSet to obtain the default string for an XFontSet.
The behavior when an invalid codepoint is supplied to any Xlib function is
undefined.
The returned string is null-terminated. It is owned by Xlib and should not be
modified or freed by the client. It may be freed after the current locale is
changed. Until freed, it will not be modified by Xlib.
To set the specified list of strings in the STRING encoding to a XTextProperty
structure, use XStringListToTextProperty.
Status XStringListToTextProperty(char **list, int count, XTextProperty
*text_prop_return);
list Specifies a list of null-terminated character strings.
count Specifies the number of strings.
text_prop_return Returns the XTextProperty structure.
The XStringListToTextProperty function sets the specified XTextProperty to be
of type STRING (format 8) with a value representing the concatenation of the
specified list of null-separated character strings. An extra null byte (which
is not included in the nitems member) is stored at the end of the value field
of text_prop_return. The strings are assumed (without verification) to be in
the STRING encoding. If insufficient memory is available for the new value
string, XStringListToTextProperty does not set any fields in the XTextProperty
structure and returns a zero status. Otherwise, it returns a nonzero status. To
free the storage for the value field, use XFree.
To obtain a list of strings from a specified XTextProperty structure in the
STRING encoding, use XTextPropertyToStringList.
Status XTextPropertyToStringList(XTextProperty *text_prop, char ***list_return,
int *count_return);
text_prop Specifies the XTextProperty structure to be used.
list_return Returns a list of null-terminated character strings.
count_return Returns the number of strings.
The XTextPropertyToStringList function returns a list of strings representing
the null-separated elements of the specified XTextProperty structure. The data
in text_prop must be of type STRING and format 8. Multiple elements of the
property (for example, the strings in a disjoint text selection) are separated
by NULL (encoding 0). The contents of the property are not null-terminated. If
insufficient memory is available for the list and its elements,
XTextPropertyToStringList sets no return values and returns a zero status.
Otherwise, it returns a nonzero status. To free the storage for the list and
its contents, use XFreeStringList.
To free the in-memory data associated with the specified string list, use
XFreeStringList.
void XFreeStringList(char **list);
list Specifies the list of strings to be freed.
The XFreeStringList function releases memory allocated by
XmbTextPropertyToTextList and XTextPropertyToStringList and the missing charset
list allocated by XCreateFontSet.
Setting and Reading Text Properties
Xlib provides two functions that you can use to set and read the text
properties for a given window. You can use these functions to set and read
those properties of type TEXT (WM_NAME, WM_ICON_NAME, WM_COMMAND, and
WM_CLIENT_MACHINE). In addition, Xlib provides separate convenience functions
that you can use to set each of these properties. For further information about
these convenience functions, see sections 14.1.4, 14.1.5, 14.2.1, and 14.2.2,
respectively.
To set one of a window's text properties, use XSetTextProperty.
void XSetTextProperty(Display *display, Window w, XTextProperty *text_prop,
Atom property);
display Specifies the connection to the X server.
w Specifies the window.
text_prop Specifies the XTextProperty structure to be used.
property Specifies the property name.
The XSetTextProperty function replaces the existing specified property for the
named window with the data, type, format, and number of items determined by the
value field, the encoding field, the format field, and the nitems field,
respectively, of the specified XTextProperty structure. If the property does
not already exist, XSetTextProperty sets it for the specified window.
XSetTextProperty can generate BadAlloc, BadAtom, BadValue, and BadWindow
errors.
To read one of a window's text properties, use XGetTextProperty.
Status XGetTextProperty(Display *display, Window w, XTextProperty
*text_prop_return, Atom property);
display Specifies the connection to the X server.
w Specifies the window.
text_prop_return Returns the XTextProperty structure.
property Specifies the property name.
The XGetTextProperty function reads the specified property from the window and
stores the data in the returned XTextProperty structure. It stores the data in
the value field, the type of the data in the encoding field, the format of the
data in the format field, and the number of items of data in the nitems field.
An extra byte containing null (which is not included in the nitems member) is
stored at the end of the value field of text_prop_return. The particular
interpretation of the property's encoding and data as text is left to the
calling application. If the specified property does not exist on the window,
XGetTextProperty sets the value field to NULL, the encoding field to None, the
format field to zero, and the nitems field to zero.
If it was able to read and store the data in the XTextProperty structure,
XGetTextProperty returns a nonzero status; otherwise, it returns a zero status.
XGetTextProperty can generate BadAtom and BadWindow errors.
Setting and Reading the WM_NAME Property
Xlib provides convenience functions that you can use to set and read the
WM_NAME property for a given window.
To set a window's WM_NAME property with the supplied convenience function, use
XSetWMName.
void XSetWMName(Display *display, Window w, XTextProperty *text_prop);
display Specifies the connection to the X server.
w Specifies the window.
text_prop Specifies the XTextProperty structure to be used.
The XSetWMName convenience function calls XSetTextProperty to set the WM_NAME
property.
To read a window's WM_NAME property with the supplied convenience function, use
XGetWMName.
Status XGetWMName(Display *display, Window w, XTextProperty *text_prop_return);
display Specifies the connection to the X server.
w Specifies the window.
text_prop_return Returns the XTextProperty structure.
The XGetWMName convenience function calls XGetTextProperty to obtain the
WM_NAME property. It returns a nonzero status on success; otherwise, it returns
a zero status.
The following two functions have been superseded by XSetWMName and XGetWMName,
respectively. You can use these additional convenience functions for window
names that are encoded as STRING properties.
To assign a name to a window, use XStoreName.
XStoreName(Display *display, Window w, char *window_name);
display Specifies the connection to the X server.
w Specifies the window.
window_name Specifies the window name, which should be a null-terminated
string.
The XStoreName function assigns the name passed to window_name to the specified
window. A window manager can display the window name in some prominent place,
such as the title bar, to allow users to identify windows easily. Some window
managers may display a window's name in the window's icon, although they are
encouraged to use the window's icon name if one is provided by the application.
If the string is not in the Host Portable Character Encoding, the result is
implementation-dependent.
XStoreName can generate BadAlloc and BadWindow errors.
To get the name of a window, use XFetchName.
Status XFetchName(Display *display, Window w, char **window_name_return);
display Specifies the connection to the X server.
w Specifies the window.
window_name_return Returns the window name, which is a null-terminated string.
The XFetchName function returns the name of the specified window. If it
succeeds, it returns a nonzero status; otherwise, no name has been set for the
window, and it returns zero. If the WM_NAME property has not been set for this
window, XFetchName sets window_name_return to NULL. If the data returned by the
server is in the Latin Portable Character Encoding, then the returned string is
in the Host Portable Character Encoding. Otherwise, the result is
implementation-dependent. When finished with it, a client must free the window
name string using XFree.
XFetchName can generate a BadWindow error.
Setting and Reading the WM_ICON_NAME Property
Xlib provides convenience functions that you can use to set and read the
WM_ICON_NAME property for a given window.
To set a window's WM_ICON_NAME property, use XSetWMIconName.
void XSetWMIconName(Display *display, Window w, XTextProperty *text_prop);
display Specifies the connection to the X server.
w Specifies the window.
text_prop Specifies the XTextProperty structure to be used.
The XSetWMIconName convenience function calls XSetTextProperty to set the
WM_ICON_NAME property.
To read a window's WM_ICON_NAME property, use XGetWMIconName.
Status XGetWMIconName(Display *display, Window w, XTextProperty
*text_prop_return);
display Specifies the connection to the X server.
w Specifies the window.
text_prop_return Returns the XTextProperty structure.
The XGetWMIconName convenience function calls XGetTextProperty to obtain the
WM_ICON_NAME property. It returns a nonzero status on success; otherwise, it
returns a zero status.
The next two functions have been superseded by XSetWMIconName and
XGetWMIconName, respectively. You can use these additional convenience
functions for window names that are encoded as STRING properties.
To set the name to be displayed in a window's icon, use XSetIconName.
XSetIconName(Display *display, Window w, char *icon_name);
display Specifies the connection to the X server.
w Specifies the window.
icon_name Specifies the icon name, which should be a null-terminated string.
If the string is not in the Host Portable Character Encoding, the result is
implementation-dependent. XSetIconName can generate BadAlloc and BadWindow
errors.
To get the name a window wants displayed in its icon, use XGetIconName.
Status XGetIconName(Display *display, Window w, char **icon_name_return);
display Specifies the connection to the X server.
w Specifies the window.
icon_name_return Returns the window's icon name, which is a null-terminated
string.
The XGetIconName function returns the name to be displayed in the specified
window's icon. If it succeeds, it returns a nonzero status; otherwise, if no
icon name has been set for the window, it returns zero. If you never assigned a
name to the window, XGetIconName sets icon_name_return to NULL. If the data
returned by the server is in the Latin Portable Character Encoding, then the
returned string is in the Host Portable Character Encoding. Otherwise, the
result is implementation-dependent. When finished with it, a client must free
the icon name string using XFree.
XGetIconName can generate a BadWindow error.
Setting and Reading the WM_HINTS Property
Xlib provides functions that you can use to set and read the WM_HINTS property
for a given window. These functions use the flags and the XWMHints structure,
as defined in the <X11/Xutil.h> header file.
To allocate an XWMHints structure, use XAllocWMHints.
XWMHints *XAllocWMHints(void);
The XAllocWMHints function allocates and returns a pointer to an XWMHints
structure. Note that all fields in the XWMHints structure are initially set to
zero. If insufficient memory is available, XAllocWMHints returns NULL. To free
the memory allocated to this structure, use XFree.
The XWMHints structure contains:
/* Window manager hints mask bits */
#define InputHint (1L<<0)
#define StateHint (1L<<1)
#define IconPixmapHint (1L<<2)
#define IconWindowHint (1L<<3)
#define IconPositionHint (1L<<4)
#define IconMaskHint (1L<<5)
#define WindowGroupHint (1L<<6)
#define UrgencyHint (1L<<8)
#define AllHints (InputHint|StateHint|IconPixmapHint|
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 window 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_pixmap */
XID window_group; /* id of related window group */
/* this structure may be extended in the future */
} XWMHints;
The input member is used to communicate to the window manager the input focus
model used by the application. Applications that expect input but never
explicitly set focus to any of their subwindows (that is, use the push model of
focus management), such as X Version 10 style applications that use real-estate
driven focus, should set this member to True. Similarly, applications that set
input focus to their subwindows only when it is given to their top-level window
by a window manager should also set this member to True. Applications that
manage their own input focus by explicitly setting focus to one of their
subwindows whenever they want keyboard input (that is, use the pull model of
focus management) should set this member to False. Applications that never
expect any keyboard input also should set this member to False.
Pull model window managers should make it possible for push model applications
to get input by setting input focus to the top-level windows of applications
whose input member is True. Push model window managers should make sure that
pull model applications do not break them by resetting input focus to
PointerRoot when it is appropriate (for example, whenever an application whose
input member is False sets input focus to one of its subwindows).
The definitions for the initial_state flag are:
#define WithdrawnState 0
#define NormalState 1 /* most applications start this way */
#define IconicState 3 /* application wants to start as an icon */
The icon_mask specifies which pixels of the icon_pixmap should be used as the
icon. This allows for nonrectangular icons. Both icon_pixmap and icon_mask must
be bitmaps. The icon_window lets an application provide a window for use as an
icon for window managers that support such use. The window_group lets you
specify that this window belongs to a group of other windows. For example, if a
single application manipulates multiple top-level windows, this allows you to
provide enough information that a window manager can iconify all of the windows
rather than just the one window.
The UrgencyHint flag, if set in the flags field, indicates that the client
deems the window contents to be urgent, requiring the timely response of the
user. The window manager will make some effort to draw the user's attention to
this window while this flag is set. The client must provide some means by which
the user can cause the urgency flag to be cleared (either mitigating the
condition that made the window urgent or merely shutting off the alarm) or the
window to be withdrawn.
To set a window's WM_HINTS property, use XSetWMHints.
XSetWMHints(Display *display, Window w, XWMHints *wmhints);
display Specifies the connection to the X server.
w Specifies the window.
wmhints Specifies the XWMHints structure to be used.
The XSetWMHints function sets the window manager hints that include icon
information and location, the initial state of the window, and whether the
application relies on the window manager to get keyboard input.
XSetWMHints can generate BadAlloc and BadWindow errors.
To read a window's WM_HINTS property, use XGetWMHints.
XWMHints *XGetWMHints(Display *display, Window w);
display Specifies the connection to the X server.
w Specifies the window.
The XGetWMHints function reads the window manager hints and returns NULL if no
WM_HINTS property was set on the window or returns a pointer to an XWMHints
structure if it succeeds. When finished with the data, free the space used for
it by calling XFree.
XGetWMHints can generate a BadWindow error.
Setting and Reading the WM_NORMAL_HINTS Property
Xlib provides functions that you can use to set or read the WM_NORMAL_HINTS
property for a given window. The functions use the flags and the XSizeHints
structure, as defined in the <X11/Xutil.h> header file.
The size of the XSizeHints structure may grow in future releases, as new
components are added to support new ICCCM features. Passing statically
allocated instances of this structure into Xlib may result in memory corruption
when running against a future release of the library. As such, it is
recommended that only dynamically allocated instances of the structure be used.
To allocate an XSizeHints structure, use XAllocSizeHints.
XSizeHints *XAllocSizeHints(void);
The XAllocSizeHints function allocates and returns a pointer to an XSizeHints
structure. Note that all fields in the XSizeHints structure are initially set
to zero. If insufficient memory is available, XAllocSizeHints returns NULL. To
free the memory allocated to this structure, use XFree.
The XSizeHints structure contains:
/* Size hints mask bits */
#define USPosition (1L<<0) /* user specified x,y */
#define USSize (1L<<1) /* user specified width,height */
#define PPosition (1L<<2) /* program specified position */
#define PSize (1L<<3) /* program specified size */
#define PMinSize (1L<<4) /* program specified minimum size */
#define PMaxSize (1L<<5) /* program specified maximum size */
#define PResizeInc (1L<<5) /* program specified resize increments */
#define PAspect (1L<<6) /* program specified min and max aspect ratios */
#define PBaseSize (1L<<8)
#define PWinGravity (1L<<9)
#define PAllHints (PPosition|Psize|
PMinSize|PMaxSize|
PResizeInc|PAspect)
/* Values */
typedef struct {
long flags; /* marks which fields in this structure are defined */
int x, y; /* Obsolete */
int width, height; /* Obsolete */
int min_width, min_height;
int max_width, max_height;
int width_inc, height_inc;
struct {
int x; /* numerator */
int y; /* denominator */
} min_aspect, max_aspect;
int base_width, base_height;
int win_gravity;
/* this structure may be extended in the future */
} XSizeHints;
The x, y, width, and height members are now obsolete and are left solely for
compatibility reasons. The min_width and min_height members specify the minimum
window size that still allows the application to be useful. The max_width and
max_height members specify the maximum window size. The width_inc and
height_inc members define an arithmetic progression of sizes (minimum to
maximum) into which the window prefers to be resized. The min_aspect and
max_aspect members are expressed as ratios of x and y, and they allow an
application to specify the range of aspect ratios it prefers. The base_width
and base_height members define the desired size of the window. The window
manager will interpret the position of the window and its border width to
position the point of the outer rectangle of the overall window specified by
the win_gravity member. The outer rectangle of the window includes any borders
or decorations supplied by the window manager. In other words, if the window
manager decides to place the window where the client asked, the position on the
parent window's border named by the win_gravity will be placed where the client
window would have been placed in the absence of a window manager.
Note that use of the PAllHints macro is highly discouraged.
To set a window's WM_NORMAL_HINTS property, use XSetWMNormalHints.
void XSetWMNormalHints(Display *display, Window w, XSizeHints *hints);
display Specifies the connection to the X server.
w Specifies the window.
hints Specifies the size hints for the window in its normal state.
The XSetWMNormalHints function replaces the size hints for the WM_NORMAL_HINTS
property on the specified window. If the property does not already exist,
XSetWMNormalHints sets the size hints for the WM_NORMAL_HINTS property on the
specified window. The property is stored with a type of WM_SIZE_HINTS and a
format of 32.
XSetWMNormalHints can generate BadAlloc and BadWindow errors.
To read a window's WM_NORMAL_HINTS property, use XGetWMNormalHints.
Status XGetWMNormalHints(Display *display, Window w, XSizeHints *hints_return,
long *supplied_return);
display Specifies the connection to the X server.
w Specifies the window.
hints_return Returns the size hints for the window in its normal state.
supplied_return Returns the hints that were supplied by the user.
The XGetWMNormalHints function returns the size hints stored in the
WM_NORMAL_HINTS property on the specified window. If the property is of type
WM_SIZE_HINTS, is of format 32, and is long enough to contain either an old
(pre-ICCCM) or new size hints structure, XGetWMNormalHints sets the various
fields of the XSizeHints structure, sets the supplied_return argument to the
list of fields that were supplied by the user (whether or not they contained
defined values), and returns a nonzero status. Otherwise, it returns a zero
status.
If XGetWMNormalHints returns successfully and a pre-ICCCM size hints property
is read, the supplied_return argument will contain the following bits:
(USPosition|USSize|PPosition|PSize|PMinSize|
PMaxSize|PResizeInc|PAspect)
If the property is large enough to contain the base size and window gravity
fields as well, the supplied_return argument will also contain the following
bits:
PBaseSize|PWinGravity
XGetWMNormalHints can generate a BadWindow error.
To set a window's WM_SIZE_HINTS property, use XSetWMSizeHints.
void XSetWMSizeHints(Display *display, Window w, XSizeHints *hints, Atom
property);
display Specifies the connection to the X server.
w Specifies the window.
hints Specifies the XSizeHints structure to be used.
property Specifies the property name.
The XSetWMSizeHints function replaces the size hints for the specified property
on the named window. If the specified property does not already exist,
XSetWMSizeHints sets the size hints for the specified property on the named
window. The property is stored with a type of WM_SIZE_HINTS and a format of 32.
To set a window's normal size hints, you can use the XSetWMNormalHints
function.
XSetWMSizeHints can generate BadAlloc, BadAtom, and BadWindow errors.
To read a window's WM_SIZE_HINTS property, use XGetWMSizeHints.
Status XGetWMSizeHints(Display *display, Window w, XSizeHints *hints_return,
long *supplied_return, Atom property);
display Specifies the connection to the X server.
w Specifies the window.
hints_return Returns the XSizeHints structure.
supplied_return Returns the hints that were supplied by the user.
property Specifies the property name.
The XGetWMSizeHints function returns the size hints stored in the specified
property on the named window. If the property is of type WM_SIZE_HINTS, is of
format 32, and is long enough to contain either an old (pre-ICCCM) or new size
hints structure, XGetWMSizeHints sets the various fields of the XSizeHints
structure, sets the supplied_return argument to the list of fields that were
supplied by the user (whether or not they contained defined values), and
returns a nonzero status. Otherwise, it returns a zero status. To get a
window's normal size hints, you can use the XGetWMNormalHints function.
If XGetWMSizeHints returns successfully and a pre-ICCCM size hints property is
read, the supplied_return argument will contain the following bits:
(USPosition|USSize|PPosition|PSize|PMinSize|
PMaxSize|PResizeInc|PAspect)
If the property is large enough to contain the base size and window gravity
fields as well, the supplied_return argument will also contain the following
bits:
PBaseSize|PWinGravity
XGetWMSizeHints can generate BadAtom and BadWindow errors.
Setting and Reading the WM_CLASS Property
Xlib provides functions that you can use to set and get the WM_CLASS property
for a given window. These functions use the XClassHint structure, which is
defined in the <X11/Xutil.h> header file.
To allocate an XClassHint structure, use XAllocClassHint.
XClassHint *XAllocClassHint(void);
The XAllocClassHint function allocates and returns a pointer to an XClassHint
structure. Note that the pointer fields in the XClassHint structure are
initially set to NULL. If insufficient memory is available, XAllocClassHint
returns NULL. To free the memory allocated to this structure, use XFree.
The XClassHint contains:
typedef struct {
char *res_name;
char *res_class;
} XClassHint;
The res_name member contains the application name, and the res_class member
contains the application class. Note that the name set in this property may
differ from the name set as WM_NAME. That is, WM_NAME specifies what should be
displayed in the title bar and, therefore, can contain temporal information
(for example, the name of a file currently in an editor's buffer). On the other
hand, the name specified as part of WM_CLASS is the formal name of the
application that should be used when retrieving the application's resources
from the resource database.
To set a window's WM_CLASS property, use XSetClassHint.
XSetClassHint(Display *display, Window w, XClassHint *class_hints);
display Specifies the connection to the X server.
w Specifies the window.
class_hints Specifies the XClassHint structure that is to be used.
The XSetClassHint function sets the class hint for the specified window. If the
strings are not in the Host Portable Character Encoding, the result is
implementation-dependent.
XSetClassHint can generate BadAlloc and BadWindow errors.
To read a window's WM_CLASS property, use XGetClassHint.
Status XGetClassHint(Display *display, Window w, XClassHint
*class_hints_return);
display Specifies the connection to the X server.
w Specifies the window.
class_hints_return Returns the XClassHint structure.
The XGetClassHint function returns the class hint of the specified window to
the members of the supplied structure. If the data returned by the server is in
the Latin Portable Character Encoding, then the returned strings are in the
Host Portable Character Encoding. Otherwise, the result is
implementation-dependent. It returns a nonzero status on success; otherwise, it
returns a zero status. To free res_name and res_class when finished with the
strings, use XFree on each individually.
XGetClassHint can generate a BadWindow error.
Setting and Reading the WM_TRANSIENT_FOR Property
Xlib provides functions that you can use to set and read the WM_TRANSIENT_FOR
property for a given window.
To set a window's WM_TRANSIENT_FOR property, use XSetTransientForHint.
XSetTransientForHint(Display *display, Window w, Window prop_window);
display Specifies the connection to the X server.
w Specifies the window.
prop_window Specifies the window that the WM_TRANSIENT_FOR property is to be
set to.
The XSetTransientForHint function sets the WM_TRANSIENT_FOR property of the
specified window to the specified prop_window.
XSetTransientForHint can generate BadAlloc and BadWindow errors.
To read a window's WM_TRANSIENT_FOR property, use XGetTransientForHint.
Status XGetTransientForHint(Display *display, Window w, Window
*prop_window_return);
display Specifies the connection to the X server.
w Specifies the window.
prop_window_return Returns the WM_TRANSIENT_FOR property of the specified
window.
The XGetTransientForHint function returns the WM_TRANSIENT_FOR property for the
specified window. It returns a nonzero status on success; otherwise, it returns
a zero status.
XGetTransientForHint can generate a BadWindow error.
Setting and Reading the WM_PROTOCOLS Property
Xlib provides functions that you can use to set and read the WM_PROTOCOLS
property for a given window.
To set a window's WM_PROTOCOLS property, use XSetWMProtocols.
Status XSetWMProtocols(Display *display, Window w, Atom *protocols, int count);
display Specifies the connection to the X server.
w Specifies the window.
protocols Specifies the list of protocols.
count Specifies the number of protocols in the list.
The XSetWMProtocols function replaces the WM_PROTOCOLS property on the
specified window with the list of atoms specified by the protocols argument. If
the property does not already exist, XSetWMProtocols sets the WM_PROTOCOLS
property on the specified window to the list of atoms specified by the
protocols argument. The property is stored with a type of ATOM and a format of
32. If it cannot intern the WM_PROTOCOLS atom, XSetWMProtocols returns a zero
status. Otherwise, it returns a nonzero status.
XSetWMProtocols can generate BadAlloc and BadWindow errors.
To read a window's WM_PROTOCOLS property, use XGetWMProtocols.
Status XGetWMProtocols(Display *display, Window w, Atom **protocols_return, int
*count_return);
display Specifies the connection to the X server.
w Specifies the window.
protocols_return Returns the list of protocols.
count_return Returns the number of protocols in the list.
The XGetWMProtocols function returns the list of atoms stored in the
WM_PROTOCOLS property on the specified window. These atoms describe window
manager protocols in which the owner of this window is willing to participate.
If the property exists, is of type ATOM, is of format 32, and the atom
WM_PROTOCOLS can be interned, XGetWMProtocols sets the protocols_return
argument to a list of atoms, sets the count_return argument to the number of
elements in the list, and returns a nonzero status. Otherwise, it sets neither
of the return arguments and returns a zero status. To release the list of
atoms, use XFree.
XGetWMProtocols can generate a BadWindow error.
Setting and Reading the WM_COLORMAP_WINDOWS Property
Xlib provides functions that you can use to set and read the
WM_COLORMAP_WINDOWS property for a given window.
To set a window's WM_COLORMAP_WINDOWS property, use XSetWMColormapWindows.
Status XSetWMColormapWindows(Display *display, Window w, Window
*colormap_windows, int count);
display Specifies the connection to the X server.
w Specifies the window.
colormap_windows Specifies the list of windows.
count Specifies the number of windows in the list.
The XSetWMColormapWindows function replaces the WM_COLORMAP_WINDOWS property on
the specified window with the list of windows specified by the colormap_windows
argument. If the property does not already exist, XSetWMColormapWindows sets
the WM_COLORMAP_WINDOWS property on the specified window to the list of windows
specified by the colormap_windows argument. The property is stored with a type
of WINDOW and a format of 32. If it cannot intern the WM_COLORMAP_WINDOWS atom,
XSetWMColormapWindows returns a zero status. Otherwise, it returns a nonzero
status.
XSetWMColormapWindows can generate BadAlloc and BadWindow errors.
To read a window's WM_COLORMAP_WINDOWS property, use XGetWMColormapWindows.
Status XGetWMColormapWindows(Display *display, Window w, Window
**colormap_windows_return, int *count_return);
display Specifies the connection to the X server.
w Specifies the window.
colormap_windows_return Returns the list of windows.
count_return Returns the number of windows in the list.
The XGetWMColormapWindows function returns the list of window identifiers
stored in the WM_COLORMAP_WINDOWS property on the specified window. These
identifiers indicate the colormaps that the window manager may need to install
for this window. If the property exists, is of type WINDOW, is of format 32,
and the atom WM_COLORMAP_WINDOWS can be interned, XGetWMColormapWindows sets
the windows_return argument to a list of window identifiers, sets the
count_return argument to the number of elements in the list, and returns a
nonzero status. Otherwise, it sets neither of the return arguments and returns
a zero status. To release the list of window identifiers, use XFree.
XGetWMColormapWindows can generate a BadWindow error.
Setting and Reading the WM_ICON_SIZE Property
Xlib provides functions that you can use to set and read the WM_ICON_SIZE
property for a given window. These functions use the XIconSize structure, which
is defined in the <X11/Xutil.h> header file.
To allocate an XIconSize structure, use XAllocIconSize.
XIconSize *XAllocIconSize(void);
The XAllocIconSize function allocates and returns a pointer to an XIconSize
structure. Note that all fields in the XIconSize structure are initially set to
zero. If insufficient memory is available, XAllocIconSize returns NULL. To free
the memory allocated to this structure, use XFree.
The XIconSize structure contains:
typedef struct {
int min_width, min_height;
int max_width, max_height;
int width_inc, height_inc;
} XIconSize;
The width_inc and height_inc members define an arithmetic progression of sizes
(minimum to maximum) that represent the supported icon sizes.
To set a window's WM_ICON_SIZE property, use XSetIconSizes.
XSetIconSizes(Display *display, Window w, XIconSize *size_list, int count);
display Specifies the connection to the X server.
w Specifies the window.
size_list Specifies the size list.
count Specifies the number of items in the size list.
The XSetIconSizes function is used only by window managers to set the supported
icon sizes.
XSetIconSizes can generate BadAlloc and BadWindow errors.
To read a window's WM_ICON_SIZE property, use XGetIconSizes.
Status XGetIconSizes(Display *display, Window w, XIconSize **size_list_return,
int *count_return);
display Specifies the connection to the X server.
w Specifies the window.
size_list_return Returns the size list.
count_return Returns the number of items in the size list.
The XGetIconSizes function returns zero if a window manager has not set icon
sizes; otherwise, it returns nonzero. XGetIconSizes should be called by an
application that wants to find out what icon sizes would be most appreciated by
the window manager under which the application is running. The application
should then use XSetWMHints to supply the window manager with an icon pixmap or
window in one of the supported sizes. To free the data allocated in
size_list_return, use XFree.
XGetIconSizes can generate a BadWindow error.
Using Window Manager Convenience Functions
The XmbSetWMProperties function stores the standard set of window manager
properties, with text properties in standard encodings for internationalized
text communication. The standard window manager properties for a given window
are WM_NAME, WM_ICON_NAME, WM_HINTS, WM_NORMAL_HINTS, WM_CLASS, WM_COMMAND,
WM_CLIENT_MACHINE, and WM_LOCALE_NAME.
void XmbSetWMProperties(Display *display, Window w, char *window_name, char
*icon_name, char *argv[], int argc, XSizeHints *normal_hints, XWMHints
*wm_hints, XClassHint *class_hints);
display Specifies the connection to the X server.
w Specifies the window.
window_name Specifies the window name, which should be a null-terminated
string.
icon_name Specifies the icon name, which should be a null-terminated string.
argv Specifies the application's argument list.
argc Specifies the number of arguments.
hints Specifies the size hints for the window in its normal state.
wm_hints Specifies the XWMHints structure to be used.
class_hints Specifies the XClassHint structure to be used.
The XmbSetWMProperties convenience function provides a simple programming
interface for setting those essential window properties that are used for
communicating with other clients (particularly window and session managers).
If the window_name argument is non-NULL, XmbSetWMProperties sets the WM_NAME
property. If the icon_name argument is non-NULL, XmbSetWMProperties sets the
WM_ICON_NAME property. The window_name and icon_name arguments are
null-terminated strings in the encoding of the current locale. If the arguments
can be fully converted to the STRING encoding, the properties are created with
type ``STRING''; otherwise, the arguments are converted to Compound Text, and
the properties are created with type ``COMPOUND_TEXT''.
If the normal_hints argument is non-NULL, XmbSetWMProperties calls
XSetWMNormalHints, which sets the WM_NORMAL_HINTS property (see section 14.1.7
). If the wm_hints argument is non-NULL, XmbSetWMProperties calls XSetWMHints,
which sets the WM_HINTS property (see section 14.1.6).
If the argv argument is non-NULL, XmbSetWMProperties sets the WM_COMMAND
property from argv and argc. An argc of zero indicates a zero-length command.
The hostname of the machine is stored using XSetWMClientMachine (see section
14.2.2).
If the class_hints argument is non-NULL, XmbSetWMProperties sets the WM_CLASS
property. If the res_name member in the XClassHint structure is set to the NULL
pointer and the RESOURCE_NAME environment variable is set, the value of the
environment variable is substituted for res_name. If the res_name member is
NULL, the environment variable is not set, and argv and argv[0] are set, then
the value of argv[0], stripped of any directory prefixes, is substituted for
res_name.
It is assumed that the supplied class_hints.res_name and argv, the
RESOURCE_NAME environment variable, and the hostname of the machine are in the
encoding of the locale announced for the LC_CTYPE category (on POSIX-compliant
systems, the LC_CTYPE, else LANG environment variable). The corresponding
WM_CLASS, WM_COMMAND, and WM_CLIENT_MACHINE properties are typed according to
the local host locale announcer. No encoding conversion is performed prior to
storage in the properties.
For clients that need to process the property text in a locale,
XmbSetWMProperties sets the WM_LOCALE_NAME property to be the name of the
current locale. The name is assumed to be in the Host Portable Character
Encoding and is converted to STRING for storage in the property.
XmbSetWMProperties can generate BadAlloc and BadWindow errors.
To set a window's standard window manager properties with strings in
client-specified encodings, use XSetWMProperties. The standard window manager
properties for a given window are WM_NAME, WM_ICON_NAME, WM_HINTS,
WM_NORMAL_HINTS, WM_CLASS, WM_COMMAND, and WM_CLIENT_MACHINE.
void XSetWMProperties(Display *display, Window w, XTextProperty *window_name,
XTextProperty *icon_name, char **argv, int argc, XSizeHints *normal_hints,
XWMHints *wm_hints, XClassHint *class_hints);
display Specifies the connection to the X server.
w Specifies the window.
window_name Specifies the window name, which should be a null-terminated
string.
icon_name Specifies the icon name, which should be a null-terminated string.
argv Specifies the application's argument list.
argc Specifies the number of arguments.
normal_hints Specifies the size hints for the window in its normal state.
wm_hints Specifies the XWMHints structure to be used.
class_hints Specifies the XClassHint structure to be used.
The XSetWMProperties convenience function provides a single programming
interface for setting those essential window properties that are used for
communicating with other clients (particularly window and session managers).
If the window_name argument is non-NULL, XSetWMProperties calls XSetWMName,
which, in turn, sets the WM_NAME property (see section 14.1.4). If the
icon_name argument is non-NULL, XSetWMProperties calls XSetWMIconName, which
sets the WM_ICON_NAME property (see section 14.1.5). If the argv argument is
non-NULL, XSetWMProperties calls XSetCommand, which sets the WM_COMMAND
property (see section 14.2.1). Note that an argc of zero is allowed to indicate
a zero-length command. Note also that the hostname of this machine is stored
using XSetWMClientMachine (see section 14.2.2).
If the normal_hints argument is non-NULL, XSetWMProperties calls
XSetWMNormalHints, which sets the WM_NORMAL_HINTS property (see section 14.1.7
). If the wm_hints argument is non-NULL, XSetWMProperties calls XSetWMHints,
which sets the WM_HINTS property (see section 14.1.6).
If the class_hints argument is non-NULL, XSetWMProperties calls XSetClassHint,
which sets the WM_CLASS property (see section 14.1.8). If the res_name member
in the XClassHint structure is set to the NULL pointer and the RESOURCE_NAME
environment variable is set, then the value of the environment variable is
substituted for res_name. If the res_name member is NULL, the environment
variable is not set, and argv and argv[0] are set, then the value of argv[0],
stripped of any directory prefixes, is substituted for res_name.
XSetWMProperties can generate BadAlloc and BadWindow errors.
Client to Session Manager Communication
This section discusses how to:
• Set and read the WM_COMMAND property
• Set and read the WM_CLIENT_MACHINE property
Setting and Reading the WM_COMMAND Property
Xlib provides functions that you can use to set and read the WM_COMMAND
property for a given window.
To set a window's WM_COMMAND property, use XSetCommand.
XSetCommand(Display *display, Window w, char **argv, int argc);
display Specifies the connection to the X server.
w Specifies the window.
argv Specifies the application's argument list.
argc Specifies the number of arguments.
The XSetCommand function sets the command and arguments used to invoke the
application. (Typically, argv is the argv array of your main program.) If the
strings are not in the Host Portable Character Encoding, the result is
implementation-dependent.
XSetCommand can generate BadAlloc and BadWindow errors.
To read a window's WM_COMMAND property, use XGetCommand.
Status XGetCommand(Display *display, Window w, char ***argv_return, int
*argc_return);
display Specifies the connection to the X server.
w Specifies the window.
argv_return Returns the application's argument list.
argc_return Returns the number of arguments returned.
The XGetCommand function reads the WM_COMMAND property from the specified
window and returns a string list. If the WM_COMMAND property exists, it is of
type STRING and format 8. If sufficient memory can be allocated to contain the
string list, XGetCommand fills in the argv_return and argc_return arguments and
returns a nonzero status. Otherwise, it returns a zero status. If the data
returned by the server is in the Latin Portable Character Encoding, then the
returned strings are in the Host Portable Character Encoding. Otherwise, the
result is implementation-dependent. To free the memory allocated to the string
list, use XFreeStringList.
Setting and Reading the WM_CLIENT_MACHINE Property
Xlib provides functions that you can use to set and read the WM_CLIENT_MACHINE
property for a given window.
To set a window's WM_CLIENT_MACHINE property, use XSetWMClientMachine.
void XSetWMClientMachine(Display *display, Window w, XTextProperty *text_prop);
display Specifies the connection to the X server.
w Specifies the window.
text_prop Specifies the XTextProperty structure to be used.
The XSetWMClientMachine convenience function calls XSetTextProperty to set the
WM_CLIENT_MACHINE property.
To read a window's WM_CLIENT_MACHINE property, use XGetWMClientMachine.
Status XGetWMClientMachine(Display *display, Window w, XTextProperty
*text_prop_return);
display Specifies the connection to the X server.
w Specifies the window.
text_prop_return Returns the XTextProperty structure.
The XGetWMClientMachine convenience function performs an XGetTextProperty on
the WM_CLIENT_MACHINE property. It returns a nonzero status on success;
otherwise, it returns a zero status.
Standard Colormaps
Applications with color palettes, smooth-shaded drawings, or digitized images
demand large numbers of colors. In addition, these applications often require
an efficient mapping from color triples to pixel values that display the
appropriate colors.
As an example, consider a three-dimensional display program that wants to draw
a smoothly shaded sphere. At each pixel in the image of the sphere, the program
computes the intensity and color of light reflected back to the viewer. The
result of each computation is a triple of red, green, and blue (RGB)
coefficients in the range 0.0 to 1.0. To draw the sphere, the program needs a
colormap that provides a large range of uniformly distributed colors. The
colormap should be arranged so that the program can convert its RGB triples
into pixel values very quickly, because drawing the entire sphere requires many
such conversions.
On many current workstations, the display is limited to 256 or fewer colors.
Applications must allocate colors carefully, not only to make sure they cover
the entire range they need but also to make use of as many of the available
colors as possible. On a typical X display, many applications are active at
once. Most workstations have only one hardware look-up table for colors, so
only one application colormap can be installed at a given time. The application
using the installed colormap is displayed correctly, and the other applications
go technicolor and are displayed with false colors.
As another example, consider a user who is running an image processing program
to display earth-resources data. The image processing program needs a colormap
set up with 8 reds, 8 greens, and 4 blues, for a total of 256 colors. Because
some colors are already in use in the default colormap, the image processing
program allocates and installs a new colormap.
The user decides to alter some of the colors in the image by invoking a color
palette program to mix and choose colors. The color palette program also needs
a colormap with eight reds, eight greens, and four blues, so just like the
image processing program, it must allocate and install a new colormap.
Because only one colormap can be installed at a time, the color palette may be
displayed incorrectly whenever the image processing program is active.
Conversely, whenever the palette program is active, the image may be displayed
incorrectly. The user can never match or compare colors in the palette and
image. Contention for colormap resources can be reduced if applications with
similar color needs share colormaps.
The image processing program and the color palette program could share the same
colormap if there existed a convention that described how the colormap was set
up. Whenever either program was active, both would be displayed correctly.
The standard colormap properties define a set of commonly used colormaps.
Applications that share these colormaps and conventions display true colors
more often and provide a better interface to the user.
Standard colormaps allow applications to share commonly used color resources.
This allows many applications to be displayed in true colors simultaneously,
even when each application needs an entirely filled colormap.
Several standard colormaps are described in this section. Usually, a window
manager creates these colormaps. Applications should use the standard colormaps
if they already exist.
To allocate an XStandardColormap structure, use XAllocStandardColormap.
XStandardColormap *XAllocStandardColormap(void);
The XAllocStandardColormap function allocates and returns a pointer to an
XStandardColormap structure. Note that all fields in the XStandardColormap
structure are initially set to zero. If insufficient memory is available,
XAllocStandardColormap returns NULL. To free the memory allocated to this
structure, use XFree.
The XStandardColormap structure contains:
/* Hints */
#define ReeaseByFreeingColormap ((XID)1L)
/* Values */
typedef struct {
Colormap colormap;
unsigned long red_max;
unsigned long red_mult;
unsigned long green_max;
unsigned long green_mult;
unsigned long blue_max;
unsigned long blue_mult;
unsigned long base_pixel;
VisualID visualid;
XID killid;
} XStandardColormap;
The colormap member is the colormap created by the XCreateColormap function.
The red_max, green_max, and blue_max members give the maximum red, green, and
blue values, respectively. Each color coefficient ranges from zero to its max,
inclusive. For example, a common colormap allocation is 3/3/2 (3 planes for
red, 3 planes for green, and 2 planes for blue). This colormap would have
red_max = 7, green_max = 7, and blue_max = 3. An alternate allocation that uses
only 216 colors is red_max = 5, green_max = 5, and blue_max = 5.
The red_mult, green_mult, and blue_mult members give the scale factors used to
compose a full pixel value. (See the discussion of the base_pixel members for
further information.) For a 3/3/2 allocation, red_mult might be 32, green_mult
might be 4, and blue_mult might be 1. For a 6-colors-each allocation, red_mult
might be 36, green_mult might be 6, and blue_mult might be 1.
The base_pixel member gives the base pixel value used to compose a full pixel
value. Usually, the base_pixel is obtained from a call to the XAllocColorPlanes
function. Given integer red, green, and blue coefficients in their appropriate
ranges, one then can compute a corresponding pixel value by using the following
expression:
(r * red_mult + g * green_mult + b * blue_mult + base_pixel) & 0xFFFFFFFF
For GrayScale colormaps, only the colormap, red_max, red_mult, and base_pixel
members are defined. The other members are ignored. To compute a GrayScale
pixel value, use the following expression:
(gray * red_mult + base_pixel) & 0xFFFFFFFF
Negative multipliers can be represented by converting the 2's complement
representation of the multiplier into an unsigned long and storing the result
in the appropriate _mult field. The step of masking by 0xFFFFFFFF effectively
converts the resulting positive multiplier into a negative one. The masking
step will take place automatically on many machine architectures, depending on
the size of the integer type used to do the computation.
The visualid member gives the ID number of the visual from which the colormap
was created. The killid member gives a resource ID that indicates whether the
cells held by this standard colormap are to be released by freeing the colormap
ID or by calling the XKillClient function on the indicated resource. (Note that
this method is necessary for allocating out of an existing colormap.)
The properties containing the XStandardColormap information have the type
RGB_COLOR_MAP.
The remainder of this section discusses standard colormap properties and atoms
as well as how to manipulate standard colormaps.
Standard Colormap Properties and Atoms
Several standard colormaps are available. Each standard colormap is defined by
a property, and each such property is identified by an atom. The following list
names the atoms and describes the colormap associated with each one. The <X11/
Xatom.h> header file contains the definitions for each of the following atoms,
which are prefixed with XA_.
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
RGB_DEFAULT_MAP 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.
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
RGB_BEST_MAP 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.
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
RGB_RED_MAP,RGB_GREEN_MAP,RGB_BLUE_MAP 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.
This atom names a property. The value of
the property is an XStandardColormap.
The property describes the best
RGB_GRAY_MAP GrayScale colormap available on the
screen. As previously mentioned, only
the colormap, red_max, red_mult, and
base_pixel members of the
XStandardColormap structure are used for
GrayScale colormaps.
Setting and Obtaining Standard Colormaps
Xlib provides functions that you can use to set and obtain an XStandardColormap
structure.
To set an XStandardColormap structure, use XSetRGBColormaps.
void XSetRGBColormaps(Display *display, Window w, XStandardColormap
*std_colormap, int count, Atom property);
display Specifies the connection to the X server.
w Specifies the window.
std_colormap Specifies the XStandardColormap structure to be used.
count Specifies the number of colormaps.
property Specifies the property name.
The XSetRGBColormaps function replaces the RGB colormap definition in the
specified property on the named window. If the property does not already exist,
XSetRGBColormaps sets the RGB colormap definition in the specified property on
the named window. The property is stored with a type of RGB_COLOR_MAP and a
format of 32. Note that it is the caller's responsibility to honor the ICCCM
restriction that only RGB_DEFAULT_MAP contain more than one definition.
The XSetRGBColormaps function usually is only used by window or session
managers. To create a standard colormap, follow this procedure:
• Open a new connection to the same server.
• Grab the server.
• See if the property is on the property list of the root window for the
screen.
• If the desired property is not present:
• Create a colormap (unless you are using the default colormap of the
screen).
• Determine the color characteristics of the visual.
• Allocate cells in the colormap (or create it with AllocAll).
• Call XStoreColors to store appropriate color values in the colormap.
• Fill in the descriptive members in the XStandardColormap structure.
• Attach the property to the root window.
• Use XSetCloseDownMode to make the resource permanent.
• Ungrab the server.
XSetRGBColormaps can generate BadAlloc, BadAtom, and BadWindow errors.
To obtain the XStandardColormap structure associated with the specified
property, use XGetRGBColormaps.
Status XGetRGBColormaps(Display *display, Window w, XStandardColormap
**std_colormap_return, int *count_return, Atom property);
display Specifies the connection to the X server.
w Specifies the window.
std_colormap_return Returns the XStandardColormap structure.
count_return Returns the number of colormaps.
property Specifies the property name.
The XGetRGBColormaps function returns the RGB colormap definitions stored in
the specified property on the named window. If the property exists, is of type
RGB_COLOR_MAP, is of format 32, and is long enough to contain a colormap
definition, XGetRGBColormaps allocates and fills in space for the returned
colormaps and returns a nonzero status. If the visualid is not present,
XGetRGBColormaps assumes the default visual for the screen on which the window
is located; if the killid is not present, None is assumed, which indicates that
the resources cannot be released. Otherwise, none of the fields are set, and
XGetRGBColormaps returns a zero status. Note that it is the caller's
responsibility to honor the ICCCM restriction that only RGB_DEFAULT_MAP contain
more than one definition.
XGetRGBColormaps can generate BadAtom and BadWindow errors.
Chapter 15. Resource Manager Functions
Table of Contents
Resource File Syntax
Resource Manager Matching Rules
Quarks
Creating and Storing Databases
Merging Resource Databases
Looking Up Resources
Storing into a Resource Database
Enumerating Database Entries
Parsing Command Line Options
A program often needs a variety of options in the X environment (for example,
fonts, colors, icons, and cursors). Specifying all of these options on the
command line is awkward because users may want to customize many aspects of the
program and need a convenient way to establish these customizations as the
default settings. The resource manager is provided for this purpose. Resource
specifications are usually stored in human-readable files and in server
properties.
The resource manager is a database manager with a twist. In most database
systems, you perform a query using an imprecise specification, and you get back
a set of records. The resource manager, however, allows you to specify a large
set of values with an imprecise specification, to query the database with a
precise specification, and to get back only a single value. This should be used
by applications that need to know what the user prefers for colors, fonts, and
other resources. It is this use as a database for dealing with X resources that
inspired the name "Resource Manager," although the resource manager can be and
is used in other ways.
For example, a user of your application may want to specify that all windows
should have a blue background but that all mail-reading windows should have a
red background. With well-engineered and coordinated applications, a user can
define this information using only two lines of specifications.
As an example of how the resource manager works, consider a mail-reading
application called xmh. Assume that it is designed so that it uses a complex
window hierarchy all the way down to individual command buttons, which may be
actual small subwindows in some toolkits. These are often called objects or
widgets. In such toolkit systems, each user interface object can be composed of
other objects and can be assigned a name and a class. Fully qualified names or
classes can have arbitrary numbers of component names, but a fully qualified
name always has the same number of component names as a fully qualified class.
This generally reflects the structure of the application as composed of these
objects, starting with the application itself.
For example, the xmh mail program has a name "xmh" and is one of a class of
"Mail" programs. By convention, the first character of class components is
capitalized, and the first letter of name components is in lowercase. Each name
and class finally has an attribute (for example, "foreground" or "font"). If
each window is properly assigned a name and class, it is easy for the user to
specify attributes of any portion of the application.
At the top level, the application might consist of a paned window (that is, a
window divided into several sections) named "toc". One pane of the paned window
is a button box window named "buttons" and is filled with command buttons. One
of these command buttons is used to incorporate new mail and has the name
"incorporate". This window has a fully qualified name,
"xmh.toc.buttons.incorporate", and a fully qualified class,
"Xmh.Paned.Box.Command". Its fully qualified name is the name of its parent,
"xmh.toc.buttons", followed by its name, "incorporate". Its class is the class
of its parent, "Xmh.Paned.Box", followed by its particular class, "Command".
The fully qualified name of a resource is the attribute's name appended to the
object's fully qualified name, and the fully qualified class is its class
appended to the object's class.
The incorporate button might need the following resources: Title string, Font,
Foreground color for its inactive state, Background color for its inactive
state, Foreground color for its active state, and Background color for its
active state. Each resource is considered to be an attribute of the button and,
as such, has a name and a class. For example, the foreground color for the
button in its active state might be named "activeForeground", and its class
might be "Foreground".
When an application looks up a resource (for example, a color), it passes the
complete name and complete class of the resource to a look-up routine. The
resource manager compares this complete specification against the incomplete
specifications of entries in the resource database, finds the best match, and
returns the corresponding value for that entry.
The definitions for the resource manager are contained in <X11/Xresource.h>.
Resource File Syntax
The syntax of a resource file is a sequence of resource lines terminated by
newline characters or the end of the file. The syntax of an individual resource
line is:
ResourceLine = Comment | IncludeFile | ResourceSpec | <empty line>
Comment = "!" {<any character except null or newline>}
IncludeFile = "#" WhiteSpace "include" WhiteSpace FileName WhiteSpace
FileName = <valid filename for operating system>
ResourceSpec = WhiteSpace ResourceName WhiteSpace ":" WhiteSpace Value
ResourceName = [Binding] {Component Binding} ComponentName
Binding = "." | "*"
WhiteSpace = {<space> | <horizontal tab>}
Component = "?" | ComponentName
ComponentName = NameChar {NameChar}
NameChar = "a"-"z" | "A"-"Z" | "0"-"9" | "_" | "-"
Value = {<any character except null or unescaped newline>}
Elements separated by vertical bar (|) are alternatives. Curly braces
({......}) indicate zero or more repetitions of the enclosed elements. Square
brackets ([......]) indicate that the enclosed element is optional. Quotes
("......") are used around literal characters.
IncludeFile lines are interpreted by replacing the line with the contents of
the specified file. The word "include" must be in lowercase. The file name is
interpreted relative to the directory of the file in which the line occurs (for
example, if the file name contains no directory or contains a relative
directory specification).
If a ResourceName contains a contiguous sequence of two or more Binding
characters, the sequence will be replaced with a single ".." character if the
sequence contains only ".." characters; otherwise, the sequence will be
replaced with a single "*" character.
A resource database never contains more than one entry for a given
ResourceName. If a resource file contains multiple lines with the same
ResourceName, the last line in the file is used.
Any white space characters before or after the name or colon in a ResourceSpec
are ignored. To allow a Value to begin with white space, the two-character
sequence "\\space" (backslash followed by space) is recognized and replaced by
a space character, and the two-character sequence "\\tab" (backslash followed
by horizontal tab) is recognized and replaced by a horizontal tab character. To
allow a Value to contain embedded newline characters, the two-character
sequence "\\n" is recognized and replaced by a newline character. To allow a
Value to be broken across multiple lines in a text file, the two-character
sequence "\\newline" (backslash followed by newline) is recognized and removed
from the value. To allow a Value to contain arbitrary character codes, the
four-character sequence "\\nnn", where each n is a digit character in the range
of "0"-"7", is recognized and replaced with a single byte that contains the
octal value specified by the sequence. Finally, the two-character sequence "\
newline" is recognized and replaced with a single backslash.
As an example of these sequences, the following resource line contains a value
consisting of four characters: a backslash, a null, a "z", and a newline:
magic.values: \\000\
z\n
Resource Manager Matching Rules
The algorithm for determining which resource database entry matches a given
query is the heart of the resource manager. All queries must fully specify the
name and class of the desired resource (use of the characters "*" and "?" is
not permitted). The library supports up to 100 components in a full name or
class. Resources are stored in the database with only partially specified names
and classes, using pattern matching constructs. An asterisk (*) is a loose
binding and is used to represent any number of intervening components,
including none. A period (.) is a tight binding and is used to separate
immediately adjacent components. A question mark (?) is used to match any
single component name or class. A database entry cannot end in a loose binding;
the final component (which cannot be the character "?") must be specified. The
lookup algorithm searches the database for the entry that most closely matches
(is most specific for) the full name and class being queried. When more than
one database entry matches the full name and class, precedence rules are used
to select just one.
The full name and class are scanned from left to right (from highest level in
the hierarchy to lowest), one component at a time. At each level, the
corresponding component and/or binding of each matching entry is determined,
and these matching components and bindings are compared according to precedence
rules. Each of the rules is applied at each level before moving to the next
level, until a rule selects a single entry over all others. The rules, in order
of precedence, are:
• An entry that contains a matching component (whether name, class, or the
character "?") takes precedence over entries that elide the level (that is,
entries that match the level in a loose binding).
• An entry with a matching name takes precedence over both entries with a
matching class and entries that match using the character "?". An entry
with a matching class takes precedence over entries that match using the
character "?".
• An entry preceded by a tight binding takes precedence over entries preceded
by a loose binding.
To illustrate these rules, consider the following resource database entries:
xmh*Paned*activeForeground: red (entry A)
*incorporate.Foreground: blue (entry B)
xmh.toc*Command*activeForeground: green (entry C)
xmh.toc*?.Foreground: white (entry D)
xmh.toc*Command.activeForeground: black (entry E)
Consider a query for the resource:
xmh.toc.messagefunctions.incorporate.activeForeground (name)
Xmh.Paned.Box.Command.Foreground (class)
At the first level (xmh, Xmh), rule 1 eliminates entry B. At the second level
(toc, Paned), rule 2 eliminates entry A. At the third level (messagefunctions,
Box), no entries are eliminated. At the fourth level (incorporate, Command),
rule 2 eliminates entry D. At the fifth level (activeForeground, Foreground),
rule 3 eliminates entry C.
Quarks
Most uses of the resource manager involve defining names, classes, and
representation types as string constants. However, always referring to strings
in the resource manager can be slow, because it is so heavily used in some
toolkits. To solve this problem, a shorthand for a string is used in place of
the string in many of the resource manager functions. Simple comparisons can be
performed rather than string comparisons. The shorthand name for a string is
called a quark and is the type XrmQuark. On some occasions, you may want to
allocate a quark that has no string equivalent.
A quark is to a string what an atom is to a string in the server, but its use
is entirely local to your application.
To allocate a new quark, use XrmUniqueQuark.
XrmQuark XrmUniqueQuark(void);
The XrmUniqueQuark function allocates a quark that is guaranteed not to
represent any string that is known to the resource manager.
Each name, class, and representation type is typedef'd as an XrmQuark.
typedef int XrmQuark, *XrmQuarkList;
typedef XrmQuark XrmName;
typedef XrmQuark XrmClass;
typedef XrmQuark XrmRepresentation;
#define NULLQUARK ((XrmQuark) 0)
Lists are represented as null-terminated arrays of quarks. The size of the
array must be large enough for the number of components used.
typedef XrmQuarkList XrmNameList;
typedef XrmQuarkList XrmClassList;
To convert a string to a quark, use XrmStringToQuark or XrmPermStringToQuark.
#define XrmStringToName(string) XrmStringToQuark(string)
#define XrmStringToClass(string) XrmStringToQuark(string)
#define XrmStringToRepresentation(string) XrmStringToQuark(string)
XrmQuark XrmStringToQuark(char *string);
string Specifies the string for which a quark(Ql is to be allocated.
These functions can be used to convert from string to quark representation. If
the string is not in the Host Portable Character Encoding, the conversion is
implementation-dependent. The string argument to XrmStringToQuark need not be
permanently allocated storage. XrmPermStringToQuark is just like
XrmStringToQuark, except that Xlib is permitted to assume the string argument
is permanently allocated, and, hence, that it can be used as the value to be
returned by XrmQuarkToString.
For any given quark, if XrmStringToQuark returns a non-NULL value, all future
calls will return the same value (identical address).
To convert a quark to a string, use XrmQuarkToString.
#define XrmNameToString(name) XrmQuarkToString(name)
#define XrmClassToString(class) XrmQuarkToString(name)
#define XrmRepresentationToString(type) XrmQuarkToString(type)
char *XrmQuarkToString(XrmQuark quark);
quark Specifies the quark for which the equivalent string is desired.
These functions can be used to convert from quark representation to string. The
string pointed to by the return value must not be modified or freed. The
returned string is byte-for-byte equal to the original string passed to one of
the string-to-quark routines. If no string exists for that quark,
XrmQuarkToString returns NULL. For any given quark, if XrmQuarkToString returns
a non-NULL value, all future calls will return the same value (identical
address).
To convert a string with one or more components to a quark list, use
XrmStringToQuarkList.
#define XrmStringToNameList(str,name) XrmStringToQuarkList((str), (name))
#define XrmStringToClassList(str,class) XrmStringToQuarkList((str), (class))
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, *XrmBindingList;
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.
Returns the binding list. The caller must allocate sufficient
bindings_return space for the binding list before calling
XrmStringToBindingQuarkList.
Returns the list of quarks. The caller must allocate sufficient
quarks_return 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), value)
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 following 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 in argv */
XrmoptionSkipLine, /* Ignore this option and the rest of argv */
XrmoptionSkipNArgs /* Ignore this option and the next
\ \ \ XrmOptionDescRec.value arguments in argv */
} XrmOptionKind;
Note that XrmoptionSkipArg is equivalent to XrmoptionSkipNArgs with the
XrmOptionDescRec.value field containing the value one. Note also that the value
zero for XrmoptionSkipNArgs indicates that only the option itself is to be
skipped.
typedef struct {
char *option; /* Option specification string in argv */
char *specifier; /* Binding and resource name (sans application name) */
XrmOptionKind argKind; /* Which style of option it is */
XPointer value; /* Value to provide if XrmoptionNoArg or
\ \ \ XrmoptionSkipNArgs */
} XrmOptionDescRec, *XrmOptionDescList;
To load a resource database from a C command line, use XrmParseCommand.
void XrmParseCommand(XrmDatabase *database, XrmOptionDescList table, int
table_count, char *name, int *argc_in_out, char **argv_in_out);
database Specifies the resource database.
table Specifies the table of command line arguments to be parsed.
table_count Specifies the number of entries in the table.
name Specifies the application name.
argc_in_out Specifies the number of arguments and returns the number of
remaining arguments.
argv_in_out Specifies the command line arguments and returns the remaining
arguments.
The XrmParseCommand function parses an (argc, argv) pair according to the
specified option table, loads recognized options into the specified database
with type ``String,'' and modifies the (argc, argv) pair to remove all
recognized options. If database contains NULL, XrmParseCommand creates a new
database and returns a pointer to it. Otherwise, entries are added to the
database specified. If a database is created, it is created in the current
locale.
The specified table is used to parse the command line. Recognized options in
the table are removed from argv, and entries are added to the specified
resource database in the order they occur in argv. The table entries contain
information on the option string, the option name, the style of option, and a
value to provide if the option kind is XrmoptionNoArg. The option names are
compared byte-for-byte to arguments in argv, independent of any locale. The
resource values given in the table are stored in the resource database without
modification. All resource database entries are created using a ``String''
representation type. The argc argument specifies the number of arguments in
argv and is set on return to the remaining number of arguments that were not
parsed. The name argument should be the name of your application for use in
building the database entry. The name argument is prefixed to the resourceName
in the option table before storing a database entry. The name argument is
treated as a single component, even if it has embedded periods. No separating
(binding) character is inserted, so the table must contain either a period (.)
or an asterisk (*) as the first character in each resourceName entry. To
specify a more completely qualified resource name, the resourceName entry can
contain multiple components. If the name argument and the resourceNames are not
in the Host Portable Character Encoding, the result is
implementation-dependent.
The following provides a sample option table:
static XrmOptionDescRec opTable[] = {
{"-background", "*background", XrmoptionSepArg, (XPointer) NULL},
{"-bd", "*borderColor", XrmoptionSepArg, (XPointer) NULL},
{"-bg", "*background", XrmoptionSepArg, (XPointer) NULL},
{"-borderwidth", "*TopLevelShell.borderWidth", XrmoptionSepArg, (XPointer) NULL},
{"-bordercolor", "*borderColor", XrmoptionSepArg, (XPointer) NULL},
{"-bw", "*TopLevelShell.borderWidth", XrmoptionSepArg, (XPointer) NULL},
{"-display", ".display", XrmoptionSepArg, (XPointer) NULL},
{"-fg", "*foreground", XrmoptionSepArg, (XPointer) NULL},
{"-fn", "*font", XrmoptionSepArg, (XPointer) NULL},
{"-font", "*font", XrmoptionSepArg, (XPointer) NULL},
{"-foreground", "*foreground", XrmoptionSepArg, (XPointer) NULL},
{"-geometry", ".TopLevelShell.geometry", XrmoptionSepArg, (XPointer) NULL},
{"-iconic", ".TopLevelShell.iconic", XrmoptionNoArg, (XPointer) "on"},
{"-name", ".name", XrmoptionSepArg, (XPointer) NULL},
{"-reverse", "*reverseVideo", XrmoptionNoArg, (XPointer) "on"},
{"-rv", "*reverseVideo", XrmoptionNoArg, (XPointer) "on"},
{"-synchronous", "*synchronous", XrmoptionNoArg, (XPointer) "on"},
{"-title", ".TopLevelShell.title", XrmoptionSepArg, (XPointer) NULL},
{"-xrm", NULL, XrmoptionResArg, (XPointer) NULL},
};
In this table, if the -background (or -bg) option is used to set background
colors, the stored resource specifier matches all resources of attribute
background. If the -borderwidth option is used, the stored resource specifier
applies only to border width attributes of class TopLevelShell (that is,
outer-most windows, including pop-up windows). If the -title option is used to
set a window name, only the topmost application windows receive the resource.
When parsing the command line, any unique unambiguous abbreviation for an
option name in the table is considered a match for the option. Note that
uppercase and lowercase matter.
Chapter 16. Application Utility Functions
Table of Contents
Using Keyboard Utility Functions
KeySym Classification Macros
Using Latin-1 Keyboard Event Functions
Allocating Permanent Storage
Parsing the Window Geometry
Manipulating Regions
Creating, Copying, or Destroying Regions
Moving or Shrinking Regions
Computing with Regions
Determining if Regions Are Empty or Equal
Locating a Point or a Rectangle in a Region
Using Cut Buffers
Determining the Appropriate Visual Type
Manipulating Images
Manipulating Bitmaps
Using the Context Manager
Once you have initialized the X system, you can use the Xlib utility functions
to:
• Use keyboard utility functions
• Use Latin-1 keyboard event functions
• Allocate permanent storage
• Parse the window geometry
• Manipulate regions
• Use cut buffers
• Determine the appropriate visual type
• Manipulate images
• Manipulate bitmaps
• Use the context manager
As a group, the functions discussed in this chapter provide the functionality
that is frequently needed and that spans toolkits. Many of these functions do
not generate actual protocol requests to the server.
Using Keyboard Utility Functions
This section discusses mapping between KeyCodes and KeySyms, classifying
KeySyms, and mapping between KeySyms and string names. The first three
functions in this section operate on a cached copy of the server keyboard
mapping. The first four KeySyms for each KeyCode are modified according to the
rules given in section 12.7. To obtain the untransformed KeySyms defined for a
key, use the functions described in section 12.7.
To obtain a KeySym for the KeyCode of an event, use XLookupKeysym.
KeySym XLookupKeysym(XKeyEvent *key_event, int index);
key_event Specifies the KeyPress or KeyRelease event.
index Specifies the index into the KeySyms list for the event's KeyCode.
The XLookupKeysym function uses a given keyboard event and the index you
specified to return the KeySym from the list that corresponds to the KeyCode
member in the XKeyPressedEvent or XKeyReleasedEvent structure. If no KeySym is
defined for the KeyCode of the event, XLookupKeysym returns NoSymbol.
To obtain a KeySym for a specific KeyCode, use XKeycodeToKeysym.
KeySym XKeycodeToKeysym(Display *display, KeyCode keycode, int index);
display Specifies the connection to the X server.
keycode Specifies the KeyCode.
index Specifies the element of KeyCode vector.
The XKeycodeToKeysym function uses internal Xlib tables and returns the KeySym
defined for the specified KeyCode and the element of the KeyCode vector. If no
symbol is defined, XKeycodeToKeysym returns NoSymbol.
To obtain a KeyCode for a key having a specific KeySym, use XKeysymToKeycode.
KeyCode XKeysymToKeycode(Display *display, KeySym keysym);
display Specifies the connection to the X server.
keysym Specifies the KeySym that is to be searched for.
If the specified KeySym is not defined for any KeyCode, XKeysymToKeycode
returns zero.
The mapping between KeyCodes and KeySyms is cached internal to Xlib. When this
information is changed at the server, an Xlib function must be called to
refresh the cache. To refresh the stored modifier and keymap information, use
XRefreshKeyboardMapping.
XRefreshKeyboardMapping(XMappingEvent *event_map);
event_map Specifies the mapping event that is to be used.
The XRefreshKeyboardMapping function refreshes the stored modifier and keymap
information. You usually call this function when a MappingNotify event with a
request member of MappingKeyboard or MappingModifier occurs. The result is to
update Xlib's knowledge of the keyboard.
To obtain the uppercase and lowercase forms of a KeySym, use XConvertCase.
void XConvertCase(KeySym keysym, KeySym *lower_return, KeySym *upper_return);
keysym Specifies the KeySym that is to be converted.
lower_return Returns the lowercase form of keysym, or keysym.
upper_return Returns the uppercase form of keysym, or keysym.
The XConvertCase function returns the uppercase and lowercase forms of the
specified Keysym, if the KeySym is subject to case conversion; otherwise, the
specified KeySym is returned to both lower_return and upper_return. Support for
conversion of other than Latin and Cyrillic KeySyms is
implementation-dependent.
KeySyms have string names as well as numeric codes. To convert the name of the
KeySym to the KeySym code, use XStringToKeysym.
KeySym XStringToKeysym(char *string);
string Specifies the name of the KeySym that is to be converted.
Standard KeySym names are obtained from <X11/keysymdef.h> by removing the XK_
prefix from each name. KeySyms that are not part of the Xlib standard also may
be obtained with this function. The set of KeySyms that are available in this
manner and the mechanisms by which Xlib obtains them is
implementation-dependent.
If the KeySym name is not in the Host Portable Character Encoding, the result
is implementation-dependent. If the specified string does not match a valid
KeySym, XStringToKeysym returns NoSymbol.
To convert a KeySym code to the name of the KeySym, use XKeysymToString.
char *XKeysymToString(KeySym keysym);
keysym Specifies the KeySym that is to be converted.
The returned string is in a static area and must not be modified. The returned
string is in the Host Portable Character Encoding. If the specified KeySym is
not defined, XKeysymToString returns a NULL.
KeySym Classification Macros
You may want to test if a KeySym is, for example, on the keypad or on one of
the function keys. You can use KeySym macros to perform the following tests.
IsCursorKey(keysym)
keysym Specifies the KeySym that is to be tested.
Returns True if the specified KeySym is a cursor key.
IsFunctionKey(keysym)
keysym Specifies the KeySym that is to be tested.
Returns True if the specified KeySym is a function key.
IsKeypadKey(keysym)
keysym Specifies the KeySym that is to be tested.
Returns True if the specified KeySym is a standard keypad key.
IsPrivateKeypadKey(keysym)
keysym Specifies the KeySym that is to be tested.
Returns True if the specified KeySym is a vendor-private keypad key.
IsMiscFunctionKey(keysym)
keysym Specifies the KeySym that is to be tested.
Returns True if the specified KeySym is a miscellaneous function key.
IsModifierKey(keysym)
keysym Specifies the KeySym that is to be tested.
Returns True if the specified KeySym is a modifier key.
IsPFKey(keysym)
keysym Specifies the KeySym that is to be tested.
Returns True if the specified KeySym is a PF key.
Using Latin-1 Keyboard Event Functions
Chapter 13 describes internationalized text input facilities, but sometimes it
is expedient to write an application that only deals with Latin-1 characters
and ASCII controls, so Xlib provides a simple function for that purpose.
XLookupString handles the standard modifier semantics described in section
12.7. This function does not use any of the input method facilities described
in chapter 13 and does not depend on the current locale.
To map a key event to an ISO Latin-1 string, use XLookupString.
int XLookupString(XKeyEvent *event_struct, char *buffer_return, int
bytes_buffer, KeySym *keysym_return, XComposeStatus *status_in_out);
event_struct Specifies the key event structure to be used. You can pass
XKeyPressedEvent or XKeyReleasedEvent.
buffer_return Returns the translated characters.
bytes_buffer Specifies the length of the buffer. No more than bytes_buffer of
translation are returned.
keysym_return Returns the KeySym computed from the event if this argument is
not NULL.
status_in_out Specifies or returns the XComposeStatus structure or NULL.
The XLookupString function translates a key event to a KeySym and a string. The
KeySym is obtained by using the standard interpretation of the Shift, Lock,
group, and numlock modifiers as defined in the X Protocol specification. If the
KeySym has been rebound (see XRebindKeysym), the bound string will be stored in
the buffer. Otherwise, the KeySym is mapped, if possible, to an ISO Latin-1
character or (if the Control modifier is on) to an ASCII control character, and
that character is stored in the buffer. XLookupString returns the number of
characters that are stored in the buffer.
If present (non-NULL), the XComposeStatus structure records the state, which is
private to Xlib, that needs preservation across calls to XLookupString to
implement compose processing. The creation of XComposeStatus structures is
implementation-dependent; a portable program must pass NULL for this argument.
XLookupString depends on the cached keyboard information mentioned in the
previous section, so it is necessary to use XRefreshKeyboardMapping to keep
this information up-to-date.
To rebind the meaning of a KeySym for XLookupString, use XRebindKeysym.
XRebindKeysym(Display *display, KeySym keysym, KeySym list[ ], int mod_count,
unsignedchar *string, int num_bytes);
display Specifies the connection to the X server.
keysym Specifies the KeySym that is to be rebound.
list Specifies the KeySyms to be used as modifiers.
mod_count Specifies the number of modifiers in the modifier list.
string Specifies the string that is copied and will be returned by
XLookupString.
num_bytes Specifies the number of bytes in the string argument.
The XRebindKeysym function can be used to rebind the meaning of a KeySym for
the client. It does not redefine any key in the X server but merely provides an
easy way for long strings to be attached to keys. XLookupString returns this
string when the appropriate set of modifier keys are pressed and when the
KeySym would have been used for the translation. No text conversions are
performed; the client is responsible for supplying appropriately encoded
strings. Note that you can rebind a KeySym that may not exist.
Allocating Permanent Storage
To allocate some memory you will never give back, use Xpermalloc.
char *Xpermalloc(unsigned int size);
The Xpermalloc function allocates storage that can never be freed for the life
of the program. The memory is allocated with alignment for the C type double.
This function may provide some performance and space savings over the standard
operating system memory allocator.
Parsing the Window Geometry
To parse standard window geometry strings, use XParseGeometry.
int XParseGeometry(char *parsestring, int *x_return, int *y_return, unsigned
int *width_return, unsigned int *height_return);
parsestring Specifies the string you want to parse.
x_return
y_return Return the x and y offsets.
width_return
height_return Return the width and height determined.
By convention, X applications use a standard string to indicate window size and
placement. XParseGeometry makes it easier to conform to this standard because
it allows you to parse the standard window geometry. Specifically, this
function lets you parse strings of the form:
[=][<width>{xX}<height>][{+-}<xoffset>{+-}<yoffset>]
The fields map into the arguments associated with this function. (Items
enclosed in < > are integers, items in [ ] are optional, and items enclosed in
{ } indicate ``choose one of.'' Note that the brackets should not appear in the
actual string.) If the string is not in the Host Portable Character Encoding,
the result is implementation-dependent.
The XParseGeometry function returns a bitmask that indicates which of the four
values (width, height, xoffset, and yoffset) were actually found in the string
and whether the x and y values are negative. By convention, −0 is not equal to
+0, because the user needs to be able to say ``position the window relative to
the right or bottom edge.'' For each value found, the corresponding argument is
updated. For each value not found, the argument is left unchanged. The bits are
represented by XValue, YValue, WidthValue, HeightValue, XNegative, or YNegative
and are defined in <X11/Xutil.h>. They will be set whenever one of the values
is defined or one of the signs is set.
If the function returns either the XValue or YValue flag, you should place the
window at the requested position.
To construct a window's geometry information, use XWMGeometry.
int XWMGeometry(Display *display, int screen, char *user_geom, char *def_geom,
unsigned int bwidth, XSizeHints *hints, int *x_return, int *y_return, int
*width_return, int *height_return, int *gravity_return);
display Specifies the connection to the X server.
screen Specifies the screen.
user_geom Specifies the user-specified geometry or NULL.
def_geom Specifies the application's default geometry or NULL.
bwidth Specifies the border width.
hints Specifies the size hints for the window in its normal state.
x_return
y_return Return the x and y offsets.
width_return
height_return Return the width and height determined.
gravity_return Returns the window gravity.
The XWMGeometry function combines any geometry information (given in the format
used by XParseGeometry) specified by the user and by the calling program with
size hints (usually the ones to be stored in WM_NORMAL_HINTS) and returns the
position, size, and gravity (NorthWestGravity, NorthEastGravity,
SouthEastGravity, or SouthWestGravity) that describe the window. If the base
size is not set in the XSizeHints structure, the minimum size is used if set.
Otherwise, a base size of zero is assumed. If no minimum size is set in the
hints structure, the base size is used. A mask (in the form returned by
XParseGeometry) that describes which values came from the user specification
and whether or not the position coordinates are relative to the right and
bottom edges is returned. Note that these coordinates will have already been
accounted for in the x_return and y_return values.
Note that invalid geometry specifications can cause a width or height of zero
to be returned. The caller may pass the address of the hints win_gravity field
as gravity_return to update the hints directly.
Manipulating Regions
Regions are arbitrary sets of pixel locations. Xlib provides functions for
manipulating regions. The opaque type Region is defined in <X11/Xutil.h>. Xlib
provides functions that you can use to manipulate regions. This section
discusses how to:
• Create, copy, or destroy regions
• Move or shrink regions
• Compute with regions
• Determine if regions are empty or equal
• Locate a point or rectangle in a region
Creating, Copying, or Destroying Regions
To create a new empty region, use XCreateRegion.
Region XCreateRegion(void);
To generate a region from a polygon, use XPolygonRegion.
Region XPolygonRegion(XPoint points[], int n, int fill_rule);
points Specifies an array of points.
n Specifies the number of points in the polygon.
fill_rule Specifies the fill-rule you want to set for the specified GC. You can
pass EvenOddRule or WindingRule.
The XPolygonRegion function returns a region for the polygon defined by the
points array. For an explanation of fill_rule, see XCreateGC.
To set the clip-mask of a GC to a region, use XSetRegion.
XSetRegion(Display *display, GC gc, Region r);
display Specifies the connection to the X server.
gc Specifies the GC.
r Specifies the region.
The XSetRegion function sets the clip-mask in the GC to the specified region.
The region is specified relative to the drawable's origin. The resulting GC
clip origin is implementation-dependent. Once it is set in the GC, the region
can be destroyed.
To deallocate the storage associated with a specified region, use
XDestroyRegion.
XDestroyRegion(Region r);
r Specifies the region.
Moving or Shrinking Regions
To move a region by a specified amount, use XOffsetRegion.
XOffsetRegion(Region r, int dx, int dy);
r Specifies the region.
dx
dy Specify the x and y coordinates, which define the amount you want to move
the specified region.
To reduce a region by a specified amount, use XShrinkRegion.
XShrinkRegion(Region r, int dx, int dy);
r Specifies the region.
dx
dy Specify the x and y coordinates, which define the amount you want to shrink
the specified region.
Positive values shrink the size of the region, and negative values expand the
region.
Computing with Regions
To generate the smallest rectangle enclosing a region, use XClipBox.
XClipBox(Region r, XRectangle *rect_return);
r Specifies the region.
rect_return Returns the smallest enclosing rectangle.
The XClipBox function returns the smallest rectangle enclosing the specified
region.
To compute the intersection of two regions, use XIntersectRegion.
XIntersectRegion(Region sra, Region srb, Region dr_return);
sra
srb Specify the two regions with which you want to perform the
computation.
dr_return Returns the result of the computation.
To compute the union of two regions, use XUnionRegion.
XUnionRegion(Region sra, Region srb, Region dr_return);
sra
srb Specify the two regions with which you want to perform the
computation.
dr_return Returns the result of the computation.
To create a union of a source region and a rectangle, use XUnionRectWithRegion.
XUnionRectWithRegion(XRectangle *rectangle, Region src_region, Region
dest_region_return);
rectangle Specifies the rectangle.
src_region Specifies the source region to be used.
dest_region_return Returns the destination region.
The XUnionRectWithRegion function updates the destination region from a union
of the specified rectangle and the specified source region.
To subtract two regions, use XSubtractRegion.
XSubtractRegion(Region sra, Region srb, Region dr_return);
sra
srb Specify the two regions with which you want to perform the
computation.
dr_return Returns the result of the computation.
The XSubtractRegion function subtracts srb from sra and stores the results in
dr_return.
To calculate the difference between the union and intersection of two regions,
use XXorRegion.
XXorRegion(Region sra, Region srb, Region dr_return);
sra
srb Specify the two regions with which you want to perform the
computation.
dr_return Returns the result of the computation.
Determining if Regions Are Empty or Equal
To determine if the specified region is empty, use XEmptyRegion.
Bool XEmptyRegion(Region r);
r Specifies the region.
The XEmptyRegion function returns True if the region is empty.
To determine if two regions have the same offset, size, and shape, use
XEqualRegion.
Bool XEqualRegion(Region r1, Region r2);
r1
r2 Specify the two regions.
The XEqualRegion function returns True if the two regions have the same offset,
size, and shape.
Locating a Point or a Rectangle in a Region
To determine if a specified point resides in a specified region, use
XPointInRegion.
Bool XPointInRegion(Region r, int x, int y);
r Specifies the region.
x
y Specify the x and y coordinates, which define the point.
The XPointInRegion function returns True if the point (x, y) is contained in
the region r.
To determine if a specified rectangle is inside a region, use XRectInRegion.
int XRectInRegion(Region r, int x, int y, unsigned int width, unsigned int
height);
r Specifies the region.
x
y Specify the x and y coordinates, which define the coordinates of the
upper-left corner of the rectangle.
width
height Specify the width and height, which define the rectangle.
The XRectInRegion function returns RectangleIn if the rectangle is entirely in
the specified region, RectangleOut if the rectangle is entirely out of the
specified region, and RectanglePart if the rectangle is partially in the
specified region.
Using Cut Buffers
Xlib provides functions to manipulate cut buffers, a very simple form of
cut-and-paste inter-client communication. Selections are a much more powerful
and useful mechanism for interchanging data between client (see section 4.5)
and generally should be used instead of cut buffers.
Cut buffers are implemented as properties on the first root window of the
display. The buffers can only contain text, in the STRING encoding. The text
encoding is not changed by Xlib when fetching or storing. Eight buffers are
provided and can be accessed as a ring or as explicit buffers (numbered 0
through 7).
To store data in cut buffer 0, use XStoreBytes.
XStoreBytes(Display *display, char *bytes, int nbytes);
display Specifies the connection to the X server.
bytes Specifies the bytes, which are not necessarily ASCII or
null-terminated.
nbytes Specifies the number of bytes to be stored.
The data can have embedded null characters and need not be null-terminated. The
cut buffer's contents can be retrieved later by any client calling XFetchBytes.
XStoreBytes can generate a BadAlloc error.
To store data in a specified cut buffer, use XStoreBuffer.
XStoreBuffer(Display *display, char *bytes, int nbytes, int buffer);
display Specifies the connection to the X server.
bytes Specifies the bytes, which are not necessarily ASCII or
null-terminated.
nbytes Specifies the number of bytes to be stored.
buffer Specifies the buffer in which you want to store the bytes.
If an invalid buffer is specified, the call has no effect. The data can have
embedded null characters and need not be null-terminated.
XStoreBuffer can generate a BadAlloc error.
To return data from cut buffer 0, use XFetchBytes.
char *XFetchBytes(Display *display, int *nbytes_return);
display Specifies the connection to the X server.
nbytes_return Returns the number of bytes in the buffer.
The XFetchBytes function returns the number of bytes in the nbytes_return
argument, if the buffer contains data. Otherwise, the function returns NULL and
sets nbytes to 0. The appropriate amount of storage is allocated and the
pointer returned. The client must free this storage when finished with it by
calling XFree.
To return data from a specified cut buffer, use XFetchBuffer.
char *XFetchBuffer(Display *display, int *nbytes_return, int buffer);
display Specifies the connection to the X server.
nbytes_return Returns the number of bytes in the buffer.
buffer Specifies the buffer from which you want the stored data
returned.
The XFetchBuffer function returns zero to the nbytes_return argument if there
is no data in the buffer or if an invalid buffer is specified.
To rotate the cut buffers, use XRotateBuffers.
XRotateBuffers(Display *display, int rotate);
display Specifies the connection to the X server.
rotate Specifies how much to rotate the cut buffers.
The XRotateBuffers function rotates the cut buffers, such that buffer 0 becomes
buffer n, buffer 1 becomes n + 1 mod 8, and so on. This cut buffer numbering is
global to the display. Note that XRotateBuffers generates BadMatch errors if
any of the eight buffers have not been created.
Determining the Appropriate Visual Type
A single display can support multiple screens. Each screen can have several
different visual types supported at different depths. You can use the functions
described in this section to determine which visual to use for your
application.
The functions in this section use the visual information masks and the
XVisualInfo structure, which is defined in <X11/Xutil.h> and contains:
/* Visual information mask bits */
#define VisualNoMask 0x0
#define VisualIDMask 0x1
#define VisualScreenMask 0x2
#define VisualDepthMask 0x4
#define VisualClassMask 0x8
#define VisualRedMaskMask 0x10
#define VisualGreenMaskMask 0x20
#define VisualBlueMaskMask 0x40
#define VisualColormapSizeMask 0x80
#define VisualBitsPerRGBMask 0x100
#define VisualAllMask 0x1FF
/* Values */
typedef struct {
Visual *visual;
VisualID visualid;
int screen;
unsigned int depth;
int class;
unsigned long red_mask;
unsigned long green_mask;
unsigned long blue_mask;
int colormap_size;
int bits_per_rgb;
} XVisualInfo;
To obtain a list of visual information structures that match a specified
template, use XGetVisualInfo.
XVisualInfo *XGetVisualInfo(Display *display, long vinfo_mask, XVisualInfo
*vinfo_template, int *nitems_return);
display Specifies the connection to the X server.
vinfo_mask Specifies the visual mask value.
vinfo_template Specifies the visual attributes that are to be used in matching
the visual structures.
nitems_return Returns the number of matching visual structures.
The XGetVisualInfo function returns a list of visual structures that have
attributes equal to the attributes specified by vinfo_template. If no visual
structures match the template using the specified vinfo_mask, XGetVisualInfo
returns a NULL. To free the data returned by this function, use XFree.
To obtain the visual information that matches the specified depth and class of
the screen, use XMatchVisualInfo.
Status XMatchVisualInfo(Display *display, int screen, int depth, int class,
XVisualInfo *vinfo_return);
display Specifies the connection to the X server.
screen Specifies the screen.
depth Specifies the depth of the screen.
class Specifies the class of the screen.
vinfo_return Returns the matched visual information.
The XMatchVisualInfo function returns the visual information for a visual that
matches the specified depth and class for a screen. Because multiple visuals
that match the specified depth and class can exist, the exact visual chosen is
undefined. If a visual is found, XMatchVisualInfo returns nonzero and the
information on the visual to vinfo_return. Otherwise, when a visual is not
found, XMatchVisualInfo returns zero.
Manipulating Images
Xlib provides several functions that perform basic operations on images. All
operations on images are defined using an XImage structure, as defined in <X11/
Xlib.h>. Because the number of different types of image formats can be very
large, this hides details of image storage properly from applications.
This section describes the functions for generic operations on images.
Manufacturers can provide very fast implementations of these for the formats
frequently encountered on their hardware. These functions are neither
sufficient nor desirable to use for general image processing. Rather, they are
here to provide minimal functions on screen format images. The basic operations
for getting and putting images are XGetImage and XPutImage.
Note that no functions have been defined, as yet, to read and write images to
and from disk files.
The XImage structure describes an image as it exists in the client's memory.
The user can request that some of the members such as height, width, and
xoffset be changed when the image is sent to the server. Note that
bytes_per_line in concert with offset can be used to extract a subset of the
image. Other members (for example, byte order, bitmap_unit, and so forth) are
characteristics of both the image and the server. If these members differ
between the image and the server, XPutImage makes the appropriate conversions.
The first byte of the first line of plane n must be located at the address
(data + (n * height * bytes_per_line)). For a description of the XImage
structure, see section 8.7.
To allocate an XImage structure and initialize it with image format values from
a display, use XCreateImage.
XImage *XCreateImage(Display *display, Visual *visual, unsigned int depth, int
format, int offset, char *data, unsigned int width, unsigned int height, int
bitmap_pad, int bytes_per_line);
display Specifies the connection to the X server.
visual Specifies the Visual structure.
depth Specifies the depth of the image.
format Specifies the format for the image. You can pass XYBitmap,
XYPixmap, or ZPixmap.
offset Specifies the number of pixels to ignore at the beginning of the
scanline.
data Specifies the image data.
width Specifies the width of the image, in pixels.
height Specifies the height of the image, in pixels.
Specifies the quantum of a scanline (8, 16, or 32). In other
bitmap_pad words, the start of one scanline is separated in client memory
from the start of the next scanline by an integer multiple of
this many bits.
bytes_per_line Specifies the number of bytes in the client image between the
start of one scanline and the start of the next.
The XCreateImage function allocates the memory needed for an XImage structure
for the specified display but does not allocate space for the image itself.
Rather, it initializes the structure byte-order, bit-order, and bitmap-unit
values from the display and returns a pointer to the XImage structure. The red,
green, and blue mask values are defined for Z format images only and are
derived from the Visual structure passed in. Other values also are passed in.
The offset permits the rapid displaying of the image without requiring each
scanline to be shifted into position. If you pass a zero value in
bytes_per_line, Xlib assumes that the scanlines are contiguous in memory and
calculates the value of bytes_per_line itself.
Note that when the image is created using XCreateImage, XGetImage, or XSubImage
, the destroy procedure that the XDestroyImage function calls frees both the
image structure and the data pointed to by the image structure.
The basic functions used to get a pixel, set a pixel, create a subimage, and
add a constant value to an image are defined in the image object. The functions
in this section are really macro invocations of the functions in the image
object and are defined in <X11/Xutil.h>.
To obtain a pixel value in an image, use XGetPixel.
unsigned long XGetPixel(XImage *ximage, int x, int y);
ximage Specifies the image.
x
y Specify the x and y coordinates.
The XGetPixel function returns the specified pixel from the named image. The
pixel value is returned in normalized format (that is, the least significant
byte of the long is the least significant byte of the pixel). The image must
contain the x and y coordinates.
To set a pixel value in an image, use XPutPixel.
XPutPixel(XImage *ximage, int x, int y, unsigned long pixel);
ximage Specifies the image.
x
y Specify the x and y coordinates.
pixel Specifies the new pixel value.
The XPutPixel function overwrites the pixel in the named image with the
specified pixel value. The input pixel value must be in normalized format (that
is, the least significant byte of the long is the least significant byte of the
pixel). The image must contain the x and y coordinates.
To create a subimage, use XSubImage.
XImage *XSubImage(XImage *ximage, int x, int y, unsigned int subimage_width,
unsigned int subimage_height);
ximage Specifies the image.
x
y Specify the x and y coordinates.
subimage_width Specifies the width of the new subimage, in pixels.
subimage_height Specifies the height of the new subimage, in pixels.
The XSubImage function creates a new image that is a subsection of an existing
one. It allocates the memory necessary for the new XImage structure and returns
a pointer to the new image. The data is copied from the source image, and the
image must contain the rectangle defined by x, y, subimage_width, and
subimage_height.
To increment each pixel in an image by a constant value, use XAddPixel.
XAddPixel(XImage *ximage, long value);
ximage Specifies the image.
value Specifies the constant value that is to be added.
The XAddPixel function adds a constant value to every pixel in an image. It is
useful when you have a base pixel value from allocating color resources and
need to manipulate the image to that form.
To deallocate the memory allocated in a previous call to XCreateImage, use
XDestroyImage.
XDestroyImage(XImage *ximage);
ximage Specifies the image.
The XDestroyImage function deallocates the memory associated with the XImage
structure.
Note that when the image is created using XCreateImage, XGetImage, or XSubImage
, the destroy procedure that this macro calls frees both the image structure
and the data pointed to by the image structure.
Manipulating Bitmaps
Xlib provides functions that you can use to read a bitmap from a file, save a
bitmap to a file, or create a bitmap. This section describes those functions
that transfer bitmaps to and from the client's file system, thus allowing their
reuse in a later connection (for example, from an entirely different client or
to a different display or server).
The X version 11 bitmap file format is:
#define name_width width
#define name_height height
#define name_x_hot x
#define name_y_hot y
static unsigned char name_bits[] = { 0xNN,... }
The lines for the variables ending with _x_hot and _y_hot suffixes are optional
because they are present only if a hotspot has been defined for this bitmap.
The lines for the other variables are required. The word ``unsigned'' is
optional; that is, the type of the _bits array can be ``char'' or ``unsigned
char''. The _bits array must be large enough to contain the size bitmap. The
bitmap unit is 8.
To read a bitmap from a file and store it in a pixmap, use XReadBitmapFile.
int XReadBitmapFile(Display *display, Drawable d, char *filename, unsigned int
*width_return, unsigned int *height_return, Pixmap *bitmap_return, int
*x_hot_return, int *y_hot_return);
display Specifies the connection to the X server.
d Specifies the drawable that indicates the screen.
filename Specifies the file name to use. The format of the file name is
operating-system dependent.
width_return
height_return Return the width and height values of the read in bitmap file.
bitmap_return Returns the bitmap that is created.
x_hot_return
y_hot_return Return the hotspot coordinates.
The XReadBitmapFile function reads in a file containing a bitmap. The file is
parsed in the encoding of the current locale. The ability to read other than
the standard format is implementation-dependent. If the file cannot be opened,
XReadBitmapFile returns BitmapOpenFailed. If the file can be opened but does
not contain valid bitmap data, it returns BitmapFileInvalid. If insufficient
working storage is allocated, it returns BitmapNoMemory. If the file is
readable and valid, it returns BitmapSuccess.
XReadBitmapFile returns the bitmap's height and width, as read from the file,
to width_return and height_return. It then creates a pixmap of the appropriate
size, reads the bitmap data from the file into the pixmap, and assigns the
pixmap to the caller's variable bitmap. The caller must free the bitmap using
XFreePixmap when finished. If name_x_hot and name_y_hot exist, XReadBitmapFile
returns them to x_hot_return and y_hot_return; otherwise, it returns −1,−1.
XReadBitmapFile can generate BadAlloc, BadDrawable, and BadGC errors.
To read a bitmap from a file and return it as data, use XReadBitmapFileData.
int XReadBitmapFileData(char *filename, unsigned int *width_return, unsigned
int *height_return, unsignedchar *data_return, int *x_hot_return, int
*y_hot_return);
filename Specifies the file name to use. The format of the file name is
operating-system dependent.
width_return
height_return Return the width and height values of the read in bitmap file.
data_return Returns the bitmap data.
x_hot_return
y_hot_return Return the hotspot coordinates.
The XReadBitmapFileData function reads in a file containing a bitmap, in the
same manner as XReadBitmapFile, but returns the data directly rather than
creating a pixmap in the server. The bitmap data is returned in data_return;
the client must free this storage when finished with it by calling XFree. The
status and other return values are the same as for XReadBitmapFile.
To write out a bitmap from a pixmap to a file, use XWriteBitmapFile.
int XWriteBitmapFile(Display *display, char *filename, Pixmap bitmap, unsigned
int width, unsigned int height, int x_hot, int y_hot);
display Specifies the connection to the X server.
filename Specifies the file name to use. The format of the file name is
operating-system dependent.
bitmap Specifies the bitmap.
width
height Specify the width and height.
x_hot
y_hot Specify where to place the hotspot coordinates (or −1,−1 if none are
present) in the file.
The XWriteBitmapFile function writes a bitmap out to a file in the X Version 11
format. The name used in the output file is derived from the file name by
deleting the directory prefix. The file is written in the encoding of the
current locale. If the file cannot be opened for writing, it returns
BitmapOpenFailed. If insufficient memory is allocated, XWriteBitmapFile returns
BitmapNoMemory; otherwise, on no error, it returns BitmapSuccess. If x_hot and
y_hot are not −1, −1, XWriteBitmapFile writes them out as the hotspot
coordinates for the bitmap.
XWriteBitmapFile can generate BadDrawable and BadMatch errors.
To create a pixmap and then store bitmap-format data into it, use
XCreatePixmapFromBitmapData.
Pixmap XCreatePixmapFromBitmapData(Display *display, Drawable d, char *data,
unsigned int width, unsigned int height, unsigned long fg, unsigned long bg,
unsigned int depth);
display Specifies the connection to the X server.
d Specifies the drawable that indicates the screen.
data Specifies the data in bitmap format.
width
height Specify the width and height.
fg
bg Specify the foreground and background pixel values to use.
depth Specifies the depth of the pixmap.
The XCreatePixmapFromBitmapData function creates a pixmap of the given depth
and then does a bitmap-format XPutImage of the data into it. The depth must be
supported by the screen of the specified drawable, or a BadMatch error results.
XCreatePixmapFromBitmapData can generate BadAlloc, BadDrawable, BadGC, and
BadValue errors.
To include a bitmap written out by XWriteBitmapFile in a program directly, as
opposed to reading it in every time at run time, use XCreateBitmapFromData.
Pixmap XCreateBitmapFromData(Display *display, Drawable d, char *data, unsigned
int width, unsigned int height);
display Specifies the connection to the X server.
d Specifies the drawable that indicates the screen.
data Specifies the location of the bitmap data.
width
height Specify the width and height.
The XCreateBitmapFromData function allows you to include in your C program
(using #include) a bitmap file that was written out by XWriteBitmapFile (X
version 11 format only) without reading in the bitmap file. The following
example creates a gray bitmap:
#include "gray.bitmap"
Pixmap bitmap;
bitmap = XCreateBitmapFromData(display, window, gray_bits, gray_width, gray_height);
If insufficient working storage was allocated, XCreateBitmapFromData returns
None. It is your responsibility to free the bitmap using XFreePixmap when
finished.
XCreateBitmapFromData can generate BadAlloc and BadGC errors.
Using the Context Manager
The context manager provides a way of associating data with an X resource ID
(mostly typically a window) in your program. Note that this is local to your
program; the data is not stored in the server on a property list. Any amount of
data in any number of pieces can be associated with a resource ID, and each
piece of data has a type associated with it. The context manager requires
knowledge of the resource ID and type to store or retrieve data.
Essentially, the context manager can be viewed as a two-dimensional, sparse
array: one dimension is subscripted by the X resource ID and the other by a
context type field. Each entry in the array contains a pointer to the data.
Xlib provides context management functions with which you can save data values,
get data values, delete entries, and create a unique context type. The symbols
used are in <X11/Xutil.h>.
To save a data value that corresponds to a resource ID and context type, use
XSaveContext.
int XSaveContext(Display *display, XID rid, XContext context, XPointer data);
display Specifies the connection to the X server.
rid Specifies the resource ID with which the data is associated.
context Specifies the context type to which the data belongs.
data Specifies the data to be associated with the window and type.
If an entry with the specified resource ID and type already exists,
XSaveContext overrides it with the specified context. The XSaveContext function
returns a nonzero error code if an error has occurred and zero otherwise.
Possible errors are XCNOMEM (out of memory).
To get the data associated with a resource ID and type, use XFindContext.
int XFindContext(Display *display, XID rid, XContext context, XPointer
*data_return);
display Specifies the connection to the X server.
rid Specifies the resource ID with which the data is associated.
context Specifies the context type to which the data belongs.
data_return Returns the data.
Because it is a return value, the data is a pointer. The XFindContext function
returns a nonzero error code if an error has occurred and zero otherwise.
Possible errors are XCNOENT (context-not-found).
To delete an entry for a given resource ID and type, use XDeleteContext.
int XDeleteContext(Display *display, XID rid, XContext context);
display Specifies the connection to the X server.
rid Specifies the resource ID with which the data is associated.
context Specifies the context type to which the data belongs.
The XDeleteContext function deletes the entry for the given resource ID and
type from the data structure. This function returns the same error codes that
XFindContext returns if called with the same arguments. XDeleteContext does not
free the data whose address was saved.
To create a unique context type that may be used in subsequent calls to
XSaveContext and XFindContext, use XUniqueContext.
XContext XUniqueContext(void);
Appendix A. Xlib Functions and Protocol Requests
This appendix provides two tables that relate to Xlib functions and the X
protocol. The following table lists each Xlib function (in alphabetical order)
and the corresponding protocol request that it generates.
Table A.1. Protocol requests made by each Xlib function
┌──────────────────────────┬───────────────────────┐
│Xlib Function │Protocol Request │
├──────────────────────────┼───────────────────────┤
│XActivateScreenSaver │ForceScreenSaver │
├──────────────────────────┼───────────────────────┤
│XAddHost │ChangeHosts │
├──────────────────────────┼───────────────────────┤
│XAddHosts │ChangeHosts │
├──────────────────────────┼───────────────────────┤
│XAddToSaveSet │ChangeSaveSet │
├──────────────────────────┼───────────────────────┤
│XAllocColor │AllocColor │
├──────────────────────────┼───────────────────────┤
│XAllocColorCells │AllocColorCells │
├──────────────────────────┼───────────────────────┤
│XAllocColorPlanes │AllocColorPlanes │
├──────────────────────────┼───────────────────────┤
│XAllocNamedColor │AllocNamedColor │
├──────────────────────────┼───────────────────────┤
│XAllowEvents │AllowEvents │
├──────────────────────────┼───────────────────────┤
│XAutoRepeatOff │ChangeKeyboardControl │
├──────────────────────────┼───────────────────────┤
│XAutoRepeatOn │ChangeKeyboardControl │
├──────────────────────────┼───────────────────────┤
│XBell │Bell │
├──────────────────────────┼───────────────────────┤
│XChangeActivePointerGrab │ChangeActivePointerGrab│
├──────────────────────────┼───────────────────────┤
│XChangeGC │ChangeGC │
├──────────────────────────┼───────────────────────┤
│XChangeKeyboardControl │ChangeKeyboardControl │
├──────────────────────────┼───────────────────────┤
│XChangeKeyboardMapping │ChangeKeyboardMapping │
├──────────────────────────┼───────────────────────┤
│XChangePointerControl │ChangePointerControl │
├──────────────────────────┼───────────────────────┤
│XChangeProperty │ChangeProperty │
├──────────────────────────┼───────────────────────┤
│XChangeSaveSet │ChangeSaveSet │
├──────────────────────────┼───────────────────────┤
│XChangeWindowAttributes │ChangeWindowAttributes │
├──────────────────────────┼───────────────────────┤
│XCirculateSubwindows │CirculateWindow │
├──────────────────────────┼───────────────────────┤
│XCirculateSubwindowsDown │CirculateWindow │
├──────────────────────────┼───────────────────────┤
│XCirculateSubwindowsUp │CirculateWindow │
├──────────────────────────┼───────────────────────┤
│XClearArea │ClearArea │
├──────────────────────────┼───────────────────────┤
│XClearWindow │ClearArea │
├──────────────────────────┼───────────────────────┤
│XConfigureWindow │ConfigureWindow │
├──────────────────────────┼───────────────────────┤
│XConvertSelection │ConvertSelection │
├──────────────────────────┼───────────────────────┤
│XCopyArea │CopyArea │
├──────────────────────────┼───────────────────────┤
│XCopyColormapAndFree │CopyColormapAndFree │
├──────────────────────────┼───────────────────────┤
│XCopyGC │CopyGC │
├──────────────────────────┼───────────────────────┤
│XCopyPlane │CopyPlane │
├──────────────────────────┼───────────────────────┤
│ │CreateGC │
│ ├───────────────────────┤
│ │CreatePixmap │
│XCreateBitmapFromData ├───────────────────────┤
│ │FreeGC │
│ ├───────────────────────┤
│ │PutImage │
├──────────────────────────┼───────────────────────┤
│XCreateColormap │CreateColormap │
├──────────────────────────┼───────────────────────┤
│XCreateFontCursor │CreateGlyphCursor │
├──────────────────────────┼───────────────────────┤
│XCreateGC │CreateGC │
├──────────────────────────┼───────────────────────┤
│XCreateGlyphCursor │CreateGlyphCursor │
├──────────────────────────┼───────────────────────┤
│XCreatePixmap │CreatePixmap │
├──────────────────────────┼───────────────────────┤
│XCreatePixmapCursor │CreateCursor │
├──────────────────────────┼───────────────────────┤
│ │CreateGC │
│ ├───────────────────────┤
│ │CreatePixmap │
│XCreatePixmapFromData ├───────────────────────┤
│ │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 │
├──────────────────────────┼───────────────────────┤
│ │GetProperty │
│XGetWMColormapWindows ├───────────────────────┤
│ │InternAtom │
├──────────────────────────┼───────────────────────┤
│XGetWMHints │GetProperty │
├──────────────────────────┼───────────────────────┤
│XGetWMIconName │GetProperty │
├──────────────────────────┼───────────────────────┤
│XGetWMName │GetProperty │
├──────────────────────────┼───────────────────────┤
│XGetWMNormalHints │GetProperty │
├──────────────────────────┼───────────────────────┤
│ │GetProperty │
│XGetWMProtocols ├───────────────────────┤
│ │InternAtom │
├──────────────────────────┼───────────────────────┤
│XGetWMSizeHints │GetProperty │
├──────────────────────────┼───────────────────────┤
│ │GetWindowAttributes │
│XGetWindowAttributes ├───────────────────────┤
│ │GetGeometry │
├──────────────────────────┼───────────────────────┤
│XGetWindowProperty │GetProperty │
├──────────────────────────┼───────────────────────┤
│XGetZoomHints │GetProperty │
├──────────────────────────┼───────────────────────┤
│XGrabButton │GrabButton │
├──────────────────────────┼───────────────────────┤
│XGrabKey │GrabKey │
├──────────────────────────┼───────────────────────┤
│XGrabKeyboard │GrabKeyboard │
├──────────────────────────┼───────────────────────┤
│XGrabPointer │GrabPointer │
├──────────────────────────┼───────────────────────┤
│XGrabServer │GrabServer │
├──────────────────────────┼───────────────────────┤
│ │InternAtom │
│XIconifyWindow ├───────────────────────┤
│ │SendEvent │
├──────────────────────────┼───────────────────────┤
│XInitExtension │QueryExtension │
├──────────────────────────┼───────────────────────┤
│XInstallColormap │InstallColormap │
├──────────────────────────┼───────────────────────┤
│XInternAtom │InternAtom │
├──────────────────────────┼───────────────────────┤
│XKillClient │KillClient │
├──────────────────────────┼───────────────────────┤
│XListExtensions │ListExtensions │
├──────────────────────────┼───────────────────────┤
│XListFonts │ListFonts │
├──────────────────────────┼───────────────────────┤
│XListFontsWithInfo │ListFontsWithInfo │
├──────────────────────────┼───────────────────────┤
│XListHosts │ListHosts │
├──────────────────────────┼───────────────────────┤
│XListInstalledColormaps │ListInstalledColormaps │
├──────────────────────────┼───────────────────────┤
│XListProperties │ListProperties │
├──────────────────────────┼───────────────────────┤
│XLoadFont │OpenFont │
├──────────────────────────┼───────────────────────┤
│ │OpenFont │
│XLoadQueryFont ├───────────────────────┤
│ │QueryFont │
├──────────────────────────┼───────────────────────┤
│XLookupColor │LookupColor │
├──────────────────────────┼───────────────────────┤
│XLowerWindow │ConfigureWindow │
├──────────────────────────┼───────────────────────┤
│ │ConfigureWindow │
│XMapRaised ├───────────────────────┤
│ │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 │
├──────────────────────────┼───────────────────────┤
│ │CreateGC │
│ ├───────────────────────┤
│ │CreatePixmap │
│XReadBitmapFile ├───────────────────────┤
│ │FreeGC │
│ ├───────────────────────┤
│ │PutImage │
├──────────────────────────┼───────────────────────┤
│XRecolorCursor │RecolorCursor │
├──────────────────────────┼───────────────────────┤
│ │ConfigureWindow │
│XReconfigureWMWindow ├───────────────────────┤
│ │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 │
├──────────────────────────┼───────────────────────┤
│ │ChangeProperty │
│XSetWMColormapWindows ├───────────────────────┤
│ │InternAtom │
├──────────────────────────┼───────────────────────┤
│XSetWMHints │ChangeProperty │
├──────────────────────────┼───────────────────────┤
│XSetWMIconName │ChangeProperty │
├──────────────────────────┼───────────────────────┤
│XSetWMName │ChangeProperty │
├──────────────────────────┼───────────────────────┤
│XSetWMNormalHints │ChangeProperty │
├──────────────────────────┼───────────────────────┤
│XSetWMProperties │ChangeProperty │
├──────────────────────────┼───────────────────────┤
│ │ChangeProperty │
│XSetWMProtocols ├───────────────────────┤
│ │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 │
├──────────────────────────┼───────────────────────┤
│ │SendEvent │
│XWithdrawWindow ├───────────────────────┤
│ │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 │
├───────────────────────┼──────────────────────────┤
│ │XChangeGC │
│ ├──────────────────────────┤
│ │XSetArcMode │
│ ├──────────────────────────┤
│ │XSetBackground │
│ ├──────────────────────────┤
│ │XSetClipMask │
│ ├──────────────────────────┤
│ │XSetClipOrigin │
│ ├──────────────────────────┤
│ │XSetFillRule │
│ ├──────────────────────────┤
│ │XSetFillStyle │
│ ├──────────────────────────┤
│ │XSetFont │
│ ├──────────────────────────┤
│ │XSetForeground │
│ChangeGC ├──────────────────────────┤
│ │XSetFunction │
│ ├──────────────────────────┤
│ │XSetGraphicsExposures │
│ ├──────────────────────────┤
│ │XSetLineAttributes │
│ ├──────────────────────────┤
│ │XSetPlaneMask │
│ ├──────────────────────────┤
│ │XSetState │
│ ├──────────────────────────┤
│ │XSetStipple │
│ ├──────────────────────────┤
│ │XSetSubwindowMode │
│ ├──────────────────────────┤
│ │XSetTile │
│ ├──────────────────────────┤
│ │XSetTSOrigin │
├───────────────────────┼──────────────────────────┤
│ │XAddHost │
│ ├──────────────────────────┤
│ │XAddHosts │
│ChangeHosts ├──────────────────────────┤
│ │XRemoveHost │
│ ├──────────────────────────┤
│ │XRemoveHosts │
├───────────────────────┼──────────────────────────┤
│ │XAutoRepeatOff │
│ ├──────────────────────────┤
│ChangeKeyboardControl │XAutoRepeatOn │
│ ├──────────────────────────┤
│ │XChangeKeyboardControl │
├───────────────────────┼──────────────────────────┤
│ChangeKeyboardMapping │XChangeKeyboardMapping │
├───────────────────────┼──────────────────────────┤
│ChangePointerControl │XChangePointerControl │
├───────────────────────┼──────────────────────────┤
│ │XChangeProperty │
│ ├──────────────────────────┤
│ │XSetClassHint │
│ ├──────────────────────────┤
│ │XSetCommand │
│ ├──────────────────────────┤
│ │XSetIconName │
│ ├──────────────────────────┤
│ │XSetIconSizes │
│ ├──────────────────────────┤
│ │XSetNormalHints │
│ ├──────────────────────────┤
│ │XSetRGBColormaps │
│ ├──────────────────────────┤
│ │XSetSizeHints │
│ ├──────────────────────────┤
│ │XSetStandardProperties │
│ ├──────────────────────────┤
│ │XSetTextProperty │
│ ├──────────────────────────┤
│ │XSetTransientForHint │
│ ├──────────────────────────┤
│ │XSetWMClientMachine │
│ChangeProperty ├──────────────────────────┤
│ │XSetWMColormapWindows │
│ ├──────────────────────────┤
│ │XSetWMHints │
│ ├──────────────────────────┤
│ │XSetWMIconName │
│ ├──────────────────────────┤
│ │XSetWMName │
│ ├──────────────────────────┤
│ │XSetWMNormalHints │
│ ├──────────────────────────┤
│ │XSetWMProperties │
│ ├──────────────────────────┤
│ │XSetWMProtocols │
│ ├──────────────────────────┤
│ │XSetWMSizeHints │
│ ├──────────────────────────┤
│ │XSetZoomHints │
│ ├──────────────────────────┤
│ │XStoreBuffer │
│ ├──────────────────────────┤
│ │XStoreBytes │
│ ├──────────────────────────┤
│ │XStoreName │
├───────────────────────┼──────────────────────────┤
│ │XAddToSaveSet │
│ ├──────────────────────────┤
│ChangeSaveSet │XChangeSaveSet │
│ ├──────────────────────────┤
│ │XRemoveFromSaveSet │
├───────────────────────┼──────────────────────────┤
│ │XChangeWindowAttributes │
│ ├──────────────────────────┤
│ │XDefineCursor │
│ ├──────────────────────────┤
│ │XSelectInput │
│ ├──────────────────────────┤
│ │XSetWindowBackground │
│ ├──────────────────────────┤
│ChangeWindowAttributes │XSetWindowBackgroundPixmap│
│ ├──────────────────────────┤
│ │XSetWindowBorder │
│ ├──────────────────────────┤
│ │XSetWindowBorderPixmap │
│ ├──────────────────────────┤
│ │XSetWindowColormap │
│ ├──────────────────────────┤
│ │XUndefineCursor │
├───────────────────────┼──────────────────────────┤
│ │XCirculateSubwindowsDown │
│ ├──────────────────────────┤
│CirculateWindow │XCirculateSubwindowsUp │
│ ├──────────────────────────┤
│ │XCirculateSubwindows │
├───────────────────────┼──────────────────────────┤
│ │XClearArea │
│ClearArea ├──────────────────────────┤
│ │XClearWindow │
├───────────────────────┼──────────────────────────┤
│ │XFreeFont │
│CloseFont ├──────────────────────────┤
│ │XUnloadFont │
├───────────────────────┼──────────────────────────┤
│ │XConfigureWindow │
│ ├──────────────────────────┤
│ │XLowerWindow │
│ ├──────────────────────────┤
│ │XMapRaised │
│ ├──────────────────────────┤
│ │XMoveResizeWindow │
│ ├──────────────────────────┤
│ │XMoveWindow │
│ConfigureWindow ├──────────────────────────┤
│ │XRaiseWindow │
│ ├──────────────────────────┤
│ │XReconfigureWMWindow │
│ ├──────────────────────────┤
│ │XResizeWindow │
│ ├──────────────────────────┤
│ │XRestackWindows │
│ ├──────────────────────────┤
│ │XSetWindowBorderWidth │
├───────────────────────┼──────────────────────────┤
│ConvertSelection │XConvertSelection │
├───────────────────────┼──────────────────────────┤
│CopyArea │XCopyArea │
├───────────────────────┼──────────────────────────┤
│CopyColormapAndFree │XCopyColormapAndFree │
├───────────────────────┼──────────────────────────┤
│CopyGC │XCopyGC │
├───────────────────────┼──────────────────────────┤
│CopyPlane │XCopyPlane │
├───────────────────────┼──────────────────────────┤
│CreateColormap │XCreateColormap │
├───────────────────────┼──────────────────────────┤
│CreateCursor │XCreatePixmapCursor │
├───────────────────────┼──────────────────────────┤
│ │XCreateGC │
│ ├──────────────────────────┤
│ │XCreateBitmapFromData │
│ ├──────────────────────────┤
│CreateGC │XCreatePixmapFromData │
│ ├──────────────────────────┤
│ │XOpenDisplay │
│ ├──────────────────────────┤
│ │XReadBitmapFile │
├───────────────────────┼──────────────────────────┤
│ │XCreateFontCursor │
│CreateGlyphCursor ├──────────────────────────┤
│ │XCreateGlyphCursor │
├───────────────────────┼──────────────────────────┤
│ │XCreatePixmap │
│ ├──────────────────────────┤
│ │XCreateBitmapFromData │
│CreatePixmap ├──────────────────────────┤
│ │XCreatePixmapFromData │
│ ├──────────────────────────┤
│ │XReadBitmapFile │
├───────────────────────┼──────────────────────────┤
│ │XCreateSimpleWindow │
│CreateWindow ├──────────────────────────┤
│ │XCreateWindow │
├───────────────────────┼──────────────────────────┤
│DeleteProperty │XDeleteProperty │
├───────────────────────┼──────────────────────────┤
│DestroySubwindows │XDestroySubwindows │
├───────────────────────┼──────────────────────────┤
│DestroyWindow │XDestroyWindow │
├───────────────────────┼──────────────────────────┤
│FillPoly │XFillPolygon │
├───────────────────────┼──────────────────────────┤
│ │XActivateScreenSaver │
│ ├──────────────────────────┤
│ForceScreenSaver │XForceScreenSaver │
│ ├──────────────────────────┤
│ │XResetScreenSaver │
├───────────────────────┼──────────────────────────┤
│FreeColormap │XFreeColormap │
├───────────────────────┼──────────────────────────┤
│FreeColors │XFreeColors │
├───────────────────────┼──────────────────────────┤
│FreeCursor │XFreeCursor │
├───────────────────────┼──────────────────────────┤
│ │XFreeGC │
│ ├──────────────────────────┤
│ │XCreateBitmapFromData │
│FreeGC ├──────────────────────────┤
│ │XCreatePixmapFromData │
│ ├──────────────────────────┤
│ │XReadBitmapFile │
├───────────────────────┼──────────────────────────┤
│FreePixmap │XFreePixmap │
├───────────────────────┼──────────────────────────┤
│GetAtomName │XGetAtomName │
├───────────────────────┼──────────────────────────┤
│GetFontPath │XGetFontPath │
├───────────────────────┼──────────────────────────┤
│ │XGetGeometry │
│GetGeometry ├──────────────────────────┤
│ │XGetWindowAttributes │
├───────────────────────┼──────────────────────────┤
│GetImage │XGetImage │
├───────────────────────┼──────────────────────────┤
│ │XGetInputFocus │
│ ├──────────────────────────┤
│GetInputFocus │XSync │
│ ├──────────────────────────┤
│ │XSynchronize │
├───────────────────────┼──────────────────────────┤
│GetKeyboardControl │XGetKeyboardControl │
├───────────────────────┼──────────────────────────┤
│GetKeyboardMapping │XGetKeyboardMapping │
├───────────────────────┼──────────────────────────┤
│GetModifierMapping │XGetModifierMapping │
├───────────────────────┼──────────────────────────┤
│GetMotionEvents │ │
├───────────────────────┼──────────────────────────┤
│GetPointerControl │XGetPointerControl │
├───────────────────────┼──────────────────────────┤
│GetPointerMapping │XGetPointerMapping │
├───────────────────────┼──────────────────────────┤
│ │XFetchBytes │
│ ├──────────────────────────┤
│ │XFetchName │
│ ├──────────────────────────┤
│ │XGetClassHint │
│ ├──────────────────────────┤
│ │XGetIconName │
│ ├──────────────────────────┤
│ │XGetIconSizes │
│ ├──────────────────────────┤
│ │XGetNormalHints │
│ ├──────────────────────────┤
│ │XGetRGBColormaps │
│ ├──────────────────────────┤
│ │XGetSizeHints │
│ ├──────────────────────────┤
│ │XGetTextProperty │
│ ├──────────────────────────┤
│ │XGetTransientForHint │
│GetProperty ├──────────────────────────┤
│ │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 │
├───────────────────────┼──────────────────────────┤
│ │XGetWMColormapWindows │
│ ├──────────────────────────┤
│ │XGetWMProtocols │
│ ├──────────────────────────┤
│ │XIconifyWindow │
│InternAtom ├──────────────────────────┤
│ │XInternAtom │
│ ├──────────────────────────┤
│ │XSetWMColormapWindows │
│ ├──────────────────────────┤
│ │XSetWMProtocols │
├───────────────────────┼──────────────────────────┤
│KillClient │XKillClient │
├───────────────────────┼──────────────────────────┤
│ListExtensions │XListExtensions │
├───────────────────────┼──────────────────────────┤
│ListFonts │XListFonts │
├───────────────────────┼──────────────────────────┤
│ListFontsWithInfo │XListFontsWithInfo │
├───────────────────────┼──────────────────────────┤
│ListHosts │XListHosts │
├───────────────────────┼──────────────────────────┤
│ListInstalledColormaps │XListInstalledColormaps │
├───────────────────────┼──────────────────────────┤
│ListProperties │XListProperties │
├───────────────────────┼──────────────────────────┤
│ │XLookupColor │
│LookupColor ├──────────────────────────┤
│ │XParseColor │
├───────────────────────┼──────────────────────────┤
│MapSubwindows │XMapSubwindows │
├───────────────────────┼──────────────────────────┤
│ │XMapRaised │
│MapWindow ├──────────────────────────┤
│ │XMapWindow │
├───────────────────────┼──────────────────────────┤
│NoOperation │XNoOp │
├───────────────────────┼──────────────────────────┤
│ │XLoadFont │
│OpenFont ├──────────────────────────┤
│ │XLoadQueryFont │
├───────────────────────┼──────────────────────────┤
│ │XDrawArc │
│PolyArc ├──────────────────────────┤
│ │XDrawArcs │
├───────────────────────┼──────────────────────────┤
│ │XFillArc │
│PolyFillArc ├──────────────────────────┤
│ │XFillArcs │
├───────────────────────┼──────────────────────────┤
│ │XFillRectangle │
│PolyFillRectangle ├──────────────────────────┤
│ │XFillRectangles │
├───────────────────────┼──────────────────────────┤
│PolyLine │XDrawLines │
├───────────────────────┼──────────────────────────┤
│ │XDrawPoint │
│PolyPoint ├──────────────────────────┤
│ │XDrawPoints │
├───────────────────────┼──────────────────────────┤
│ │XDrawRectangle │
│PolyRectangle ├──────────────────────────┤
│ │XDrawRectangles │
├───────────────────────┼──────────────────────────┤
│ │XDrawLine │
│PolySegment ├──────────────────────────┤
│ │XDrawSegments │
├───────────────────────┼──────────────────────────┤
│ │XDrawString │
│PolyText8 ├──────────────────────────┤
│ │XDrawText │
├───────────────────────┼──────────────────────────┤
│ │XDrawString16 │
│PolyText16 ├──────────────────────────┤
│ │XDrawText16 │
├───────────────────────┼──────────────────────────┤
│ │XPutImage │
│ ├──────────────────────────┤
│ │XCreateBitmapFromData │
│PutImage ├──────────────────────────┤
│ │XCreatePixmapFromData │
│ ├──────────────────────────┤
│ │XReadBitmapFile │
├───────────────────────┼──────────────────────────┤
│ │XQueryBestCursor │
│ ├──────────────────────────┤
│ │XQueryBestSize │
│QueryBestSize ├──────────────────────────┤
│ │XQueryBestStipple │
│ ├──────────────────────────┤
│ │XQueryBestTile │
├───────────────────────┼──────────────────────────┤
│ │XQueryColor │
│QueryColors ├──────────────────────────┤
│ │XQueryColors │
├───────────────────────┼──────────────────────────┤
│ │XInitExtension │
│QueryExtension ├──────────────────────────┤
│ │XQueryExtension │
├───────────────────────┼──────────────────────────┤
│ │XLoadQueryFont │
│QueryFont ├──────────────────────────┤
│ │XQueryFont │
├───────────────────────┼──────────────────────────┤
│QueryKeymap │XQueryKeymap │
├───────────────────────┼──────────────────────────┤
│QueryPointer │XQueryPointer │
├───────────────────────┼──────────────────────────┤
│ │XQueryTextExtents │
│QueryTextExtents ├──────────────────────────┤
│ │XQueryTextExtents16 │
├───────────────────────┼──────────────────────────┤
│QueryTree │XQueryTree │
├───────────────────────┼──────────────────────────┤
│RecolorCursor │XRecolorCursor │
├───────────────────────┼──────────────────────────┤
│ReparentWindow │XReparentWindow │
├───────────────────────┼──────────────────────────┤
│ │XRotateBuffers │
│RotateProperties ├──────────────────────────┤
│ │XRotateWindowProperties │
├───────────────────────┼──────────────────────────┤
│ │XIconifyWindow │
│ ├──────────────────────────┤
│ │XReconfigureWMWindow │
│SendEvent ├──────────────────────────┤
│ │XSendEvent │
│ ├──────────────────────────┤
│ │XWithdrawWindow │
├───────────────────────┼──────────────────────────┤
│ │XDisableAccessControl │
│ ├──────────────────────────┤
│SetAccessControl │XEnableAccessControl │
│ ├──────────────────────────┤
│ │XSetAccessControl │
├───────────────────────┼──────────────────────────┤
│SetClipRectangles │XSetClipRectangles │
├───────────────────────┼──────────────────────────┤
│SetCloseDownMode │XSetCloseDownMode │
├───────────────────────┼──────────────────────────┤
│SetDashes │XSetDashes │
├───────────────────────┼──────────────────────────┤
│SetFontPath │XSetFontPath │
├───────────────────────┼──────────────────────────┤
│SetInputFocus │XSetInputFocus │
├───────────────────────┼──────────────────────────┤
│SetModifierMapping │XSetModifierMapping │
├───────────────────────┼──────────────────────────┤
│SetPointerMapping │XSetPointerMapping │
├───────────────────────┼──────────────────────────┤
│ │XGetScreenSaver │
│SetScreenSaver ├──────────────────────────┤
│ │XSetScreenSaver │
├───────────────────────┼──────────────────────────┤
│SetSelectionOwner │XSetSelectionOwner │
├───────────────────────┼──────────────────────────┤
│ │XStoreColor │
│StoreColors ├──────────────────────────┤
│ │XStoreColors │
├───────────────────────┼──────────────────────────┤
│StoreNamedColor │XStoreNamedColor │
├───────────────────────┼──────────────────────────┤
│TranslateCoordinates │XTranslateCoordinates │
├───────────────────────┼──────────────────────────┤
│UngrabButton │XUngrabButton │
├───────────────────────┼──────────────────────────┤
│UngrabKey │XUngrabKey │
├───────────────────────┼──────────────────────────┤
│UngrabKeyboard │XUngrabKeyboard │
├───────────────────────┼──────────────────────────┤
│UngrabPointer │XUngrabPointer │
├───────────────────────┼──────────────────────────┤
│UngrabServer │XUngrabServer │
├───────────────────────┼──────────────────────────┤
│UninstallColormap │XUninstallColormap │
├───────────────────────┼──────────────────────────┤
│UnmapSubwindows │XUnmapSubWindows │
├───────────────────────┼──────────────────────────┤
│ │XUnmapWindow │
│UnmapWindow ├──────────────────────────┤
│ │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 108
#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 116
#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 136
#define XC_heart 62 #define XC_top_side 138
#define XC_icon 64 #define XC_top_tee 140
#define XC_iron_cross 66 #define XC_trek 142
#define XC_left_ptr 68 #define XC_ul_angle 144
#define XC_left_side 70 #define XC_umbrella 146
#define XC_left_tee 72 #define XC_ur_angle 148
#define XC_leftbutton 74 #define XC_watch 150
#define XC_xterm 152
Appendix C. Extensions
Table of Contents
Basic Protocol Support Routines
Hooking into Xlib
Hooks into the Library
Hooks onto Xlib Data Structures
GC Caching
Graphics Batching
Writing Extension Stubs
Requests, Replies, and Xproto.h
Request Format
Starting to Write a Stub Procedure
Locking Data Structures
Sending the Protocol Request and Arguments
Variable Length Arguments
Replies
Synchronous Calling
Allocating and Deallocating Memory
Portability Considerations
Deriving the Correct Extension Opcode
Because X can evolve by extensions to the core protocol, it is important that
extensions not be perceived as second-class citizens. At some point, your
favorite extensions may be adopted as additional parts of the X Standard.
Therefore, there should be little to distinguish the use of an extension from
that of the core protocol. To avoid having to initialize extensions explicitly
in application programs, it is also important that extensions perform lazy
evaluations, automatically initializing themselves when called for the first
time.
This appendix describes techniques for writing extensions to Xlib that will run
at essentially the same performance as the core protocol requests.
Note
It is expected that a given extension to X consists of multiple requests.
Defining 10 new features as 10 separate extensions is a bad practice. Rather,
they should be packaged into a single extension and should use minor opcodes to
distinguish the requests.
The symbols and macros used for writing stubs to Xlib are listed in <X11/
Xlibint.h>.
Basic Protocol Support Routines
The basic protocol requests for extensions are XQueryExtension and
XListExtensions.
Bool XQueryExtension(Display *display, char *name, int *major_opcode_return,
int *first_event_return, int *first_error_return);
display Specifies the connection to the X server.
name Specifies the extension name.
major_opcode_return Returns the major opcode.
first_event_return Returns the first event code, if any.
first_error_return Returns the first error code, if any.
The XQueryExtension function determines if the named extension is present. If
the extension is not present, XQueryExtension returns False; otherwise, it
returns True. If the extension is present, XQueryExtension returns the major
opcode for the extension to major_opcode_return; otherwise, it returns zero.
Any minor opcode and the request formats are specific to the extension. If the
extension involves additional event types, XQueryExtension returns the base
event type code to first_event_return; otherwise, it returns zero. The format
of the events is specific to the extension. If the extension involves
additional error codes, XQueryExtension returns the base error code to
first_error_return; otherwise, it returns zero. The format of additional data
in the errors is specific to the extension.
If the extension name is not in the Host Portable Character Encoding the result
is implementation-dependent. Uppercase and lowercase matter; the strings
``thing'', ``Thing'', and ``thinG'' are all considered different names.
char **XListExtensions(Display *display, int *nextensions_return);
display Specifies the connection to the X server.
nextensions_return Returns the number of extensions listed.
The XListExtensions function returns a list of all extensions supported by the
server. If the data returned by the server is in the Latin Portable Character
Encoding, then the returned strings are in the Host Portable Character
Encoding. Otherwise, the result is implementation-dependent.
XFreeExtensionList(char **list);
list Specifies the list of extension names.
The XFreeExtensionList function frees the memory allocated by XListExtensions.
Hooking into Xlib
These functions allow you to hook into the library. They are not normally used
by application programmers but are used by people who need to extend the core X
protocol and the X library interface. The functions, which generate protocol
requests for X, are typically called stubs.
In extensions, stubs first should check to see if they have initialized
themselves on a connection. If they have not, they then should call
XInitExtension to attempt to initialize themselves on the connection.
If the extension needs to be informed of GC/font allocation or deallocation or
if the extension defines new event types, the functions described here allow
the extension to be called when these events occur.
The XExtCodes structure returns the information from XInitExtension and is
defined in <X11/Xlib.h>:
typedef struct _XExtCodes { /* public to extension, cannot be changed */
int extension; /* extension number */
int major_opcode; /* major op-code assigned by server */
int first_event; /* first event number for the extension */
int first_error; /* first error number for the extension */
} XExtCodes;
XExtCodes *XInitExtension(Display *display, char *name);
display Specifies the connection to the X server.
name Specifies the extension name.
The XInitExtension function determines if the named extension exists. Then, it
allocates storage for maintaining the information about the extension on the
connection, chains this onto the extension list for the connection, and returns
the information the stub implementor will need to access the extension. If the
extension does not exist, XInitExtension returns NULL.
If the extension name is not in the Host Portable Character Encoding, the
result is implementation-dependent. Uppercase and lowercase matter; the strings
``thing'', ``Thing'', and ``thinG'' are all considered different names.
The extension number in the XExtCodes structure is needed in the other calls
that follow. This extension number is unique only to a single connection.
XExtCodes *XAddExtension(Display *display);
display Specifies the connection to the X server.
For local Xlib extensions, the XAddExtension function allocates the XExtCodes
structure, bumps the extension number count, and chains the extension onto the
extension list. (This permits extensions to Xlib without requiring server
extensions.)
Hooks into the Library
These functions allow you to define procedures that are to be called when
various circumstances occur. The procedures include the creation of a new GC
for a connection, the copying of a GC, the freeing of a GC, the creating and
freeing of fonts, the conversion of events defined by extensions to and from
wire format, and the handling of errors.
All of these functions return the previous procedure defined for this
extension.
int XESetCloseDisplay(Display *display, int extension, int (*proc)());
display Specifies the connection to the X server.
extension Specifies the extension number.
proc Specifies the procedure to call when the display is closed.
The XESetCloseDisplay function defines a procedure to be called whenever
XCloseDisplay is called. It returns any previously defined procedure, usually
NULL.
When XCloseDisplay is called, your procedure is called with these arguments:
int (*proc)(Display *display, XExtCodes *codes);
int *XESetCreateGC(Display *display, int extension, int (*proc)());
display Specifies the connection to the X server.
extension Specifies the extension number.
proc Specifies the procedure to call when a GC is closed.
The XESetCreateGC function defines a procedure to be called whenever a new GC
is created. It returns any previously defined procedure, usually NULL.
When a GC is created, your procedure is called with these arguments:
int (*proc)(Display *display, GC gc, XExtCodes *codes);
int *XESetCopyGC(Display *display, int extension, int (*proc)());
display Specifies the connection to the X server.
extension Specifies the extension number.
proc Specifies the procedure to call when GC components are copied.
The XESetCopyGC function defines a procedure to be called whenever a GC is
copied. It returns any previously defined procedure, usually NULL.
When a GC is copied, your procedure is called with these arguments:
int (*proc)(Display *display, GC gc, XExtCodes *codes);
int *XESetFreeGC(Display *display, int extension, int (*proc)());
display Specifies the connection to the X server.
extension Specifies the extension number.
proc Specifies the procedure to call when a GC is freed.
The XESetFreeGC function defines a procedure to be called whenever a GC is
freed. It returns any previously defined procedure, usually NULL.
When a GC is freed, your procedure is called with these arguments:
int (*proc)(Display *display, GC gc, XExtCodes *codes);
int *XESetCreateFont(Display *display, int extension, int (*proc)());
display Specifies the connection to the X server.
extension Specifies the extension number.
proc Specifies the procedure to call when a font is created.
The XESetCreateFont function defines a procedure to be called whenever
XLoadQueryFont and XQueryFont are called. It returns any previously defined
procedure, usually NULL.
When XLoadQueryFont or XQueryFont is called, your procedure is called with
these arguments:
int (*proc)(Display *display, XFontStruct *fs, XExtCodes *codes);
int *XESetFreeFont(Display *display, int extension, int (*proc)());
display Specifies the connection to the X server.
extension Specifies the extension number.
proc Specifies the procedure to call when a font is freed.
The XESetFreeFont function defines a procedure to be called whenever XFreeFont
is called. It returns any previously defined procedure, usually NULL.
When XFreeFont is called, your procedure is called with these arguments:
int (*proc)(Display *display, XFontStruct *fs, XExtCodes *codes);
The XESetWireToEvent and XESetEventToWire functions allow you to define new
events to the library. An XEvent structure always has a type code (type int) as
the first component. This uniquely identifies what kind of event it is. The
second component is always the serial number (type unsigned long) of the last
request processed by the server. The third component is always a Boolean (type
Bool) indicating whether the event came from a SendEvent protocol request. The
fourth component is always a pointer to the display the event was read from.
The fifth component is always a resource ID of one kind or another, usually a
window, carefully selected to be useful to toolkit dispatchers. The fifth
component should always exist, even if the event does not have a natural
destination; if there is no value from the protocol to put in this component,
initialize it to zero. There is an implementation limit such that your host
event structure size cannot be bigger than the size of the XEvent union of
structures. There also is no way to guarantee that more than 24 elements or 96
characters in the structure will be fully portable between machines.
int *XESetWireToEvent(Display *display, int event_number, Status (*proc)());
display Specifies the connection to the X server.
event_number Specifies the event code.
proc Specifies the procedure to call when converting an event.
The XESetWireToEvent function defines a procedure to be called when an event
needs to be converted from wire format (xEvent) to host format (XEvent). The
event number defines which protocol event number to install a conversion
procedure for. XESetWireToEvent returns any previously defined procedure. You
can replace a core event conversion function with one of your own, although
this is not encouraged. It would, however, allow you to intercept a core event
and modify it before being placed in the queue or otherwise examined. When Xlib
needs to convert an event from wire format to host format, your procedure is
called with these arguments:
int (*proc)(Display *display, XEvent *re, xEvent *event);
Your procedure must return status to indicate if the conversion succeeded. The
re argument is a pointer to where the host format event should be stored, and
the event argument is the 32-byte wire event structure. In the XEvent structure
you are creating, you must fill in the five required members of the event
structure. You should fill in the type member with the type specified for the
xEvent structure. You should copy all other members from the xEvent structure
(wire format) to the XEvent structure (host format). Your conversion procedure
should return True if the event should be placed in the queue or False if it
should not be placed in the queue.
To initialize the serial number component of the event, call
_XSetLastRequestRead with the event and use the return value.
unsigned long_XSetLastRequestRead(Display *display, xGenericReply *rep);
display Specifies the connection to the X server.
rep Specifies the wire event structure.
The _XSetLastRequestRead function computes and returns a complete serial number
from the partial serial number in the event.
Status *XESetEventToWire(Display *display, int event_number, int (*proc)());
display Specifies the connection to the X server.
event_number Specifies the event code.
proc Specifies the procedure to call when converting an event.
The XESetEventToWire function defines a procedure to be called when an event
needs to be converted from host format (XEvent) to wire format (xEvent) form.
The event number defines which protocol event number to install a conversion
procedure for. XESetEventToWire returns any previously defined procedure. It
returns zero if the conversion fails or nonzero otherwise. You can replace a
core event conversion function with one of your own, although this is not
encouraged. It would, however, allow you to intercept a core event and modify
it before being sent to another client. When Xlib needs to convert an event
from host format to wire format, your procedure is called with these arguments:
int (*proc)(Display *display, XEvent *re, xEvent *event);
The re argument is a pointer to the host format event, and the event argument
is a pointer to where the 32-byte wire event structure should be stored. You
should fill in the type with the type from the XEvent structure. All other
members then should be copied from the host format to the xEvent structure.
Bool *XESetWireToError(Display *display, int error_number, Bool (*proc)());
display Specifies the connection to the X server.
error_number Specifies the error code.
proc Specifies the procedure to call when an error is received.
The XESetWireToError function defines a procedure to be called when an
extension error needs to be converted from wire format to host format. The
error number defines which protocol error code to install the conversion
procedure for. XESetWireToError returns any previously defined procedure.
Use this function for extension errors that contain additional error values
beyond those in a core X error, when multiple wire errors must be combined into
a single Xlib error, or when it is necessary to intercept an X error before it
is otherwise examined.
When Xlib needs to convert an error from wire format to host format, the
procedure is called with these arguments:
int (*proc)(Display *display, XErrorEvent *he, xError *we);
The he argument is a pointer to where the host format error should be stored.
The structure pointed at by he is guaranteed to be as large as an XEvent
structure and so can be cast to a type larger than an XErrorEvent to store
additional values. If the error is to be completely ignored by Xlib (for
example, several protocol error structures will be combined into one Xlib
error), then the function should return False; otherwise, it should return True
.
int *XESetError(Display *display, int extension, int (*proc)());
display Specifies the connection to the X server.
extension Specifies the extension number.
proc Specifies the procedure to call when an error is received.
Inside Xlib, there are times that you may want to suppress the calling of the
external error handling when an error occurs. This allows status to be returned
on a call at the cost of the call being synchronous (though most such functions
are query operations, in any case, and are typically programmed to be
synchronous).
When Xlib detects a protocol error in _XReply, it calls your procedure with
these arguments:
int (*proc)(Display *display, xError *err, XExtCodes *codes, int *ret_code);
The err argument is a pointer to the 32-byte wire format error. The codes
argument is a pointer to the extension codes structure. The ret_code argument
is the return code you may want _XReply returned to.
If your procedure returns a zero value, the error is not suppressed, and the
client's error handler is called. (For further information, see section 11.8.2
.) If your procedure returns nonzero, the error is suppressed, and _XReply
returns the value of ret_code.
char *XESetErrorString(Display *display, int extension, char *(*proc)());
display Specifies the connection to the X server.
extension Specifies the extension number.
proc Specifies the procedure to call to obtain an error string.
The XGetErrorText function returns a string to the user for an error.
XESetErrorString allows you to define a procedure to be called that should
return a pointer to the error message. The following is an example.
int (*proc)(Display *display, int code, XExtCodes *codes, char *buffer, int
nbytes);
Your procedure is called with the error code for every error detected. You
should copy nbytes of a null-terminated string containing the error message
into buffer.
void *XESetPrintErrorValues(Display *display, int extension, void (*proc)());
display Specifies the connection to the X server.
extension Specifies the extension number.
proc Specifies the procedure to call when an error is printed.
The XESetPrintErrorValues function defines a procedure to be called when an
extension error is printed, to print the error values. Use this function for
extension errors that contain additional error values beyond those in a core X
error. It returns any previously defined procedure.
When Xlib needs to print an error, the procedure is called with these
arguments:
void (*proc)(Display *display, XErrorEvent *ev, void *fp);
The structure pointed at by ev is guaranteed to be as large as an XEvent
structure and so can be cast to a type larger than an XErrorEvent to obtain
additional values set by using XESetWireToError. The underlying type of the fp
argument is system dependent; on a POSIX-compliant system, fp should be cast to
type FILE*.
int *XESetFlushGC(Display *display, int extension, int *(*proc)());
display Specifies the connection to the X server.
extension Specifies the extension number.
proc Specifies the procedure to call when a GC is flushed.
The procedure set by the XESetFlushGC function has the same interface as the
procedure set by the XESetCopyGC function, but is called when a GC cache needs
to be updated in the server.
int *XESetCopyGC(Display *display, int extension, int *(*proc)());
display Specifies the connection to the X server.
extension Specifies the extension number.
proc Specifies the procedure to call when a buffer is flushed.
The XESetBeforeFlush function defines a procedure to be called when data is
about to be sent to the server. When data is about to be sent, your procedure
is called one or more times with these arguments:
void (*proc)(Display *display, XExtCodes *codes, char *data, long len);
The data argument specifies a portion of the outgoing data buffer, and its
length in bytes is specified by the len argument. Your procedure must not alter
the contents of the data and must not do additional protocol requests to the
same display.
Hooks onto Xlib Data Structures
Various Xlib data structures have provisions for extension procedures to chain
extension supplied data onto a list. These structures are GC, Visual, Screen,
ScreenFormat, Display, and XFontStruct. Because the list pointer is always the
first member in the structure, a single set of procedures can be used to
manipulate the data on these lists.
The following structure is used in the functions in this section and is defined
in <X11/Xlib.h>
typedef struct _XExtData {
int number; /* number returned by XInitExtension */
struct _XExtData *next; /* next item on list of data for structure */
int (*free_private)(); /* if defined, called to free private */
XPointer private_data; /* data private to this extension. */
} XExtData;
When any of the data structures listed above are freed, the list is walked, and
the structure's free procedure (if any) is called. If free is NULL, then the
library frees both the data pointed to by the private_data member and the
structure itself.
union { Display *display;
GC gc;
Visual *visual;
Screen *screen;
ScreenFormat *pixmap_format;
XFontStruct *font } XEDataObject;
XExtData **XEHeadOfExtensionList(XEDataObject object);
object Specifies the object.
The XEHeadOfExtensionList function returns a pointer to the list of extension
structures attached to the specified object. In concert with
XAddToExtensionList, XEHeadOfExtensionList allows an extension to attach
arbitrary data to any of the structures of types contained in XEDataObject.
XAddToExtensionList(XExtData **structure, XExtData *ext_data);
structure Specifies the extension list.
ext_data Specifies the extension data structure to add.
The structure argument is a pointer to one of the data structures enumerated
above. You must initialize ext_data->number with the extension number before
calling this function.
XExtData *XFindOnExtensionList(struct_XExtData **structure, int number);
structure Specifies the extension list.
number Specifies the extension number from XInitExtension.
The XFindOnExtensionList function returns the first extension data structure
for the extension numbered number. It is expected that an extension will add at
most one extension data structure to any single data structure's extension data
list. There is no way to find additional structures.
The XAllocID macro, which allocates and returns a resource ID, is defined in
<X11/Xlib.h>.
XAllocID(Display *display);
display Specifies the connection to the X server.
This macro is a call through the Display structure to an internal resource ID
allocator. It returns a resource ID that you can use when creating new
resources.
The XAllocIDs macro allocates and returns an array of resource ID.
XAllocIDs(Display *display, XID *ids_return, int count);
display Specifies the connection to the X server.
ids_return Returns the resource IDs.
rep Specifies the number of resource IDs requested.
This macro is a call through the Display structure to an internal resource ID
allocator. It returns resource IDs to the array supplied by the caller. To
correctly handle automatic reuse of resource IDs, you must call XAllocIDs when
requesting multiple resource IDs. This call might generate protocol requests.
GC Caching
GCs are cached by the library to allow merging of independent change requests
to the same GC into single protocol requests. This is typically called a
write-back cache. Any extension procedure whose behavior depends on the
contents of a GC must flush the GC cache to make sure the server has up-to-date
contents in its GC.
The FlushGC macro checks the dirty bits in the library's GC structure and calls
_XFlushGCCache if any elements have changed. The FlushGC macro is defined as
follows:
FlushGC(Display *display, GC gc);
display Specifies the connection to the X server.
gc Specifies the GC.
Note that if you extend the GC to add additional resource ID components, you
should ensure that the library stub sends the change request immediately. This
is because a client can free a resource immediately after using it, so if you
only stored the value in the cache without forcing a protocol request, the
resource might be destroyed before being set into the GC. You can use the
_XFlushGCCache procedure to force the cache to be flushed. The _XFlushGCCache
procedure is defined as follows:
_XFlushGCCache(Display *display, GC gc);
display Specifies the connection to the X server.
gc Specifies the GC.
Graphics Batching
If you extend X to add more poly graphics primitives, you may be able to take
advantage of facilities in the library to allow back-to-back single calls to be
transformed into poly requests. This may dramatically improve performance of
programs that are not written using poly requests. A pointer to an xReq, called
last_req in the display structure, is the last request being processed. By
checking that the last request type, drawable, gc, and other options are the
same as the new one and that there is enough space left in the buffer, you may
be able to just extend the previous graphics request by extending the length
field of the request and appending the data to the buffer. This can improve
performance by five times or more in naive programs. For example, here is the
source for the XDrawPoint stub. (Writing extension stubs is discussed in the
next section.)
#include <X11/Xlibint.h>
/* precompute the maximum size of batching request allowed */
static int size = sizeof(xPolyPointReq) + EPERBATCH * sizeof(xPoint);
XDrawPoint(dpy, d, gc, x, y)
register Display *dpy;
Drawable d;
GC gc;
int x, y; /* INT16 */
{
xPoint *point;
LockDisplay(dpy);
FlushGC(dpy, gc);
{
register xPolyPointReq *req = (xPolyPointReq *) dpy->last_req;
/* if same as previous request, with same drawable, batch requests */
if (
(req->reqType == X_PolyPoint)
&& (req->drawable == d)
&& (req->gc == gc->gid)
&& (req->coordMode == CoordModeOrigin)
&& ((dpy->bufptr + sizeof (xPoint)) <= dpy->bufmax)
&& (((char *)dpy->bufptr - (char *)req) < size) ) {
point = (xPoint *) dpy->bufptr;
req->length += sizeof (xPoint) >> 2;
dpy->bufptr += sizeof (xPoint);
}
else {
GetReqExtra(PolyPoint, 4, req); /* 1 point = 4 bytes */
req->drawable = d;
req->gc = gc->gid;
req->coordMode = CoordModeOrigin;
point = (xPoint *) (req + 1);
}
point->x = x;
point->y = y;
}
UnlockDisplay(dpy);
SyncHandle();
}
To keep clients from generating very long requests that may monopolize the
server, there is a symbol defined in <X11/Xlibint.h> of EPERBATCH on the number
of requests batched. Most of the performance benefit occurs in the first few
merged requests. Note that FlushGC is called before picking up the value of
last_req, because it may modify this field.
Writing Extension Stubs
All X requests always contain the length of the request, expressed as a 16-bit
quantity of 32 bit words. This means that a single request can be no more than
256K bytes in length. Some servers may not support single requests of such a
length. The value of dpy->max_request_size contains the maximum length as
defined by the server implementation. For further information, see X Window
System Protocol.
Requests, Replies, and Xproto.h
The <X11/Xproto.h> file contains three sets of definitions that are of interest
to the stub implementor: request names, request structures, and reply
structures.
You need to generate a file equivalent to <X11/Xproto.h> for your extension and
need to include it in your stub procedure. Each stub procedure also must
include <X11/Xlibint.h>.
The identifiers are deliberately chosen in such a way that, if the request is
called X_DoSomething, then its request structure is xDoSomethingReq, and its
reply is xDoSomethingReply. The GetReq family of macros, defined in <X11/
Xlibint.h>, takes advantage of this naming scheme.
For each X request, there is a definition in <X11/Xproto.h> that looks similar
to this:
#define X_DoSomething 42
In your extension header file, this will be a minor opcode, instead of a major
opcode.
Request Format
Every request contains an 8-bit major opcode and a 16-bit length field
expressed in units of 4 bytes. Every request consists of 4 bytes of header
(containing the major opcode, the length field, and a data byte) followed by
zero or more additional bytes of data. The length field defines the total
length of the request, including the header. The length field in a request must
equal the minimum length required to contain the request. If the specified
length is smaller or larger than the required length, the server should
generate a BadLength error. Unused bytes in a request are not required to be
zero. Extensions should be designed in such a way that long protocol requests
can be split up into smaller requests, if it is possible to exceed the maximum
request size of the server. The protocol guarantees the maximum request size to
be no smaller than 4096 units (16384 bytes).
Major opcodes 128 through 255 are reserved for extensions. Extensions are
intended to contain multiple requests, so extension requests typically have an
additional minor opcode encoded in the second data byte in the request header,
but the placement and interpretation of this minor opcode as well as all other
fields in extension requests are not defined by the core protocol. Every
request is implicitly assigned a sequence number (starting with one) used in
replies, errors, and events.
Most protocol requests have a corresponding structure typedef in <X11/
Xproto.h>, which looks like:
typedef struct _DoSomethingReq {
CARD8 reqType; /* X_DoSomething */
CARD8 someDatum; /* used differently in different requests */
CARD16 length; /* total # of bytes in request, divided by 4 */
...
/* request-specific data */
...
} xDoSomethingReq;
If a core protocol request has a single 32-bit argument, you need not declare a
request structure in your extension header file. Instead, such requests use the
xResourceReq structure in <X11/Xproto.h>. This structure is used for any
request whose single argument is a Window, Pixmap, Drawable, GContext, Font,
Cursor, Colormap, Atom, or VisualID.
typedef struct _ResourceReq {
CARD8 reqType; /* the request type, e.g. X_DoSomething */
BYTE pad; /* not used */
CARD16 length; /* 2 (= total # of bytes in request, divided by 4) */
CARD32 id; /* the Window, Drawable, Font, GContext, etc. */
} xResourceReq;
If convenient, you can do something similar in your extension header file.
In both of these structures, the reqType field identifies the type of the
request (for example, X_MapWindow or X_CreatePixmap). The length field tells
how long the request is in units of 4-byte longwords. This length includes both
the request structure itself and any variable-length data, such as strings or
lists, that follow the request structure. Request structures come in different
sizes, but all requests are padded to be multiples of four bytes long.
A few protocol requests take no arguments at all. Instead, they use the xReq
structure in <X11/Xproto.h>, which contains only a reqType and a length (and a
pad byte).
If the protocol request requires a reply, then <X11/Xproto.h> also contains a
reply structure typedef:
typedef struct _DoSomethingReply {
BYTE type; /* always X_Reply */
BYTE someDatum; /* used differently in different requests */
CARD16 sequenceNumber; /* # of requests sent so far */
CARD32 length; /* # of additional bytes, divided by 4 */
...
/* request-specific data */
...
} xDoSomethingReply;
Most of these reply structures are 32 bytes long. If there are not that many
reply values, then they contain a sufficient number of pad fields to bring them
up to 32 bytes. The length field is the total number of bytes in the request
minus 32, divided by 4. This length will be nonzero only if:
• The reply structure is followed by variable-length data, such as a list or
string.
• The reply structure is longer than 32 bytes.
Only GetWindowAttributesl, QueryFont, QueryKeymap, and GetKeyboardControl have
reply structures longer than 32 bytes in the core protocol.
A few protocol requests return replies that contain no data. <X11/Xproto.h>
does not define reply structures for these. Instead, they use the xGenericReply
structure, which contains only a type, length, and sequence number (and
sufficient padding to make it 32 bytes long).
Starting to Write a Stub Procedure
An Xlib stub procedure should start like this:
#include "<X11/Xlibint.h>
XDoSomething (arguments, ... )
/* argument declarations */
{
register XDoSomethingReq *req;
...
If the protocol request has a reply, then the variable declarations should
include the reply structure for the request. The following is an example:
xDoSomethingReply rep;
Locking Data Structures
To lock the display structure for systems that want to support multithreaded
access to a single display connection, each stub will need to lock its critical
section. Generally, this section is the point from just before the appropriate
GetReq call until all arguments to the call have been stored into the buffer.
The precise instructions needed for this locking depend upon the machine
architecture. Two calls, which are generally implemented as macros, have been
provided.
LockDisplay(Display *display);
UnlockDisplay(Display *display);
display Specifies the connection to the X server.
Sending the Protocol Request and Arguments
After the variable declarations, a stub procedure should call one of four
macros defined in <X11/Xlibint.h>: GetReq, GetReqExtra, GetResReq, or
GetEmptyReq. All of these macros take, as their first argument, the name of the
protocol request as declared in <X11/Xproto.h> except with X_ removed. Each one
declares a Display structure pointer, called dpy, and a pointer to a request
structure, called req, which is of the appropriate type. The macro then appends
the request structure to the output buffer, fills in its type and length field,
and sets req to point to it.
If the protocol request has no arguments (for instance, X_GrabServer), then use
GetEmptyReq.
GetEmptyReq (DoSomething, req);
If the protocol request has a single 32-bit argument (such as a Pixmap, Window,
Drawable, Atom, and so on), then use GetResReq. The second argument to the
macro is the 32-bit object. X_MapWindow is a good example.
GetResReq (DoSomething, rid, req);
The rid argument is the Pixmap, Window, or other resource ID.
If the protocol request takes any other argument list, then call GetReq. After
the GetReq, you need to set all the other fields in the request structure,
usually from arguments to the stub procedure.
GetReq (DoSomething, req);
/* fill in arguments here */
req->arg1 = arg1;
req->arg2 = arg2;
...
A few stub procedures (such as XCreateGC and XCreatePixmap) return a resource
ID to the caller but pass a resource ID as an argument to the protocol request.
Such procedures use the macro XAllocID to allocate a resource ID from the range
of IDs that were assigned to this client when it opened the connection.
rid = req->rid = XAllocID();
...
return (rid);
Finally, some stub procedures transmit a fixed amount of variable-length data
after the request. Typically, these procedures (such as XMoveWindow and
XSetBackground) are special cases of more general functions like
XMoveResizeWindow and XChangeGC. These procedures use GetReqExtra, which is the
same as GetReq except that it takes an additional argument (the number of extra
bytes to allocate in the output buffer after the request structure). This
number should always be a multiple of four. Note that it is possible for req to
be set to NULL as a defensive measure if the requested length exceeds the
Xlib's buffer size (normally 16K).
Variable Length Arguments
Some protocol requests take additional variable-length data that follow the
xDoSomethingReq structure. The format of this data varies from request to
request. Some requests require a sequence of 8-bit bytes, others a sequence of
16-bit or 32-bit entities, and still others a sequence of structures.
It is necessary to add the length of any variable-length data to the length
field of the request structure. That length field is in units of 32-bit
longwords. If the data is a string or other sequence of 8-bit bytes, then you
must round the length up and shift it before adding:
req->length += (nbytes+3)>>2;
To transmit variable-length data, use the Data macros. If the data fits into
the output buffer, then this macro copies it to the buffer. If it does not fit,
however, the Data macro calls _XSend, which transmits first the contents of the
buffer and then your data. The Data macros take three arguments: the display, a
pointer to the beginning of the data, and the number of bytes to be sent.
Data(display, (char *) data, nbytes);
Data16(display, (short *) data, nbytes);
Data32(display, (long *) data, nbytes);
Data, Data16, and Data32 are macros that may use their last argument more than
once, so that argument should be a variable rather than an expression such as
``nitems*sizeof(item)''. You should do that kind of computation in a separate
statement before calling them. Use the appropriate macro when sending byte,
short, or long data.
If the protocol request requires a reply, then call the procedure _XSend
instead of the Data macro. _XSend takes the same arguments, but because it
sends your data immediately instead of copying it into the output buffer (which
would later be flushed anyway by the following call on _XReply), it is faster.
Replies
If the protocol request has a reply, then call _XReply after you have finished
dealing with all the fixed-length and variable-length arguments. _XReply
flushes the output buffer and waits for an xReply packet to arrive. If any
events arrive in the meantime, _XReply places them in the queue for later use.
Status _XReply(Display *display, xReply *rep, int extra, Bool discard);
display Specifies the connection to the X server.
rep Specifies the reply structure.
extra Specifies the number of 32-bit words expected after the replay.
discard Specifies if any data beyond that specified in the extra argument
should be discarded.
The _XReply function waits for a reply packet and copies its contents into the
specified rep. _XReply handles error and event packets that occur before the
reply is received. _XReply takes four arguments:
• A Display * structure
• A pointer to a reply structure (which must be cast to an xReply *)
• The number of additional 32-bit words (beyond sizeof( xReply) = 32 bytes)
in the reply structure
• A Boolean that indicates whether _XReply is to discard any additional bytes
beyond those it was told to read
Because most reply structures are 32 bytes long, the third argument is usually
0. The only core protocol exceptions are the replies to GetWindowAttributesl,
QueryFont, QueryKeymap, and GetKeyboardControl, which have longer replies.
The last argument should be False if the reply structure is followed by
additional variable-length data (such as a list or string). It should be True
if there is not any variable-length data. This last argument is provided for
upward-compatibility reasons to allow a client to communicate properly with a
hypothetical later version of the server that sends more data than the client
expected. For example, some later version of GetWindowAttributesl might use a
larger, but compatible, xGetWindowAttributesReply that contains additional
attribute data at the end. _XReply returns True if it received a reply
successfully or False if it received any sort of error.
For a request with a reply that is not followed by variable-length data, you
write something like:
_XReply(display, (xReply *)&rep, 0, True);
*ret1 = rep.ret1;
*ret2 = rep.ret2;
*ret3 = rep.ret3;
...
UnlockDisplay(dpy);
SyncHandle();
return (rep.ret4);
}
If there is variable-length data after the reply, change the True to False, and
use the appropriate _XRead function to read the variable-length data.
_XRead(Display *display, char *data_return, long nbytes);
display Specifies the connection to the X server.
data_return Specifies the buffer.
nbytes Specifies the number of bytes required.
The _XRead function reads the specified number of bytes into data_return.
_XRead16(Display *display, short *data_return, long nbytes);
display Specifies the connection to the X server.
data_return Specifies the buffer.
nbytes Specifies the number of bytes required.
The _XRead16 function reads the specified number of bytes, unpacking them as
16-bit quantities, into the specified array as shorts.
_XRead32(Display *display, long *data_return, long nbytes);
display Specifies the connection to the X server.
data_return Specifies the buffer.
nbytes Specifies the number of bytes required.
The _XRead32 function reads the specified number of bytes, unpacking them as
32-bit quantities, into the specified array as longs.
_XRead16Pad(Display *display, short *data_return, long nbytes);
display Specifies the connection to the X server.
data_return Specifies the buffer.
nbytes Specifies the number of bytes required.
The _XRead16Pad function reads the specified number of bytes, unpacking them as
16-bit quantities, into the specified array as shorts. If the number of bytes
is not a multiple of four, _XRead16Pad reads and discards up to two additional
pad bytes.
_XReadPad(Display *display, char *data_return, long nbytes);
display Specifies the connection to the X server.
data_return Specifies the buffer.
nbytes Specifies the number of bytes required.
The _XReadPad function reads the specified number of bytes into data_return. If
the number of bytes is not a multiple of four, _XReadPad reads and discards up
to three additional pad bytes.
Each protocol request is a little different. For further information, see the
Xlib sources for examples.
Synchronous Calling
Each procedure should have a call, just before returning to the user, to a
macro called SyncHandle. If synchronous mode is enabled (see XSynchronize), the
request is sent immediately. The library, however, waits until any error the
procedure could generate at the server has been handled.
Allocating and Deallocating Memory
To support the possible reentry of these procedures, you must observe several
conventions when allocating and deallocating memory, most often done when
returning data to the user from the window system of a size the caller could
not know in advance (for example, a list of fonts or a list of extensions). The
standard C library functions on many systems are not protected against signals
or other multithreaded uses. The following analogies to standard I/O library
functions have been defined:
These should be used in place of any calls you would make to the normal C
library functions.
If you need a single scratch buffer inside a critical section (for example, to
pack and unpack data to and from the wire protocol), the general memory
allocators may be too expensive to use (particularly in output functions, which
are performance critical). The following function returns a scratch buffer for
use within a critical section:
char *_XAllocScratch(Display *display, unsigned long nbytes);
display Specifies the connection to the X server.
nbytes Specifies the number of bytes required.
This storage must only be used inside of a critical section of your stub. The
returned pointer cannot be assumed valid after any call that might permit
another thread to execute inside Xlib. For example, the pointer cannot be
assumed valid after any use of the GetReq or Data families of macros, after any
use of _XReply, or after any use of the _XSend or _XRead families of functions.
The following function returns a scratch buffer for use across critical
sections:
char *_XAllocTemp(Display *display, unsigned long nbytes);
display Specifies the connection to the X server.
nbytes Specifies the number of bytes required.
This storage can be used across calls that might permit another thread to
execute inside Xlib. The storage must be explicitly returned to Xlib. The
following function returns the storage:
void _XFreeTemp(Display *display, char *buf, unsigned long nbytes);
display Specifies the connection to the X server.
buf Specifies the buffer to return.
nbytes Specifies the size of the buffer.
You must pass back the same pointer and size that were returned by _XAllocTemp.
Portability Considerations
Many machine architectures do not correctly or efficiently access data at
unaligned locations; their compilers pad out structures to preserve this
characteristic. Many other machines capable of unaligned references pad inside
of structures as well to preserve alignment, because accessing aligned data is
usually much faster. Because the library and the server use structures to
access data at arbitrary points in a byte stream, all data in request and reply
packets must be naturally aligned; that is, 16-bit data starts on 16-bit
boundaries in the request and 32-bit data on 32-bit boundaries. All requests
must be a multiple of 32 bits in length to preserve the natural alignment in
the data stream. You must pad structures out to 32-bit boundaries. Pad
information does not have to be zeroed unless you want to preserve such fields
for future use in your protocol requests, but it is recommended to zero it to
avoid inadvertent data leakage and improve compressability. Floating point
varies radically between machines and should be avoided completely if at all
possible.
This code may run on machines with 16-bit ints. So, if any integer argument,
variable, or return value either can take only nonnegative values or is
declared as a CARD16 in the protocol, be sure to declare it as unsigned int and
not as int. (This, of course, does not apply to Booleans or enumerations.)
Similarly, if any integer argument or return value is declared CARD32 in the
protocol, declare it as an unsigned long and not as int or long. This also goes
for any internal variables that may take on values larger than the maximum
16-bit unsigned int.
The library has always assumed that a char is 8 bits, a short is 16 bits, an
int is 16 or 32 bits, and a long is 32 bits. Unfortunately, this assumption
remains on machines where a long can hold 64-bits, and many functions and
structures require unnecessarily large fields to avoid breaking compatibility
with existing code. Special care must be taken with arrays of values that are
transmitted in the protocol as CARD32 or INT32 but have to be converted to
arrays of 64-bit long when passed to or from client applications.
The PackData macro is a half-hearted attempt to deal with the possibility of 32
bit shorts. However, much more work is needed to make this work properly.
Deriving the Correct Extension Opcode
The remaining problem a writer of an extension stub procedure faces that the
core protocol does not face is to map from the call to the proper major and
minor opcodes. While there are a number of strategies, the simplest and fastest
is outlined below.
• Declare an array of pointers, _NFILE long (this is normally found in
<stdio.h> and is the number of file descriptors supported on the system) of
type XExtCodes. Make sure these are all initialized to NULL.
• When your stub is entered, your initialization test is just to use the
display pointer passed in to access the file descriptor and an index into
the array. If the entry is NULL, then this is the first time you are
entering the procedure for this display. Call your initialization procedure
and pass to it the display pointer.
• Once in your initialization procedure, call XInitExtension; if it succeeds,
store the pointer returned into this array. Make sure to establish a close
display handler to allow you to zero the entry. Do whatever other
initialization your extension requires. (For example, install event
handlers and so on.) Your initialization procedure would normally return a
pointer to the XExtCodes structure for this extension, which is what would
normally be found in your array of pointers.
• After returning from your initialization procedure, the stub can now
continue normally, because it has its major opcode safely in its hand in
the XExtCodes structure.
Appendix D. Compatibility Functions
Table of Contents
X Version 11 Compatibility Functions
Setting Standard Properties
Setting and Getting Window Sizing Hints
Getting and Setting an XStandardColormap Structure
Parsing Window Geometry
Getting the X Environment Defaults
X Version 10 Compatibility Functions
Drawing and Filling Polygons and Curves
Associating User Data with a Value
The X Version 11 and X Version 10 functions discussed in this appendix are
obsolete, have been superseded by newer X Version 11 functions, and are
maintained for compatibility reasons only.
X Version 11 Compatibility Functions
You can use the X Version 11 compatibility functions to:
• Set standard properties
• Set and get window sizing hints
• Set and get an XStandardColormap structure
• Parse window geometry
• Get X environment defaults
Setting Standard Properties
To specify a minimum set of properties describing the simplest application, use
XSetStandardProperties. This function has been superseded by XSetWMProperties
and sets all or portions of the WM_NAME, WM_ICON_NAME, WM_HINTS, WM_COMMAND,
and WM_NORMAL_HINTS properties.
XSetStandardProperties(Display *display, Window w, char *window_name, char
*icon_name, Pixmap icon_pixmap, char **argv, int argc, XSizeHints *hints);
display Specifies the connection to the X server.
w Specifies the window.
window_name Specifies the window name, which should be a null-terminated
string.
icon_name Specifies the icon name, which should be a null-terminated string.
icon_pixmap Specifies the bitmap that is to be used for the icon or None.
argv Specifies the application's argument list.
argc Specifies the number of arguments.
hints Specifies a pointer to the size hints for the window in its normal
state.
The XSetStandardProperties function provides a means by which simple
applications set the most essential properties with a single call.
XSetStandardProperties should be used to give a window manager some information
about your program's preferences. It should not be used by applications that
need to communicate more information than is possible with
XSetStandardProperties. (Typically, argv is the argv array of your main
program.) If the strings are not in the Host Portable Character Encoding, the
result is implementation-dependent.
XSetStandardProperties can generate BadAlloc and BadWindow errors.
Setting and Getting Window Sizing Hints
Xlib provides functions that you can use to set or get window sizing hints. The
functions discussed in this section use the flags and the XSizeHints structure,
as defined in the <X11/Xutil.h> header file and use the WM_NORMAL_HINTS
property.
To set the size hints for a given window in its normal state, use
XSetNormalHints. This function has been superseded by XSetWMNormalHints.
XSetNormalHints(Display *display, Window w, XSizeHints *hints);
display Specifies the connection to the X server.
w Specifies the window.
hints Specifies a pointer to the size hints for the window in its normal
state.
The XSetNormalHints function sets the size hints structure for the specified
window. Applications use XSetNormalHints to inform the window manager of the
size or position desirable for that window. In addition, an application that
wants to move or resize itself should call XSetNormalHints and specify its new
desired location and size as well as making direct Xlib calls to move or
resize. This is because window managers may ignore redirected configure
requests, but they pay attention to property changes.
To set size hints, an application not only must assign values to the
appropriate members in the hints structure but also must set the flags member
of the structure to indicate which information is present and where it came
from. A call to XSetNormalHints is meaningless, unless the flags member is set
to indicate which members of the structure have been assigned values.
XSetNormalHints can generate BadAlloc and BadWindow errors.
To return the size hints for a window in its normal state, use XGetNormalHints.
This function has been superseded by XGetWMNormalHints.
Status XGetNormalHints(Display *display, Window w, XSizeHints *hints_return);
display Specifies the connection to the X server.
w Specifies the window.
hints_return Returns the size hints for the window in its normal state.
The XGetNormalHints function returns the size hints for a window in its normal
state. It returns a nonzero status if it succeeds or zero if the application
specified no normal size hints for this window.
XGetNormalHints can generate a BadWindow error.
The next two functions set and read the WM_ZOOM_HINTS property.
To set the zoom hints for a window, use XSetZoomHints. This function is no
longer supported by the Inter-Client Communication Conventions Manual.
XSetZoomHints(Display *display, Window w, XSizeHints *zhints);
display Specifies the connection to the X server.
w Specifies the window.
zhints Specifies a pointer to the zoom hints.
Many window managers think of windows in one of three states: iconic, normal,
or zoomed. The XSetZoomHints function provides the window manager with
information for the window in the zoomed state.
XSetZoomHints can generate BadAlloc and BadWindow errors.
To read the zoom hints for a window, use XGetZoomHints. This function is no
longer supported by the Inter-Client Communication Conventions Manual.
Status XGetZoomHints(Display *display, Window w, XSizeHints *zhints_return);
display Specifies the connection to the X server.
w Specifies the window.
zhints_return Returns the zoom hints.
The XGetZoomHints function returns the size hints for a window in its zoomed
state. It returns a nonzero status if it succeeds or zero if the application
specified no zoom size hints for this window.
XGetZoomHints can generate a BadWindow error.
To set the value of any property of type WM_SIZE_HINTS, use XSetSizeHints. This
function has been superseded by XSetWMSizeHints.
XSetSizeHints(Display *display, Window w, XSizeHints *hints, Atom property);
display Specifies the connection to the X server.
w Specifies the window.
hints Specifies a pointer to the size hints.
property Specifies the property name.
The XSetSizeHints function sets the XSizeHints structure for the named property
and the specified window. This is used by XSetNormalHints and XSetZoomHints and
can be used to set the value of any property of type WM_SIZE_HINTS. Thus, it
may be useful if other properties of that type get defined.
XSetSizeHints can generate BadAlloc, BadAtom, and BadWindow errors.
To read the value of any property of type WM_SIZE_HINTS, use XGetSizeHints.
This function has been superseded by XGetWMSizeHints.
Status XGetSizeHints(Display *display, Window w, XSizeHints *hints_return, Atom
property);
display Specifies the connection to the X server.
w Specifies the window.
hints_return Returns the size hints.
property Specifies the property name.
The XGetSizeHints function returns the XSizeHints structure for the named
property and the specified window. This is used by XGetNormalHints and
XGetZoomHints. It also can be used to retrieve the value of any property of
type WM_SIZE_HINTS. Thus, it may be useful if other properties of that type get
defined. XGetSizeHints returns a nonzero status if a size hint was defined or
zero otherwise.
XGetSizeHints can generate BadAtom and BadWindow errors.
Getting and Setting an XStandardColormap Structure
To get the XStandardColormap structure associated with one of the described
atoms, use XGetStandardColormap. This function has been superseded by
XGetRGBColormaps.
Status XGetStandardColormap(Display *display, Window w, XStandardColormap
*colormap_return, Atom property);
display Specifies the connection to the X server.
w Specifies the window.
colormap_return Returns the colormap associated with the specified atom.
property Specifies the property name.
The XGetStandardColormap function returns the colormap definition associated
with the atom supplied as the property argument. XGetStandardColormap returns a
nonzero status if successful and zero otherwise. For example, to fetch the
standard GrayScale colormap for a display, you use XGetStandardColormap with
the following syntax:
XGetStandardColormap(dpy, DefaultRootWindow(dpy), &cmap, XA_RGB_GRAY_MAP);
See section 14.3 for the semantics of standard colormaps.
XGetStandardColormap can generate BadAtom and BadWindow errors.
To set a standard colormap, use XSetStandardColormap. This function has been
superseded by XSetRGBColormaps.
XSetStandardColormap(Display *display, Window w, XStandardColormap *colormap,
Atom property);
display Specifies the connection to the X server.
w Specifies the window.
colormap Specifies the colormap.
property Specifies the property name.
The XSetStandardColormap function usually is only used by window or session
managers.
XSetStandardColormap can generate BadAlloc, BadAtom, BadDrawable, and BadWindow
errors.
Parsing Window Geometry
To parse window geometry given a user-specified position and a default
position, use XGeometry. This function has been superseded by XWMGeometry.
int XGeometry(Display *display, int screen, char *position, char
*default_position, unsigned int bwidth, unsigned int fwidth, unsigned int
fheight, int xadder, int yadder, int *x_return, int *y_return, int
*width_return, int *height_return);
display Specifies the connection to the X server.
screen Specifies the screen.
position
default_position Specify the geometry specifications.
bwidth Specifies the border width.
fheight
fwidth Specify the font height and width in pixels (increment size).
xadder
yadder Specify additional interior padding needed in the window.
x_return
y_return Return the x and y offsets.
width_return
height_return Return the width and height determined.
You pass in the border width (bwidth), size of the increments fwidth and
fheight (typically font width and height), and any additional interior space
(xadder and yadder) to make it easy to compute the resulting size. The
XGeometry function returns the position the window should be placed given a
position and a default position. XGeometry determines the placement of a window
using a geometry specification as specified by XParseGeometry and the
additional information about the window. Given a fully qualified default
geometry specification and an incomplete geometry specification, XParseGeometry
returns a bitmask value as defined above in the XParseGeometry call, by using
the position argument.
The returned width and height will be the width and height specified by
default_position as overridden by any user-specified position. They are not
affected by fwidth, fheight, xadder, or yadder. The x and y coordinates are
computed by using the border width, the screen width and height, padding as
specified by xadder and yadder, and the fheight and fwidth times the width and
height from the geometry specifications.
Getting the X Environment Defaults
The XGetDefault function provides a primitive interface to the resource manager
facilities discussed in chapter 15. It is only useful in very simple
applications.
char *XGetDefault(Display *display, char *program, char *option);
display Specifies the connection to the X server.
program Specifies the program name for the Xlib defaults (usually argv[0] of
the main program).
option Specifies the option name.
The XGetDefault function returns the value of the resource prog.option, where
prog is the program argument with the directory prefix removed and option must
be a single component. Note that multilevel resources cannot be used with
XGetDefault. The class "Program.Name" is always used for the resource lookup.
If the specified option name does not exist for this program, XGetDefault
returns NULL. The strings returned by XGetDefault are owned by Xlib and should
not be modified or freed by the client.
If a database has been set with XrmSetDatabase, that database is used for the
lookup. Otherwise, a database is created and is set in the display (as if by
calling XrmSetDatabase). The database is created in the current locale. To
create a database, XGetDefault uses resources from the RESOURCE_MANAGER
property on the root window of screen zero. If no such property exists, a
resource file in the user's home directory is used. On a POSIX-conformant
system, this file is "$HOME/.Xdefaults". After loading these defaults,
XGetDefault merges additional defaults specified by the XENVIRONMENT
environment variable. If XENVIRONMENT is defined, it contains a full path name
for the additional resource file. If XENVIRONMENT is not defined, XGetDefault
looks for "$HOME/.Xdefaults-name" , where name specifies the name of the
machine on which the application is running.
X Version 10 Compatibility Functions
You can use the X Version 10 compatibility functions to:
• Draw and fill polygons and curves
• Associate user data with a value
Drawing and Filling Polygons and Curves
Xlib provides functions that you can use to draw or fill arbitrary polygons or
curves. These functions are provided mainly for compatibility with X Version 10
and have no server support. That is, they call other Xlib functions, not the
server directly. Thus, if you just have straight lines to draw, using
XDrawLines or XDrawSegments is much faster.
The functions discussed here provide all the functionality of the X Version 10
functions XDraw, XDrawFilled, XDrawPatterned, XDrawDashed, and XDrawTiled. They
are as compatible as possible given X Version 11's new line-drawing functions.
One thing to note, however, is that VertexDrawLastPoint is no longer supported.
Also, the error status returned is the opposite of what it was under X Version
10 (this is the X Version 11 standard error status). XAppendVertex and
XClearVertexFlag from X Version 10 also are not supported.
Just how the graphics context you use is set up actually determines whether you
get dashes or not, and so on. Lines are properly joined if they connect and
include the closing of a closed figure (see XDrawLines). The functions
discussed here fail (return zero) only if they run out of memory or are passed
a Vertex list that has a Vertex with VertexStartClosed set that is not followed
by a Vertex with VertexEndClosed set.
To achieve the effects of the X Version 10 XDraw, XDrawDashed, and
XDrawPatterned, use XDraw.
#include <X11/X10.h>
Status XDraw(Display *display, Drawable d, GC gc, Vertex *vlist, int vcount);
display Specifies the connection to the X server.
d Specifies the drawable.
gc Specifies the GC.
vlist Specifies a pointer to the list of vertices that indicate what to draw.
vcount Specifies how many vertices are in vlist.
The XDraw function draws an arbitrary polygon or curve. The figure drawn is
defined by the specified list of vertices (vlist). The points are connected by
lines as specified in the flags in the vertex structure.
Each Vertex, as defined in <X11/X10.h>, is a structure with the following
members:
typedef struct _Vertex {
short x,y;
unsigned short flags;
} Vertex;
The x and y members are the coordinates of the vertex that are relative to
either the upper left inside corner of the drawable (if VertexRelative is zero)
or the previous vertex (if VertexRelative is one).
The flags, as defined in <X11/X10.h>, are as follows:
VertexRelative 0x0001 /* else absolute */
VertexDontDraw 0x0002 /* else draw */
VertexCurved 0x0004 /* else straight */
VertexStartClosed 0x0008 /* else not */
VertexEndClosed 0x0010 /* else not */
• If VertexRelative is not set, the coordinates are absolute (that is,
relative to the drawable's origin). The first vertex must be an absolute
vertex.
• If VertexDontDraw is one, no line or curve is drawn from the previous
vertex to this one. This is analogous to picking up the pen and moving to
another place before drawing another line.
• If VertexCurved is one, a spline algorithm is used to draw a smooth curve
from the previous vertex through this one to the next vertex. Otherwise, a
straight line is drawn from the previous vertex to this one. It makes sense
to set VertexCurved to one only if a previous and next vertex are both
defined (either explicitly in the array or through the definition of a
closed curve).
• It is permissible for VertexDontDraw bits and VertexCurved bits both to be
one. This is useful if you want to define the previous point for the smooth
curve but do not want an actual curve drawing to start until this point.
• If VertexStartClosed is one, then this point marks the beginning of a
closed curve. This vertex must be followed later in the array by another
vertex whose effective coordinates are identical and that has a
VertexEndClosed bit of one. The points in between form a cycle to determine
predecessor and successor vertices for the spline algorithm.
This function uses these GC components: function, plane-mask, line-width,
line-style, cap-style, join-style, fill-style, subwindow-mode, clip-x-origin,
clip-y-origin, and clip-mask. It also uses these GC mode-dependent components:
foreground, background, tile, stipple, tile-stipple-x-origin,
tile-stipple-y-origin, dash-offset, and dash-list.
To achieve the effects of the X Version 10 XDrawTiled and XDrawFilled, use
XDrawFilled.
#include <X11/X10.h>
Status XDrawFilled(Display *display, Drawable d, GC gc, Vertex *vlist, int
vcount);
display Specifies the connection to the X server.
d Specifies the drawable.
gc Specifies the GC.
vlist Specifies a pointer to the list of vertices that indicate what to draw.
vcount Specifies how many vertices are in vlist.
The XDrawFilled function draws arbitrary polygons or curves and then fills
them.
This function uses these GC components: function, plane-mask, line-width,
line-style, cap-style, join-style, fill-style, subwindow-mode, clip-x-origin,
clip-y-origin, and clip-mask. It also uses these GC mode-dependent components:
foreground, background, tile, stipple, tile-stipple-x-origin,
tile-stipple-y-origin, dash-offset, dash-list, fill-style, and fill-rule.
Associating User Data with a Value
These functions have been superseded by the context management functions (see
section 16.10). It is often necessary to associate arbitrary information with
resource IDs. Xlib provides the XAssocTable functions that you can use to make
such an association. Application programs often need to be able to easily refer
to their own data structures when an event arrives. The XAssocTable system
provides users of the X library with a method for associating their own data
structures with X resources (Pixmaps, Fonts, Windows, and so on).
An XAssocTable can be used to type X resources. For example, the user may want
to have three or four types of windows, each with different properties. This
can be accomplished by associating each X window ID with a pointer to a window
property data structure defined by the user. A generic type has been defined in
the X library for resource IDs. It is called an XID.
There are a few guidelines that should be observed when using an XAssocTable :
• All XIDs are relative to the specified display.
• Because of the hashing scheme used by the association mechanism, the
following rules for determining the size of a XAssocTable should be
followed. Associations will be made and looked up more efficiently if the
table size (number of buckets in the hashing system) is a power of two and
if there are not more than 8 XIDs per bucket.
To return a pointer to a new XAssocTable, use XCreateAssocTable.
XAssocTable *XCreateAssocTable(int size);
size Specifies the number of buckets in the hash system of XAssocTable.
The size argument specifies the number of buckets in the hash system of
XAssocTable. For reasons of efficiency the number of buckets should be a power
of two. Some size suggestions might be: use 32 buckets per 100 objects, and a
reasonable maximum number of objects per buckets is 8. If an error allocating
memory for the XAssocTable occurs, a NULL pointer is returned.
To create an entry in a given XAssocTable, use XMakeAssoc.
XMakeAssoc(Display *display, XAssocTable *table, XID x_id, char *data);
display Specifies the connection to the X server.
table Specifies the assoc table.
x_id Specifies the X resource ID.
data Specifies the data to be associated with the X resource ID.
The XMakeAssoc function inserts data into an XAssocTable keyed on an XID. Data
is inserted into the table only once. Redundant inserts are ignored. The queue
in each association bucket is sorted from the lowest XID to the highest XID.
To obtain data from a given XAssocTable, use XLookUpAssoc.
char *XLookUpAssoc(Display *display, XAssocTable *table, XID x_id);
display Specifies the connection to the X server.
table Specifies the assoc table.
x_id Specifies the X resource ID.
The XLookUpAssoc function retrieves the data stored in an XAssocTable by its
XID. If an appropriately matching XID can be found in the table, XLookUpAssoc
returns the data associated with it. If the x_id cannot be found in the table,
it returns NULL.
To delete an entry from a given XAssocTable, use XDeleteAssoc.
XDeleteAssoc(Display *display, XAssocTable *table, XID x_id);
display Specifies the connection to the X server.
table Specifies the assoc table.
x_id Specifies the X resource ID.
The XDeleteAssoc function deletes an association in an XAssocTable keyed on its
XID. Redundant deletes (and deletes of nonexistent XIDs) are ignored. Deleting
associations in no way impairs the performance of an XAssocTable.
To free the memory associated with a given XAssocTable, use XDestroyAssocTable.
XDestroyAssocTable(XAssocTable *table);
table Specifies the assoc table.
Glossary
Access control list
X maintains a list of hosts from which client programs can be run. By
default, only programs on the local host and hosts specified in an initial
list read by the server can use the display. This access control list can
be changed by clients on the local host. Some server implementations can
also implement other authorization mechanisms in addition to or in place of
this mechanism. The action of this mechanism can be conditional based on
the authorization protocol name and data received by the server at
connection setup.
Active grab
A grab is active when the pointer or keyboard is actually owned by the
single grabbing client.
Ancestors
If W is an inferior of A, then A is an ancestor of W.
Atom
An atom is a unique ID corresponding to a string name. Atoms are used to
identify properties, types, and selections.
Background
An InputOutput window can have a background, which is defined as a pixmap.
When regions of the window have their contents lost or invalidated, the
server automatically tiles those regions with the background.
Backing store
When a server maintains the contents of a window, the pixels saved
off-screen are known as a backing store.
Base font name
A font name used to select a family of fonts whose members may be encoded
in various charsets. The CharSetRegistry and CharSetEncoding fields of an
XLFD name identify the charset of the font. A base font name may be a full
XLFD name, with all fourteen '-' delimiters, or an abbreviated XLFD name
containing only the first 12 fields of an XLFD name, up to but not
including CharSetRegistry, with or without the thirteenth '-', or a non-
XLFD name. Any XLFD fields may contain wild cards.
When creating an XFontSet, Xlib accepts from the client a list of one or
more base font names which select one or more font families. They are
combined with charset names obtained from the encoding of the locale to
load the fonts required to render text.
Bit gravity
When a window is resized, the contents of the window are not necessarily
discarded. It is possible to request that the server relocate the previous
contents to some region of the window (though no guarantees are made). This
attraction of window contents for some location of a window is known as bit
gravity.
Bit plane
When a pixmap or window is thought of as a stack of bitmaps, each bitmap is
called a bit plane or plane.
Bitmap
A bitmap is a pixmap of depth one.
Border
An InputOutput window can have a border of equal thickness on all four
sides of the window. The contents of the border are defined by a pixmap,
and the server automatically maintains the contents of the border. Exposure
events are never generated for border regions.
Button grabbing
Buttons on the pointer can be passively grabbed by a client. When the
button is pressed, the pointer is then actively grabbed by the client.
Byte order
For image (pixmap/bitmap) data, the server defines the byte order, and
clients with different native byte ordering must swap bytes as necessary.
For all other parts of the protocol, the client defines the byte order, and
the server swaps bytes as necessary.
Character
A member of a set of elements used for the organization, control, or
representation of text (ISO2022, as adapted by XPG3). Note that in ISO2022
terms, a character is not bound to a coded value until it is identified as
part of a coded character set.
Character glyph
The abstract graphical symbol for a character. Character glyphs may or may
not map one-to-one to font glyphs, and may be context-dependent, varying
with the adjacent characters. Multiple characters may map to a single
character glyph.
Character set
A collection of characters.
Charset
An encoding with a uniform, state-independent mapping from characters to
codepoints. A coded character set.
For display in X, there can be a direct mapping from a charset to one font,
if the width of all characters in the charset is either one or two bytes. A
text string encoded in an encoding such as Shift-JIS cannot be passed
directly to the X server, because the text imaging requests accept only
single-width charsets (either 8 or 16 bits). Charsets which meet these
restrictions can serve as ``font charsets''. Font charsets strictly
speaking map font indices to font glyphs, not characters to character
glyphs.
Note that a single font charset is sometimes used as the encoding of a
locale, for example, ISO8859-1.
Children
The children of a window are its first-level subwindows.
Class
Windows can be of different classes or types. See the entries for
InputOnly and InputOutput windows for further information about valid
window types.
Client
An application program connects to the window system server by some
interprocess communication (IPC) path, such as a TCP connection or a shared
memory buffer. This program is referred to as a client of the window system
server. More precisely, the client is the IPC path itself. A program with
multiple paths open to the server is viewed as multiple clients by the
protocol. Resource lifetimes are controlled by connection lifetimes, not by
program lifetimes.
Clipping region
In a graphics context, a bitmap or list of rectangles can be specified to
restrict output to a particular region of the window. The image defined by
the bitmap or rectangles is called a clipping region.
Coded character
A character bound to a codepoint.
Coded character set
A set of unambiguous rules that establishes a character set and the
one-to-one relationship between each character of the set and its bit
representation. (ISO2022, as adapted by XPG3) A definition of a one-to-one
mapping of a set of characters to a set of codepoints.
Codepoint
The coded representation of a single character in a coded character set.
Colormap
A colormap consists of a set of entries defining color values. The colormap
associated with a window is used to display the contents of the window;
each pixel value indexes the colormap to produce an RGB value that drives
the guns of a monitor. Depending on hardware limitations, one or more
colormaps can be installed at one time so that windows associated with
those maps display with true colors.
Connection
The IPC path between the server and client program is known as a
connection. A client program typically (but not necessarily) has one
connection to the server over which requests and events are sent.
Containment
A window contains the pointer if the window is viewable and the hotspot of
the cursor is within a visible region of the window or a visible region of
one of its inferiors. The border of the window is included as part of the
window for containment. The pointer is in a window if the window contains
the pointer but no inferior contains the pointer.
Coordinate system
The coordinate system has X horizontal and Y vertical, with the origin [0,
0] at the upper left. Coordinates are integral and coincide with pixel
centers. Each window and pixmap has its own coordinate system. For a
window, the origin is inside the border at the inside upper-left corner.
Cursor
A cursor is the visible shape of the pointer on a screen. It consists of a
hotspot, a source bitmap, a shape bitmap, and a pair of colors. The cursor
defined for a window controls the visible appearance when the pointer is in
that window.
Depth
The depth of a window or pixmap is the number of bits per pixel it has. The
depth of a graphics context is the depth of the drawables it can be used in
conjunction with graphics output.
Device
Keyboards, mice, tablets, track-balls, button boxes, and so on are all
collectively known as input devices. Pointers can have one or more buttons
(the most common number is three). The core protocol only deals with two
devices: the keyboard and the pointer.
DirectColor
DirectColor is a class of colormap in which a pixel value is decomposed
into three separate subfields for indexing. The first subfield indexes an
array to produce red intensity values. The second subfield indexes a second
array to produce blue intensity values. The third subfield indexes a third
array to produce green intensity values. The RGB (red, green, and blue)
values in the colormap entry can be changed dynamically.
Display
A server, together with its screens and input devices, is called a display.
The Xlib Display structure contains all information about the particular
display and its screens as well as the state that Xlib needs to communicate
with the display over a particular connection.
Drawable
Both windows and pixmaps can be used as sources and destinations in
graphics operations. These windows and pixmaps are collectively known as
drawables. However, an InputOnly window cannot be used as a source or
destination in a graphics operation.
Encoding
A set of unambiguous rules that establishes a character set and a
relationship between the characters and their representations. The
character set does not have to be fixed to a finite pre-defined set of
characters. The representations do not have to be of uniform length.
Examples are an ISO2022 graphic set, a state-independent or state-dependent
combination of graphic sets, possibly including control sets, and the X
Compound Text encoding.
In X, encodings are identified by a string which appears as: the
CharSetRegistry and CharSetEncoding components of an XLFD name; the name of
a charset of the locale for which a font could not be found; or an atom
which identifies the encoding of a text property or which names an encoding
for a text selection target type. Encoding names should be composed of
characters from the X Portable Character Set.
Escapement
The escapement of a string is the distance in pixels in the primary draw
direction from the drawing origin to the origin of the next character (that
is, the one following the given string) to be drawn.
Event
Clients are informed of information asynchronously by means of events.
These events can be either asynchronously generated from devices or
generated as side effects of client requests. Events are grouped into
types. The server never sends an event to a client unless the client has
specifically asked to be informed of that type of event. However, clients
can force events to be sent to other clients. Events are typically reported
relative to a window.
Event mask
Events are requested relative to a window. The set of event types a client
requests relative to a window is described by using an event mask.
Event propagation
Device-related events propagate from the source window to ancestor windows
until some client has expressed interest in handling that type of event or
until the event is discarded explicitly.
Event source
The deepest viewable window that the pointer is in is called the source of
a device-related event.
Event synchronization
There are certain race conditions possible when demultiplexing device
events to clients (in particular, deciding where pointer and keyboard
events should be sent when in the middle of window management operations).
The event synchronization mechanism allows synchronous processing of device
events.
Exposure event
Servers do not guarantee to preserve the contents of windows when windows
are obscured or reconfigured. Exposure events are sent to clients to inform
them when contents of regions of windows have been lost.
Extension
Named extensions to the core protocol can be defined to extend the system.
Extensions to output requests, resources, and event types are all possible
and expected.
Font
A font is an array of glyphs (typically characters). The protocol does no
translation or interpretation of character sets. The client simply
indicates values used to index the glyph array. A font contains additional
metric information to determine interglyph and interline spacing.
Font glyph
The abstract graphical symbol for an index into a font.
Frozen events
Clients can freeze event processing during keyboard and pointer grabs.
GC
GC is an abbreviation for graphics context. See Graphics context.
Glyph
An identified abstract graphical symbol independent of any actual image.
(ISO/IEC/DIS 9541-1) An abstract visual representation of a graphic
character, not bound to a codepoint.
Glyph image
An image of a glyph, as obtained from a glyph representation displayed on a
presentation surface. (ISO/IEC/DIS 9541-1)
Grab
Keyboard keys, the keyboard, pointer buttons, the pointer, and the server
can be grabbed for exclusive use by a client. In general, these facilities
are not intended to be used by normal applications but are intended for
various input and window managers to implement various styles of user
interfaces.
Graphics context
Various information for graphics output is stored in a graphics context (GC
), such as foreground pixel, background pixel, line width, clipping region,
and so on. A graphics context can only be used with drawables that have the
same root and the same depth as the graphics context.
Gravity
The contents of windows and windows themselves have a gravity, which
determines how the contents move when a window is resized. See Bit gravity
and Window gravity.
GrayScale
GrayScale can be viewed as a degenerate case of PseudoColor, in which the
red, green, and blue values in any given colormap entry are equal and thus,
produce shades of gray. The gray values can be changed dynamically.
Host Portable Character Encoding
The encoding of the X Portable Character Set on the host. The encoding
itself is not defined by this standard, but the encoding must be the same
in all locales supported by Xlib on the host. If a string is said to be in
the Host Portable Character Encoding, then it only contains characters from
the X Portable Character Set, in the host encoding.
Hotspot
A cursor has an associated hotspot, which defines the point in the cursor
corresponding to the coordinates reported for the pointer.
Identifier
An identifier is a unique value associated with a resource that clients use
to name that resource. The identifier can be used over any connection to
name the resource.
Inferiors
The inferiors of a window are all of the subwindows nested below it: the
children, the children's children, and so on.
Input focus
The input focus is usually a window defining the scope for processing of
keyboard input. If a generated keyboard event usually would be reported to
this window or one of its inferiors, the event is reported as usual.
Otherwise, the event is reported with respect to the focus window. The
input focus also can be set such that all keyboard events are discarded and
such that the focus window is dynamically taken to be the root window of
whatever screen the pointer is on at each keyboard event.
Input manager
Control over keyboard input is typically provided by an input manager
client, which usually is part of a window manager.
InputOnly window
An InputOnly window is a window that cannot be used for graphics requests.
InputOnly windows are invisible and are used to control such things as
cursors, input event generation, and grabbing. InputOnly windows cannot
have InputOutput windows as inferiors.
InputOutput window
An InputOutput window is the normal kind of window that is used for both
input and output. InputOutput windows can have both InputOutput and
InputOnly windows as inferiors.
Internationalization
The process of making software adaptable to the requirements of different
native languages, local customs, and character string encodings. Making a
computer program adaptable to different locales without program source
modifications or recompilation.
ISO2022
ISO standard for code extension techniques for 7-bit and 8-bit coded
character sets.
Key grabbing
Keys on the keyboard can be passively grabbed by a client. When the key is
pressed, the keyboard is then actively grabbed by the client.
Keyboard grabbing
A client can actively grab control of the keyboard, and key events will be
sent to that client rather than the client the events would normally have
been sent to.
Keysym
An encoding of a symbol on a keycap on a keyboard.
Latin-1
The coded character set defined by the ISO8859-1 standard.
Latin Portable Character Encoding
The encoding of the X Portable Character Set using the Latin-1 codepoints
plus ASCII control characters. If a string is said to be in the Latin
Portable Character Encoding, then it only contains characters from the X
Portable Character Set, not all of Latin-1.
Locale
The international environment of a computer program defining the
``localized'' behavior of that program at run-time. This information can be
established from one or more sets of localization data. ANSI C defines
locale-specific processing by C system library calls. See ANSI C and the X/
Open Portability Guide specifications for more details. In this
specification, on implementations that conform to the ANSI C library, the
``current locale'' is the current setting of the LC_CTYPE setlocale
category. Associated with each locale is a text encoding. When text is
processed in the context of a locale, the text must be in the encoding of
the locale. The current locale affects Xlib in its:
☆ Encoding and processing of input method text
☆ Encoding of resource files and values
☆ Encoding and imaging of text strings
☆ Encoding and decoding for inter-client text communication
Locale name
The identifier used to select the desired locale for the host C library and
X library functions. On ANSI C library compliant systems, the locale
argument to the setlocale function.
Localization
The process of establishing information within a computer system specific
to the operation of particular native languages, local customs and coded
character sets. (XPG3)
Mapped
A window is said to be mapped if a map call has been performed on it.
Unmapped windows and their inferiors are never viewable or visible.
Modifier keys
Shift, Control, Meta, Super, Hyper, Alt, Compose, Apple, CapsLock,
ShiftLock, and similar keys are called modifier keys.
Monochrome
Monochrome is a special case of StaticGray in which there are only two
colormap entries.
Multibyte
A character whose codepoint is stored in more than one byte; any encoding
which can contain multibyte characters; text in a multibyte encoding. The
``char *'' null-terminated string datatype in ANSI C. Note that references
in this document to multibyte strings imply only that the strings may
contain multibyte characters.
Obscure
A window is obscured if some other window obscures it. A window can be
partially obscured and so still have visible regions. Window A obscures
window B if both are viewable InputOutput windows, if A is higher in the
global stacking order, and if the rectangle defined by the outside edges of
A intersects the rectangle defined by the outside edges of B. Note the
distinction between obscures and occludes. Also note that window borders
are included in the calculation.
Occlude
A window is occluded if some other window occludes it. Window A occludes
window B if both are mapped, if A is higher in the global stacking order,
and if the rectangle defined by the outside edges of A intersects the
rectangle defined by the outside edges of B. Note the distinction between
occludes and obscures. Also note that window borders are included in the
calculation and that InputOnly windows never obscure other windows but can
occlude other windows.
Padding
Some padding bytes are inserted in the data stream to maintain alignment of
the protocol requests on natural boundaries. This increases ease of
portability to some machine architectures.
Parent window
If C is a child of P, then P is the parent of C.
Passive grab
Grabbing a key or button is a passive grab. The grab activates when the key
or button is actually pressed.
Pixel value
A pixel is an N-bit value, where N is the number of bit planes used in a
particular window or pixmap (that is, is the depth of the window or
pixmap). A pixel in a window indexes a colormap to derive an actual color
to be displayed.
Pixmap
A pixmap is a three-dimensional array of bits. A pixmap is normally thought
of as a two-dimensional array of pixels, where each pixel can be a value
from 0 to 2^N-1, and where N is the depth (z axis) of the pixmap. A pixmap
can also be thought of as a stack of N bitmaps. A pixmap can only be used
on the screen that it was created in.
Plane
When a pixmap or window is thought of as a stack of bitmaps, each bitmap is
called a plane or bit plane.
Plane mask
Graphics operations can be restricted to only affect a subset of bit planes
of a destination. A plane mask is a bit mask describing which planes are to
be modified. The plane mask is stored in a graphics context.
Pointer
The pointer is the pointing device currently attached to the cursor and
tracked on the screens.
Pointer grabbing
A client can actively grab control of the pointer. Then button and motion
events will be sent to that client rather than the client the events would
normally have been sent to.
Pointing device
A pointing device is typically a mouse, tablet, or some other device with
effective dimensional motion. The core protocol defines only one visible
cursor, which tracks whatever pointing device is attached as the pointer.
POSIX
Portable Operating System Interface, ISO/IEC 9945-1 (IEEE Std 1003.1).
POSIX Portable Filename Character Set
The set of 65 characters which can be used in naming files on a POSIX
-compliant host that are correctly processed in all locales. The set is:
a..z A..Z 0..9 ._-
Property
Windows can have associated properties that consist of a name, a type, a
data format, and some data. The protocol places no interpretation on
properties. They are intended as a general-purpose naming mechanism for
clients. For example, clients might use properties to share information
such as resize hints, program names, and icon formats with a window
manager.
Property list
The property list of a window is the list of properties that have been
defined for the window.
PseudoColor
PseudoColor is a class of colormap in which a pixel value indexes the
colormap entry to produce an independent RGB value; that is, the colormap
is viewed as an array of triples (RGB values). The RGB values can be
changed dynamically.
Rectangle
A rectangle specified by [x,y,w,h] has an infinitely thin outline path with
corners at [x,y], [x+w,y], [x+w,y+h], and [x, y+h]. When a rectangle is
filled, the lower-right edges are not drawn. For example, if w=h=0, nothing
would be drawn. For w=h=1, a single pixel would be drawn.
Redirecting control
Window managers (or client programs) may enforce window layout policy in
various ways. When a client attempts to change the size or position of a
window, the operation may be redirected to a specified client rather than
the operation actually being performed.
Reply
Information requested by a client program using the X protocol is sent back
to the client with a reply. Both events and replies are multiplexed on the
same connection. Most requests do not generate replies, but some requests
generate multiple replies.
Request
A command to the server is called a request. It is a single block of data
sent over a connection.
Resource
Windows, pixmaps, cursors, fonts, graphics contexts, and colormaps are
known as resources. They all have unique identifiers associated with them
for naming purposes. The lifetime of a resource usually is bounded by the
lifetime of the connection over which the resource was created.
RGB values
RGB values are the red, green, and blue intensity values that are used to
define a color. These values are always represented as 16-bit, unsigned
numbers, with 0 the minimum intensity and 65535 the maximum intensity. The
X server scales these values to match the display hardware.
Root
The root of a pixmap or graphics context is the same as the root of
whatever drawable was used when the pixmap or GC was created. The root of a
window is the root window under which the window was created.
Root window
Each screen has a root window covering it. The root window cannot be
reconfigured or unmapped, but otherwise it acts as a full-fledged window. A
root window has no parent.
Save set
The save set of a client is a list of other clients' windows that, if they
are inferiors of one of the client's windows at connection close, should
not be destroyed and that should be remapped if currently unmapped. Save
sets are typically used by window managers to avoid lost windows if the
manager should terminate abnormally.
Scanline
A scanline is a list of pixel or bit values viewed as a horizontal row (all
values having the same y coordinate) of an image, with the values ordered
by increasing the x coordinate.
Scanline order
An image represented in scanline order contains scanlines ordered by
increasing the y coordinate.
Screen
A server can provide several independent screens, which typically have
physically independent monitors. This would be the expected configuration
when there is only a single keyboard and pointer shared among the screens.
A Screen structure contains the information about that screen and is linked
to the Display structure.
Selection
A selection can be thought of as an indirect property with dynamic type.
That is, rather than having the property stored in the X server, it is
maintained by some client (the owner). A selection is global and is thought
of as belonging to the user and being maintained by clients, rather than
being private to a particular window subhierarchy or a particular set of
clients. When a client asks for the contents of a selection, it specifies a
selection target type, which can be used to control the transmitted
representation of the contents. For example, if the selection is ``the last
thing the user clicked on,'' and that is currently an image, then the
target type might specify whether the contents of the image should be sent
in XY format or Z format.
The target type can also be used to control the class of contents
transmitted; for example, asking for the ``looks'' (fonts, line spacing,
indentation, and so forth) of a paragraph selection, rather than the text
of the paragraph. The target type can also be used for other purposes. The
protocol does not constrain the semantics.
Server
The server, which is also referred to as the X server, provides the basic
windowing mechanism. It handles IPC connections from clients, multiplexes
graphics requests onto the screens, and demultiplexes input back to the
appropriate clients.
Server grabbing
The server can be grabbed by a single client for exclusive use. This
prevents processing of any requests from other client connections until the
grab is completed. This is typically only a transient state for such things
as rubber-banding, pop-up menus, or executing requests indivisibly.
Shift sequence
ISO2022 defines control characters and escape sequences which temporarily
(single shift) or permanently (locking shift) cause a different character
set to be in effect (``invoking'' a character set).
Sibling
Children of the same parent window are known as sibling windows.
Stacking order
Sibling windows, similar to sheets of paper on a desk, can stack on top of
each other. Windows above both obscure and occlude lower windows. The
relationship between sibling windows is known as the stacking order.
State-dependent encoding
An encoding in which an invocation of a charset can apply to multiple
characters in sequence. A state-dependent encoding begins in an ``initial
state'' and enters other ``shift states'' when specific ``shift sequences''
are encountered in the byte sequence. In ISO2022 terms, this means use of
locking shifts, not single shifts.
State-independent encoding
Any encoding in which the invocations of the charsets are fixed, or span
only a single character. In ISO2022 terms, this means use of at most single
shifts, not locking shifts.
StaticColor
StaticColor can be viewed as a degenerate case of PseudoColor in which the
RGB values are predefined and read-only.
StaticGray
StaticGray can be viewed as a degenerate case of GrayScale in which the
gray values are predefined and read-only. The values are typically linear
or near-linear increasing ramps.
Status
Many Xlib functions return a success status. If the function does not
succeed, however, its arguments are not disturbed.
Stipple
A stipple pattern is a bitmap that is used to tile a region to serve as an
additional clip mask for a fill operation with the foreground color.
STRING encoding
Latin-1, plus tab and newline.
String Equivalence
Two ISO Latin-1 STRING8 values are considered equal if they are the same
length and if corresponding bytes are either equal or are equivalent as
follows: decimal values 65 to 90 inclusive (characters ``A'' to ``Z'') are
pairwise equivalent to decimal values 97 to 122 inclusive (characters ``a''
to ``z''), decimal values 192 to 214 inclusive (characters ``A grave'' to
``O diaeresis'') are pairwise equivalent to decimal values 224 to 246
inclusive (characters ``a grave'' to ``o diaeresis''), and decimal values
216 to 222 inclusive (characters ``O oblique'' to ``THORN'') are pairwise
equivalent to decimal values 246 to 254 inclusive (characters ``o oblique''
to ``thorn'').
Tile
A pixmap can be replicated in two dimensions to tile a region. The pixmap
itself is also known as a tile.
Timestamp
A timestamp is a time value expressed in milliseconds. It is typically the
time since the last server reset. Timestamp values wrap around (after about
49.7 days). The server, given its current time is represented by timestamp
T, always interprets timestamps from clients by treating half of the
timestamp space as being earlier in time than T and half of the timestamp
space as being later in time than T. One timestamp value, represented by
the constant CurrentTime, is never generated by the server. This value is
reserved for use in requests to represent the current server time.
TrueColor
TrueColor can be viewed as a degenerate case of DirectColor in which the
subfields in the pixel value directly encode the corresponding RGB values.
That is, the colormap has predefined read-only RGB values. The values are
typically linear or near-linear increasing ramps.
Type
A type is an arbitrary atom used to identify the interpretation of property
data. Types are completely uninterpreted by the server. They are solely for
the benefit of clients. X predefines type atoms for many frequently used
types, and clients also can define new types.
Viewable
A window is viewable if it and all of its ancestors are mapped. This does
not imply that any portion of the window is actually visible. Graphics
requests can be performed on a window when it is not viewable, but output
will not be retained unless the server is maintaining backing store.
Visible
A region of a window is visible if someone looking at the screen can
actually see it; that is, the window is viewable and the region is not
occluded by any other window.
Whitespace
Any spacing character. On implementations that conform to the ANSI C
library, whitespace is any character for which isspace returns true.
Window gravity
When windows are resized, subwindows may be repositioned automatically
relative to some position in the window. This attraction of a subwindow to
some part of its parent is known as window gravity.
Window manager
Manipulation of windows on the screen and much of the user interface
(policy) is typically provided by a window manager client.
X Portable Character Set
A basic set of 97 characters which are assumed to exist in all locales
supported by Xlib. This set contains the following characters:
a..z A..Z 0..9
!"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~
<space>, <tab>, and <newline>
This is the left/lower half (also called the G0 set) of the graphic
character set of ISO8859-1 plus <space>, <tab>, and <newline>. It is also
the set of graphic characters in 7-bit ASCII plus the same three control
characters. The actual encoding of these characters on the host is system
dependent; see the Host Portable Character Encoding.
XLFD
The X Logical Font Description Conventions that define a standard syntax
for structured font names.
XY format
The data for a pixmap is said to be in XY format if it is organized as a
set of bitmaps representing individual bit planes with the planes appearing
from most-significant to least-significant bit order.
Z format
The data for a pixmap is said to be in Z format if it is organized as a set
of pixel values in scanline order.
Index
Symbols
_XAllocScratch, Allocating and Deallocating Memory
_XAllocTemp, Allocating and Deallocating Memory
_Xdebug, Enabling or Disabling Synchronization
_XFlushGCCache, GC Caching
_XFreeTemp, Allocating and Deallocating Memory
_XReply, Replies
_XSetLastRequestRead, Hooks into the Library
A
Access control list, Controlling Host Access, Glossary
Active grab, Pointer Grabbing, Glossary
Allocation
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, Drawing Single and Multiple Arcs
filling, Filling Single and Multiple Arcs
Areas
clearing, Clearing Areas
copying, Copying Areas
Atom, 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
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
grabbing, Pointer Grabbing, Glossary
ungrabbing, Pointer Grabbing
ButtonPress, Keyboard and Pointer Events
ButtonRelease, Keyboard and Pointer Events
Byte
order, Glossary
C
CallbackPrototype, Input Method Callback Semantics
CCC, Color Conversion Contexts and Gamut Mapping
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 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
maximum, TekHVC Queries, TekHVC Queries, TekHVC Queries
CIE metric lightness, 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
minimum, CIELab Queries, CIELuv Queries
CirculateNotify, CirculateNotify Events
CirculateRequest, CirculateRequest Events
Class, Glossary
Clearing
areas, Clearing Areas
windows, Clearing Areas
Client, Glossary
Client White Point, Color Conversion Contexts and Gamut Mapping
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
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
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, 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, Standard Colormap Properties and Atoms
ConfigureNotify, ConfigureNotify Events
ConfigureRequest, ConfigureRequest Events
Connection, Glossary
ConnectionNumber, Display Macros
Containment, Glossary
Coordinate system, Glossary
Copying
areas, Copying Areas
planes, Copying Areas
CreateNotify, CreateNotify Events
CurrentTime, Event Processing Overview, Pointer Grabbing
Cursor, Glossary
Initial State, Creating Windows
limitations, Creating, Recoloring, and Freeing Cursors
Cut Buffers, Using Cut Buffers
D
Debugging
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, 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
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
DISPLAY, Opening the Display
Error
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, 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
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
$HOME/.Xdefaults, Getting the X Environment Defaults
/etc/X?.hosts, Controlling Host Access
<X11/cursorfont.h>, Standard Header Files
<X11/keysym.h>, Standard Header Files, Manipulating the Keyboard Encoding
<X11/keysymdef.h>, Standard Header Files, Manipulating the Keyboard
Encoding, Using Keyboard Utility Functions
<X11/X.h>, Overview of the X Window System, Standard Header Files,
Manipulating Graphics Context/State, Event Types, Event Masks
<X11/X10.h>, Standard Header Files, Drawing and Filling Polygons and Curves
, Drawing and Filling Polygons and Curves
<X11/Xatom.h>, Standard Header Files, Properties and Atoms, Loading and
Freeing Fonts, Standard Colormap Properties and Atoms
<X11/Xcms.h>, Standard Header Files, Color Management Functions
<X11/Xlib.h>, Standard Header Files, Opening the Display, Color Management
Functions, Event Structures, Manipulating Images
<X11/Xlibint.h>, Standard Header Files
<X11/Xproto.h>, Standard Header Files, GraphicsExpose and NoExpose Events
<X11/Xprotostr.h>, Standard Header Files
<X11/Xresource.h>, Standard Header Files, Resource Manager Functions
<X11/Xutil.h>, Standard Header Files, Setting and Reading the WM_HINTS
Property, Setting and Reading the WM_NORMAL_HINTS Property, Setting and
Reading the WM_CLASS Property, Setting and Reading the WM_ICON_SIZE
Property, Parsing the Window Geometry, Manipulating Regions, Determining
the Appropriate Visual Type, Manipulating Images, Using the Context Manager
, Setting and Getting Window Sizing Hints
Filling
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
freeing font information, Loading and Freeing Fonts
getting information, Loading and Freeing Fonts
unloading, Loading and Freeing Fonts
Freeing
colors, Allocating and Freeing Color Cells
resources, Window Attributes, Changing Window Attributes, Changing Window
Attributes
Frozen events, Glossary
Function set, Function Sets
LINEAR_RGB, Function Sets
G
Gamut compression, Color Conversion Contexts and Gamut Mapping
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
buttons, Pointer Grabbing
keyboard, Keyboard Grabbing
keys, Keyboard Grabbing
pointer, Pointer Grabbing
server, Grabbing the Server
Graphics context, 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, Standard Header Files
<X11/cursorfont.h>, Standard Header Files
<X11/keysym.h>, Standard Header Files, Manipulating the Keyboard Encoding
<X11/keysymdef.h>, Standard Header Files, Manipulating the Keyboard
Encoding, Using Keyboard Utility Functions
<X11/X.h>, Overview of the X Window System, Standard Header Files,
Manipulating Graphics Context/State, Event Types, Event Masks
<X11/X10.h>, Standard Header Files, Drawing and Filling Polygons and Curves
, Drawing and Filling Polygons and Curves
<X11/Xatom.h>, Standard Header Files, Properties and Atoms, Loading and
Freeing Fonts, Standard Colormap Properties and Atoms
<X11/Xcms.h>, Standard Header Files, Color Management Functions
<X11/Xlib.h>, Standard Header Files, Opening the Display, Color Management
Functions, Event Structures, Manipulating Images
<X11/Xlibint.h>, Standard Header Files
<X11/Xproto.h>, Standard Header Files, GraphicsExpose and NoExpose Events
<X11/Xprotostr.h>, Standard Header Files
<X11/Xresource.h>, Standard Header Files, Resource Manager Functions
<X11/Xutil.h>, Standard Header Files, Setting and Reading the WM_HINTS
Property, Setting and Reading the WM_NORMAL_HINTS Property, Setting and
Reading the WM_CLASS Property, Setting and Reading the WM_ICON_SIZE
Property, Parsing the Window Geometry, Manipulating Regions, Determining
the Appropriate Visual Type, Manipulating Images, Using the Context Manager
, Setting and Getting Window Sizing Hints
HeightMMOfScreen, Screen Information Macros
HeightOfScreen, Screen Information Macros
Host Portable Character Encoding, Glossary
Hotspot, Glossary
I
Identifier, Glossary
Image text
drawing, Drawing Image Text Characters
ImageByteOrder, Image Format Functions and Macros
IMInstantiateCallback, Input Method Functions
Inferiors, Glossary
Input
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
grabbing, Keyboard Grabbing, Glossary
ungrabbing, Keyboard Grabbing
Keyboard
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, 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
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, Glossary
copying, Copying Areas
mask, Manipulating Graphics Context/State, Glossary
PlanesOfScreen, Screen Information Macros
Pointer, Glossary
grabbing, Pointer Grabbing, Pointer Grabbing, Glossary
ungrabbing, Pointer Grabbing
Pointing device, Glossary
Points
drawing, Drawing Single and Multiple Points
Polygons
drawing, Drawing Single and Multiple Lines
filling, Filling a Single Polygon
POSIX, Glossary
POSIX Portable Filename Character Set, Glossary
POSIX System Call
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, 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
DECnet, Opening the Display
TCP, Opening the Display
ProtocolRevision, Display Macros
ProtocolVersion, Display Macros
PseudoColor, Glossary
Psychometric Chroma, CIELab Queries, CIELab 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, 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, Allocating and Freeing Color Cells
Read/write colormap planes
allocating, Allocating and Freeing Color Cells
Rectangle, Glossary
filling, Filling Single and Multiple Rectangles
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, Closing the Display, 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
order, Glossary
Screen, Overview of the X Window System, Opening the Display, 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, 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, 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, Drawing Text Characters
T
Text
drawing, Drawing Complex Text
Tile, Overview of the X Window System, Glossary
mode, Window Attributes
pixmaps, Window Attributes
Time, Pointer Grabbing
Timestamp, Glossary
True, Generic Values and Types
TrueColor, Glossary
Type, Glossary
U
Ungrabbing
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
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
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
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, Window Attributes
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
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
Generated by dwww version 1.15 on Fri May 24 09:10:53 CEST 2024.