IRIS Viewkit™ Programmer's Guide

IRIS ViewKit™ Programmer’s Guide Document Number 007-2124-006 CONTRIBUTORS Written by Ken Jones, Douglas B. O’Morain, and Sandra Motroni Illustrated by Martha Levine Edited by Christina Cary Production by Linda Rae Sande Engineering contributions by Doug Young, Kim Rachmeler, Mike Yang, Robert Blean, Richard Hess, and Richard Offer St Peter’s Basilica image courtesy of ENEL SpA and InfoByte SpA. Disk Thrower image courtesy of Xavier Berenguer, Animatica. © 1997-1999, Silicon Graphics, Inc.— All Rights Reserved The contents of this document may not be copied or duplicated in any form, in whole or in part, without the prior written permission of Silicon Graphics, Inc. RESTRICTED RIGHTS LEGEND Use, duplication, or disclosure of the technical data contained in this document by the Government is subject to restrictions as set forth in subdivision (c) (1) (ii) of the Rights in Technical Data and Computer Software clause at DFARS 52.227-7013 and/or in similar or successor clauses in the FAR, or in the DOD or NASA FAR Supplement. Unpublished rights reserved under the Copyright Laws of the United States. Contractor/manufacturer is Silicon Graphics, Inc., 2011 N. Shoreline Blvd., Mountain View, CA 94043-1389. Silicon Graphics, the Silicon Graphics logo, and IRIS are registered trademarks and IRIX Interactive Desktop, IRIS InSight, IRIS ViewKit, and IRIX are trademarks of Silicon Graphics, Inc. PostScript is a registered trademark of Adobe Systems, Inc. X Window System is a trademark of Massachusetts Institute of Technology. Motif and OSF/Motif are trademarks of The Open Group. ToolTalk is a trademark of Sun Microsystems, Inc. IRIS ViewKit™ Programmer’s Guide Document Number 007-2124-006 What’s New New Features IRIS ViewKit 2.1 now supports multiple displays and screens. Because IRIS ViewKit 1.5.3 is still the default development environment, the information about ViewKit 2.1 is in Appendix B, “Changes and Additions in ViewKit 2.1.” Major Documentation Changes The following items were corrected: • The descriptions of overlay apps, overlay menus, and overlay dialogs were changed to clarify the methods of specifying the use of the overlay planes. • A note was added to the description of VkOutline stating that one of the components utilized by this class is not documented and not supported for external use. • The section on buildZoomMenu() in VkGraph was amended to remove the reference to overriding the function. • References to the Indigo Magic Desktop and IRIS IM were updated to IRIX Interactive Desktop and Motif, respectively. iii Contents What’s New iii New Features iii Major Documentation Changes iii Examples xvii Figures xxi Tables xxv Introduction xxvii What This Guide Contains xxvii What You Should Know Before Reading This Guide xxix Conventions Used in This Guide xxxi Typographical Conventions xxxi Class Inheritance Graph Conventions xxxii 1. Overview of ViewKit 1 Major ViewKit Elements 2 Framework Classes 2 Interface Components 2 Convenience Utilities 3 Mixing ViewKit and Standard X and Motif Functions 3 Compiling and Linking ViewKit Programs 5 Required Packages 5 Required Header Files 6 Required Libraries 6 Getting Started 7 The Simplest ViewKit Program 7 Demonstration Programs 10 v Contents 2. Components 11 Definition of a Component 11 VkComponent Class 12 Component Constructors 13 Component Destructors 16 VkComponent Access Functions 17 Displaying and Hiding Components 19 VkComponent Utility Functions 20 Using Xt Callbacks With Components 21 Handling Component Widget Destruction 24 Component Resource Support 26 Setting Resource Values by Class or Individual Component 27 Initializing Data Members Based on Resource Values 28 Setting Default Resource Values for a Component 30 Convenience Function for Retrieving Resource Values 32 ViewKit Callback Support 34 Registering ViewKit Callbacks 35 Removing ViewKit Callbacks 38 Defining and Triggering ViewKit Callbacks 39 Predefined ViewKit Callbacks 40 Deriving Subclasses to Create New Components 41 Subclassing Summary 41 Creating a New Component 43 Using and Subclassing a Component Class 46 VkNameList Class 53 VkNameList Constructor and Destructor 53 VkNameList Member Functions 53 Using VkNameList 56 3. The ViewKit Application Class 59 Overview of the VkApp Class 59 VkApp Constructor 60 Running ViewKit Applications 62 ViewKit Event Handling 62 vi Contents Customizing Event Handling 64 Quitting ViewKit Applications 65 Managing Top-Level Windows 66 Setting Application Cursors 67 Setting and Retrieving the Normal Cursor 67 Setting and Retrieving the Busy Cursor 68 Setting and Retrieving a Temporary Cursor 74 Supporting Busy States 75 Entering and Exiting Busy States Using ViewKit 75 Animating the Busy Cursor 78 Installing Different Busy Dialogs 79 Maintaining Product and Version Information 80 Application Data Access Functions 82 Deriving Classes From VkApp 83 VkApp Protected Functions and Data Members 83 Subclassing VkApp 84 Putting Applications in the Overlay Planes 86 4. ViewKit Windows 89 Overview of ViewKit Window Support 89 ViewKit’s Multi-Window Model 89 ViewKit Window Classes 90 Window Class Constructors 92 Window Class Destructors 93 Creating the Window Interface 93 Creating the Window Interface in the Constructor 93 Creating the Window Interface in the setUpInterface() Function 100 Adding a Window Interface to a Direct Instantiation of a ViewKit Window Class 102 Replacing a Window’s View 103 Manipulating Windows 103 Window Data Access Functions 104 vii Contents Window Manager Interface 105 Window and Icon Titles 105 Window Properties and Shell Resources 107 Menu Bar Support 108 Deriving Window Subclasses 110 Additional Virtual Functions and Data Members 110 Window Creation Summary 113 Window Subclassing 115 5. Creating Menus With ViewKit 123 Overview of ViewKit Menu Support 124 ViewKit Menu Item Classes 126 Common Features of Menu Items 126 Menu Actions 130 Confirmable Menu Actions 131 Menu Toggles 131 Menu Labels 132 Menu Separators 132 ViewKit Menu Base Class 133 Constructing Menus 133 Manipulating Items in Menu 149 Menu Access Functions 155 Using ViewKit Menu Subclasses 156 Menu Bar 156 Submenus 157 Radio Submenus 159 Option Menus 162 Popup Menus 167 Putting Menus in the Overlay Planes 171 viii Contents 6. ViewKit Undo Management and Command Classes 173 Undo Management 173 Overview of ViewKit Undo Management 173 Using ViewKit’s Undo Manager 174 Using ViewKit’s Undo Manager 180 Command Classes 184 Overview of Command Classes 184 Using Command Classes in ViewKit 185 7. Using Dialogs in ViewKit 189 Overview of ViewKit Dialog Management 190 ViewKit Dialog Class Overview 190 ViewKit Dialog Base Class 192 Posting Dialogs 193 Manipulating Dialogs Prior to Posting 200 Unposting Dialogs 201 Setting the Title of the Dialog 201 Setting the Button Labels 203 Dialog Access and Utility Functions 204 Using the ViewKit Dialog Subclasses 206 Information Dialogs 206 Warning Dialogs 208 Error Dialogs 209 Fatal Error Dialogs 209 Busy Dialog 210 Interruptible Busy Dialog 210 Progress Dialog 212 Question Dialog 215 Prompt Dialog 215 File Selection Dialog 217 Color Chooser Dialog 220 Deriving New Dialog Classes Using the Generic Dialog 223 Putting Dialogs in the Overlay Planes 225 ix Contents 8. Preference Dialogs 227 Overview of ViewKit Preference Dialogs 228 ViewKit Preference Dialog Class 228 ViewKit Preference Item Classes 229 Building a ViewKit Preference Dialog 231 ViewKit Preference Item Base Class 235 Preference Item Labels 235 Getting and Setting Preference Item Values 237 Preference Item Access Functions 238 ViewKit Preference Item Classes 239 Text Fields 239 Toggle Buttons 240 Option Menus 244 Labels 247 Separators 249 “Empty” Space Preference Items 249 Groups of Preference Items 249 ViewKit Preference Dialog Class 256 Creating a Preference Dialog 256 Setting the Preference Items for a Preference Dialog 257 Posting and Dismissing Preference Dialogs 257 Responding When the User Clicks a Preference Dialog Button 258 Using Values Set in a Preference Dialog 260 Creating Preference Dialog Subclasses 261 9. Handling Visuals With ViewKit 263 Overview of the VkVisual Class 263 Overview of X Visuals 264 X11 Visual Attributes 264 Xt Visual Handling 265 Visual Inheritance in ViewKit 266 Maintaining Consistency 267 Colormap Coordination 268 Useful Enums 269 x Contents VkVisual Constructors and Destructor 270 Member Functions 271 Setting the Class’s Visual Information 271 Data Access Functions 273 Debugging Functions 276 Static Functions 277 VkVisual Examples 278 10. ViewKit Cut and Paste 279 Overview of ViewKit Cut and Paste 279 Primary and Clipboard Transfer Models 280 VkCutPaste Constructor and Destructor 280 Copying Data 281 Pasting Data 283 Dragging Data 285 Accepting Drops 287 Accepting Drops From the IRIX Interactive Desktop 291 Registering New Data Types 292 Using Data Type Converters 295 File and Data Ownership 298 Miscellaneous Functions 304 11. Using a Help System With ViewKit 307 ViewKit Programmatic Interface to a Help Library 307 Using ViewKit Help 308 Using the SGIHelp Library 309 Using an External Help Library 310 ViewKit Support for Building Help 310 ViewKit Help Menu 310 Implementation of the Help Menu 310 Other Types of Help 313 Context-Sensitive Help Procedures 313 Dialog Help Procedures 313 Application Help Button Procedures 314 xi Contents QuickHelp 314 12. The ViewKit Graph Component 317 Overview of ViewKit Graphs 317 Graph Widget 318 Building a Graph 319 Interactive Viewing Features Provided by VkGraph 322 ViewKit Node Class 327 Basic Node Functionality 328 Creating Node

Load more