XVIew reference manual linux 2

Volume SevenXView Programming Manual By Dan Heller Updated for XView Version 3.2 by Thomas Van Raalte O’Reilly & Associates, Inc... While developing XView user interfaces does not requir

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.

Table of Contents Volume 7A: Programming Manual

Page

2.3 Internal Attribute-Value Lists 23

2.5.3 Relationship Among the Notifier, Objects, and the Application 37

4.2.4 Quit Confirmation 67

Chapter 6 Handling Input 115

7.1.1 Scrollable Panels 156

7.16 Numeric Text Items 193

8.7 Positioning the Text Displayed in a Text Subwindow 226

18.2.3.1 Specifying the target type (selection requestor) 400

18.2.3.5 Requesting the CLIPBOARD selection-non-blocking 402

18.2.4.2 Sample selection owner with conversion procedure 404

18.2.7 Cleanup - When the Selection Completes (Selection Owner) 410

18.4.1 How to Handle Incremental Replies (Selection Requestor) 416

Chapter 19 Drag and Drop 433

20.8 Reading and Writing Through File Descriptors 479

21.3.1 Foreground and Background Colors 520

22.2.1 Localized Text Handling - Application Programmer Interface 544

Chapter 23 Help Facilities 557

25.5.2 The Implementation File 593

25.11.9.10 The resize function 629

Appendix D Version 3.2 and the File Chooser 677

F.4 type_font.c 727

Page

1-5 The Notifier exists between the server and the XView application 10

4-3 Simple base frame created without any FRAME attributes specified 63

7-6 Visual feedback for button controls 166

7-11 Sample panel with abbreviated choice (unselected and selected) 174

10-2 Relationship between a scrollbar and the object it scrolls 255

18-3 Selection requestor class hierarchy 399

A-1 Byte stream after selection_ask() returns the current text selection 641

Page

14-1 The icon_demo.c program 340

15-1 Getting a pointer for a particular frame object (screen.c) 351

B-2 The trigger_notice.c program 659

12-2 Screen-Locking Notice Attributes (for NOTICE_LOCK_SCREEN = TRUE) 317

19-1 Drag and Drop Semantic Events 437

This page intentionally left blank

to preserve original page counts.

This page intentionally left blank

to preserve original page counts.

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

objects follow theOPEN LOOKGraphical User Interface (GUI) specification Jointly

devel-oped by Sun Microsystems and AT&T as the graphical user interface standard for System V

Release 4,OPEN LOOKprovides 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: anotice 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’tdespair —that does not mean it cannot be done Some features in XView are not addressed inthis book—especially the more advanced ones You are encouraged to experiment with thetoolkit 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 strongrequirement 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:

Chapter 1, XView and the X Window System, provides a conceptual overview of the X

Window System, the role of the XView Toolkit, and theOPEN LOOKcal user interface It provides a general introduction to basic X terminology,but it does not go into great detail about X

graphi-Chapter 2, The XView Programmer’s Model, provides an overview of XView as an

object-oriented programming system The programmer creates and modifiesobjects that implement the OPEN LOOK 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.Chapter 3, Creating XView Applications, begins from the application developer’s point

of view and explains the basic elements of an XView application Itdescribes what is involved in initializing XView and creating XView objectssuch as frames and subwindows

Chapter 4, Frames, explains how to create window frames There are two basic types of

frames: base frames and command frames Each application has at least onebase frame that manages subwindows, panels, and other objects It presentsthe routines used to create and manage frames

Chapter 5, Canvases and Openwin, presents canvases as the most basic type of

subwin-dow or winsubwin-dow pane It presents the canvas model, which permits a drawingsurface larger than what is visible in the canvas subwindow

Chapter 6, Handling Input, explains how events are handled by X, the Notifier, and

XView objects

Chapter 7, Panels, explains a variety ofOPEN LOOKcontrols 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

There are also item-specific attributes

Chapter 8, Text Subwindows, describes how to create a text subwindow and how to use

its text editing features

Chapter 9, TTY Subwindows, describes the tty subwindow that performs terminal

emula-tion funcemula-tions

Chapter 10, Scrollbars, covers the creation and use of scrollbars A scrollbar is a window

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

Chapter 11, Menus, explains how to implement various sorts of pop-up menus.

Chapter 12, Notices, explains how pop-up windows serve as notices or dialog boxes.

Chapter 13, Cursors, shows variousOPEN LOOKpointers and demonstrates their use

Chapter 14, Icons, describes the use of bitmap images as application icons When an

application is closed, or iconified, the application is represented on the screen

as an icon

Chapter 15, Nonvisual Objects, describes objects that do not contain windows: Server,

Screen, and Fullscreen

Chapter 16, Fonts, describes how to load and use fonts from the X server.

Chapter 17, Resources, describes the implications of X resources for an XView

applica-tion Resources allow individual users to control and customize their

envi-ronment

Chapter 18, Selections, discusses how XView applications communicate with other

appli-cations, including window managers and applications that are not OPEN

LOOK-compliant It shows how XView provides for selections according to

the Inter-Client Communication Conventions Manual.

Chapter 19, Drag and Drop, discusses how XView applications implement dragging and

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 applicaapplica-tions

Chapter 20, The Notifier, describes the Notifier and advanced event handling. It

describes the relationship of the Notifier and X to the host operating system

Chapter 21, Color, discusses issues concerning color in windows and other XView

objects

Chapter 22, Internationalization , discusses the internationalization features of XView.

Chapter 23, Help Facilities, discusses the help mechanism available in XView packages.

Chapter 24, Error Recovery, discusses error handling in XView packages.

Chapter 25, XView Internals, discusses the internals to the XView packages and

intro-duces the concepts involved in writing your own packages

Appendix A, The Selection Service, describes the selection service which provides

compa-tibility with older versions of XView that did not have aSELECTION age

Pack-Appendix B, Notices, describes the notice procedure notice_prompt() which

pro-vides compatibility with older versions of XView that did not have aNOTICE

Package

Appendix C, Mouseless Model Keyboard Mappings, presents the mouseless model

key-board mappings

Appendix D, XView Version 3.2 Additions, describes the changes and additions for XView

Version 3.2, including the File Chooser documentation

Appendix E, OPEN LOOK User Interface Compliance, discusses XView’s compliance with

theOPEN LOOK GUI Functional Specification

Appendix F, Example Programs, presents supplementary programs.

Assumptions

Readers should be proficient in the C programming language, although examples are 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 ishelpful Finally, if you do not understand how to use Xlib routines to render graphics, thenwriting useful programs might be difficult, although you should be able to buildOPEN LOOKuser interfaces easily

pro-Font Conventions Used in This Manual

Italic is used for:

• UNIXpathnames, filenames, program names, user command names, and optionsfor user commands

• New terms where they are introduced

Typewriter Fontis used for:

• Anything that would be typed verbatim into code, such as examples of sourcecode 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

• XView and Xlib functions

• Names of subroutines of the example programs

Italic Typewriter Fontis used for:

• Arguments to XView functions, since they could be typed in code as shown but

are arbitrary

Helvetica Italicsare 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

*When referring to all members of a particular package, such as CANVAS , the notation CANVAS_* 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 beimproved, 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: xview@ora.com

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) UseBITFTPif you sendelectronic mail viaBITNET UseUUCPif none of the above works

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.

230 Guest login ok, access restrictions apply.

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:

% zcat xview.ora.examples.tar.Z | tar xovf –

If zcat is not available on your system, use separate uncompress and tar commands.

FTPMAIL

FTPMAILis 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

anon-ymous ftp host and the ftp commands you want to run The server will run anonanon-ymous 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

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

BITFTPis a mail server forBITNETusers You send it electronic mail messages requestingfiles, and it sends you back the files by electronic mail BITFTPcurrently serves only userswho send it mail from nodes that are directly onBITNET,EARN, or NetNorth.BITFTPis apublic service of Princeton University Here’s how it works

To useBITFTP, send mail containing your ftp commands to BITFTP@PUCC For a complete

help file, sendHELPas the message body

The following is the message body you should send toBITFTP:

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

Questions aboutBITFTPcan be directed to Melinda Varian, MAINT@PUCC onBITNET

UUCP

UUCPis standard on virtually allUNIXsystems, and is available for IBM-compatible PCs andApple Macintoshes The examples are available by UUCP via modem from UUNET;UUNET’s connect-time charges apply

You can get the examples fromUUNETwhether you have an account or not If you or yourcompany has an account withUUNET, you will have a system with a directUUCPconnection

toUUNET 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

mail, then contactUUNETat 703-204-8000

If you don’t have aUUNETaccount, you can set up aUUCPconnection toUUNETusing thephone number 1-900-468-7727 As of this writing, the cost is 50 cents per minute Thecharges 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