By convention, a preface describes the book itself,
while the introduction describes the subject matter. You should read
through the preface to get an idea of how the book is organized, the
conventions it follows, and so on.
This book describes how to write applications using
the Motif toolkit from the Open Software Foundation (OSF). The Motif
toolkit is based on the X Toolkit Intrinsics (Xt), which is the
standard mechanism on which many of the toolkits written for the X
Window System are based. Xt provides a library of user-interface
objects called widgets and gadgets, which provide a
convenient interface for creating and manipulating X windows,
colormaps, events, and other cosmetic attributes of the display. In
short, widgets can be thought of as building blocks that the programmer
uses to construct a complete application.
However, the widgets that Xt provides are generic in
nature and impose no user-interface policy whatsoever. That is the job
of a user-interface toolkit such as Motif. Motif provides a complete
set of widgets designed to implement the application look and feel
specified in the Motif Style Guide and the Motif Application
Environment Specification.
The book provides a complete programmer's guide to
the Motif toolkit. While the OSF/Motif toolkit is based on Xt, the
focus of the book is on Motif itself, not on the Intrinsics. Detailed
information about Xt is provided by Volume Four, X Toolkit
Intrinsics Programming Manual, and references are made to that
volume throughout the course of this book. You are not required to have
Volume Four in order to use this book effectively, as the books are not
companion volumes, but complementary ones. However, truly robust
applications require a depth of knowledge about Xt and Xlib, the layer
on which Xt itself is based, that is not addressed in this book alone.
We never leave you completely in the dark about Xt or Xlib functions
that we use or reference, but you won't learn everything there is to
know about them through this particular volume.
This book covers Motif 1.2, which is the latest
major release of the Motif toolkit. Motif 1.2 is based on Release 5 of
the Xlib and Xt specifications (X11R5). This release of Motif provides
many new features, as well as a number of enhancements to existing
functionality. All of the changes in Motif 1.2 are summarized in
Section #smotif12, which provides references to other sections that
describe the changes in more detail.
There are several plots and subplots in this book
and the stories told are intertwined. Our primary goal is to help you
learn about the Motif environment from both the programmer's and the
user's perspectives. However, we are talking to you as a programmer,
not as a user. We treat the user as a third party who is not with us
now. In order to create an application for the user, you sometimes have
to assume her role, so at times we may ask you to play such a role to
help you think about things from the user's perspective rather than the
programmer's.
Each chapter begins by discussing the goals that
Motif is trying to achieve using a particular widget or gadget. For
example, before we describe how to create a FileSelectionDialog, we
introduce the object visually and conceptually, discuss its features
and drawbacks, and put you in the role of the user. Once you understand
what the user is working with, you should have a better perspective on
the task of presenting it to her.
The next subplot is that of application design. Many
design concepts transcend the graphical user interface (GUI) and are
common to all programs that interact with users. You could even
interpret this book as a programmer's guide that happens to use Motif
as an example. As you read the material, you should stop and think
about how you might approach a particular interface method if you were
using another toolkit instead of Motif. A wild concept, perhaps, but
this approach is the key to better application design and to toolkit
independence. If Motif changes in a later release, or if you decide to
port your application to another toolkit or even another windowing
system, the more generalized your code is, the easier it will be to
bring it into a new realm successfully.
The last story we are telling is that of general
programming technique. By providing you with examples of good
programming habits, styles, and usages, we hope to propagate a
programming methodology that has proven to be successful over the
years. These techniques have been applied to applications that have
been ported to multiple architectures and operating systems. As an
added bonus, we have thrown in a number of interesting programming
tricks. No, these are not hacks, but conveniences that are particular
to C, to UNIX, or even to the X Window System. We don't focus on these
things, but they are made available to you in passing, so you should
have no problem identifying them when they come up.
This book is intended to be used as a programmer's
manual, not a reference manual. Volume Six B, Motif Reference Manual
, contains reference material for all of the Motif library functions and
widget classes. We have tried to identify those features of the toolkit
that are most important for general discussion, so we do not discuss
every aspect of the Motif toolkit in the body of this book.
Any major software development effort, especially in
its early stages, has bugs that prevent certain features from being
used and the Motif toolkit is no exception. There are some bugs in the
Motif toolkit that have not yet been worked out, but this does not
imply that the toolkit is poorly written or riddled with errors.
Throughout the book, we try to alert you to any potential problems you
may encounter due to bugs. In some cases, there are things that work in
Motif, but they are poorly designed, and we don't recommend that you
use them. Again, we provide an explanation of what's going on and
sometimes describe an alternative solution. There are also some
features, resources, and functions available in the toolkit that are
not supported by OSF. OSF reserves the right to change anything not
publicly documented, so rather than discuss undocumented features, we
simply ignore them.
We should also point out that this book is not
intended to solve all your problems or answer all your questions
concerning Motif or its toolkit. It is not going to spoon feed you by
giving you step-by-step instructions on how to achieve a particular
task. You are encouraged, and even expected, to experiment on your own
with the example applications or, better yet, with your own programs.
We want to provide you with discussion and examples that provoke you
into asking questions like, "What would happen if I changed this
program to do this?" It would be unrealistic to believe that we could
address every problem that might come up. Rather than approaching
situations using overly specific examples, we discuss them in a
generalized way that should be applicable to many different scenarios.
The basic method for creating simple applications in
Motif is conceptually simple and straightforward. Even if you only
dabble in C, you can probably understand the concepts well enough to do
most things. However, unless you have a strong handle on the C
programming language, there is an upper limit to what you will be able
to do when you try to create a full-featured, functioning application.
After all, the user-interface portion of most applications should make
up no more than 30-40% of the total code. The functionality of an
application is up to you and is not discussed here. Without a strong
background with C, or some other structured programming language, you
might have a problem keeping up with the material presented here.
This book also assumes that you are familiar with
the concepts and architecture of the X Toolkit Intrinsics, which are
presented in Volume Four, X Toolkit Intrinsics Programming Manual,
Motif Edition, and Volume Five, X Toolkit Intrinsics Reference
Manual. A basic understanding of the X Window System is also
useful. For some advanced topics, the reader may need to consult
Volume One, Xlib Programming Manual, and Volume Two, Xlib
Reference Manual.
While this book attempts to serve the widest
possible audience, that does not imply that the material is so simple
that it is only useful to novice programmers. In fact, this book can be
considered an advanced programmer's handbook, since in many places, it
assumes a fairly sophisticated knowledge of many features of the X
Window System.
Each chapter is organized so that it gets more
demanding as you read through it. Each chapter begins with a short
introduction to the particular Motif element that is the subject of the
chapter. The basic mechanics involved in creating and manipulating the
object are addressed next, followed by the resources and other
configurable aspects of the object. If there is any advanced material
about the object, it is presented at the end of the chapter. Many
chapters also include exercises that suggest how the material can be
adapted for uses not discussed explicitly in the text.
While the chapters may be read sequentially, it is
certainly not required or expected that you do so. As you will soon
discover, there are many circular dependencies that justify skipping
around between chapters. Since there is no organization that would
eliminate this problem, the material is not organized so that you
"learn as you go." Instead, we organized the material in a top-down
manner, starting with several chapters that provide an introduction to
the Motif look and feel, followed by chapters organized on a
widget-by-widget basis. The higher-level manager widgets are discussed
first, followed by the primitive widgets and gadgets. Advanced material
is positioned at the end of the book, since the details are not of
paramount importance to the earlier material. The last four chaapters
are devoted to UIL.
In short, everything is used everywhere. Starting at
the beginning, however, means that we won't necessarily assume you know
about the material that is referenced in later chapters. On the other
hand, the later chapters may make the assumption that you are aware of
material in earlier chapters.
The book is broken down into twenty six chapters and one appendix as follows:
The following books on the X Window System are
available from O'Reilly & Associates:
Italic is used for:
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. Source licenses must
be obtained directly from OSF:
OSF Direct
Open Software Foundation
11 Cambridge Center
Cambridge, MA 02142
USA
+1 617 621-7300
Internet: direct@osf.org
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.
Versions of the example programs for both Motif 1.2
and Motif 1.1 are available electronically. If you want the Motif 1.2
version, use the filename examples12.tar.Z, as shown in the
sample sessions below. The filename for the Motif 1.1 version is
examples11.tar.Z.
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:paula): anonymous 331 Guest login ok, send domain style e-mail address as password. Password: paula@ora.com (use your user name and host here) 230 Guest login ok, access restrictions apply. ftp> cd /published/oreilly/xbook/motif 250 CWD command successful. ftp> binary (Very important! You must specify binary transfer for compressed files.) 200 Type set to I. ftp> get examples12.tar.Z 200 PORT command successful. 150 Opening BINARY mode data connection for examples12.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 examples12.tar.Z | tar xf -System V systems require the following tar command instead:
% zcat examples12.tar.Z | tar xof -
If zcat is not available on your system, use
separate uncompress and tar commands.
FTPMAIL is a mail server available to anyone who can
send electronic mail to and receive it from Internet sites. This
includes any company or service provider that allows email connections
to the Internet. Here's how you do it.
You send mail to ftpmail@online.ora.com. In
the message body, give 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 example files. The
listing is useful if there's a later version of the examples you're
interested in.
% mail ftpmail@online.ora.com Subject: reply-to paula@ora.com Where you want files mailed open cd /published/oreilly/xbook/motif dir mode binary uuencode get examples12.tar.Z quitA 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.
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/motif DIR BINARY GET examples12.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/motif/examples12.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.
It's a good idea to get the file
/published/oreilly/xbook/motif/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.
The example programs are written by Dan Heller and
Paula Ferguson for the Motif Programming Manual, Copyright 1994
O'Reilly & Associates, Inc. Permission to use, copy, and modify these
programs without restriction is hereby granted, as long as this
copyright notice appears in each copy of the program source code.
For the purposes of making the book easier to read,
the above copyright notice does not appear in the program examples.
However, the copyright does exist in the electronic form of the
programs available on the Internet.
Once you have the examples and you've 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 that
are included with the examples. If you have imake, you should go
to the top-level directory containing the examples, and type:
% xmkmf % make Makefiles % make
The examples all have the same application class for
purposes of the app-defaults file. The class name is "Demos" and the
app-defaults file (Demos) in the main examples directory should
be placed in /usr/lib/X11/app-defaults/Demos on a UNIX system.
If you can't write to that directory, or if your normal X11 directory
tree is installed elsewhere, you should set the environment variable
XAPPLRESDIR to the directory where you installed the examples.
Many of the screenshots in this book that are not
based on the example programs are of Z-Mail, an electronic mail
program. Z-Mail is the culmination of years of work, starting with a
freely-distributed program called Mail User's Shell (Mush). Mush's only
GUI interface was SunView, although it also supported tty and curses
interfaces. Over the course of writing this book, I developed the Motif
interface for Z-Mail that you see here, which was my reality-check that
what I preach really does work.
It should be mentioned that Z-Mail also supports an
OPEN LOOK interface. To do the OPEN LOOK version, I chose to use OLIT
(OPEN LOOK Intrinsics Toolkit) because, like Motif, it is based on the
X Toolkit Intrinsics. Xt is a great environment for developing
applications for the X environment. I also believe that the best
applications are those whose user interfaces can be abstracted,
generalized, and modularized so that you can unplug one interface and
plug in another. My approach to doing that is also reflected in this
book, although not as a major topic.
Since the first writing of this book, I'm happy to
say that Z-Mail has become a great success. It has been ported to
Microsoft Windows and to the Apple Macintosh, both of which have
graphical user environments that are substantially different from Motif
in look, feel, and API implementations. However, the models described
in this book, namely the abstraction and generalization of core
components from one another, were maintained throughout the course of
the porting processes.
Dan Heller
The current edition of this book was updated to cover Motif 1.2,
including drag and drop and internationalization, by Paula Ferguson.
Dave Brennan, of HaL Computer Systems, took on the unenviable task of
learning everything he could about UIL and Mrm, in order to write the
UIL programming material for this edition. He did a great job of
covering a complex subject.
Adrian Nye deserves recognition for allowing me to
work on this project, when I'm sure that he had other projects he would
have liked to send my way. I don't think either one of us had any idea
how involved this update project would become. He also provided
editorial support that helped keep me on track in the final stages of
the work on the book.
The other writers at O'Reilly & Associates in
Cambridge, Valerie Quercia and Linda Mui, provided support that kept me
sane while I was working on the book. Their willingness to listen and
offer advice is greatly appreciated. Extra gratitude goes to Valerie
Quercia for her help with the screen dumps for the book.
David Flanagan deserves credit for always being
willing to answer my questions about the technical details of Motif and
X. Douglas Rand, Scott Meeks, and David Brooks at OSF answered
questions and helped review the new material. Daniel Jahn, of SAS
Institute, Inc., also provided valuable review comments for this
edition.
Special thanks go to the people who worked on the
production of this book. The final form of this book is the work of the
staff at O'Reilly & Associates. The authors would like to thank Chris
Reilly for the figures, Donna Woonteiler, Chris Tong, and Ellie Cutler
for indexing, Lenny Muellner for tools support, and Stephen Spainhour,
Clairemarie Fisher O'Leary, Kismet McDonough, and Eileen Kramer for
copyediting and production of the final copy. Thanks also to Donna
Woonteiler for her patience in helping me understand the production
process.
Finally, I'd like to thank my friends for putting up
with me when I kept telling them that I'd be done working non-stop in a
month or two. Special thanks to my housemate, Meredith Hunt, who put up
with me when I was stressed out and not much fun to live with, and who
took care of the cats when I wasn't around. My friends Karen Lewis and
Liz Bradley opened their house to me when I needed to escape and be
someplace where there are mountains. And thanks to the great people at
the Boston Rock Gym, who provided me with a much-needed outlet for
climbing the walls.
Despite the efforts of all of these people, the
authors alone are responsible for any errors or omissions that remain.
Paula M. Ferguson
The first edition of this book took over a year and a half to write
and compile from the beginning. But when I look back on the entire
effort, and I think about what it takes to do things like this (and
other difficult things in life), I realize that what it really
requires is a state of mind and a mental model that lends itself to
seeing the big picture and choosing to do what's necessary to get the
job done.
To this, I can only credit one person, Tim O'Reilly,
my friend and editor of this book. It's his approach to life, his
values, his way of thinking about things, and his talent for expressing
them is what has influenced me more than anything else in adopting the
kind of mental framework necessary to write a book like this (or to
start my company, Z-Code Software, or to do anything I do in life). He
never gives me advice when I ask for it, nor does he tell me what to
do. Instead, he uses quotes, cites anecdotes, or just describes an
abstract thought that always seems to be appropriate to every
situation. In short, he's shown me a way of thinking about things that
appreciates the big picture. I take this with me wherever I go, and in
whatever I do. Without it, I couldn't have written this book.
Those who worked most closely with me on the project
include Irene Jacobson, who dedicated long hours to meticulous editing
and support. Her intuition and insistence on proper use of words saved
many cuts of Tim O'Reilly's scalpel. David Lewis also gets super-high
marks for his excellent feedback, for his technical expertise, and for
helping take care of certain Z-Mail ports while I was busy hunched over
this computer. More thanks go to the great folks at Z-Code Software,
Bart Schaefer and Don Hatch, for not laughing at me when I told people
for at least six months that the book would take "just two more weeks
now." (I really meant it, too!) Actually, they helped quite a bit with
reading nroff'd manuscripts, and by taking care of the business
whenever I was at O'Reilly & Associates' offices in "Bahston."
The figures in this book come in two forms:
screendumps and hand-generated figures done by Chris Reilly. What a
super job he did--and always on time. And how can I thank Kismet
McDonough, Lenny Muellner, Rosanne Wagger, Mike Sierra, Eileen Kramer,
and the other production folks at O'Reilly & Associates, who did a
wonderful job of copyediting, proofing, page layout, and all the other
things that make the difference between a manuscript and a finished
book. And that's not all: Ellie Cutler wrote the index. Tony Marotto of
Cambridge Computer Associates figured out how to convert our screen
dumps into PostScript files and how to scale screen dumps without the
moire and plaid patterns you see in many books. He used Jeff
Poskanzer's pmbplus to convert xwd dumps to gif
format, and then wrote a set of image-processing programs that shift
and enhance the tones. Daniel Gilly took on the enormous job of
developing the reference appendices when it became clear that I
wouldn't have time.
Enthusiastic applause goes to Libby Hanna (do I get
a real official OSF/Motif decoder ring now!!??), David Brooks,
Scott Meeks, Susan Thompson, Carl Scholz, Benjamin Ellsworth, and the
entire cast at OSF in Cambridge for their support. And, of course,
everyone on the motif-talk mailing list. (I wish I could remember
all your names!)
People I can't forget: Bill "Rock" Petro, Akkana,
Mike Harrigan at NCD for the terminal, Danny Backx at BIM (sorry I
didn't get you any review copies!), John Harkin, and certain folks at
Sun that I'd love to mention, but I can't because they're into that
OL-thang and they wouldn't want to be associated with the M-word
, Jordan Hayes, Paula Ferguson, and Kee Hinckley (just because he's
cool). Also thanks to Ralph Swick and Donna Converse at the X
Consortium for being somewhat patient with me.
Added thanks to Lynn Vaughn at CNN for keeping me
informed about what's going on in the world, since I have no time to
look out the window; to Short Attention-Span Theatre, for keeping me
amused; and to Yogurt World, for keeping me fed.
This book was written using a Sun workstation, the
vi editor (for which I guess I ought to thank Bill Joy), SoftQuad's
sqtroff, X11R4 and various versions of Motif (1.0 through 1.1.3).
For catching and reporting errors that have been
fixed in the second printing, I'd like to thank Akkana, Wayne Robertz,
Glen Shute, Scott Strool, Trevor Taylor, Peter Wagner, Andrew Wason,
Tim Weinrich, and Bill Wohler.
Dan Heller
We have tested and verified all of the information
in this book to the best of our ability, but you may find that features
have changed (or even that we have made mistakes!). Please let us know
about any errors you find, as well as your suggestions for future
editions, by writing:
O'Reilly & Associates, Inc.
103 Morris Street, Suite A
Sebastopol, CA 95472
1-800-998-9938 (in the US or Canada)
1-707-829-0515 (international/local)
1-707-829-0104 (FAX)
You can also send us messages electronically. To be put on the mailing
list or request a catalog, send email to:
info@ora.com (via the Internet)
uunet!ora!info (via UUCP)
To ask technical questions or comment on the book, send email to:
bookquestions@ora.com (via the Internet)