Xlib − C Language X Interface
`
`X Window System Standard
`
`X Version 11, Release 6.7
`
`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, 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
`
`APPLE 1050
`
`1
`
`

`

`The X Window System is a trademark of The Open Group.
`
`TekHVC is a trademark of Tektronix, Inc.
`
`Copyright © 1985, 1986, 1987, 1988, 1989, 1990, 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 documenta-
`tion 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 Soft-
`ware.
`
`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 PARTIC-
`ULAR 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 OTH-
`ERWISE, 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 pro-
`mote the sale, use or other dealings in this Software without prior written authorization from The Open Group.
`
`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 per-
`taining to this documentation without specific, written prior permission. Digital and Tektronix makes no representa-
`tions about the suitability of this documentation for any purpose. It is provided ‘‘as is’’ without express or implied war-
`ranty.
`
`2
`
`

`

`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 Dig-
`ital 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 use-
`ful document. The work they hav e done will help many everywhere. We also would like to thank
`Hal Murray (Digital SRC) and Peter George (Digital VMS) who contributed much by proofread-
`ing the early drafts of this document.
`Our thanks also goes to Jeff Dike (Digital UEG), Tom Benson, Jackie Granfield, and Vince Orgo-
`van (Digital VMS) who helped with the library utilities implementation; to Hania Gajewska (Dig-
`ital 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 signifi-
`cant that the bug reports (and many fi xes) during alpha and beta test came almost exclusively
`from just a few of the alpha testers, mostly hardware vendors working on product implementa-
`tions of X. The continued public contribution of vendors and universities is certainly to the bene-
`fit 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.
`
`3
`
`

`

`Finally, our thanks goes to MIT, Digital Equipment Corporation, and IBM for providing the envi-
`ronment 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 Founda-
`tion) and Bill McMahon (Hewlett-Packard). The principal author of the rest of the international-
`ization 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 imple-
`mentation. 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 Labo-
`ratory), Kazunori Nishihara (Fuji Xerox), Masaki Takeuchi (Sony), Katsuhisa Yano (Toshiba),
`Makoto Wakamatsu (Sony Corporation) for producing the another complete sample implementa-
`tion 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 Consor-
`tium), 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 fash-
`ion.
`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
`
`4
`
`

`

`of the design are due to them, many others have contributed substantially to the design and imple-
`mentation. They are: Takashi Fujiwara (Fujitsu), Yoshio Horiuchi (IBM), Makoto Inada (Digital),
`Hiromu Inukai (Nihon SunSoft), Song JaeKyung (KAIST), Franky Ling (Digital), Tom McFar-
`land (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 internation-
`alization 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
`
`5
`
`

`

`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 appli-
`cation programs (clients) use to interface with the window system by means of a stream connec-
`tion. 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 Win-
`dow 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 definiti ve 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
`
`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 subwin-
`dows. 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 dis-
`play 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 com-
`pletely 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
`
`1
`
`6
`
`

`

`Xlib − C Library
`
`X11, Release 6.7
`
`children of a window hav e 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 sup-
`pressed 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 windo w.
`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 hid-
`den and then brought back onto the screen, its contents may be lost. The server then sends the
`client program an Expose ev ent 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 applica-
`tions.
`Client programs are informed of events. Events may either be side effects of a request (for exam-
`ple, restacking windows generates Expose ev ents) 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 ev ents. These ev ents 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.
`
`2
`
`7
`
`

`

`Xlib − C Library
`
`X11, Release 6.7
`
`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, how-
`ev er, 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:
`<X11/Xlib.h>
`•
`This is the main header file for Xlib . The majority of all Xlib symbols are declared by
`including this file. This file also contains the preprocessor symbol XlibSpecificationRe-
`lease. This symbol is defined to ha ve the 6 in this release of the standard. (Release 5 of
`Xlib was the first release to ha ve this symbol.)
`<X11/X.h>
`This file declares types and constants for the X protocol that are to be used by applications.
`It is included automatically from <X11/Xlib.h>, so application code should never need to
`reference this file directly.
`<X11/Xcms.h>
`This file contains symbols for much of the color management facilities described in chapter
`6. All functions, types, and symbols with the prefix ‘‘Xcms’’, plus the Color Con version
`Contexts macros, are declared in this file. <X11/Xlib.h> m ust be included before including
`this file.
`<X11/Xutil.h>
`This file declares various functions, types, and symbols used for inter-client communication
`and application utility functions, which are described in chapters 14 and 16. <X11/Xlib.h>
`must be included before including this file.
`<X11/Xresource.h>
`This file declares all functions, types, and symbols for the resource manager facilities,
`which are described in chapter 15. <X11/Xlib.h> must be included before including this
`file.
`<X11/Xatom.h>
`This file declares all predefined atoms, which are symbols with the prefix ‘‘XA_’’.
`<X11/cursorfont.h>
`This file declares the cursor symbols for the standard cursor font, which are listed in appen-
`dix B. All cursor symbols have the prefix ‘‘XC_’’.
`<X11/keysymdef.h>
`This file declares all standard K eySym values, which are symbols with the prefix ‘‘XK_’’.
`The KeySyms are arranged in groups, and a preprocessor symbol controls inclusion of each
`
`•
`
`•
`
`•
`
`•
`
`•
`
`3
`
`8
`
`

`

`Xlib − C Library
`
`X11, Release 6.7
`
`group. The preprocessor symbol must be defined prior to inclusion of the file to obtain the
`associated values. The preprocessor symbols are XK_MISCELLANY, XK_XKB_KEYS,
`XK_3270, XK_LATIN1, XK_LATIN2, XK_LATIN3, XK_LATIN4, XK_KATAKANA,
`XK_ARABIC, XK_CYRILLIC, XK_GREEK, XK_TECHNICAL, XK_SPECIAL,
`XK_PUBLISHING, XK_APL, XK_HEBREW, XK_THAI, and XK_KOREAN.
`<X11/keysym.h>
`This file defines the preprocessor symbols XK_MISCELLANY , XK_XKB_KEYS,
`XK_LATIN1, XK_LATIN2, XK_LATIN3, XK_LATIN4, and XK_GREEK and then
`includes <X11/keysymdef.h>.
`<X11/Xlibint.h>
`This file declares all the functions, types, and symbols used for extensions, which are
`described in appendix C. This file automatically includes <X11/Xlib.h>.
`<X11/Xproto.h>
`This file declares types and symbols for the basic X protocol, for use in implementing
`extensions. It is included automatically from <X11/Xlibint.h>, so application and exten-
`sion code should never need to reference this file directly.
`<X11/Xprotostr.h>
`This file declares types and symbols for the basic X protocol, for use in implementing
`extensions. It is included automatically from <X11/Xproto.h>, so application and exten-
`sion code should never need to reference this file directly.
`<X11/X10.h>
`This file declares all the functions, types, and symbols used for the X10 compatibility func-
`tions, which are described in appendix D.
`
`•
`
`•
`
`•
`
`•
`
`•
`
`1.4. 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.
`•
`
`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:
`•
`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 (_).
`
`•
`•
`•
`
`•
`
`•
`
`4
`
`9
`
`

`

`Xlib − C Library
`
`X11, Release 6.7
`
`•
`•
`
`•
`
`•
`•
`•
`•
`
`•
`
`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 com-
`monly, 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.
`
`1.6. Programming Considerations
`The major programming considerations are:
`•
`Coordinates and sizes in X are actually 16-bit quantities. This decision was made to mini-
`mize the bandwidth required for a given lev el 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 his 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, howev er, is up to your application.
`For further information, see chapter 14 and the Inter-Client Communication Conventions
`Manual.
`
`•
`
`•
`
`•
`
`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:
`•
`X Portable Character Set
`A basic set of 97 characters, which are assumed to exist in all locales supported by Xlib.
`This set contains the following characters:
`
`a..z A..Z 0..9
`!"#$%&’()*+,-./:;<=>?@[\]ˆ_‘{|}˜
`<space>, <tab>, and <newline>
`
`•
`
`This set is the left/lower half of the graphic character set of ISO8859-1 plus space, tab, and
`newline. It is also the set of graphic characters in 7-bit ASCII plus the same three control
`characters. The actual encoding of these characters on the host is system dependent.
`Host Portable Character Encoding
`The encoding of the X Portable Character Set on the host. The encoding itself is not
`defined by this standard, but the encoding must be the same in all locales supported by Xlib
`on the host. If a string is said to be in the Host Portable Character Encoding, then it only
`contains characters from the X Portable Character Set, in the host encoding.
`
`5
`
`10
`
`

`

`Xlib − C Library
`
`X11, Release 6.7
`
`•
`
`•
`
`•
`
`•
`
`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 con-
`trol characters. If a string is said to be in the Latin Portable Character Encoding, then it
`only contains characters from the X Portable Character Set, not all of Latin-1.
`STRING Encoding
`Latin-1, plus tab and newline.
`POSIX Portable Filename Character Set
`The set of 65 characters, which can be used in naming files on a POSIX-compliant host,
`that are correctly processed in all locales. The set is:
`
`a..z A..Z 0..9 ._-
`
`•
`
`1.8. 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, sym-
`•
`bols defined in include files, or structure names. When declared and defined, function argu-
`ments 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 func-
`tions. 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 func-
`tion 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.
`
`•
`
`•
`
`6
`
`11
`
`

`

`Xlib − C Library
`
`X11, Release 6.7
`
`Chapter 11
`
`Event Handling Functions
`
`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
`ev ent.
`
`11.1. 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 XCre-
`ateWindow and XChangeWindowAttributes. Another way is to use XSelectInput.
`
`XSelectInput (display, w, event_mask)
`Display *display;
`Window w;
`long event_mask;
`
`display
`w
`event_mask
`
`Specifies the connection to the X server.
`Specifies the windo w whose events you are interested in.
`Specifies the e vent mask.
`
`The XSelectInput function requests that the X server report the events associated with the speci-
`fied e vent 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 ances-
`tor 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 win