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.
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.
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 (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.
Appendix H, Release Notes, describes the changes between Releases 3, 4 and 5. This manual describes Release 4 and Release 5.
The Glossary gives you somewhere to turn should you run across a term with which you are unfamiliar. Some care has been taken to see that all terms are defined where they are first used in the text, but this assumes a sequential reading of the manual.
Volume Two consists of a permuted index, reference pages to each library function, and appendices that cover macros, structures, function groups, events, fonts, colors, cursors, keysyms, and errors. Finally, Volume Two concludes with at-a-glance charts that help in setting the graphics context (GC) and the window attributes. This volume should be consulted to obtain the specifics of calling each Xlib function.
The example programs in this book are available electronically in a number of ways: by ftp, ftpmail, bitftp, and uucp. The cheapest, fastest, and easiest ways are listed first. If you read from the top down, the first one that works for you is probably the best. Use ftp if you are directly on the Internet. Use ftpmail if you are not on the Internet but can send and receive electronic mail to internet sites (this includes CompuServe users). Use BITFTP if you send electronic mail via BITNET. Use UUCP if none of the above works.
To use FTP, you need a machine with direct access to the Internet. A sample session is shown, with what you should type in boldface.
% ftp ftp.uu.net Connected to ftp.uu.net. 220 FTP server (Version 6.21 Tue Mar 10 22:09:55 EST 1992) ready. Name (ftp.uu.net:kismet): anonymous 331 Guest login ok, send domain style e-mail address as password. Password: kismet@ora.com (use your user name and host here) 230 Guest login ok, access restrictions apply. ftp> cd /published/oreilly/xbook/xlib/ 250 CWD command successful. ftp> binary (Very important! You must specify binary transfer for compressed files.) 200 Type set to I. ftp> get xlibprgs3.tar.Z 200 PORT command successful. 150 Opening BINARY mode data connection for xlibprgs3.tar.Z. 226 Transfer complete. ftp> quit 221 Goodbye. % |
If the file is a compressed tar archive, extract the files from the archive by typing:
% zcat xlibprgs3.tar.Z | tar xf - |
System V systems require the following tar command instead:
% zcat xlibprgs3.tar.Z | tar xof - |
If zcat is not available on your system, use separate uncompress and tar commands.
If the file is a compressed shar archive, you can extract the files from the archive by typing:
% uncompress FILE.shar.Z % /bin/sh FILE.shar |
FTPMAIL is a mail server available to anyone who can send and receive electronic mail to and from Internet sites. This includes most workstations that have an email connection to the outside world, and CompuServe users. You do not need to be directly on the Internet. Here's how to do it.
You send mail to ftpmail@decwrl.dec.com. In the message body, give the name of the anonymous ftp host and the ftp commands you want to run. The server will run anonymous ftp for you and mail the files back to you. To get a complete help file, send a message with no subject and the single word “help” in the body. The following is an example mail session that should get you the examples. This command sends you a listing of the files in the selected directory, and the requested examples file. The listing is useful in case there's a later version of the examples you're interested in.
% mail ftpmail@decwrl.dec.com Subject: reply jerry@ora.com (where you want files mailed) connect ftp.uu.net chdir /published/oreilly/xbook/xlib/ dir binary uuencode (or btoa if you have it) get xlibprgs3.tar.Z quit % |
A signature at the end of the message is acceptable as long as it appears after “quit.”
All retrieved files will be split into 60KB chunks and mailed to you. You then remove the mail headers and concatenate them into one file, and then uudecode or atob it. Once you've got the desired file, follow the directions under FTP to extract the files from the archive.
VMS, DOS, and Mac versions of uudecode, atob, uncompress, and tar are available. The VMS versions are on gatekeeper.dec.com in /archive/pub/VMS.
BITFTP is a mail server for BITNET users. You send it electronic mail messages requesting files, and it sends you back the files by electronic mail. BITFTP currently serves only users who send it mail from nodes that are directly on BITNET, EARN, or NetNorth. BITFTP is a public service of Princeton University. Here's how it works.
To use BITFTP, send mail containing your ftp commands to BITFTP@PUCC. For a complete help file, send HELP as the message body.
The following is the message body you should send to BITFTP:
FTP ftp.uu.net NETDATA
USER anonymous
PASS your Internet email address (not your bitnet address)
CD /published/oreilly/xbook/xlib/
DIR
BINARY
GET xlibprgs3.tar.Z
QUIT
|
Once you've got the desired file, follow the directions under FTP to extract the files from the archive. Since you are probably not on a UNIX system, you may need to get versions of uudecode, uncompress, atob, and tar for your system. VMS, DOS, and Mac versions are available. The VMS versions are on gatekeeper.dec.com in /archive/pub/VMS.
Questions about BITFTP can be directed to Melinda Varian, MAINT@PUCC on BITNET.
UUCP is standard on virtually all UNIX systems, and is available for IBM-compatible PCs and Apple Macintoshes. The examples are available by UUCP via modem from UUNET; UUNET's connect-time charges apply.
You can get the examples from UUNET whether you have an account or not. If you or your company has an account with UUNET, you will have a system with a direct UUCP connection to UUNET. Find that system, and type:
uucp uunet\!~/published/oreilly/xbook/xlib//xlibprgs3.tar.Z yourhost\!~/yourname/ |
The backslashes can be omitted if you use the Bourne shell (sh) instead of csh. The file should appear some time later (up to a day or more) in the directory /usr/spool/uucppublic/yourname. If you don't have an account but would like one so that you can get electronic mail, then contact UUNET at 703-204-8000.
If you don't have a UUNET account, you can set up a UUCP connection to UUNET using the phone number 1-900-468-7727. As of this writing, the cost is 50 cents per minute. The charges will appear on your next telephone bill. The login name is “uucp” with no password. For example, an L.sys/Systems entry might look like:
uunet Any ACU 19200 1-900-468-7727 ogin:--ogin: uucp |
Your entry may vary depending on your UUCP configuration. If you have a PEP-capable modem, make sure s50=255s111=30 is set before calling.
It's a good idea to get the file /published/oreilly/xbook/xlib//ls-lR.Z as a short test file containing the filenames and sizes of all the files in the directory.
Once you've got the desired file, follow the directions under FTP to extract the files from the archive.
Once you've got the examples and unpacked the archive as described above, you're ready to compile them. The easiest way is to use imake, a program supplied with the X11 distribution that generates proper Makefiles on a wide variety of systems. imake uses configuration files called Imakefiles which are included. If you have imake, you should go to the top-level directory containing the examples, and type:
% xmkmf % make Makefiles % make |
All the application-defaults files are in the main examples directory. The application-defaults files are not automatically installed in the system application-defaults directory (usually /usr/lib/X11/app-defaults on UNIX systems). (See Chapter 9, Resource Management and Type Conversion, for details.) If you have permission to write to that directory, you can copy them there yourself. Otherwise, you can set the XAPPLRESDIR environment variable to the complete path of the directory where you installed the examples. The value of XAPPLRESDIR must end with a / (slash). (Most of the examples will not function properly without the application-defaults files.)
Readers should be proficient in the C programming language, although examples are provided for infrequently used features of the language that are necessary or useful when programming with X. In addition, general familiarity with the principles of raster graphics will be helpful.
The C Programming Language by B. W. Kernighan and D. M. Ritchie.
The following documents are included on the X11 source tape:
Xt Toolkit Intrinsics by Joel McCormack, Paul Asente, and Ralph Swick
Xt Toolkit Widgets by Ralph Swick and Terry Weissman
Xlib-C Language X Interface by Jim Gettys, Ron Newman, and Robert Scheifler
X Window System Protocol, Version 11 by Robert Scheifler
The following other books on the X Window System are available from O'Reilly and Associates, Inc.:
Volume Zero -- X Protocol Reference Manual
Volume Two -- Xlib Reference Manual
Volume Three -- X Window System User's Guide
Volume Four -- X Toolkit Intrinsics Programming Manual
Volume Five -- X Toolkit Intrinsics Reference Manual
Volume Six -- Motif Programming Manual
Volume Seven -- XView Programmer's Guide
Volume Eight -- X Administrator's Guide (forthcoming)
PHIGS Programming Manual
PHIGS Reference Manual
Quick Reference -- The X Window System in a Nutshell
Please write to tell us about any flaws you find in this manual or how you think it could be improved, to help us provide you with the best documentation possible.
Our U.S. mail address, e-mail address, and telephone number are as follows:
O'Reilly and Associates, Inc. 103 Morris Street Sebastopol, CA 95472 (800) 338-6887 UUCP: uunet!ora!adrian Internet: adrian@ora.com
This manual is being resold by many workstation manufacturers as their official X Window System documentation. For information on volume discounts for bulk purchase, call O'Reilly and Associates, Inc. at 617-354-5800, or send e-mail to linda@ora.com (uunet!ora!linda).
Source licensing terms for online documentation are also available.
The information contained in this manual is based in part on Xlib-C Language X Interface, written by Jim Gettys, Ron Newman, and Robert Scheifler, and the X Window System Protocol, Version 11, by Robert Scheifler (with many contributors). The X Window System software and these documents were written under the auspices of Project Athena at MIT. In addition, this manual includes material from Oliver Jones' Xlib tutorial presentation, which was given at the MIT X Conference in January 1988, and from David Rosenthal's Inter-Client Communication Conventions Manual. I owe a great debt to the X Consortium policy allowing others to build on their work.
I would like to thank the people who helped this book come into being. It was Tim O'Reilly who originally sent me out on a contract to write a manual for X Version 10 for a workstation manufacturer and later to another company to write a manual for X Version 11, from which this book began. I have learned most of what I know about computers and technical writing while working for Tim. For this book, he acted as an editor, he helped me reorganize several chapters, he worked on the Color and Managing User Preferences chapters when time was too short for me to do it, and he kept my spirits up through this long project. While I was concentrating on the details, his eye was on the overall presentation, and his efforts improved the book enormously.
This book would not be as good (and we might still be working on it) had it not been for Daniel Gilly. Daniel was my production assistant for critical periods in the project. He dealt with formatting issues, checked for consistent usage of terms and noticed irregularities in content, and edited files from written corrections by me and by others. His job was to take as much of the work off me as possible, and with his technical skill and knowledge of UNIX, he did that very well.
This manual has benefitted from the work and assistance of the entire staff of O'Reilly and Associates, Inc. Sue Willing was responsible for graphics and design, and she proofed many drafts of the book; Linda Mui tailored the troff macros to the design by Sue Willing and myself and was invaluable in the final production process; John Strang figured out the resource manager and wrote the original section on that topic; Karen Cakebread edited a draft of the manual and established some conventions for terms and format. Peter Mui executed the “at-a-glance” tables for the inside back cover; Tom Scanlon entered written edits and performed copy fitting; Donna Woonteiler wrote the index of the book; Valerie Quercia, Tom Van Raalte, and Linda Walsh all contributed in some small ways; and Cathy Brennan, Suzanne Van Hove, and Jill Berlin fielded many calls from people interested in the X manual and saved me all the time that would have taken. Ruth Terry, Lenny Muellner, and Donna Woonteiler produced the Second Edition, with graphics done by Chris Reilley. Mike Sierra produced the Third Edition. A special thanks to everyone at O'Reilly and Associates for putting up with my habits of printer and terminal hogging, lugging X books around, recycling paper, and for generally being good at what they do and good-natured to boot.
David Flanagan wrote much of the material on X11R5, which appeared originally in his book Programmer's Supplement for Release 5. I'm sincerely grateful to him for doing such a great job.
I would also like to thank the people from other companies that reviewed the book or otherwise made this project possible: John Posner, Barry Kingsbury, Jeff MacMann and Jeffrey Vroom of Stellar Computer; Oliver Jones of Apollo Computer; Sam Black, Jeff Graber, and Janet Egan of Masscomp; Al Tabayoyon, Paul Shearer, and many others from Tektronix; Robert Scheifler and Jim Fulton of the X Consortium (who helped with the Color and Managing User Preferences chapters), and Peter Winston II and Aub Harden of Integrated Computer Solutions. Despite the efforts of the reviewers and everyone else, any errors that remain are my own.
-- Adrian Nye