Xlib - C Language X Interface

X Consortium Standard

X Version 11, Release 6.4

James Gettys

Cambridge Research Laboratory
Digital Equipment Corporation

Robert W. Scheifler

Laboratory for Computer Science
Massachusetts Institute of Technology

with contributions from

Chuck Adams, Tektronix, Inc.

Vania Joloboff, Open Software Foundation

Hideki Hiura, SunSoft, Inc.

Bill McMahon, Hewlett-Packard Company

Ron Newman, Massachusetts Institute of Technology

Al Tabayoyon, Tektronix, Inc.

Glenn Widener, Tektronix, Inc.

Shigeru Yamada, Fujitsu OSSI

The X Window System is a trademark of X Consortium, Inc.

TekHVC is a trademark of Tektronix, Inc.

Copyright 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994,1996 X Consortium

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 X CONSORTIUM 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 X Consortium 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 X Consortium.

Copyright 1985, 1986, 1987, 1988, 1989, 1990, 1991 by Digital Equipment Corporation

Portions Copyright 1990, 1991 by Tektronix, Inc.

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 all copies, and that the names of Digital and Tektronix not be used in in advertising or publicity pertaining to this documentation without specific, written prior permission. Digital and Tektronix makes no representations about the suitability of this documentation for any purpose. It is provided ``as is'' without express or implied warranty.

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

Chapter 1

Introduction to Xlib

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:

1.1. Overview of the X Window System

Some of the terms used in this book are unique to X, and other terms that are common to other window systems have different meanings in X. You may find it helpful to refer to the glossary, which is located at the end of the book.

The X Window System supports one or more screens containing overlapping windows or subwindows. A screen is a physical monitor and hardware that can be color, grayscale, or monochrome. There can be multiple screens for each display or workstation. A single X server can provide display services for any number of screens. A set of screens for a single user with one keyboard and one pointer (usually a mouse) is called a display.

All the windows in an X server are arranged in strict hierarchies. At the top of each hierarchy is a root window, which covers each of the display screens. Each root window is partially or completely covered by child windows. All windows, except for root windows, have parents. There is usually at least one window for each application program. Child windows may in turn have their own children. In this way, an application program can create an arbitrarily deep tree on each screen. X provides graphics, text, and raster operations for windows.

A child window can be larger than its parent. That is, part or all of the child window can extend beyond the boundaries of the parent, but all output to a window is clipped by its parent. If several children of a window have overlapping locations, one of the children is considered to be on top of or raised over the others, thus obscuring them. Output to areas covered by other windows is suppressed by the window system unless the window has backing store. If a window is obscured by a second window, the second window obscures only those ancestors of the second window that are also ancestors of the first window.

A window has a border zero or more pixels in width, which can be any pattern (pixmap) or solid color you like. A window usually but not always has a background pattern, which will be repainted by the window system when uncovered. Child windows obscure their parents, and graphic operations in the parent window usually are clipped by the children.

Each window and pixmap has its own coordinate system. The coordinate system has the X axis horizontal and the Y axis vertical with the origin [0, 0] at the upper-left corner. Coordinates are integral, in terms of pixels, and coincide with pixel centers. For a window, the origin is inside the border at the inside, upper-left corner.

X does not guarantee to preserve the contents of windows. When part or all of a window is hidden and then brought back onto the screen, its contents may be lost. The server then sends the client program an Expose event to notify it that part or all of the window needs to be repainted. Programs must be prepared to regenerate the contents of windows on demand.

X also provides off-screen storage of graphics objects, called pixmaps. Single plane (depth 1) pixmaps are sometimes referred to as bitmaps. Pixmaps can be used in most graphics functions interchangeably with windows and are used in various graphics operations to define patterns or tiles. Windows and pixmaps together are referred to as drawables.

Most of the functions in Xlib just add requests to an output buffer. These requests later execute asynchronously on the X server. Functions that return values of information stored in the server do not return (that is, they block) until an explicit reply is received or an error occurs. You can provide an error handler, which will be called when the error is reported.

If a client does not want a request to execute asynchronously, it can follow the request with a call to XSync, which blocks until all previously buffered asynchronous events have been sent and acted on. As an important side effect, the output buffer in Xlib is always flushed by a call to any function that returns a value from the server or waits for input.

Many Xlib functions will return an integer resource ID, which allows you to refer to objects stored on the X server. These can be of type Window, Font, Pixmap, Colormap, Cursor, and GContext, as defined in the file <X11/X.h>. These resources are created by requests and are destroyed (or freed) by requests or when connections are closed. Most of these resources are potentially sharable between applications, and in fact, windows are manipulated explicitly by window manager programs. Fonts and cursors are shared automatically across multiple screens. Fonts are loaded and unloaded as needed and are shared by multiple clients. Fonts are often cached in the server. Xlib provides no support for sharing graphics contexts between applications.

Client programs are informed of events. Events may either be side effects of a request (for example, restacking windows generates Expose events) or completely asynchronous (for example, from the keyboard). A client program asks to be informed of events. Because other applications can send events to your application, programs must be prepared to handle (or ignore) events of all types.

Input events (for example, a key pressed or the pointer moved) arrive asynchronously from the server and are queued until they are requested by an explicit call (for example, XNextEvent or XWindowEvent). In addition, some library functions (for example, XRaiseWindow) generate Expose and ConfigureRequest events. These events also arrive asynchronously, but the client may wish to explicitly wait for them by calling XSync after calling a function that can cause the server to generate events.

1.2. 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.

1.3. Standard Header Files

The following include files are part of the Xlib standard:

1.4. Generic Values and Types

The following symbols are defined by Xlib and used throughout the manual:

1.5. 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:

1.6. Programming Considerations

The major programming considerations are:

1.7. 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..z A..Z 0..9 ._-

1.8. Formatting Conventions

Xlib - C Language X Interface uses the following conventions:

Xlib - C Library X11, Release 6.4

2

Chapter 2

Display Functions

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:

2.1. Opening the Display

To open a connection to the X server that controls a display, use XOpenDisplay.

__

Display *XOpenDisplay(display_name)

      char *display_name;

display_name

Specifies the hardware display name, which determines the display and communications domain to be used. On a POSIX-conformant system, if the display_name is NULL, it defaults to the value of the DISPLAY environment variable.

__

The encoding and interpretation of the display name are implementation-dependent. Strings in the Host Portable Character Encoding are supported; support for other characters is implementation-dependent. On POSIX-conformant systems, the display name or DISPLAY environment variable can be a string in the format:

__

          hostname:number.screen_number

screen_number

Specifies the screen to be used on that server. Multiple screens can be controlled by a single X server. The screen_number sets an internal variable that can be accessed by using the DefaultScreen macro or the XDefaultScreen function if you are using languages other than C (see section 2.2.1).

__

For example, the following would specify screen 1 of display 0 on the machine named ``dual-headed'':

     dual-headed:0.1

The XOpenDisplay function returns a Display structure that serves as the connection to the X server and that contains all the information about that X server. XOpenDisplay connects your application to the X server through TCP or DECnet communications protocols, or through some local inter-process communication protocol. If the hostname is a host machine name and a single colon (:) separates the hostname and display number, XOpenDisplay connects using TCP streams. If the hostname is 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).

2.2. 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:

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.

Note

2.2.1. 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()

__

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, screen_number)

      Display *display;

      int screen_number;

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, screen_number)

      Display *display;

      int screen_number;

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;

__

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, screen_number)

      Display *display;

      int screen_number;

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, screen_number)

      Display *display;

      int screen_number;

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, screen_number, count_return)

      Display *display;

      int screen_number;

      int *count_return;

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, screen_number)

      Display *display;

      int screen_number;

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;

__

Both return the root window for the default screen.

__

DefaultScreenOfDisplay(display)

Screen *XDefaultScreenOfDisplay(display)

      Display *display;

__

Both return a pointer to the default screen.

__

ScreenOfDisplay(display, screen_number)

Screen *XScreenOfDisplay(display, screen_number)

      Display *display;

      int screen_number;

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;

__

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, screen_number)

      Display *display;

      int screen_number;

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, screen_number)

      Display *display;

      int screen_number;

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, screen_number)

      Display *display;

      int screen_number;

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;

__

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;

__

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;

__

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;

__

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;

__

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;

__

Both return the major version number (11) of the X protocol associated with the connected display.

__

ProtocolRevision(display)

int XProtocolRevision(display)

      Display *display;

__

Both return the minor protocol revision number of the X server.

__

QLength(display)

int XQLength(display)

      Display *display;

__

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, screen_number)

      Display *display;

      int screen_number;

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;

__

Both return the number of available screens.

__

ServerVendor(display)

char *XServerVendor(display)

      Display *display;

__

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;

__

Both return a number related to a vendor's release of the X server.

2.2.2. 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, count_return)

      Display *display;

      int *count_return;

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;

__

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.

__

BitmapUnit(display)

int XBitmapUnit(display)

      Display *display;

__

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;

__

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;

__

Each scanline must be padded to a multiple of bits returned by this macro or function.

__

DisplayHeight(display, screen_number)

int XDisplayHeight(display, screen_number)

      Display *display;

      int screen_number;

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, screen_number)

      Display *display;

      int screen_number;

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, screen_number)

      Display *display;

      int screen_number;

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, screen_number)

      Display *display;

      int screen_number;

screen_number

Specifies the appropriate screen number on the host server.

__

Both return the width of the specified screen in millimeters.

2.2.3. 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;

__

Both return the black pixel value of the specified screen.

__

WhitePixelOfScreen(screen)

unsigned long XWhitePixelOfScreen(screen)

      Screen *screen;

__

Both return the white pixel value of the specified screen.

__

CellsOfScreen(screen)

int XCellsOfScreen(screen)

      Screen *screen;

__

Both return the number of colormap cells in the default colormap of the specified screen.

__

DefaultColormapOfScreen(screen)

Colormap XDefaultColormapOfScreen(screen)

      Screen *screen;

__

Both return the default colormap of the specified screen.

__

DefaultDepthOfScreen(screen)

int XDefaultDepthOfScreen(screen)

      Screen *screen;

__

Both return the depth of the root window.

__

DefaultGCOfScreen(screen)

GC XDefaultGCOfScreen(screen)

      Screen *screen;

__

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.

__

DefaultVisualOfScreen(screen)

Visual *XDefaultVisualOfScreen(screen)

      Screen *screen;

__

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;

__

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;

__

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;

__

Both return the display of the specified screen.

__

int XScreenNumberOfScreen(screen)

      Screen *screen;

__

The XScreenNumberOfScreen function returns the screen index number of the specified screen.

__

EventMaskOfScreen(screen)

long XEventMaskOfScreen(screen)

      Screen *screen;

__

Both return the event mask of the root window for the specified screen at connection setup time.

__

WidthOfScreen(screen)

int XWidthOfScreen(screen)

      Screen *screen;

__

Both return the width of the specified screen in pixels.

__

HeightOfScreen(screen)

int XHeightOfScreen(screen)

      Screen *screen;

__

Both return the height of the specified screen in pixels.

__

WidthMMOfScreen(screen)

int XWidthMMOfScreen(screen)

      Screen *screen;

__

Both return the width of the specified screen in millimeters.

__

HeightMMOfScreen(screen)

int XHeightMMOfScreen(screen)

      Screen *screen;

__

Both return the height of the specified screen in millimeters.

__

MaxCmapsOfScreen(screen)

int XMaxCmapsOfScreen(screen)

      Screen *screen;

__

Both return the maximum number of installed colormaps supported by the specified screen (see section 9.3).

__

MinCmapsOfScreen(screen)

int XMinCmapsOfScreen(screen)

      Screen *screen;

__

Both return the minimum number of installed colormaps supported by the specified screen (see section 9.3).

__

PlanesOfScreen(screen)

int XPlanesOfScreen(screen)

      Screen *screen;

__

Both return the depth of the root window.

__

RootWindowOfScreen(screen)

Window XRootWindowOfScreen(screen)

      Screen *screen;

__

Both return the root window of the specified screen.

2.3. Generating a NoOperation Protocol Request

To execute a NoOperation protocol request, use XNoOp.

__

XNoOp(display)

      Display *display;

__

The XNoOp function sends a NoOperation protocol request to the X server, thereby exercising the connection.

2.4. Freeing Client-Created Data

To free in-memory data that was created by an Xlib function, use XFree.

__

XFree(data)

     void *data;

__

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.

2.5. Closing the Display

To close a display or disconnect from the X server, use XCloseDisplay.

__

XCloseDisplay(display)

      Display *display;

__

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 resource 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, close_mode)

      Display *display;

      int close_mode;

close_mode

Specifies the client close-down mode. You can pass DestroyAll, RetainPermanent, or RetainTemporary.

__

The XSetCloseDownMode 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.

2.6. 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:

When the close-down mode is DestroyAll, the X server destroys all of a client's resources as follows:

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:

However, the X server does not reset if you close a connection with a close-down mode set to RetainPermanent or RetainTemporary.

2.7. 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();

__

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.

__

void XLockDisplay(display)

      Display *display;

__

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.

__

void XUnlockDisplay(display)

      Display *display;

__

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.

2.8. 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, client_data, fd, opening, watch_data)

      Display *display;

      XPointer client_data;

      int fd;

      Bool opening;

      XPointer *watch_data;

Status XAddConnectionWatch(display, procedure, client_data)

      Display *display;

      XWatchProc procedure;

      XPointer client_data;

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, procedure, client_data)

      Display *display;

      XWatchProc procedure;

      XPointer client_data;

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, fd)

      Display *display;

      int fd;

__

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, fd_return, count_return)

      Display *display;

      int **fd_return;

      int *count_return;

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.

Xlib - C Library X11, Release 6.4

3

Chapter 3

Window Functions

In the X Window System, a window is a rectangular area on the screen that lets you view graphic output. Client applications can display overlapping and nested windows on one or more screens that are driven by X servers on one or more machines. Clients who want to create windows must first connect their program to the X server by calling XOpenDisplay. This chapter begins with a discussion of visual types and window attributes. The chapter continues with a discussion of the Xlib functions you can use to:

This chapter also identifies the window actions that may generate events.

Note that it is vital that your application conform to the established conventions for communicating with window managers for it to work well with the various window managers in use (see section 14.1). Toolkits generally adhere to these conventions for you, relieving you of the burden. Toolkits also often supersede many functions in this chapter with versions of their own. For more information, refer to the documentation for the toolkit that you are using.

3.1. 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:

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:

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;

__

The XVisualIDFromVisual function returns the visual ID for the specified visual type.

3.2. 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:

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 */

/* 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:

3.2.1. 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 speci