Note that while Motif is used for the examples in this book, the techniques described are equally applicable to and provide a good introduction to programming with any other widget set based on Xt. It is not difficult to convert an application between any of the widget sets listed above, since all of them use the same Xt Intrinsics programming interface.
This book describes how to write X Window System programs using the Xt Intrinsics library (or simply Xt). Xt is a standard established by the X Consortium that provides an object-oriented programming style in the C language.
OSF's Motif library provides user-interface objects to be used with Xt. Motif is not an X Consortium standard, though it may nevertheless become a de facto industry standard. This book primarily describes the Xt Intrinsics, but it also provides an introduction to Motif and uses Motif for many of the examples.
The Xt Intrinsics together with a second library such as Motif are collectively called the X Toolkit.
The discussion of the X Toolkit is divided into three volumes, Volumes Four, Five, and Six of the X Window System Series available from O'Reilly & Associates, Inc.
This is Volume Four, X Toolkit Intrinsics Programming Manual, Motif Edition. It provides an explanation of the X Toolkit, including tutorial material and numerous programming examples. Arranged by task or topic, each chapter brings together a group of Xt functions, describes the conceptual foundation on which they are based, and illustrates how they are most often used in writing applications. This volume is structured to be useful as a tutorial and also as a task-oriented reference.
Volume Five, X Toolkit Intrinsics Reference Manual, includes reference pages for each of the Xt functions, as well as for the widget classes defined by Xt, organized alphabetically for ease of reference; a permuted index; and numerous appendices and quick reference aids.
Volume Six, Motif Programming Manual provides detailed, practical instructions for building real applications with the Motif widget set.
The three volumes are designed to be used together. To get the most out of the examples in Volume Four, you will need the exact calling sequences of each function from Volume Five. To understand fully how to use each of the functions described in Volume Five, all but the most experienced Toolkit “hacker” will need the explanation and examples in Volume Four. Volume Six gives you the specifics of using each Motif widget and guidance in practical programming.
Volumes Four and Five include material from the original Toolkit documentation provided by MIT, though in Volume Four this material is mostly limited to the appendices. We have done our best to incorporate all the useful information from the MIT documentation, 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 Five includes the detailed description of the routine found in X Toolkit Intrinsics--C Language 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 the definitions of structures and symbolic constants used as arguments or returned values by the function, as well as cross-references to related reference pages and to where additional information can be found in Volume Four.
This book makes no assumptions about the reader's knowledge of object-oriented programming or the X Window System. 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 the X Toolkit. In addition, general familiarity with the principles of raster graphics will be helpful.
However, even though the Toolkit is intended to hide the low-level X interface provided by Xlib, there are times in writing applications or widgets when Xlib functions will be necessary because no Xt feature exists to do the same thing. This book describes the most common occasions for using Xlib, but does not provide a reference to the particular functions involved. Additional documentation on Xlib, such as that provided by Volume One, Xlib Programming Manual, and Volume Two, Xlib Reference Manual, will be indispensable.
Several other books and a journal on the X Window System are available from O'Reilly & Associates, Inc.:
| Volume Zero | X Protocol Reference Manual | |
| Volume One | Xlib Programming Manual | |
| Volume Two | Xlib Reference Manual | |
| Volume Three | X Window System User's Guide, Motif Edition | |
| Volume Five | X Toolkit Intrinsics Reference Manual | |
| Volume Six | Motif Programming Manual | |
| Volume Seven | XView Programming Manual | |
| Volume Eight | X Window System Administrator's Guide (forthcoming, Fall 1992) | |
| Quick Reference | The X Window System in a Nutshell | |
| PHIGS in X | PHIGS Programming Manual PHIGS Reference Manual (forthcoming, Fall 1992) | |
| The X Resource | The X Resource is a journal dedicated to X programming. It contains the latest information about X including articles, papers, and documentation. |
The following book published by Prentice Hall may be necessary to obtain details of the Motif widgets: OSF/Motif Programmer's Reference
The following documents are included on the X11 source tape (the X distribution from MIT):
X Toolkit Intrinsics--C Language Interface, by Joel McCormack, Paul Asente, and Ralph Swick
X Toolkit Athena Widgets--C Language Interface, by Ralph Swick and Terry Weissman
Xlib--C Language X Interface, by Jim Gettys, Ron Newman, and Robert Scheifler
The following Nutshell Handbooks published by O'Reilly and Associates, Inc. are useful when programming in C:
Checking C Programs with lint, by Ian Darwin Managing Projects with make, by Andrew Oram and Steve Talbott Using C on the UNIX System, by Dave Curry Posix Programmer's Guide, by Donald Lewine Practical C Programming, by Steve Oualline Power Programming with RPC, by John Bloomer
The following is the classic introduction to C programming:
The C Programming Language, by B. W. Kernighan and D. M. Ritchie
Volume Four explains both application programming with widgets and widget programming (the design and coding of new widgets).
The first five chapters treat widgets largely as “black boxes,” which is appropriate considering the object-oriented philosophy of the Toolkit. These chapters also provide an overview of many elements of the X Toolkit, and so are appropriate for all readers.
| Chapter 1 | "Introduction to the X Window System," provides a discussion of the context in which X programs operate. Programmers who are comfortable programming with Xlib can skip "Chapter 1, Introduction to the X Window System." | |
| Chapter 2 | "Introduction to the X Toolkit and Motif," describes the conceptual foundations underlying Toolkit programming, and shows how to write simple programs that use widgets from existing widget sets. It introduces such fundamental Toolkit programming concepts as resources, the Translation Manager, callbacks, and actions. | |
| Chapter 3 | "More Techniques for Using Widgets," describes how to use some of the more complex widgets found in applications, including composite widgets, constraint widgets, and popups. It also describes how to define application resources and command-line options, and how to hardcode the value of widget resources when you create a widget. Finally, it describes how to create multiple top-level windows, and how to use application contexts to create applications that are more portable. | |
| Chapter 4 | "An Example Application," describes a complete application, in several iterations. First, it shows a simple version of the program, a bitmap editor, as it would be written assuming the existence of a BitmapEdit widget (which is actually developed in "Chapter 6, Inside a Widget"). Then, two refined versions are developed, each demonstrating additional Toolkit programming techniques. Finally, the same application is shown as it would be written if the bitmap editor were implemented in an application window rather than with the BitmapEdit widget, as it would be written if no BitmapEdit widget existed. | |
| Chapter 5 | "More About Motif," describes and illustrates the widgets available in the Motif 1.1 widget set, and introduces the features and functions provided by Motif that add to the programming model defined by Xt. As mentioned earlier, this volume does not contain detailed reference information on each widget, and it gives examples using only a few of the widgets in the Motif widget set. Additional information on each Motif widget is presented in Volume Six (available Spring '91). |
The next two chapters describe widget internals, and the process of creating new widgets. While this information is not essential for all application programmers, many applications require a custom widget to implement their special graphics capabilities.
| Chapter 6 | "Inside a Widget," describes the code inside a widget. Much of this code is common to all widgets. You can think of it as a framework that Xt uses to implement a widget's features. After reading this chapter, you should understand the procedure for creating your own widget around this framework. | |
| Chapter 7 | "Basic Widget Methods," describes a widget's initialize, expose, set_values, destroy, resize, and query_geometry methods. (A widget's methods are internal routines called automatically by Xt to give the widget a degree of independence from the application.) The chapter explains when Xt calls each method, and describes in detail what should be in each of these methods. Among other things, these methods prepare for and do the drawing of graphics that appear in a widget. This chapter describes what the Toolkit adds to the graphics model provided by Xlib but does not describe in detail how to draw using Xlib; this topic is described in Chapters 5, 6, and 7 of Volume One, Xlib Programming Manual. |
Later chapters treat various topics of interest to either application or widget programmers, or both. Some of these topics have been introduced in the earlier chapters and are explored more completely in the following ones.
| Chapter 8 | "Events, Translations, and Accelerators," describes the complete syntax of translation tables, which allow the user to configure the mapping of event sequences into widget actions. It also describes accelerators, a mechanism for mapping events in one widget to actions in another. | |
| Chapter 9 | "More Input Techniques," describes how to handle events with event handlers and how to use information from the event structure inside an event handler or action routine. It also describes how to get file, pipe, or socket input, how to use timeouts to call a function after a delay or at particular intervals, and how to use work procedures to do background processing. Finally, it discusses some low-level features of Xt for directly interacting with the event queue. | |
| Chapter 10 | "Resource Management and Type Conversion," is a more thorough discussion of how resources work and how they should be used. This chapter describes in detail the resource file format and the rules that govern the precedence of resource settings. It also describes how to add your own type converter so that you can set application- or widget-specific data through resources. Finally, it describes subresources and how to use them. | |
| Chapter 11 | "Interclient Communications," discusses communication through the X server between an application and the window manager, and between two applications. The application-window manager communication is performed by code in the Shell widget. The application sets shell resources to control this communication with the window manager. Application-application communication is usually done with a process called selections. This form of communication is already implemented in most widgets that display text, but you may want to implement it in your own custom widgets. Selections can also pass other kinds of data such as graphics. | |
| Chapter 12 | "Geometry Management," discusses how composite and constraint widgets manage the layout of widgets, and how to write your own simple composite and constraint widgets. | |
| Chapter 13 | "Menus, Gadgets, and Cascaded Popups," describes how menus work and describes several ways to create menu widgets. One of these ways involves the use of windowless widgets, or gadgets. This chapter also describes how to use more advanced features of the Xt popup mechanism, including modal cascades, to implement cascading popup menus. | |
| Chapter 14 | "Miscellaneous Toolkit Programming Techniques," describes various Xt functions and techniques that have not been treated elsewhere in the book. These include functions for error and warning handling, case conversion, using editres and so on. | |
| Appendix A | "Athena, OPEN LOOK, and Motif," provides a comparison of the widgets available in AT&T's OPEN LOOK widget set and OSF's Motif. These widgets are contrasted with those in the Athena widget set. | |
| Appendix B | "Specifying Fonts and Colors," gives information on the values that can be used when specifying fonts and colors as resources. | |
| Appendix C | "Naming Conventions," describes a suggested set of conventions for naming widgets and elements within widget code. | |
| Appendix D | "Release Notes," describes the changes between Release 4 and Release 5. This manual describes Release 4 and Release 5. | |
| Appendix E | "The xbitmap Application," shows the complete code for an advanced version of the xbitmap application and the BitmapEdit widget, which are described in Chapters 6 and 7. | |
| Appendix F | "Sources of Additional Information," lists where to get the X software, lists companies that offer training in X programming, and describes additional books on the subject that have been or soon will be published. | |
| Glossary | gives you somewhere to turn should you run across an unfamiliar term. Some care has been taken to see that all terms are defined where they are first used in the text, but not everyone will read the manual in sequential order. |
Volume Five consists of a permuted index, reference pages to each library function, and appendices that cover macros, structures, and defined symbols.
To help us provide you with the best documentation possible, please write to tell us about any flaws you find in this manual or how you think it could be improved.
Our U.S. mail address, e-mail address, and phone numbers are as follows:
O'Reilly & Associates, Inc. 103 Morris Street, Suite A Sebastopol, CA 95472 800-998-9938 international +1 707-829-0515 fax +1 707-829-0104 UUCP: uunet!ora.com!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 800-998-9938 or send e-mail to linda@ora.com (uunet!ora.com!linda).
For companies requiring extensive customization of the book, source licensing terms are also available.
The X window system is copyrighted but freely distributed. The only restriction this places on its use is that the copyright notice identifying the author and the terms of use must accompany all copies of the software or documentation. Thanks to this policy, the software is available for a nominal cost from a variety of sources. See "Appendix F, Sources of Additional Information" for a listing of these sources.
If your hardware vendor is an OSF member, they may be able to provide Motif binaries for your machine. Various independent vendors also provide binaries for some machines: see "Appendix F, Sources of Additional Information" for a listing of a few of these. Source licenses must be obtained directly from OSF. Call OSF at 617-621-7300 for ordering information.
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/xbook/xt/ 250 CWD command successful. ftp> binary (Very important! You must specify binary transfer for compressed files.) 200 Type set to I. ftp> get motifpg2.tar.Z 200 PORT command successful. 150 Opening BINARY mode data connection for motifpg2.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 motifpg2.tar.Z | tar xf - |
System V systems require the following tar command instead:
% zcat motifpg2.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/xbook/xt/ dir binary uuencode (or btoa if you have it) get motifpg2.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/xbook/xt/
DIR
BINARY
GET motifpg2.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/xbook/xt//motifpg2.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/xbook/xt//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).[1] If you have permission to write to that directory, you can copy them there yourself. Or you may 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.)
As mentioned above, this manual includes some material from the X Toolkit Intrinsics--C Language Interface, by Paul Asente and Ralph Swick. This is the document that defines the X Consortium standard for Xt, known as the Xt specification. Overt borrowings from the Xt specification are rare in this volume. However, the Xt specification document, as well as the sample code of Xt distributed with releases of X, provides the intellectual basis for most of what appears here. Many thanks to the X Consortium for their copyright policy that allows others to build on their work.
We'd like to thank Sony Microsystems for the loan of a Sony NEWS workstation running their implementation of the X Window System. The speed and power of the Sony workstation, and the support of Sony's staff, were a great help in developing these books. Additional development was done on a Sun-3 workstation running MIT's sample server, a Visual 640 X Display Station, and an NCD16 Network Display Station.
We would also like to thank the reviewers of the Alpha draft of this book, even though we almost had to start over because of their comments. They were David Lewis of Integrated Computer Solutions (ICS), Wendy Eisner of Sunquest Information Systems, Dan Heller of Island Graphics, Inc. (now working with O'Reilly and Associates), Miles O'Neal of Systems and Software Solutions, Inc., and Chris Peterson of MIT Project Athena (now of the X Consortium). Ian Darwin of SoftQuad and Bradley Ross of Cambridge Computer Associates reviewed the Beta draft. Extra thanks are due to Ralph Swick, Chris Peterson, and Robert Scheifler, who answered many questions during the development of this book.
Of course, we alone take responsibility for any errors or omissions that remain.
Special thanks go to Mark Langley, who wrote an early draft of this book. He helped to educate us about the Toolkit, and his efforts to make the book a success did not go unnoticed.
Special thanks also go to Integrated Computer Solutions, for their assistance in preparing this Motif edition. Thanks to Chris Peterson for permission to use his material on editres.
Of course, the authors would like to thank the entire staff of O'Reilly and Associates for producing the book, and the staff of Cambridge Computer Associates, Inc., for lending their support. David Flanagan and Paula Ferguson provided much of the information on Release 5 and Motif 1.2.
Perhaps most of all, we would like to thank our readers and customers for their patience, which we tested by promising that this book would be finished next month--every month for the last eight months. These days, with word processors, it is easy to generate a book-length manuscript, but no easier than it ever was to carve that text into something worth reading. We have had that book-length manuscript for a year, but have not been satisfied until now that it presented the material in a clear, friendly, and authoritative manner. We hope that the extra time we have spent boiling down the facts about this very new and continuously advancing subject will prove worthwhile to you, the reader.
--Adrian Nye and Tim O'Reilly