Decwindows Motif Guide to Application Programming
Total Page:16
File Type:pdf, Size:1020Kb
DECwindows Motif Guide to Application Programming Order Number: AA–PGZEB–TE January 1994 This document describes the programming interface for widgets provided by Digital in the DECwindows Motif Version 1.2 Toolkit. This document also includes tutorial programming information for the DECwindows Motif Version 1.2 Toolkit. Revision/Update Information: This is a revised manual. Operating System: OpenVMS AXP Version 1.5 VMS Version 5.5–2 Software Version: DECwindows Motif Version 1.2 for OpenVMS AXP DECwindows Motif Version 1.2 for OpenVMS VAX Digital Equipment Corporation Maynard, Massachusetts January 1994 The information in this document is subject to change without notice and should not be construed as a commitment by Digital Equipment Corporation. Digital Equipment Corporation assumes no responsibility for any errors that may appear in this document. The software described in this document is furnished under a license and may be used or copied only in accordance with the terms of such license. No responsibility is assumed for the use or reliability of software on equipment that is not supplied by Digital Equipment Corporation or its affiliated companies. Restricted Rights: Use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013. © Digital Equipment Corporation 1994. All Rights Reserved. The postpaid Reader’s Comments forms at the end of this document request your critical evaluation to assist in preparing future documentation. The following are trademarks of Digital Equipment Corporation: Alpha AXP, AXP, Bookreader, DEC, DECpaint, DECterm, DECwindows, DECwrite, Digital, eXcursion, OpenVMS, VAX, VAX DOCUMENT, VMS, XUI, and the DIGITAL logo. The following are third-party trademarks: Adobe, Display Postscript, and PostScript are registered trademarks of Adobe Systems Incorporated. Helvetica and Times are registered trademarks of Allied Corporation. Motif and OSF/Motif are registered trademarks of the Open Software Foundation, Inc. ITC Avant Garde Gothic is a registered trademark of International Typeface Corporation. UNIX is a registered trademark licensed exclusively by the X/Open Company Limited. Windows is a trademark, and Windows NT and NT are registered trademarks of Microsoft Corporation. X Window System is a trademark of the Massachusetts Institute of Technology. All other trademarks and registered trademarks are the property of their respective holders. ZK5639 This document is available on CD-ROM. This document was prepared using DECdocument, Version 3.3-1b. Contents Preface ............................................................ xi 1 Introduction 1.1 Overview of DECwindows Motif Toolkit ........................... 1–1 1.1.1 Toolkit Building Blocks: Widgets and Gadgets ................... 1–2 1.1.2 Widget Types ............................................ 1–3 1.1.3 Widgets in the OSF/Motif Toolkit ............................. 1–3 1.1.4 Widgets Provided by Digital . ................................ 1–3 1.1.5 Toolkit Widget and Gadget Routines . ....................... 1–3 1.1.6 Application Development Tools .............................. 1–5 1.1.7 Internationalization Using UIL and MRM ...................... 1–6 1.1.8 Toolkit Intrinsic Routines . ................................ 1–6 1.2 Toolkit Routines Contrasted with UIL ............................ 1–6 1.3 Toolkit Routines Contrasted with Xlib Routines .................... 1–7 1.4 Toolkit Programming Considerations ............................. 1–7 1.4.1 Application Widget Hierarchy ............................... 1–7 1.4.2 OpenVMS DECburger Application Hierarchy ................... 1–8 1.4.3 Form Versus Function ..................................... 1–9 1.4.4 Associating Functions with Callbacks . ....................... 1–11 1.4.5 Using Widget Attributes in Applications ....................... 1–12 1.4.5.1 Size and Position Attributes ............................. 1–12 1.4.5.2 Appearance Attributes . ................................ 1–12 1.4.5.3 Callback Attributes .................................... 1–13 1.4.5.4 Assigning Values to Widget Attributes ...................... 1–13 1.5 Using the OpenVMS DECburger Demo Application . ............... 1–13 1.6 Non-C Language Examples for OpenVMS . ....................... 1–14 2 DECwindows Application Interface Design 2.1 Designing a DECwindows Application—Where to Begin .............. 2–1 2.1.1 Application Design Topics . ................................ 2–1 2.1.2 Use of Callbacks . ........................................ 2–2 2.1.3 Making Assumptions About Resources . ....................... 2–2 2.1.4 Selecting Appropriate Widgets ............................... 2–2 2.1.5 Widgets in the OpenVMS DECburger Application . ............... 2–3 2.1.6 Toolkit Intrinsic Routines Used in OpenVMS DECburger . ....... 2–9 iii 3 Helpful Hints for Creating a DECwindows Application 3.1 Using Widgets Supplied by Digital from UIL ....................... 3–1 3.2 XmForm Widget Hints ........................................ 3–1 3.2.1 Creating a Form Dialog Box with Children . ................... 3–1 3.2.2 Aligning Children of Different Sizes .......................... 3–6 3.2.3 Centering Widgets at Positions Within an XmForm Widget ......... 3–8 3.2.4 Spacing XmPushButtons in XmForm Widgets ................... 3–13 3.3 Using Default Files .......................................... 3–13 3.4 Using Default Files to Save Customized Settings ................... 3–14 3.5 Using Multiple Displays . .................................... 3–21 3.5.1 Using Multiple Independent Displays ......................... 3–22 3.5.2 Using Multiple Interconnected Displays ....................... 3–27 3.6 Creating a Cursor ........................................... 3–30 3.7 Using the XtAppAddInput Routine . ............................ 3–31 3.8 Freeing Resources Allocated Through UIL ......................... 3–42 4 Using the Help Widget 4.1 Overview of the Help Widget ................................... 4–1 4.1.1 Invoking the Help Widget .................................. 4–2 4.1.2 Help Widget Terminology ................................... 4–3 4.2 OpenVMS Help Library Information . ............................ 4–3 4.2.1 OpenVMS Help Library Modules . ............................ 4–4 4.2.1.1 Accessing OpenVMS Help Library Modules .................. 4–4 4.2.1.2 Specifying OpenVMS Help Library Key Names ............... 4–5 4.2.2 OpenVMS Help Library Enhancements ........................ 4–5 4.3 Help Widget Components . .................................... 4–8 4.4 Modifying Help Widget Appearance . ............................ 4–9 4.4.1 Modifying Help Widget Labels and Mnemonics .................. 4–10 4.4.2 Help Widget Messages . .................................... 4–11 4.5 Help Widget Callbacks ........................................ 4–11 4.6 Specifying Help Widget Topics .................................. 4–11 4.7 Using the Help Widget ........................................ 4–12 4.7.1 Context-Sensitive Help . .................................... 4–13 4.7.1.1 Creating the On Context Push Button in UIL ................ 4–14 4.7.1.2 Entering Context-Sensitive Help Mode . ................... 4–15 4.7.2 Specifying a Help Callback ................................. 4–17 4.8 Creating the Help Widget with UIL . ............................ 4–18 4.9 Help Widget Implementation—C Language Module ................. 4–24 4.10 Using the Toolkit Help Widget Creation Routine . ................... 4–32 5 Using the DECwindows Motif Help System 5.1 Overview of the Help System ................................... 5–1 5.2 Invoking the Help System . .................................... 5–3 5.3 Help File Information ........................................ 5–4 5.4 Help File Information—VAX DOCUMENT Example ................. 5–4 5.5 Context-Sensitive Help Callbacks . ............................ 5–8 5.5.1 Creating the On Context Push Button in UIL ................... 5–9 5.5.2 Entering Context-Sensitive Help Mode ........................ 5–10 5.5.3 Specifying a Help Callback ................................. 5–11 5.6 Implementing the Help System ................................. 5–13 5.7 Help System Implementation—C Language Module ................. 5–20 iv 6 Using the Color Mixing Widget 6.1 Overview of the Color Mixing Widget ............................. 6–1 6.2 Color Mixing Widget Resources . ................................ 6–2 6.3 Color Models ............................................... 6–2 6.3.1 Color Picker Model ........................................ 6–2 6.3.1.1 Color Picker Model Spectrum ............................. 6–3 6.3.1.2 Selecting a Color Using the Color Picker Model ............... 6–4 6.3.1.3 Using the Interpolator . ................................ 6–4 6.3.2 HLS Color Model . ........................................ 6–5 6.3.3 RGB Color Model . ........................................ 6–5 6.3.4 Browser Color Model ...................................... 6–7 6.3.5 Greyscale Mixer . ........................................ 6–9 6.4 Color Mixing Widget Components ............................... 6–10 6.4.1 Scratch Pad ............................................. 6–11 6.4.2 Color Display Subwidget . ................................ 6–12 6.4.3 Color Model Option Menu Subwidget . ....................... 6–12 6.4.4 Color Mixer Subwidget ..................................... 6–12 6.4.5 Push-Button Subwidgets . ...............................