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 Preface xxxiii Please Read This Section! xxxiii How to Use This Manual xxxiv Assumptions xxxvi Font Conventions Used in This Manual xxxvi Related Documents xxxvii Requests for Comments xxxviii Obtaining the Example Programs xxxviii FTP xxxviii FTPMAIL xxxix BITFTP xl UUCP xl Acknowledgments xli Acknowledgments for XView Version 3 Update xlii Chapter 1 XView and the X Window System 3 1.1 The X Window System 3 1.1.1 The Server and Client 5 1.2 The Software Hierarchy 7 1.3 Extensions to X 8 1.4 The Window Manager 9 1.5 Handling Events 9 1.6 Development of the XView Toolkit 11 1.7 Versions of the XView Toolkit 12 1.8 OPEN LOOK Graphical User Interface 12 Chapter 2 The XView Programmer's Model 17 2.1 Object-oriented Programming 17 2.1.1 Object Class Hierarchy 18 2.1.2 Object Handles 19 2.2 Attribute-based Functions 21 2.2.1 Creating and Manipulating Objects 21 2.2.2 Changing Object Attributes 22 2.2.3 Types of Attributes 22 2.3 Internal Attribute-Value Lists 23 2.4 Types of Objects 23 2.4.1 Generic Objects 24 2.4.2 Window Objects 25 2.4.3 Frames and Subframes 26 2.4.4 Subwindows 29 2.4.4.1 Canvas subwindows 30 2.4.4.2 Text subwindows 30 2.4.4.3 Panels 30 2.4.4.4 Menus 31 2.4.4.5 Scrollbars 33 2.4.4.6 Icons 34 2.4.5 Nonvisual Objects 34 2.5 The Notifier Model 35 2.5.1 Callback Style of Programming 35 2.5.2 Why a Notification-based System? 36 2.5.3 Relationship Among the Notifier, Objects, and the Application 37 2.5.4 Calling the Notifier Directly 37 Chapter 3 Creating XView Applications 41 3.1 Interface Overview 41 3.1.1 Compiling XView Programs 41 3.1.2 XView Libraries 42 3.1.3 Header Files 42 3.1.4 Naming Conventions 43 3.1.4.1 Reserved names 43 3.1.5 Example of XView-style Programming 43 3.2 Initializing XView 45 3.2.1 Using xv_init() 46 3.3 Creating and Modifying Objects 47 3.3.1 Using xv_create() 47 3.3.2 Using xv_find() 49 3.3.3 Using xv_destroy() 50 3.3.4 Using xv_set() and xv_get() 51 3.3.5 Precedence of Resource Options 53 3.4 xv_main_loop() and the Notifier 54 Chapter 4 Frames 59 4.1 Types of Frames 61 4.1.1 The Role of the Window Manager 61 4.2 Base Frames 62 4.2.1 XView Initialization and Base Frames 62 4.2.2 Headers and Footers 63 4.2.3 Closed Base Frames 66 4.2.4 Quit Confirmation 67 4.3 Command Frames 68 4.3.1 Manually Displaying Frames 69 4.3.2 The Pushpin 69 4.3.3 The FRAME_DONE_PROC Procedure 71 4.3.4 Showing Resize Corners 73 4.3.5 Minimum and Maximum Frame Sizes 73 4.4 Miscellaneous Attributes 73 4.5 Busy Frames 74 4.6 Frame Sizes 74 4.7 Frame Colors 75 4.8 Child Windows 76 4.9 Window Loop 77 4.10 Removing Decorations 78 4.11 Setting Properties and Saving Command-line Options 78 4.12 Destroying Frames 79 4.13 Frame Resize and Repaint Events 81 4.14 Frame Package Summary 81 Chapter 5 Canvases and Openwin 85 5.1 Canvas Model 86 5.2 Creating a Canvas 88 5.2.1 Drawing in a Canvas 89 5.2.1.1 Draw programs 89 5.2.1.2 Paint programs 90 5.2.1.3 Text-based programs 90 5.2.1.4 Visualization programs 90 5.2.1.5 Rendering graphics 91 5.3 The Repaint Procedure 91 5.4 Controlling Canvas Sizes 98 5.4.1 Automatic Canvas Sizing 98 5.4.2 Explicit Canvas Sizing 99 5.4.3 Tracking Changes in the Canvas Size 100 5.5 Scrolling Canvases 101 5.6 Splitting Canvas Views 102 5.6.1 Splitting Views Using Scrollbars 102 5.6.2 Splitting Views Using xv_set() 103 5.6.3 Getting View Windows 103 5.6.3.1 Getting the newest view 103 5.6.3.2 Getting arbitrary views 104 5.7 Handling Input in the Canvas Package 105 5.7.1 Default Events 106 5.7.2 Notification of Events 106 5.8 Canvas and Openwin Package Summaries 110 Chapter 6 Handling Input 115 6.1 Introduction to Events in XView 116 6.2 Classes of Events 116 6.2.0.1 Event IDs 117 6.2.0.2 Semantic events 117 6.3 Registering Events 118 6.3.1 Specifying X Event Masks 118 6.3.2 Specifying XView Events 119 6.3.2.1 Mouse events 120 6.3.2.2 Keyboard events 121 6.3.2.3 Resize and repaint events 122 6.3.2.4 Client messages 123 6.3.2.5 Miscellaneous events 123 6.4 The Event Handler 124 6.5 The Event Structure 124 6.6 Determining the Event 125 6.6.0.1 Event states 126 6.6.0.2 Modifier keys 126 6.6.1 Keyboard Events 126 6.6.1.1 Mouse events 128 6.6.1.2 Keyboard focus 129 6.6.1.3 Selection events 130 6.7 Interpreting Client Messages 130 6.7.1 Sending and Reading Client Messages 130 6.8 Reading Input Directly 131 6.9 Sample Program 133 6.10 Extensions for Events 138 6.11 Selecting Events on Other Clients 139 6.12 Soft Function Keys and Virtual Keyboards 140 6.12.1 Soft Function Keys 140 6.12.2 Virtual Keyboards 142 6.12.2.1 Multiple language support 142 6.13 The Mouseless Model 142 6.13.1 Keyboard Command Mapping 143 6.13.2 Mouseless Model Resources 145 6.13.3 Using the Mouseless Model 145 6.13.3.1 The role of the window manager 146 6.13.3.2 Application responsibilities 146 6.13.4 The Location Cursor 146 6.13.5 Events 147 6.14 Using Accelerators 147 Chapter 7 Panels 153 7.1 Creating a Panel 155 7.1.0.1 Fonts and panels 156 7.1.1 Scrollable Panels 156 7.2 Creating Panel Items 157 7.3 Layout of Panels and Panel Items 159 7.3.1 Panel Layout 159 7.3.2 Panel Item Layout 160 7.4 Explicit Panel Item Positioning 161 7.4.1 Relative Panel Item Positioning 161 7.4.2 Absolute Panel Item Positioning 162 7.4.2.1 General positioning of items 163 7.4.3 Layout of Panel Items with Values 163 7.5 Sizing Panels 164 7.6 Panel Item Values 164 7.7 Iterating Over a Panel's Items 165 7.8 Panel Item Classes 165 7.9 Button Items 166 7.9.1 Button Selection 167 7.9.1.1 Making a button inactive 167 7.9.2 Menu Buttons 167 7.9.2.1 Destroying menu buttons 169 7.9.3 Panel Button Width 170 7.9.4 Abbreviated Menu Buttons 170 7.10 Choice Items 171 7.10.1 Display and Layout of Item Choices 171 7.10.2 Exclusive and Nonexclusive Choices 172 7.10.3 Abbreviated Choices 173 7.10.4 Checkbox Choices 174 7.10.5 Choice Selection and Notification 175 7.10.6 Foreground Color in Choice Items 175 7.10.7 Parallel Lists 176 7.11 Scrolling Lists 177 7.11.1 Displaying List Items 178 7.11.2 Adding and Deleting List Entries 181 7.11.3 List Selection 182 7.11.4 List Notification 183 7.11.4.1 List item client data 184 7.11.5 The Scrolling List Menu 184 7.12 Message Items 184 7.13 Slider Items 186 7.13.1 Slider Selection 187 7.13.2 Slider Notification 187 7.13.3 Slider Value 187 7.14 Gauges 188 7.15 Text Items 188 7.15.1 The Current Keyboard Focus 190 7.15.2 Text Selection 191 7.15.3 Text Notification 191 7.15.4 Writing Your Own Text Notify Procedure 192 7.15.5 Text Value 193 7.16 Numeric Text Items 193 7.17 Multiline Text Items 193 7.18 Drop Target Items 194 7.18.1 Programming a Panel Drop Target Item 196 7.18.1.1 Create the drop target item 196 7.18.1.2 Specify the glyphs 196 7.18.1.3 Create the drag and drop object 197 7.18.1.4 Define the drop target item's requestor 197 7.18.1.5 Controlling the glyphs 198 7.18.1.6 Dropping on the drop target 198 7.18.1.7 Dragging from the drop target item 198 7.18.2 Drop Target Notification 198 7.19 Advanced Panel Usage 199 7.19.1 Attaching Data to Panel Items 199 7.19.2 Using PANEL_REPAINT_PROC 202 7.19.3 Painting Panel Items 205 7.19.4 Panel Event Handling 205 7.19.5 Using an Interpose Function 207 7.19.6 Using PANEL_BACKGROUND_PROC 207 7.19.7 Using PANEL_EVENT_PROC 207 7.19.8 Event Handling Example 208 7.20 Panel Package Summary 209 Chapter 8 Text Subwindows 215 8.1 Creating Text Subwindows 216 8.2 Setting Text Subwindow Attributes 216 8.3 Text Subwindow Contents 216 8.4 Editing a Text Subwindow 217 8.4.1 Loading a File 217 8.4.2 Checking the Status of the Text Subwindow 218 8.4.3 Writing to a Text Subwindow 219 8.4.3.1 Setting the insertion point 219 8.4.4 Reading from a Text Subwindow 219 8.4.5 Deleting Text 220 8.4.6 Emulating an Editing Character 221 8.4.7 Replacing Characters 221 8.4.8 The Editing Log 222 8.4.9 Which File is Being Edited? 222 8.4.9.1 Interactions with the file system 223 8.5 Saving Edits in a Subwindow 223 8.5.1 Storing Edits 223 8.5.2 Discarding Edits 224 8.6 Setting the Contents of a Text Subwindow 224 8.6.1 TEXTSW_FILE_CONTENTS 224 8.6.2 TEXTSW_CONTENTS 225 8.6.3