CONTENTS

  Preface
    Audience
    Applicability
    Purpose
    Document Usage
    Related Documents
    Typographic and Keying Conventions
      Keyboard Conventions
      Mouse Conventions
    Problem Reporting

  Chapter 1. Introduction
    1.1 The X Window System
    1.2 Xlib, Xt, and Motif
      1.2.1 Xlib
      1.2.2 Xt
        1.2.2.1 Widgets
        1.2.2.2 Widget Geometry
        1.2.2.3 Event Handling
      1.2.3 Motif
        1.2.3.1 Visual Style
        1.2.3.2 Selections and Drag and Drop
        1.2.3.3 Keyboard Traversal
        1.2.3.4 Compound Strings and Font Lists
        1.2.3.5 Motif Window Manager
        1.2.3.6 UIL and MRM
      1.2.4 Using Xlib, Xt, and Motif
    1.3 Widget Classes and Hierarchy
      1.3.1 Xt Classes
      1.3.2 Motif Classes
        1.3.2.1 Primitives and Gadgets
        1.3.2.2 Managers
        1.3.2.3 Shells
        1.3.2.4 Other Motif Classes
    1.4 Header Files and Libraries

  Chapter 2. The Motif Programming Model
    2.1 A User-Centered Model
    2.2 Separating Interface from Application
    2.3 Building Blocks: Primitive Widgets and Gadgets
      2.3.1 Label and Separator
      2.3.2 Buttons
      2.3.3 ScrollBar
      2.3.4 List
      2.3.5 Text
    2.4 Managers
      2.4.1 Frame
      2.4.2 Scale
      2.4.3 PanedWindow
      2.4.4 ScrolledWindow and MainWindow
      2.4.5 RowColumn
      2.4.6 BulletinBoard, Form, MessageBox, SelectionBox
      2.4.7 DrawingArea
    2.5 Shells
      2.5.1 VendorShell
      2.5.2 DialogShell
      2.5.3 MenuShell
    2.6 Applications, Top-Level Widgets, and Dialogs
      2.6.1 Applications
      2.6.2 Top-Level Widgets
      2.6.3 Dialogs
    2.7 Resources: User and Program Customization
    2.8 Handling Input and Output

  Chapter 3. Structure of a Motif Program
    3.1 Including Header Files
    3.2 Initializing the Intrinsics
      3.2.1 The Initial Resource Database
        3.2.1.1 File Search Paths
        3.2.1.2 Initial Database Components
        3.2.1.3 Command-Line Specifications
        3.2.1.4 Per-Host User Resources
        3.2.1.5 Screen-Specific Resources
        3.2.1.6 Server or User-Preference Resources
        3.2.1.7 User Application File
        3.2.1.8 Application Class Resource File
    3.3 Creating Widgets
      3.3.1 Specifying Resource Values
        3.3.1.1 Widget Initialization
        3.3.1.2 Arguments that Specify Resource Values
        3.3.1.3 Setting Resource Values
        3.3.1.4 Retrieving Resource Values
        3.3.1.5 Resource Value Data Types
        3.3.1.6 Resource Values and Memory Management
    3.4 Adding Callback Procedures
    3.5 Making Widgets Visible
      3.5.1 Managing Widgets
      3.5.2 Realizing Widgets
      3.5.3 Mapping Widgets
      3.5.4 Multiple Screens, Displays, and Applications
    3.6 Entering the Event Loop

  Chapter 4. Structure of a Program Using UIL and MRM
    4.1 Structure of a UIL Module
      4.1.1 module Clause
      4.1.2 Module-Level Declarations
      4.1.3 include Directive
      4.1.4 value Declaration
      4.1.5 identifier Declaration
      4.1.6 procedure Declaration
      4.1.7 object Declaration
        4.1.7.1 Object Type
        4.1.7.2 Children
        4.1.7.3 Resource Values
        4.1.7.4 Callback Procedures
      4.1.8 list Declaration
      4.1.9 end module Clause
    4.2 Structure of a Program Using MRM
      4.2.1 Including Header Files
      4.2.2 Initializing the Intrinsics
      4.2.3 Initializing MRM
      4.2.4 Opening UID Files
      4.2.5 Registering Callbacks and Identifiers
      4.2.6 Fetching Information from UID Files
      4.2.7 Closing the UID File
      4.2.8 Defining Callback Procedures
      4.2.9 Making Widgets Visible
      4.2.10 Entering the Event Loop

  Chapter 5. Basic Controls
    5.1 Core, RectObj, XmPrimitive, and XmGadget Classes
      5.1.1 Core
      5.1.2 RectObj
      5.1.3 XmPrimitive
      5.1.4 XmGadget
    5.2 Labels, Buttons, and Separators
      5.2.1 Labels
      5.2.2 Buttons
        5.2.2.1 CascadeButtons
        5.2.2.2 PushButtons
        5.2.2.3 ToggleButtons
        5.2.2.4 DrawnButtons
        5.2.2.5 ArrowButtons
      5.2.3 Separators
    5.3 ScrollBar
    5.4 Scale
    5.5 List
    5.6 Text and TextField

  Chapter 6. Menus and Options
    6.1 Menu Components: Buttons, RowColumn, MenuShell
      6.1.1 Buttons
      6.1.2 RowColumn
      6.1.3 MenuShell
    6.2 MenuBar
    6.3 Popup Menu
    6.4 PulldownMenu
    6.5 OptionMenu
    6.6 RadioBox and CheckBox
    6.7 TearOffMenus

  Chapter 7. Dialogs
    7.1 BulletinBoard and DialogShell
      7.1.1 BulletinBoard
      7.1.2 Activation, Cancellation, and Help
      7.1.3 DialogShell
      7.1.4 Initial Focus
    7.2 Making a Selection: SelectionBox
    7.3 Choosing a Pathname: FileSelectionBox
    7.4 Command
    7.5 MessageBox
    7.6 Form

  Chapter 8. Text
    8.1 Text and TextField
    8.2 Selection
      8.2.1 Mouse Selection
      8.2.2 Keyboard Selection
    8.3 Text Editing and Callbacks
    8.4 Text Resources and Geometry
    8.5 Convenience Routines
    8.6 ScrolledText
    8.7 Storing Text in a File
    8.8 Sharing Text Sources

  Chapter 9. Scrolling, Panes, and Frames
    9.1 ScrolledWindow
      9.1.1 Automatic and Application-Defined Scrolling
      9.1.2 Other Resources
    9.2 Automatic Scrolling
      9.2.1 Traversing to Obscured Widgets
      9.2.2 Example of Automatic Scrolling
    9.3 Application-Defined Scrolling
      9.3.1 Example of Application-Defined Scrolling
    9.4 MainWindow
    9.5 Frame
    9.6 PanedWindow

  Chapter 10. Managing Geometry
    10.1 Xt and Geometry Management
      10.1.1 Widget Class Procedures
      10.1.2 Geometry Change Requests
      10.1.3 The geometry_manager Procedure
      10.1.4 Intermediate Geometry Requests
      10.1.5 XtSetValues
      10.1.6 The resize Procedure
      10.1.7 Preferred Size and Location
      10.1.8 Exposure and Redisplay
    10.2 Shells and Their Children
    10.3 Manager Widgets and Their Children
    10.4 Managing Geometry Using RowColumn
    10.5 Managing Geometry Using BulletinBoard and DrawingArea
    10.6 Managing Geometry Using Form

  Chapter 11. Internationalization
    11.1 Issues in Internationalized Applications
      11.1.1 Internationalization and Localization
      11.1.2 Obtaining Input
        11.1.2.1 The Problems
        11.1.2.2 The Solution
      11.1.3 Displaying Output
      11.1.4 Locales and Localization
    11.2 Compound Strings, Fonts, and Text Display
      11.2.1 Compound String Components
        11.2.1.1 Compound Strings and Resources
          11.2.1.1.1 Setting a Compound String Programmatically
          11.2.1.1.2 Setting a Compound String in a Defaults File
        11.2.1.2 Compound Strings in UIL
      11.2.2 Fonts, Font Lists, and Font Sets
        11.2.2.1 Font List Structure
        11.2.2.2 Font Lists and Resources
        11.2.2.3 Font List Resource Defaults
        11.2.2.4 Font Lists in UIL
      11.2.3 Compound Strings and Font Lists
      11.2.4 Text and TextField Widgets and Font Lists
    11.3 Localizing Applications
      11.3.1 Techniques for Localization
        11.3.1.1 Establishing the Language Environment
        11.3.1.2 Using Locales
        11.3.1.3 Localization without Locales
      11.3.2 Resources and Localization
        11.3.2.1 Initial Resource Database
        11.3.2.2 Resource File Locations
        11.3.2.3 An Example
      11.3.3 UIL and Localization
        11.3.3.1 Preparing Localized UID Files
        11.3.3.2 MRM and Localized UID Files
      11.3.4 Message Catalogs and Localization
      11.3.5 Images, Pixmaps, and Localization
      11.3.6 Comparing Approaches to Localization
    11.4 Advanced Topics in Internationalization
      11.4.1 Internationalization and Text Input
        11.4.1.1 Input Method
        11.4.1.2 Input Context
        11.4.1.3 Input and the Motif Text widget
        11.4.1.4 Text Input Using a DrawingArea
        11.4.1.5 Geometry Management of Pre-edit and Status Areas
      11.4.2 Compound Strings and Compound Text

  Chapter 12. Color and Pixmaps
    12.1 Default Colors
      12.1.1 Borders
      12.1.2 Backgrounds
      12.1.3 Foregrounds
      12.1.4 Shadows
      12.1.5 Focus Highlights
      12.1.6 Arming and Selection
    12.2 Application-Defined Color Generation
    12.3 Colormaps
    12.4 Using Pixmaps

  Chapter 13. Input, Focus, and Keyboard Navigation
    13.1 Focus Models
    13.2 Controlling Keyboard Navigation
      13.2.1 Sensitivity
      13.2.2 XmNtraversalOn
      13.2.3 Tab Groups
        13.2.3.1 Controlling Tab Group Traversal Order
      13.2.4 Initial Focus
      13.2.5 Traversing to Obscured Widgets
      13.2.6 XmProcessTraversal
      13.2.7 Focus Callbacks
    13.3 Translations and Actions
      13.3.1 Translation Table Format
      13.3.2 Using Translations
      13.3.3 Actions
      13.3.4 Bindings for osf Keysyms
    13.4 Mnemonics and Accelerators
    13.5 Event Handlers

  Chapter 14. Graphics and Text in a DrawingArea
    14.1 DrawingArea: A General-Purpose Widget
    14.2 Event Handling and Callbacks
      14.2.1 Handling Resize Events
        14.2.1.1 Moving and Resizing Children
        14.2.1.2 Resizing and Redisplay
        14.2.1.3 Example of a Resize Procedure
      14.2.2 Handling Exposure Events
        14.2.2.1 Example of an Expose Procedure
      14.2.3 Handling Input Events
        14.2.3.1 Example of an Input Procedure
    14.3 Using a DrawingArea in a ScrolledWindow
    14.4 Using a DrawingArea for Graphics
    14.5 DrawingArea and Advanced Text Editing
      14.5.1 Text Output
      14.5.2 Text Input

  Chapter 15. Drag and Drop
    15.1 User Overview of Drag and Drop
      15.1.1 Overview of User Interaction
      15.1.2 Overview of Drag Over Effects
        15.1.2.1 Drag States
        15.1.2.2 Drag Operations
      15.1.3 Overview of Drag Under Effects
      15.1.4 Overview of Drop Effects
    15.2 Technical Overview of Drag and Drop
      15.2.1 Complexity of Drag and Drop Programs
        15.2.1.1 A Simple Drag Receiver
        15.2.1.2 A Simple Drag Source
      15.2.2 Drag Sources and Drop Sites
      15.2.3 Protocols
        15.2.3.1 Drag Protocols
        15.2.3.2 Drop Protocol
      15.2.4 Drag and Drop Widget Classes
      15.2.5 Drag and Drop Functions
      15.2.6 Targets
      15.2.7 Operations
        15.2.7.1 Drop Site Status
      15.2.8 Overview of Programmer Responsibilities
    15.3 Drag and Drop Protocols
      15.3.1 Drag Protocols
        15.3.1.1 The Preregister Drag Protocol
        15.3.1.2 The Dynamic Drag Protocol
      15.3.2 Choosing the Protocol and Visual Style
        15.3.2.1 Specifying Drag Protocols
        15.3.2.2 Protocols and Visuals
      15.3.3 Drop Protocol
    15.4 Drop Receiver Responsibilities for Dragging
      15.4.1 Establishing a Drop Site
        15.4.1.1 Changing a Drop Site
        15.4.1.2 Specially-Shaped Drop Sites
        15.4.1.3 Nested Drop Sites
        15.4.1.4 Overlapping Drop Sites
        15.4.1.5 Drag Under Visual Effects
      15.4.2 XmNdragProc
        15.4.2.1 Simulating Nested Drop Sites
    15.5 Drag Initiator Responsibilities for Dragging
      15.5.1 Recognizing a Drag Has Started
      15.5.2 Starting a Drag With XmDragStart
      15.5.3 Overriding Existing Drag Sources
      15.5.4 Drag-over Visual Effects
        15.5.4.1 Source Icon
        15.5.4.2 State Icon
        15.5.4.3 Operation Icon
        15.5.4.4 Drag Icon Blending and Attachment
        15.5.4.5 Visual Style Notes
        15.5.4.6 Creating a Drag Icon
      15.5.5 Drag Callbacks
      15.5.6 Getting Data about the Current Drop Site
      15.5.7 Cancelling the Drag
    15.6 Drop Receiver Responsibilities for Dropping
      15.6.1 The XmNdropProc
      15.6.2 XmDropTransfer
        15.6.2.1 Processing Each Operation
      15.6.3 Cancelling a Drop
      15.6.4 Providing Help
    15.7 Drag Initiator Responsibilities for Dropping
      15.7.1 XmNdropStartCallback
      15.7.2 Dealing with Requests for Transfer
      15.7.3 XmNdropFinishCallback
      15.7.4 XmNdragDropFinishCallback

  Chapter 16. Interclient Communication
    16.1 Window Managers, ICCCM, and Shells
      16.1.1 Application Startup
      16.1.2 Window Configuration
      16.1.3 Icons
      16.1.4 Window Groups
      16.1.5 Menus and Dialogs
      16.1.6 Input Focus
      16.1.7 Colormaps
      16.1.8 Application Shutdown and Restart
    16.2 MWM Properties and Resources
      16.2.1 Decorations
      16.2.2 Functions
      16.2.3 Input Mode
      16.2.4 Window Menu
      16.2.5 MWM Messages
      16.2.6 MWM Information
    16.3 Atom and Protocol Management
    16.4 Selections
      16.4.1 Selection Types
      16.4.2 Targets
      16.4.3 Text Conversion
      16.4.4 Incremental Transfers
      16.4.5 The Xt Selection Interface
    16.5 The Motif Clipboard
      16.5.1 Copying Data to the Clipboard
      16.5.2 Retrieving Data from the Clipboard
      16.5.3 Utility Routines

  Appendix A. The Widget Meta-Language Facility
    A.1 Using WML
      A.1.1 Building WML
      A.1.2 Running WML
      A.1.3 Installing UIL
      A.1.4 Building UIL

  Appendix B. Drag and Drop Example Program
    B.1 DNDDemo.h
    B.2 DNDDemo.c
    B.3 DNDDraw.c

  Figures

  11-1: Information External to the Applica ­ tion

  11-2: Compound String Relationships With Explicit Tag

  11-3: Compound String Relationships With XmFONTLIST_DEFAULT_TAG

  11-4: Text Widget Pre-Edit and Status Areas Using over-the-spot

  11-5: Text Widget Pre-Edit Area After Next Character Entry

  11-6: Input Method and Input Contexts

  11-7: Text Widget Pre-Edit and Status Areas Using Off-the-Spot

  11-8: Reason for Compound Text

  15-1: A Drag Icon

  15-2: A Label Widget Receiver Before and After Drag

  15-3: A ScrollBar Widget as Drag Source

  15-4: A Label Widget

  15-5: Special Shaped Drop Site

  15-6: Default Drag Under Animation

  15-7: Simulated Drop Sites

  15-8: A Drag Icon

  15-9: Source Icons

  15-10: Operation Icons

  15-11: Copy and Noop Drag Icons

  15-12: An Attach_Hot Icon

  15-13: Custom Source Icon

  15-14: Help Dialog Box

  B-1: Drag and Drop Demonstration

  Tables

  3-1: Steps in Writing Widget Programs

  11-1: Areas and Typical Character Sets

  11-2: Widgets With A Font List Resource