IRIX® Interactive Desktop Integration Guide 007-2006-130 CONTRIBUTORS Written by Beth Fryer, Jed Hartman, Ken Jones, and Pete Sullivan Updated by Max Anderson Updated by Julie Boney Illustrated by Beth Fryer and Seth Katz Production by Karen Jacobson Engineering contributions by Bob Blean, Susan Dahlberg, Susan Ellis, John Krystynak, Chandra Pisupati, Jack Repenning, CJ Smith, Dave Story, Steve Strasnick, Rebecca Underwood, Steve Yohanan, and Betsy Zeller. COPYRIGHT © 1999, 2001 Silicon Graphics, Inc. All rights reserved; provided portions may be copyright in third parties, as indicated elsewhere herein. No permission is granted to copy, distribute, or create derivative works from the contents of this electronic documentation in any manner, in whole or in part, without the prior written permission of Sili LIMITED RIGHTS LEGEND The electronic (software) version of this document was developed at private expense; if acquired under an agreement with the USA government or any contractor thereto, it is acquired as "commercial computer software" subject to the provisions of its applicable license agreement, as specified in (a) 48 CFR 12.212 of the FAR; or, if acquired for Department of Defense units, (b) 48 CFR 227-7202 of the DoD FAR Supplement; or sections succeeding thereto. Contractor/manufacturer is Silicon Graphics, Inc., 1600 Amphitheatre Pkwy 2E, Mountain View, CA 94043-1351 TRADEMARKS AND ATTRIBUTIONS Silicon Graphics, IRIS, IRIX, and OpenGL are registered trademarks and SGI, IRIS GL, the SGI logo, IRIS InSight, IRIS ViewKit, the Graphics Library, Open Inventor, and RapidApp are trademarks of Silicon Graphics, Inc. Apple is a registered trademark and Apple Quicktime is a trademark of Apple Computer, Inc. Kodak is a trademark of Eastman Kodak Company. Microsoft is a registered trademark of Microsoft Corporation. Motif and OSF/Motif are trademarks of the Open Software Foundation. PostScript is a registered trademark of Adobe Systems, Inc. Solaris is a registered trademark and Sun and SunOS are trademarks of Sun Microsystems, Inc. UNIX is a registered trademarkof the Open Group in the United States and other countries. Wavefront is a trademark of Alias/Wavefront, a division of Silicon Graphics Limited. X Window System is a trademark of the Open Group. Cover Design By Sarah Bolles, Sarah Bolles Design, and Dany Galgani, SGI Technical Publications. Contents Examples . xv Figures . xvii Tables . xix New Features in This Guide. xxi Record of Revision . xxiii About This Guide. xxv What This Guide Contains . xxv How to Use This Guide . xxv What You Should Know Before Reading This Guide . xxv Suggested Reading . xxvi Font Conventions in This Guide . xxvii Integrating an Application Into the IRIX Interactive Desktop Environment: An Introduction . xxix About the IRIX Interactive Desktop Environment . xxix Implementation Strategies and Toolkits . xxxii Implementation Checklist . xxxii Using ViewKit and RapidApp . xxxiv Integrating an Application . xxxvii PART I Getting the Right Look and Feel 1. Getting the Right Look and Feel: An Overview . 3 About the IRIX Interactive Desktop Look and Feel . 3 Getting the Right Look and Feel: The Basic Steps . .4 007-2006-130 iii Contents 2. Getting the IRIX Interactive Desktop Look . 5 3. Using Schemes . 7 Schemes Overview . 7 Why You Should Use Schemes . 8 Basic Scheme Concepts . 8 Using Schemes in Your Application . 9 Turning on Schemes for Your Application . 9 Special Considerations for Programming with Schemes . 10 Assigning Non-Default Colors and Fonts to Widgets . 11 Directly Accessing Colors and Fonts . 13 Pre-Defined Scheme Resources and Symbolic Values . 15 Extending a Scheme to Support New Colors . .18 Scheme File Organization. 19 How to Extend a Scheme . 19 Testing Your Application with Schemes. 21 Creating New Schemes . 21 Hard-Coding a Scheme for an Application . 22 4. Using the SGI Enhanced Widgets . 23 Using the SGI Enhanced Widgets . 23 Using the Widget Demos . 24 Location of Widget Demos . 24 Instructions for Building the Widget Demos . 24 The Enhanced Widgets . 25 The File Selection Box Widget . 25 The Scale (Percent Done Indicator) Widget. 27 The Text and TextField Widgets . 28 The Mixed-Model Programming Widgets . .29 iv 007-2006-130 Contents The SGI Enhanced Widgets . 30 The Color Chooser Widget . 30 The Dial Widget . 36 The Thumbwheel Widget . 38 The Drop Pocket Widget . 41 The Finder Widget . 42 The Graph Widget . 46 The Springbox Widget . 47 The Grid Widget . 48 HTML Viewer Component . 52 Overview of the HTML Viewer Components . 54 Viewer Components . 54 Supported Tags and Attributes . 55 5. Window, Session, and Desk Management . 59 Window, Session, and Desk Management Overview . 59 Window Management . 59 Session Management . 60 Desk Management . 64 Further Reading on Window and Session Management . 65 Implementing an Application Model . 65 Implementing the “Single Document, One Primary” Model . 66 Implementing the “Single Document, Multiple Primaries” Model . 66 Implementing the “Multiple Document, Visible Main” Model . 66 Implementing the “Multiple Document, No Visible Main” Model . 67 Interacting With the Window and Session Manager . 68 Creating Windows and Setting Decorations . 68 Handling Window Manager Protocols . 75 Setting the Window Title. 79 Controlling Window Placement and Size . 79 6. Customizing Your Application’s Minimized Windows. 83 Some Different Sources for Minimized Window Images . 84 007-2006-130 v Contents Creating a Minimized Window Image: The Basic Steps . 85 Using mediarecorder to Get an RGB Format Image . 86 Resizing the RGB Image Using imgworks . 88 Setting the Minimized Window Label . 89 Changing the Minimized Window Image . .89 7. Interapplication Data Exchange . 91 Data Exchange Overview . 91 Primary Transfer Model Overview . 92 Clipboard Transfer Model Overview . .93 Interaction Between the Primary and Clipboard Transfer Models . 94 Implementing the Primary Transfer Model . 95 Data Selection . 95 Requests for the Primary Selection . 96 Loss of the Primary Selection. 97 Inserting the Primary Selection . 97 Implementing the Clipboard Transfer Model . .98 Cut Actions. 98 Copy Actions . 100 Requests for the Clipboard Selection . 100 Paste Actions . 100 Loss of the Clipboard Selection . 101 Supported Target Formats. 101 Data Conversion Service . 105 The Converter Registry . 106 The GoldenGate API . 106 8. Monitoring Changes to Files and Directories . 107 FAM Overview . 107 Theory of Operation . 108 FAM Libraries and Include Files. 108 vi 007-2006-130 Contents The FAM Interface. .109 Opening and Closing a FAM Connection . .109 Monitoring a File or Directory . .110 Suspending, Resuming, and Canceling Monitoring . .111 Detecting Changes to Files and Directories . .112 FAM Examples . .116 Using FAM . .118 Waiting for File Changes. .118 Polling for File Changes . .122 9. Providing Online Help With SGIHelp . .125 Overview of SGIHelp . .126 The Help Viewer . .126 The SGIHelp Library and Include File . .128 Help Document Files . .129 Application Helpmap Files . .129 The SGIHelp Interface. .129 Initializing the Help Session . .130 Displaying a Help Topic . .131 Displaying the Help Index . .132 Implementing Help in an Application . .133 Constructing a Help Menu . .134 Implementing a Help Button . .135 Providing Context-Sensitive Help . .136 Application Helpmap Files . .138 Helpmap File Conventions . .139 Helpmap File Format. .139 Widget Hierarchies in the Helpmap File . .142 007-2006-130 vii Contents Writing the Online Help . 145 Overview of Help Document Files . 145 Viewing the Sample Help Document Files . 146 Creating a Help Document File . 146 Preparing to Build the Online Help . 147 Building the Online Help . 149 Finding and Correcting Build Errors . ..