Skip to content

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

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