XVIew Reference Manual Linux 2 Free ebook download
XView Programming Manual
Volume Seven
XView Programming
Manual
By Dan Heller
Updated for XView Version 3.2 by Thomas Van Raalte
O’Reilly & Associates, Inc.
XView Programming Manual by Dan Heller Updated for XView Version 3.2 by Thomas Van Raalte Copyright © 1990, 1991 O’Reilly & Associates, Inc. All rights reserved. Printed in the United States of America.
X Series Editor: Tim O’Reilly Editor: Dale Dougherty Printing History: January 1990: First edition.
April 1990: Minor corrections. July 1990: Second edition. Updated for XView Version 2. October 1990: Minor corrections. September 1991: Third edition. Updated for XView Version 3. March 1992: Minor corrections. August 1992: Minor corrections. August 1993: Minor additions. Updated for XView Version 3.2.
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.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.
This book is printed on acid-free paper with 50% recycled content, 10-15% post-consumer waste. O’Reilly &
Associates is committed to using paper with the highest recycled content available consistent with high quality.
Volume 7: ISBN 0–937175–87-0[11/93]
Table of Contents
Volume 7A: Programming Manual
Page
Figures
Page
Examples
Page
Tables
Page
This page intentionally left blank
to preserve original page counts.
This page intentionally left blank
to preserve original page counts.
P re fa Preface ce
XView (X Window-System-based Visual/Integrated Environment for Workstations) is a user-interface toolkit to support interactive, graphics-based applications running under the X Window System. This toolkit, developed by Sun Microsystems, Inc., is derived from earlier toolkits for the SunView windowing system. With over 2000 SunView applications in the workstation market, there are many programmers already familiar with the SunView applica- tion programmer’s interface (API).
XView has many advantages for programmers developing new applications in X, such as a mature and proven API based on the development experience of SunView programmers. It features an object-oriented style interface that is straightforward and simple to learn. Like any X toolkit, XView provides a set of pre-built, user-interface objects such as can- vases, scrollbars, menus, and control panels. The appearance and functionality of these
OPEN LOOK GUI
objects follow the Graphical User Interface ( ) specification. Jointly devel- oped by Sun Microsystems and AT&T as the graphical user interface standard for System V
OPEN LOOK
Release 4, provides users with a simple, consistent, and efficient interface for performing tasks within an application.
XView is based upon Xlib, the lowest level of the X Window System available to the pro- grammer. While developing XView user interfaces does not require Xlib programming expe- rience, there are good reasons for learning more about Xlib, especially if your application renders graphics.
Please Read This Section! This manual provides a basic introduction to developing applications using the XView Toolkit. You do not need any knowledge of SunView, and prior experience with the X Win- dow System is helpful, but also not required. Nonetheless, like any complex system, a pro- grammer needs to know a lot to program effectively in XView. For each functional area in XView, there are chapters that present the basic concepts and sug- gest some common ways to implement and use a particular function. Also addressed are some snags to watch out for when implementing certain combinations of functions. Care was taken to keep the content of the chapters brief and to the point. Simple and straightforward functions are not discussed in depth.
The XView Reference Manual is a companion to this manual. It contains complete descrip-
tions for all of the XView attributes and procedures, as well as additional reference material.
The XView Programming Manual has been updated to cover XView Version 3, and includes
several appendices providing compatibility information for previous XView versions.
XView Version 3 contains many features not available in previous versions, including: a
notice package, a selection package and a drag and drop package. The new Version 3 pack-
ages are presented in the corresponding chapters in this manual.If you can’t figure out how to accomplish a task because it is not documented here, don’t
despair —that does not mean it cannot be done. Some features in XView are not addressed in
this book—especially the more advanced ones. You are encouraged to experiment with the toolkit and discover new ways of using XView.
How to Use This Manual
The chapters in the book are designed to be read sequentially. However, that is not a strong requirement. Reading ahead probably won’t affect your understanding of the material, although later chapters might reference earlier material. The following paragraphs briefly describe the contents of this book:
XView and the X Window System, provides a conceptual overview of the X
Chapter 1, OPEN LOOK Window System, the role of the XView Toolkit, and the graphi- cal user interface. It provides a general introduction to basic X terminology, but it does not go into great detail about X.
The XView Programmer’s Model, provides an overview of XView as an
Chapter 2, object-oriented programming system. The programmer creates and modifies
OPEN LOOK
objects that implement the interface. This chapter also dis- cusses windows as objects that receive events. It introduces callback func- tions as the method of registering application-specific event handlers.
Creating XView Applications, begins from the application developer’s point
Chapter 3, of view and explains the basic elements of an XView application. It describes what is involved in initializing XView and creating XView objects such as frames and subwindows.
Frames, explains how to create window frames. There are two basic types of
Chapter 4, frames: base frames and command frames. Each application has at least one base frame that manages subwindows, panels, and other objects. It presents the routines used to create and manage frames.
Canvases and Openwin, presents canvases as the most basic type of subwin-
Chapter 5, dow or window pane. It presents the canvas model, which permits a drawing surface larger than what is visible in the canvas subwindow.
Handling Input, explains how events are handled by X, the Notifier, and
Chapter 6, XView objects.
Panels, explains a variety of OPEN LOOK
Chapter 7, controls that are implemented as items on a control panel. It demonstrates how to create and use buttons, check boxes, choices, lists, messages, toggles, text items , and sliders. A set of panel attributes controls the behavior in common with all panel items.
P There are also item-specific attributes. re fa
Text Subwindows, describes how to create a text subwindow and how to use
Chapter 8,
ce its text editing features.
TTY Subwindows, describes the tty subwindow that performs terminal emula-
Chapter 9, tion functions. Scrollbars, covers the creation and use of scrollbars. A scrollbar is a window Chapter 10, attached to another window, such as a canvas or text subwindow or a panel. The scrollbar package only manages the scrollbar; the application must gauge the impact of scrolling on its windows. Menus, explains how to implement various sorts of pop-up menus. Chapter 11, Notices, explains how pop-up windows serve as notices or dialog boxes. Chapter 12, Cursors, shows various OPEN LOOK Chapter 13, pointers and demonstrates their use. Icons, describes the use of bitmap images as application icons. When an Chapter 14, application is closed, or iconified, the application is represented on the screen as an icon.
Nonvisual Objects, describes objects that do not contain windows: Server,
Chapter 15, Screen, and Fullscreen. Fonts, describes how to load and use fonts from the X server. Chapter 16, Resources, describes the implications of X resources for an XView applica- Chapter 17, tion. Resources allow individual users to control and customize their envi- ronment.
Selections, discusses how XView applications communicate with other appli-
Chapter 18, OPEN cations, including window managers and applications that are not LOOK-compliant. It shows how XView provides for selections according to the Inter-Client Communication Conventions Manual.
Drag and Drop, discusses how XView applications implement dragging and
Chapter 19, dropping, where data is transferred by selecting an item and moving it to another workspace location. This is one method XView provides for applica- tions to communicate with other applications.
The Notifier, describes the Notifier and advanced event handling. It
Chapter 20, describes the relationship of the Notifier and X to the host operating system. Color, discusses issues concerning color in windows and other XView Chapter 21, objects.
Internationalization , discusses the internationalization features of XView.
Chapter 22, Help Facilities, discusses the help mechanism available in XView packages. Chapter 23,
Error Recovery, discusses error handling in XView packages.
Chapter 24, XView Internals, discusses the internals to the XView packages and intro- Chapter 25, duces the concepts involved in writing your own packages. The Selection Service, describes the selection service which provides compa- Appendix A, SELECTION tibility with older versions of XView that did not have a Pack- age.
Notices, describes the notice procedure notice_prompt()
Appendix B, which pro-
NOTICE vides compatibility with older versions of XView that did not have a Package.
Mouseless Model Keyboard Mappings, presents the mouseless model key-
Appendix C, board mappings.
XView Version 3.2 Additions, describes the changes and additions for XView
Appendix D, Version 3.2, including the File Chooser documentation.
OPEN LOOK User Interface Compliance, discusses XView’s compliance with
Appendix E, OPEN LOOK GUI Functional Specification. the Example Programs, presents supplementary programs.
Appendix F,
Assumptions
Readers should be proficient in the C programming language, although examples are pro- vided for infrequently used features of the language that are necessary or useful when pro- gramming with X. In addition, general familiarity with the principles of raster graphics is helpful. Finally, if you do not understand how to use Xlib routines to render graphics, then
OPEN LOOK
writing useful programs might be difficult, although you should be able to build user interfaces easily.
Font Conventions Used in This Manual Italic is used for:
- UNIX pathnames, filenames, program names, user command names, and options for user commands. New terms where they are introduced. •
Typewriter Font is used for:
Anything that would be typed verbatim into code, such as examples of source • code and text on the screen.
XView packages.* • The contents of include files, such as structure types, structure members, sym- • bols (defined constants and bit flags), and macros.
P
XView and Xlib functions. •
re fa • Names of subroutines of the example programs. ce Italic Typewriter Font
is used for: Arguments to XView functions, since they could be typed in code as shown but • are arbitrary.
Helvetica Italics are used for: • Titles of examples, figures, and tables.
Boldface is used for: • Chapter and section headings.
Related Documents The C Programming Language by B. W. Kernighan and D. M. Ritchie
The following documents are included on the X11 source tape and are also available from Sun Microsystems, Inc. and Addison-Wesley Publishing Company, Inc.:
OPEN LOOK Graphical User Interface Functional Specification OPEN LOOK Graphical User Interface Style Guide
The following books in the X Window System series from O’Reilly and Associates, Inc. are currently available: Volume Zero — X Protocol Reference Manual Volume One — Xlib Programming 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 Quick Reference — The X Window System in a Nutshell
CANVAS CANVAS_* *When referring to all members of a particular package, such as , the notation will be used.
This should not be interpreted as a C-language pointer construct.
Requests for Comments
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, phone numbers, and e-mail addresses are as follows: O’Reilly and Associates, Inc. 103 Morris Street, Suite A Sebastopol, CA 95472 in USA and Canada 1-800-998-9938, international +1 707-829-0515
UUCP
: uunet!ora!xview Internet: [email protected]
Obtaining the Example Programs
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.
FTP
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:eileen): anonymous 331 Guest login ok, send domain style e-mail address as password. Password: [email protected] (use your user name and host here) 230 Guest login ok, access restrictions apply. ftp> cd /published/oreilly/xbook/xview 250 CWD command successful. ftp> binary ( Very important! You must specify binary transfer for compressed files. ) 200 Type set to I. ftp> get xview.ora.examples.tar.Z 200 PORT command successful. 150 Opening BINARY mode data connection for xview.ora.examples.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 xview.ora.examples.tar.Z | tar xvf –
System V systems require the following tar command instead:
P
% zcat xview.ora.examples.tar.Z | tar xovf –
re fa ce If zcat is not available on your system, use separate uncompress and tar commands. FTPMAIL 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 [email protected] . In the message body, give the name of the anon- ymous 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 sub- ject 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 [email protected] Subject:
reply [email protected] ( where you want files mailed ) connect ftp.uu.net chdir /published/oreilly/xbook/xview dir binary uuencode (or btoa if you have it) get xview.ora.examples.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 btoa 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, btoa, uncompress, and tar are available. The VMS versions are on gatekeeper.dec.com in /archive/pub/VMS .
BITFTP
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/xview DIR BINARY GET xview.ora.examples.tar.Z QUIT
Once you’ve got the desired file, follow the directions under FTP to extract the files from the
UNIX
archive. Since you are probably not on a system, you may need to get versions of
uudecode, uncompress, btoa, and tar for your system. VMS, DOS, and Mac versions are
available. The VMS versions are on gatekeeper.dec.com in /archive/pub/VMS .BITFTP BITNET Questions about can be directed to Melinda Varian, MAINT@PUCC on .
UUCP
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/xview/xview.ora.examples.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/uucppub-
lic/yourname. If you don’t have an account but would like one so that you can get electronic
UUNET mail, then contact at 703-204-8000.UUNET UUCP UUNET
If you don’t have a account, you can set up a connection to 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 login:--login: uucp
UUCP
Your entry may vary depending on your 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/ls-lR.Z as a short test file containing the filenames and sizes of all the files in the directory.
P re
Once you’ve got the desired file, follow the directions under FTP to extract the files from the
fa ce archive. Acknowledgments :-)
I always wanted to do this —but for my first record album! This book was influenced by an amalgamation of several sources: The SunView Program-
mer’s Manual for design and structure of the chapters, the people on the XView development
team at Sun Microsystems for technical detail and the latest up-to-the-minute changes, and my personal experience in programming for narrative content. Chapter 1, XView and the X
Window System, is based on Chapter 1 of Volume Four, X Toolkit Intrinsics Programming Manual, by Adrian Nye.
This book was created using SoftQuad’s sqtroff, a PostScript laser printer and a Sun 3/60 color workstation. Special thanks to everyone at O’Reilly & Associates for their diligent efforts. In particular, Dale Dougherty, Daniel Gilly, Laurel Katz, Lenny Muellner, Chris Reilley, Ruth Terry, and Sue Willing. Many others pitched in for the final push to complete this book. At Sun Microsystems, I’d like to thank Richard Probst who helped make this entire project possible, Tom Jacobs, for keeping everything in order and reading all that e-mail, Tony Hillman, and the rest of the reviewing squad. Also, Bart Schaefer, for taking care of Mush while I’ve been too busy. Mike Ilnicki for con- tinuing to play racquetball with me. Penguin’s frozen yogurt for nutrition. David Letterman for being on at the perfect time: dinner.
. . . and most of all, I’d like to thank Tim O’Reilly —the only one who could talk me, a cast-in-stone programmer, into trying my hand at technical writing. Thanks for the confi- dence in me.
Acknowledgments for XView Version 3 Update
Thanks to John Stone for all his help in preparing this manual. John dealt with formatting issues and helped produce several review drafts. Special thanks also go to Darci Chapman for her assistance. Jon Lee edited several chapters of the draft. Dale Dougherty kept the big picture in sight and managed this project. Thanks to Chris Reil- ley who did the illustrations. Lenny Muellner, Sue Willing, Michael Sierra, and Eileen Kra- mer put the final manual together. The XView developers at Sun Microsystems spent many hours reviewing the new chapters as well as the draft of the complete, updated manual. In particular, Chris Kasso added exten- sively to the new Version 3 material and answered numerous questions. Thanks to Isa Hashim who made many additions and corrections. Mitch Jerome was very helpful and pro- vided a large amount of new material. Darren Austin, Sri Atreya, Shirley Joe, and Shanmugh Natarajan reviewed several drafts and helped in numerous ways. Stan Raichlen helped to test the code and update the figures. Thanks also go to Tony Hillman, Bhaskar Prabhala, and Greg Kimura. Carole Coffland, Dave Borders, Jeremy Uejio, Dipti Ranganathan, Richard Goldstein, and Martha Venegas read the draft of this manual and made helpful suggestions. Despite all the reviews, any errors that remain are my own.
This page intentionally left blank
to preserve original page counts.
This page intentionally left blank
to preserve original page counts.
1 XView and the X Window System
X X
The XView Toolkit allows a programmer to build the interface to an application without hav-
V W ie
ing to learn many of the details of the underlying windowing system. However, it is valuable
w in d a
to have some understanding of X before attempting to build applications under XView. This o
n w d
chapter introduces many of the most important concepts on which the X Window System is S
th ys
based and describes the computing environment for X applications. It also describes the role e
te of the XView Toolkit in the X Window System. m
For the most part, this chapter assumes that you are new to programming the X Window Sys- tem. This chapter describes the basics of the X Window System—further details will be described as necessary later in the manual. However, this book does not repeat the detailed description of Xlib programming found in Volume One, Xlib Programming Manual. If you already have some experience programming the X Window System, you might wish to begin at Chapter 2, The XView Programmer’s Model.
1.1 The X Window System
X controls a bit-mapped display in which every pixel (dot on the screen) is individually con- trollable. This allows drawing of pictures in addition to text. Until recently, individual con- trol of screen pixels was widely available only on personal computers (PCs) and high-priced technical workstations, while more general-purpose machines were limited to output on text- only terminals. X brings the same world of graphic output to both PCs and more powerful machines. Figure 1-1 shows an X application in comparison with a traditional text terminal.
Like other windowing systems, X divides the screen into multiple input and output areas called windows, each of which can act as an independent virtual terminal. Using a terminal emulator, windows can run ordinary text-based applications. However, windows can also run applications designed to take advantage of the graphic power of the bitmapped display.
X takes user input from a pointer, which is usually a mouse but could just as well be a track- ball or tablet. The pointer allows the user to point at certain graphics on the screen and use the buttons on the mouse to control a program without using the keyboard. This method of using programs is often easier to learn than traditional keyboard control, because it is more intuitive. Figure 1-2 shows a typical pointer being used to select a menu item.
1 5lib/ 2 include/ 1 sccs 1 5include 1 hosts/ 1 pub/ Line 1 Xlir3@ 1 kvm 1 share/ 1 adm@ 4 lib/ 1 spool@ 1 sbin/ 3 etc/ 1 preserve/ total 49 Move Area Overlay Area Filled Circle Copy Area Flood Fill Invert Area Clear Area Set Area Invert All X window system Clear All Set All Circle xterm 6 bin/ 1 local/ 1 sqps 1 diag/ 1 mdc/ 1 tmp@ 1 dict 1 old/ 2 ucb/ colorful-96% 1 demo/ 1 man@ 1 sys@ 1 boot/ 8 lost+found/ 1 stand/ Set Hot Spot Write Output Quit The terms are as follows: communications discussions on June 9, 1989 and in subsequent reached in our This letter details the book distribution agreement we .LP Dear Mr. Sekino: .Ls N text terminal that we will from Janpanese customers to Toppan. The only exption is ORA will refer all sales inquiries Associates, Inc. (ORA). in Japan for all titles published by O'Reilly and Toppan shall be the esclusive distributor /fBExclusivity/fP. @ "sekinol" 108 lines, 3726 characters .Li
Grouch-0 8%!g Figure 1-1. An X application and a traditional text terminal colorful-19% colorful:/usr Workspace total 49 cmdtool(CONSOLE)-/bin/csh Exit...
Properties...