Volume One: Xlib Programming Manual for Version 11 of the X Window System X Window SystemISBN 1−56592−002−3 1992 Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this book, and O’Reilly & Associates, Inc. was aware of a trademark claim, the designations have been printed in caps or initial caps. This document is based in part on Xlib−−−C Language X Interface, by Jin Gettys, Ron Newman, and Robert Scheifer, and the X Window System Protocol, Version 11, by Robert Scheifer and Ron Newman, both of which are copyright © 1985, 1986, 1987, the Massachusetts Institute of Technology, Cambridge, Massachusetts, and Digital Equipment Corporation, Maynard, Massachusetts. In addition, we have included some material provided in Oliver Jones’ Xlib Tutorial Overheads, which was distributed at the MIT X Conference in January 1988 and which is copyright © 1987 Apollo Computer, Inc. We have used this material under the terms of its copyright, which grants free use, subject to the following conditions: "Permission to use, copy, modify and distribute this documentation (i.e., the original MIT, DEC, Sun Microsystems, or Apollo material) for any purpose and without fee is hereby granted, provided that the above copyright notice appears in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the names of MIT, Apollo, Digital, Tektronix, or Sun not be used in advertising or publicity pertaining to this documentation without specific, written prior permission. MIT and Digital make no representations about the suitability of the software described herein for any purpose. It is provided ‘as is’ without expressed or implied warranty. " Note, however, that those portions of this document that are based on the original X11 documentation and other source material have been significantly revised, and that all such revisions are copyright © 1987, 1988, 1989, and 1990 O’Reilly & Associates, Inc. Inasmuch as the proprietary revisions cannot be separated from the freely copyable MIT source material, the net result is that copying of this document is not allowed. Sorry for the doublespeak! While every precaution has been taken in the preparation of this book, the publisher assumes no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein. August 1988: First Edition. November 1988: Minor revisions. May 1989: Release 3 updates added. Minor revisions. April 1990: Second Edition covers Release 3 and Release 4. July 1990: Minor revisions. October 1990: Minor revisions. December 1991: Minor revisions. June 1992: Third Edition covers Release 4 and Release 5. March 1993: Minor revisions. Preface About This Manual This manual describes the X library, the C Language programming interface to Version 11 of the X Window System. The X library, known as Xlib, is the lowest level of programming interface to X. This library enables a programmer to write applications with an advanced user interface based on windows on the screen, with complete network transparency, that will run without changes on many types of workstations and personal computers. Xlib is powerful enough to write effective applications without additional programming tools and is necessary for certain tasks even in applications written with higher−level "toolkits." There are a number of these toolkits for X programming, the most notable being the DEC/MIT toolkit Xt, the Andrew toolkit developed by IBM and Carnegie−Mellon University, and the InterViews toolkit from Stanford. These toolkits are still evolving, and only Xt is currently part of the X standard. Toolkits simplify the process of application writing considerably, providing a number of widgets that implement menus, command buttons, and other common features of the user interface. This manual does not describe Xt or any other toolkit. That is done in Volumes Four and Five of our X Window System series. Nonetheless, much of the material described in this book is helpful for understanding and using the toolkits, since the toolkits themselves are written using Xlib and allow Xlib code to be intermingled with toolkit code. Summary of Contents This manual is divided into two volumes. This is the first volume, the Xlib Programming Manual. It provides a conceptual introduction to Xlib, including tutorial material and numerous programming examples. Arranged by task or topic, each chapter brings together a group of Xlib functions, describes the conceptual foundation they are based on, and illustrates how they are most often used in writing applications (or, in the case of the last chapter, in writing window managers). Volume One is structured so as to be useful as a tutorial and also as a task−oriented reference. The second volume, the Xlib Reference Manual, includes reference pages for each of the Xlib functions, organized alphabetically for ease of reference; a permuted index; and numerous appendices and quick reference aids. Volume One and Volume Two are designed to be used together. To get the most out of the examples in Volume One, you will need the exact calling sequences of each function from Volume Two. To understand fully how to use each of the functions described in Volume Two, all but the most experienced X "hacker" will need the explanation and examples in Volume One. Both volumes include material from the original Xlib and X11 protocol documentation provided by MIT, as well as from other documents provided on the MIT release tape. We have done our best to incorporate all of the useful information from the MIT documentation, to correct code references we found to be in error, to reorganize and present it in a more useful form, and to supplement it with conceptual material, tutorials, reference aids, and examples. In other words, this manual is not only a replacement but is a superset of the MIT documentation. Those of you familiar with the MIT documentation will recognize that each reference page in Volume Two includes the detailed description of the routine found in Gettys, Newman, and Scheifler’s Xlib−C Language X Interface, plus, in many cases, additional text that clarifies ambiguities and describes the context in which the routine would be used. We have also added cross references to related reference pages and to where additional information can be found in Volume One. How to Use This Manual Volume One is intended as an introduction to all the basic concepts of X programming and also as a useful reference for many of the most common programming techniques. It is divided into 14 chapters, which describe and demonstrate the use of the X programming library, and numerous appendices. You will find it necessary to read at least Chapters 1, 2, and 3 before attempting to program with the X library. Chapter 1, Introduction, provides a discussion of the context in which X programs operate. Chapter 2, X Concepts, describes the conceptual foundations underlying X programming. Chapter 3, Basic Window Program, presents a simple program. Chapters 4 through 9 (Window Attributes, The Graphics Context, Drawing Graphics and Text, Color, Events, and The Keyboard and Pointer) discuss various programming techniques that are used in all X programs. These chapters can be read as a tutorial and consulted for reference later. Chapter 10, Internationalization, and Chapter 11, Internationalized Text Input describe the Xlib features for making an application usable in any language without changes to the application binary. These features were added in Release 5. Chapter 12, Interclient Communication, is a description of communication between applications and between applications and the window manager, including properties and selections. The proposed conventions for interclient communication are presented in Appendix L, Interclient Communcation Conventions, of Volume Zero, X Protocol Reference Manual (as of the second printing). Chapter 13, Managing User Preferences, describes the facilities provided for database management, parsing the command line, and managing user preferences. Xlib calls this the resource manager. Chapter 14, A Complete Application, provides an example of a complete application. This chapter is especially useful in demonstrating managing user preferences with the resource manager. Chapter 15, Other Programming Techniques, describes programming techniques that will be useful to some but not all programs. It should be scanned for applicable techniques and read in detail when needed for a particular project. Chapter 16, Window Management, describes what window managers do and how they work. This information should provide a more complete knowledge of the variety of contexts in which X applications may function. It also describes the Xlib functions that are intended primarily for window management. A simple window manager program is described. Appendix A, Specifying Fonts, describes how the programmer should specify default font names. Appendix B, X10 Compatibility, describes the routines supported in X11 for compatibility with X Version 10. Appendix C, Writing Extensions to X, is a guide to writing extensions to X. This is for experienced X programmers only. It is provided so that this manual can serve as a complete replacement for the MIT Xlib documentation. Appendix D, The basecalc Application, presents the complete code for basecalc, the complete application described in Chapter 12, A Complete Application. Appendix E, Event Reference, describes each event type in a reference page format. Included is how to select the events, when they are generated, the contents of the event structures, and notes on how to use them. This information is vital in using the numerous events. Appendix F, The Xmu Library, describes the routines in this miscellaneous utilities library that are useful in Xlib programming. This library is not an X Consortium standard but is widely available. Appendix G, Sources of Additional Information, lists where to get the X software, companies that offer training in X programming, and descriptions of additional published books on the subject.