OSF/Motif™ Programmer's Guide

Revision 1.2

(For OSF/Motif Release 1.2)

Open Software Foundation

P T R Prentice Hall, Englewood Cliffs, New Jersey 07632

Contents

Preface xiii

Audience xiii

Applicability xiv

Purpose xiv

Document Usage xiv

Related Documents xvi

Typographic and Keying Conventions xvi Keyboard Conventions xvii Mouse Conventions xvii

Problem Reporting xviii

Chapter 1. Introduction 1-1

1.1 The X Window System 1-2

1.2 Xlib, Xt, and Motif 1-5 1.2.1 Xlib 1-5 1.2.2 Xt 1-6 1.2.3 Motif 1-11 1.2.4 Using Xlib, Xt, and Motif 1-14

1.3 Widget Classes and Hierarchy 1-15 1.3.1 Xt Classes 1-15 1.3.2 Motif Classes 1-16

1.4 Header Files and Libraries 1-20

Chapter 2. The Motif Programming Model 2-1

2.1 A User-Centered Model 2-3

2.2 Separating Interface from Application 2-5

2.3 Building Blocks: Primitive Widgets and Gadgets 2-6 2.3.1 Label and Separator 2-7 2.3.2 Buttons 2-8 2.3.3 ScrollBar 2-8 2.3.4 List 2-9

i

OSF/Motif Programmer's Guide

2.3.5 Text 2-9 2.4 Managers 2-10

2.4.1 Frame 2-10 2.4.2 Scale 2-11 2.4.3 PanedWindow 2-11 2.4.4 ScrolledWindow and MainWindow 2-11 2.4.5 RowColumn 2-12 2.4.6 BulletinBoard, Form, MessageBox,

SelectionBox 2-13 2.4.7 DrawingArea 2-14

2.5 Shells 2-15 2.5.1 VendorShell 2-15 2.5.2 DialogShell • 2-16 2.5.3 MenuShell 2-16

2.6 Applications, Top-Level Widgets, and Dialogs . . . . 2-16 2.6.1 Applications 2-17 2.6.2 Top-Level Widgets 2-18 2.6.3 Dialogs 2-18

2.7 Resources: User and Program Customization . . . . 2-19

2.8 Handling Input and Output 2-20

Chapter 3. Structure of a Motif Program 3-1

3.1 Including Header Files 3-3

3.2 Initializing the Intrinsics 3-3 3.2.1 The Initial Resource Database 3-4

3.3 Creating Widgets 3-9 3.3.1 Specifying Resource Values 3-10

3.4 Adding Callback Procedures 3-15

3.5 Making Widgets Visible 3-18 3.5.1 Managing Widgets 3-18 3.5.2 Realizing Widgets 3-19 3.5.3 Mapping Widgets 3-20 3.5.4 Multiple Screens, Displays, and

Applications 3-20 3.6 Entering the Event Loop 3-22

Chapter 4. Structure of a Program Using UIL and MRM 4-1

4.1 Structure of a UIL Module . 4-3 4.1.1 module Clause 4-3 4.1.2 Module-Level Declarations 4-4 4.1.3 include Directive 4-5 4.1.4 value Declaration 4-5

ii

Contents

4.1.5 identifier Declaration 4-6 4.1.6 procedure Declaration 4-6 4.1.7 object Declaration 4-7 4.1.8 list Declaration 4-11 4.1.9 end module Clause 4-13

4.2 Structure of a Program Using MRM 4-13 4.2.1 Including Header Files 4-13 4.2.2 Initializing the Intrinsics 4-13 4.2.3 Initializing MRM 4-14 4.2.4 Opening UID Files 4-14 4.2.5 Registering Callbacks and Identifiers . . . . 4-16 4.2.6 Fetching Information from UID Files . . . . 4-17 4.2.7 Closing the UID File 4-19 4.2.8 Defining Callback Procedures 4-19 4.2.9 Making Widgets Visible 4-19 4.2.10 Entering the Event Loop 4-21

Chapter 5. Basic Controls 5-1

5.1 Core, RectObj, XmPrimitive, and XmGadget Classes 5-2 5.1.1 Core 5-2 5.1.2 RectObj 5-2 5.1.3 XmPrimitive 5-3 5.1.4 XmGadget 5-3

5.2 Labels, Buttons, and Separators 5-4 5.2.1 Labels 5-4 5.2.2 Buttons 5-5 5.2.3 Separators 5-8

5.3 ScrollBar 5-8

5.4 Scale 5-10

5.5 List 5-12

5.6 Text and TextField 5-14

Chapter 6. Menus and Options 6-1

6.1 Menu Components: Buttons, RowColumn, MenuShell 6-2 6.1.1 Buttons 6-3 6.1.2 RowColumn 6-3 6.1.3 MenuShell 6-4

6.2 MenuBar 6-5

6.3 PopupMenu 6-6

6.4 PulldownMenu 6-8

iij

OSF/Motif Programmer's Guide

6.5 OptionMenu 6-9

6.6 RadioBox and Checkbox 6-11

6.7 TearOffMenus 6-12

Chapter 7. Dialogs 7-1

7.1 BulletinBoard and DialogShell 7-2 7.1.1 BulletinBoard 7-2 7.1.2 Activation, Cancellation, and Help 7-3 7.1.3 DialogShell 7-4 7.1.4 Initial Focus 7-5

7.2 Making a Selection: SelectionBox 7-6

7.3 Choosing a Pathname: FileSelectionBox 7-8

7.4 Command 7-9

7.5 MessageBox 7-10

7.6 Form 7-11

Chapter 8. Text 8-1

8.1 Text and TextField 8-2

8.2 Selection 8-3 8.2.1 Mouse Selection 8-5 8.2.2 Keyboard Selection 8-6

8.3 Text Editing and Callbacks 8-7

8.4 Text Resources and Geometry 8-10

8.5 Convenience Routines 8-12

8.6 ScrolledText 8-13

8.7 Storing Text in a File 8-13

8.8 Sharing Text Sources 8-15

Chapter 9. Scrolling, Panes, and Frames 9-1

9.1 ScrolledWindow 9-2 9.1.1 Automatic and Application-Defined

Scrolling 9-2 9.1.2 Other Resources 9-3

9.2 Automatic Scrolling 9-5 9.2.1 Traversing to Obscured Widgets 9-7 9.2.2 Example of Automatic Scrolling . . . . . . 9-7

9.3 Application-Defined Scrolling 9-11 9.3.1 Example of Application-Defined

Scrolling 9-13

Contents

9.4 MainWindow 9-22

9.5 Frame 9-24

9.6 PanedWindow 9-26

Chapter 10. Managing Geometry 10-1

10.1 Xt and Geometry Management 10-2 10.1.1 Widget Class Procedures 10-2 10.1.2 Geometry Change Requests 10-4 10.1.3 The geometry_manager Procedure 10-5 10.1.4 Intermediate Geometry Requests 10-6 10.1.5 XtSetValues 10-8 10.1.6 The resize Procedure 10-9 10.1.7 Preferred Size and Location 10-10 10.1.8 Exposure and Redisplay 10-11

10.2 Shells and Their Children 10-11

10.3 Manager Widgets and Their Children 10-13

10.4 Managing Geometry Using RowColumn 10-13

10.5 Managing Geometry Using BulletinBoard and

DrawingArea 10-18

10.6 Managing Geometry Using Form 10-20

Chapter 11. Internationalization 11-1

11.1 Issues in Internationalized Applications 11-1 11.1.1 Internationalization and Localization . . . . 11-2 11.1.2 Obtaining Input 11-4 11.1.3 Displaying Output 11-5 11.1.4 Locales and Localization 11-5

11.2 Compound Strings, Fonts, and Text Display 11-6 11.2.1 Compound String Components 11-6 11.2.2 Fonts, Font Lists, and Font Sets 11-11 11.2.3 Compound Strings and Font Lists 11-17 11.2.4 Text and TextField Widgets and Font

Lists 11-20

11.3 Localizing Applications 11-20 11.3.1 Techniques for Localization 11-21 11.3.2 Resources and Localization 11-25 11.3.3 UIL and Localization 11-28 11.3.4 Message Catalogs and Localization 11-31 11.3.5 Images, Pixmaps, and Localization 11-32 11.3.6 Comparing Approaches to Localization . . . . 11-34

11.4 Advanced Topics in Internationalization 11-34 11.4.1 Internationalization and Text Input 11-34

v

OSF/Motif Programmer's Guide

11.4.2 Compound Strings and Compound Text . . . . 11^40

Chapter 12. Color and Pixmaps 12-1

12.1 Default Colors and Pixmaps 12-2 12.1.1 Borders 12-3 12.1.2 Backgrounds 12-3 12.1.3 Foregrounds 12-3 12.1.4 Shadows 12-4 12.1.5 Focus Highlights 12-5 12.1.6 Arming and Selection 12-5

12.2 Application-Defined Color Generation 12-6

12.3 Colormaps 12-8

12.4 Using Pixmaps 12-8

Chapter 13. Input, Focus, and Keyboard Navigation 13-1

13.1 Focus Models 13-3

13.2 Controlling Keyboard Navigation 13-4 13.2.1 Sensitivity 13-6 13.2.2 XmNtraversalOn 13-7 13.2.3 Tab Groups 13-8 13.2.4 Initial Focus 13-12 13.2.5 Traversing to Obscured Widgets 13-13 13.2.6 XmProcessTraversal 13-14 13.2.7 Focus Callbacks 13-19

13.3 Translations and Actions 13-19 13.3.1 Translation Table Format 13-20 13.3.2 Using Translations 13-21 13.3.3 Actions 13-23 13.3.4 Bindings for osfKeysyms 13-24

13.4 Mnemonics and Accelerators 13-26

13.5 Event Handlers 13-28

Chapter 14. Graphics and Text in a DrawingArea 14-1

14.1 DrawingArea: A General-Purpose Widget 14-1

14.2 Event Handling and Callbacks 14-2 14.2.1 Handling Resize Events 14-3 14.2.2 Handling Exposure Events 14-7 14.2.3 Handling Input Events 14-10

14.3 Using a DrawingArea in a ScrolledWindow 14-13

14.4 Using a DrawingArea for Graphics 14-14

14.5 DrawingArea and Advanced Text Editing 14-19 14.5.1 Text Output 14-19

vi

Contents

14.5.2 Text Input 14-20

Chapter 15. Drag and Drop 15-1

15.1 User Overview of Drag and Drop 15-2 15.1.1 Overview of User Interaction 15-2 15.1.2 Overview of Drag-Over Effects 15-3 15.1.3 Overview of Drag-Under Effects 15-5 15.1.4 Overview of Drop Effects 15-5

15.2 Technical Overview of Drag and Drop 15-6 15.2.1 Complexity of Drag and Drop Programs . . . . 15-7 15.2.2 Drag Sources and Drop Sites 15-16 15.2.3 Protocols 15-17 15.2.4 Drag and Drop Widget Classes 15-18 15.2.5 Drag and Drop Functions 15-19 15.2.6 Targets 15-21 15.2.7 Operations 15-22 15.2.8 Overview of Programmer

Responsibilities 15-23

15.3 Drag and Drop Protocols 15-27 15.3.1 Drag Protocols 15-27 15.3.2 Choosing the Protocol and Visual Style . . . . 15-29 15.3.3 Drop Protocol 15-32

15.4 Drop Receiver Responsibilities for Dragging . . . . 15-33 15.4.1 Establishing a Drop Site 15-34 15.4.2 XmNdragProc 15-41

15.5 Drag Initiator Responsibilities for Dragging 15-51 15.5.1 Recognizing a Drag Has Started 15-51 15.5.2 Starting a Drag With XmDragStart 15-52 15.5.3 Overriding Existing Drag Sources 15-54 15.5.4 Drag-Over Visual Effects 15-54 15.5.5 Drag Callbacks 15-64 15.5.6 Getting Data about the Current Drop

Site 15-68 15.5.7 Cancelling the Drag 15-68

15.6 Drop Receiver Responsibilities for Dropping . . . . 15-69 15.6.1 XmNdropProc 15-69 15.6.2 XmDropTransfer 15-72 15.6.3 Cancelling a Drop 15-75 15.6.4 Providing Help 15-75

15.7 Drag Initiator Responsibilities for Dropping 15-82 15.7.1 XmNdropStartCallback 15-83 15.7.2 Dealing with Requests for Transfer 15-83 15.7.3 XmNdropFinishCallback 15-86 15.7.4 XmNdragDropFinishCallback 15-86

vii

OSF/Motif Programmer's Guide

Chapter 16. Interclient Communication 16-1

16.1 Window Managers, ICCCM, and Shells 16-2 16.1.1 Application Startup 16-2 16.1.2 Window Configuration 16-3 16.1.3 Icons 16-7 16.1.4 Window Groups 16-9 16.1.5 Menus and Dialogs 16-9 16.1.6 Input Focus 16-10 16.1.7 Colormaps 16-12 16.1.8 Application Shutdown and Restart 16-13

16.2 MWM Properties and Resources 16-15 16.2.1 Decorations 16-15 16.2.2 Functions 16-15 16.2.3 Input Mode 16-16 16.2.4 Window Menu 16-16 16.2.5 MWM Messages 16-17 16.2.6 MWM Information 16-17

16.3 Atom and Protocol Management 16-17

16.4 Selections 16-19 16.4.1 Selection Types 16-19 16.4.2 Targets 16-20 16.4.3 Text Conversion 16-21 16.4.4 Incremental Transfers 16-23 16.4.5 The Xt Selection Interface 16-23

16.5 The Motif Clipboard 16-25 16.5.1 Copying Data to the Clipboard 16-25 16.5.2 Retrieving Data from the Clipboard 16-27 16.5.3 Utility Routines 16-28

Appendix A. The Widget Meta-Language Facility A-l

A.l Using WML A-2 A.l.l Building WML A-4 A. 1.2 Running WML A-5 A.1.3 Installing UIL A-7 A. 1.4 Building UIL A-7

Appendix B. Drag and Drop Example Program B-l

B.l DNDDemo.h B-3

B.2 DNDDemo.c B-9

B.3 DNDDraw.c B-53

Glossary GL-1

Index Index-1

viii