CONTENTS

  Title Page

  Copyright Page

  Preface

  1      Introduction

  1.1     Overview of DECwindows Motif Toolkit
    1.1.1      Toolkit Building Blocks:  Widgets and Gadgets
    1.1.2      Widget Types
    1.1.3      Widgets in the OSF/Motif Toolkit
    1.1.4      Widgets Provided by Digital
    1.1.5      Toolkit Widget and Gadget Routines
    1.1.6      Application Development Tools
    1.1.7      Internationalization Using UIL and MRM
    1.1.8      Toolkit Intrinsic Routines

  1.2     Toolkit Routines Contrasted with UIL

  1.3     Toolkit Routines Contrasted with Xlib Routines

  1.4     Toolkit Programming Considerations
    1.4.1      The Application Widget Hierarchy
    1.4.2      The DECburger Application Hierarchy
    1.4.3      Form Versus Function
    1.4.4      Associating Functions with Callbacks
    1.4.5      Using Widget Attributes in Applications
      1.4.5.1      Size and Position Attributes
      1.4.5.2      Appearance Attributes
      1.4.5.3      Callback Attributes
      1.4.5.4      Assigning Values to Widget Attributes

  1.5     Using the DECburger Demo Application

  1.6     Non-C Language Examples

  2      DECwindows Application Interface Design

  2.1     Designing a DECwindows Application-Where to Begin
    2.1.1      Application Design Topics
    2.1.2      Use of Callbacks
    2.1.3      Making Assumptions About Resources
    2.1.4      Selecting Appropriate Widgets
    2.1.5      Widgets in the DECburger Application
    2.1.6      Toolkit Intrinsic Routines Used in DECburger

  3      Helpful Hints for Creating a DECwindows Application

  3.1     Using Widgets Supplied by Digital from UIL

  3.2     XmForm Widget Hints
    3.2.1      Creating a Form Dialog Box with Children
    3.2.2      Aligning Children of Different Sizes
    3.2.3      Centering Widgets at Positions Within an XmForm Widget
    3.2.4      Spacing XmPushButtons in XmForm Widgets

  3.3     Using Default Files

  3.4     Using Default Files to Save Customized Settings

  3.5     Using Multiple Displays
    3.5.1      Using Multiple Independent Displays
    3.5.2      Using Multiple Interconnected Displays

  3.6     Creating a Cursor

  3.7     Using the XtAppAddInput Routine

  3.8     Freeing Resources Allocated Through UIL

  4      Using the Help Widget

  4.1     Overview of the Help Widget
    4.1.1      Invoking the Help Widget
    4.1.2      Help Widget Terminology

  4.2     Help Library Information
    4.2.1      Help Library Modules
      4.2.1.1      Accessing Help Library Modules
      4.2.1.2      Specifying Help Library Key Names
    4.2.2      VMS Help Library Enhancements

  4.3     Help Widget Components

  4.4     Modifying Help Widget Appearance
    4.4.1      Modifying Help Widget Labels and Mnemonics
    4.4.2      Help Widget Messages

  4.5     Help Widget Callbacks

  4.6     Specifying Help Widget Topics

  4.7     Using the Help Widget
    4.7.1      Context-Sensitive Help
      4.7.1.1      Creating the On Context Push Button in UIL
      4.7.1.2      Entering Context-Sensitive Help Mode
    4.7.2      Specifying a Help Callback

  4.8     Creating the Help Widget with UIL

  4.9     Help Widget Implementation-C Language Module

  4.10    Using the Toolkit Help Widget Creation Routine

  5      Using the DECwindows Motif Help System

  5.1     Overview of the Help System

  5.2     Invoking The Help System

  5.3     Help File Information

  5.4     Help File Information-VAX DOCUMENT Example

  5.5     Context-Sensitive Help Callbacks
    5.5.1      Creating the On Context Push Button in UIL
    5.5.2      Entering Context-Sensitive Help Mode
    5.5.3      Specifying a Help Callback

  5.6     Implementing the Help System

  5.7     Help System Implementation-C Language Module

  6      Using the Color Mixing Widget

  6.1     Overview of the Color Mixing Widget

  6.2     Color Mixing Widget Resources

  6.3     Color Models
    6.3.1      Color Picker Model
      6.3.1.1      Color Picker Model Spectrum
      6.3.1.2      Selecting a Color Using the Color Picker Model
      6.3.1.3      Using the Interpolator
    6.3.2      HLS Color Model
    6.3.3      RGB Color Model
    6.3.4      Browser Color Model
    6.3.5      Greyscale Mixer

  6.4     Color Mixing Widget Components
    6.4.1      Scratch Pad
    6.4.2      Color Display Subwidget
    6.4.3      Color Model Option Menu Subwidget
    6.4.4      Color Mixer Subwidget
    6.4.5      Push Button Subwidgets
    6.4.6      Label Subwidgets
    6.4.7      Work Area Subwidget
    6.4.8      Setting and Retrieving New Color Values
    6.4.9      Customizing the Color Mixing Widget
      6.4.9.1      Specifying Size
      6.4.9.2      Specifying Margins
      6.4.9.3      Labeling the Color Mixing Widget
      6.4.9.4      Defining the Background Color of the Color Display Subwidget
      6.4.9.5      Adding a Work Area to the Color Mixing Widget
      6.4.9.6      Customizing the Color Picker Color Model

  6.5     Supporting Other Color Models
    6.5.1      Replacing the Color Display Subwidget
    6.5.2      Replacing the Color Mixer Subwidget

  6.6     Associating Callbacks with a Color Mixing Widget

  6.7     Creating a Color Mixing Widget
    6.7.1      Creating a Color Mixing Widget-UIL Example
    6.7.2      Color Mixing Widget-OK Callback
    6.7.3      Color Mixing Widget-Apply Callback
    6.7.4      Color Mixing Widget-Cancel Callback
    6.7.5      Creating a Color Mixing Widget-Toolkit Example

  7      Using the Print Widget

  7.1     Overview of the Print Widget

  7.2     Print Widget Walk-Through

  7.3     Print Widget Components

  7.4     Print Widget Callbacks

  7.5     Print Widget File-Type Guesser

  7.6     Print Widget Resources
    7.6.1      Suppressing Print Widget Features
    7.6.2      Adding Print Widget Functions
      7.6.2.1      Adding Print Formats
      7.6.2.2      Adding to Option Menus

  7.7     Creating the Print Widget with UIL

  7.8     Creating the Print Widget with a Toolkit Routine

  7.9     Submitting Print Jobs

  8      Using the Compound String Text Widget

  8.1     Overview of the CSText Widget

  8.2     Modifying CSText Widget Resources
    8.2.1      Manipulating the Text Contents of the CSText Widget
      8.2.1.1      Placing a Compound String in a CSText Widget
      8.2.1.2      Retrieving Compound Strings from a CSText Widget
      8.2.1.3      Disabling Text Editing
      8.2.1.4      Limiting the Length of the Text
    8.2.2      Customizing the Appearance of the CSText Widget
      8.2.2.1      Specifying Size
      8.2.2.2      Specifying Margins
      8.2.2.3      Controlling Resizing Behavior
      8.2.2.4      Scroll Bar Positioning
      8.2.2.5      Controlling Text Cursor Appearance
      8.2.2.6      Positioning the Insertion Point
      8.2.2.7      Identifying the Current Writing and Editing Directions
    8.2.3      Multiline Editing in a CSText Widget
    8.2.4      Handling Text Selections
      8.2.4.1      Selecting Text
      8.2.4.2      Retrieving Selected Text
      8.2.4.3      Copy Selected Text to the Clipboard
      8.2.4.4      Pasting Selected Text from the Clipboard
      8.2.4.5      Deleting Selected Text from the Clipboard
      8.2.4.6      Getting Position Information About the Selection
      8.2.4.7      Determining Primary Selection Ownership
      8.2.4.8      Canceling the Selection of Text
    8.2.5      Associating Callbacks with CSText Widgets

  8.3     Conversion Routines

  8.4     Creating CSText Widgets
    8.4.1      Using UIL to Create a CSText Widget
    8.4.2      Using the Toolkit CSText Widget Creation Routine

  9      Using the SVN Widget

  9.1     Overview of the SVN Widget
    9.1.1      Components of an Entry
    9.1.2      Selection Mode
    9.1.3      Tree Mode Navigation Window
    9.1.4      Location Cursor
    9.1.5      Highlighting Entries
    9.1.6      Editable Text
    9.1.7      Sensitive Entries
    9.1.8      Disabling/Enabling the SVN Widget
    9.1.9      Invalidating the SVN widget
    9.1.10     Outer Scroll Bar Arrows
    9.1.11     Scroll Bar Index Window

  9.2     SVN Widget Programming Considerations
    9.2.1      Creating the Data Hierarchy
      9.2.1.1      Attaching to Data-The DXmSvnNattachToSourceCallback Callback
      9.2.1.2      Understanding the entry_number Field
      9.2.1.3      Getting Information About an Entry
      9.2.1.4      Associating Hierarchy Data with SVN
    9.2.2      Disabling/Enabling the SVN Widget
    9.2.3      Setting the Location Cursor
    9.2.4      Invalidating an Entry
    9.2.5      Setting a Tree Style
    9.2.6      Setting the Display Mode
    9.2.7      Setting an Entry Coordinate Position
    9.2.8      Setting an Entry Position
    9.2.9      Selecting Entries
    9.2.10     Manipulating Entries
    9.2.11     Manipulating Column Mode Entries
    9.2.12     Flushing an Entry
    9.2.13     Manipulating Components
    9.2.14     Highlighting an Entry
    9.2.15     Getting the Displayed Entries
    9.2.16     Dragging an Entry
    9.2.17     Ghosting
    9.2.18     Setting Entry Font Lists

  9.3     Setting Tree Mode Attributes
    9.3.1      Manipulating Tree Position
    9.3.2      Setting the Tree Mode Arc Width
    9.3.3      Centering Tree Mode Components
    9.3.4      Tree Mode Outlines
    9.3.5      Tree Mode Entry Shadows
    9.3.6      Tree Mode Perpendicular Lines

  9.4     Associating Callbacks with an SVN Widget

  9.5     SVN Help Callback
    9.5.1      User-Generated Callbacks

  9.6     Creating an SVN Widget

  9.7     The SVN Demo Application

  10     Interoperability Coding Recommendations

  10.1    Why Interoperability Is Important

  10.2    Font Fallback
    10.2.1     Font Naming Convention
    10.2.2     Font Fallback Implementation
    10.2.3     Using Common Fonts
    10.2.4     Implementing Font Fallback Through UIL
    10.2.5     Implementing Font Fallback Through Toolkit Routines

  10.3    Screen Independence
    10.3.1     Screen DPI Assumptions
    10.3.2     MultiHead Server Support
      10.3.2.1     Using XtAppInitialize to Specify a Screen
      10.3.2.2     Using XtOpenDisplay to Specify a Screen
    10.3.3     Window Size for Small Screens
    10.3.4     Using Scrolled Windows for Small Screens
    10.3.5     Using the DXmNfitToScreenPolicy Resource
    10.3.6     Window Placement for Small Screens

  10.4    Color Support
    10.4.1     Matching Color Requirements to Display Types
      10.4.1.1     Writable Color Cells
      10.4.1.2     Display Depth
      10.4.1.3     Handling Insufficient Color Resources

  10.5    Image Format
    10.5.1     Image Format Implementaion
    10.5.2     Determining Image Format

  A   Using the DECTERM PORT Routine

  EXAMPLES

  1-1        Passing an Argument List

  1-2        Form Versus Function

  1-3        Form Versus Function-Generic Pulldown Menu

  3-1        XmForm Dialog with Children-UIL Module

  3-2        Aligning Children of Different Sizes

  3-3        Centering Child Widgets at Positions in XmForm-UIL Module

  3-4        Centering Child Widgets at Positions in XmForm-C Module

  3-5        Calling the DXmFormSpaceButtonsEqually Routine

  3-6        Saving Application Defaults-UIL Module

  3-7        Saving Application Defaults-C Module

  3-8        Using Multiple Independent Displays-UIL Module

  3-9        Using Multiple Independent Displays-C Module

  3-10       Using Multiple Interconnected Displays

  3-11       The DXmCreateCursor Routine

  3-12       Using the XtAppAddInput Routine-UIL Module

  3-13       Using the XtAppAddInput Routine-C Module

  4-1        Sample Help File

  4-2        The On Context Push Button in UIL

  4-3        Calling the DXmHelpOnContext Routine

  4-4        Specifying a Help Callback-UIL Module

  4-5        Specifying a Help Callback-C Module

  4-6        UIL Help Widget Implementation

  4-7        Help Widget Implementation-C Language Module

  4-8        Help Widget Implementation-Callbacks

  4-9        Creating Help Widget with Toolkit Routine

  5-1        DECBURGER_HELP.SDML Help File

  5-2        The On Context Push Button in UIL

  5-3        Calling the DXmHelpOnContext Routine

  5-4        Specifying a Help Callback-UIL Module

  5-5        Specifying a Help Callback-C Module

  5-6        UIL Help System Implementation

  5-7        Help System Implementation-C Language Module

  6-1        The DXmColorMixCallbackStruct Data Structure

  6-2        Creating a Color Mixing Widget-UIL Example

  6-3        C Source Code for Creating a Color Mixing Widget with UIL

  6-4        Color Mixing Widget-OK Callback

  6-5        Color Mixing Widget-Apply Callback

  6-6        Color Mixing Widget-Cancel Callback

  6-7        Creating a Color Mixing Widget-Toolkit Example

  7-1        Setting Print Widget Resources Through UIL

  7-2        Adding Print Formats

  7-3        Adding Print Options

  7-4        Creating the Print Widget Through UIL

  7-5        Creating the Print Widget Through UIL-C Support

  7-6        Calling the DXmCreatePrintDialog Routine

  7-7        Calling the DXmPrintWgtPrintJob Routine

  8-1        Using the DXmCSTextGetString Support Routine

  8-2        Creating a Scrolled CSText Widget

  8-3        CSText Widget with Multiline Editing

  8-4        Creating a CSText Widget with UIL

  8-5        C Source for Creating a CSText Widget with UIL

  8-6        Toolkit CSText Creation Routine

  9-1        Portion of the SVN Demo Application Data Hierarchy

  9-2        The DXmSvnCallbackStruct Data Structure

  9-3        The SVN Help Callback

  9-4        SVN.UIL Module

  9-5        SVN.C Module

  9-6        SVN Callbacks

  9-7        SVN Hierarchy Data

  9-8        Creating the SVN Pixmaps (Icons)

  10-1       Font Fallback Through Toolkit Routines

  10-2       Testing XVisual.class Member

  10-3       Testing Color Resources

  A-1        Creating a DECterm Window on a Remote Node

  A-2        Command Procedure to Compile, Link, and Run a DECterm on a Remote Node

  FIGURES

  1-1        The OSF/Motif Periodic Demonstration Program

  1-2        The DECburger Widget Hierarchy

  2-1        DECburger User Interface

  2-2        DECburger XmMainWindow Widget

  2-3        DECburger XmMenuBar Widget

  2-4        DECburger XmPulldownMenu Widget

  2-5        DECburger XmFormDialog Widget

  2-6        DECburger XmRadioBox Widget

  2-7        DECburger XmRowColumn Widget

  2-8        DECburger XmScale Widget

  2-9        DECburger XmOptionMenu Widget

  2-10       DECburger XmText Widget

  2-11       DECburger XmScrolledList Widget

  2-12       DECburger XmForm Widget

  2-13       DECburger XmFormDialog Widget

  4-1        Sample Help Widget

  4-2        Help Widget Components

  5-1        Comparison of Help Widget and the Help System Windows

  6-1        Components of the Color Mixing Widget (Color Picker Model)

  6-2        Components of the Color Mixing Widget (HLS Color Model)

  6-3        Components of the Color Mixing Widget (RGB Color Model)

  6-4        Components of the Color Mixing Widget (Browser Color Model)

  6-5        Components of the Color Mixing Widget (Greyscale Mixer)

  6-6        Components of the Scratch Pad

  7-1        Print Widget Main Dialog Box

  7-2        Print Widget Secondary Dialog Box

  9-1        The SVN Widget

  9-2        Tree Format

  9-3        Column Format

  9-4        SVN Tree-Mode Navigation Window

  TABLES

  1-1        Widget Size and Position Attributes

  1-2        Callback Attributes Supported by the Push Button Widget

  3-1        Freeing Resources Allocated Through UIL

  4-1        Help Widget Terminology

  4-2        VMS Librarian Utility Extensions

  4-3        Help Widget Callbacks

  4-4        Help Widget Topic Resources

  4-5        Help Widget Creation Routines

  6-1        Color Model Constants

  6-2        Support Routines for the Color Mixing Widget

  6-3        Customizing the Color Picker Color Model

  6-4        Color Mixing Widget Callbacks

  6-5        Mechanisms for Creating the Color Mixing Widget

  7-1        Print Widget Callbacks

  8-1        CSText Widget Support Routines

  8-2        Text Widget Callbacks

  8-3        Conversion Routines

  8-4        Mechanisms for Creating CSText Widgets

  9-1        The _Node Data Structure

  9-2        User-Generated Callbacks

  9-3        SVN Widget Creation Routines

  10-1       Font Fallbacks

  10-2       Terminal Font Fallbacks

  10-3       DECwindows Visual Types