Motif Programming Manual

• 1.1 The Plot
• 1.2 Assumptions
• 1.3 How This Book Is Organized
• 1.4 Related Documents
• 1.5 Conventions Used in This Book
• 1.6 Obtaining Motif
• 1.7 Obtaining the Example Programs
• 1.7.1 FTP
• 1.7.2 FTPMAIL
• 1.7.3 BITFTP
• 1.7.4 UUCP
• 1.7.5 Copyright
• 1.7.6 Compiling the Example Programs
• 1.8 Notes on Z-Mail
• 1.9 Acknowledgments
• 1.10 We'd Like to Hear From You

• 2.1 A True Story
• 2.2 Basic User-interface Concepts
• 2.3 What Is Motif?
• 2.4 Designing User Interfaces

• 3.1 Basic X Toolkit Terminology and Concepts
• 3.2 The Xm and Xt Libraries
• 3.3 Programming With Xt and Motif
• 3.3.1 Header Files
• 3.3.2 Setting the Language Procedure
• 3.3.3 Initializing the Toolkit
• 3.3.4 Creating Widgets
• 3.3.5 Setting and Getting Widget Resources
• 3.3.6 Event Handling for Widgets
• 3.3.7 The Event Loop
• 3.4 Summary

• 4.1 The Motif Style
• 4.2 Application Controls
• 4.2.1 The Primitive Widget Class
• 4.2.2 Gadgets
• 4.3 Application Layout
• 4.3.1 The Manager Widget Class
• 4.3.2 Geometry Management
• 4.3.3 Gadget Management
• 4.3.4 Keyboard Traversal
• 4.4 Putting Together a Complete Application
• 4.4.1 The Main Window
• 4.4.2 Menus
• 4.4.3 The Window Manager
• 4.4.4 Dialogs
• 4.4.5 Pixmaps
• 4.4.6 Color
• 4.5 Changes in Motif 1.2
• 4.5.1 General Toolkit Changes
• 4.5.2 Specific Widget Changes
• 4.5.3 Changes to the Example Programs
• 4.6 Summary

• 5.1 Creating a MainWindow
• 5.2 The MenuBar
• 5.2.1 Creating a PulldownMenu
• 5.2.2 SimpleMenu Callback Routines
• 5.2.3 A Sample Application
• 5.3 The Command and Message Areas
• 5.4 Using Resources
• 5.5 Summary
• 5.6 Exercises

• 6.1 The Purpose of Dialogs
• 6.2 The Anatomy of a Dialog
• 6.3 Creating Motif Dialogs
• 6.3.1 Dialog Header Files
• 6.3.2 Creating a Dialog
• 6.3.3 Setting Resources
• 6.3.4 Dialog Management
• 6.3.5 Closing Dialogs
• 6.3.6 Generalizing Dialog Creation
• 6.4 Dialog Resources
• 6.4.1 The Default Button
• 6.4.2 Initial Keyboard Focus
• 6.4.3 Button Sizes
• 6.4.4 The Dialog Title
• 6.4.5 Dialog Resizing
• 6.4.6 Dialog Fonts
• 6.5 Dialog Callback Routines
• 6.6 Piercing the Dialog Abstraction
• 6.6.1 Convenience Routines
• 6.6.2 The DialogShell
• 6.6.3 Internal Widgets
• 6.7 Dialog Modality
• 6.7.1 Implementing Modal Dialogs
• 6.7.2 Forcing an Immediate Response
• 6.8 Summary

• 7.1 Types of SelectionDialogs
• 7.2 SelectionDialogs
• 7.2.1 Callback Routines
• 7.2.2 Internal Widgets
• 7.3 PromptDialogs
• 7.4 The Command Widget
• 7.5 FileSelectionDialogs
• 7.5.1 Creating a FileSelectionDialog
• 7.5.2 Internal Widgets
• 7.5.3 Callback Routines
• 7.5.4 File Searching
• 7.6 Summary

• 8.1 Modifying Motif Dialogs
• 8.1.1 Modifying MessageDialogs
• 8.1.2 Modifying SelectionDialogs
• 8.2 Designing New Dialogs
• 8.2.1 The Shell
• 8.2.2 The Manager Child
• 8.2.3 The Control Area
• 8.2.4 The Action Area
• 8.3 Building a Dialog
• 8.3.1 The Shell
• 8.3.2 The Manager Child
• 8.3.3 The Control Area
• 8.3.4 The Action Area
• 8.4 Generalizing the Action Area
• 8.5 Using a TopLevelShell for a Dialog
• 8.6 Positioning Dialogs
• 8.7 Summary

• 9.1 Types of Manager Widgets
• 9.2 Creating Manager Widgets
• 9.3 The BulletinBoard Widget
• 9.3.1 Resources
• 9.3.2 Geometry Management
• 9.4 The Form Widget
• 9.4.1 Form Attachments
• 9.4.2 Attachment Offsets
• 9.4.3 Position Attachments
• 9.4.4 Additional Resources
• 9.4.5 Nested Forms
• 9.4.6 Common Problems
• 9.5 The RowColumn Widget
• 9.5.1 Rows and Columns
• 9.5.2 Homogeneous Children
• 9.5.3 Callbacks
• 9.6 The Frame Widget
• 9.7 The PanedWindow Widget
• 9.7.1 Pane Constraints
• 9.7.2 Sashes
• 9.8 Keyboard Traversal
• 9.8.1 Turning Traversal Off
• 9.8.2 Modifying Tab Groups
• 9.8.3 Handling Event Translations
• 9.8.4 Processing Traversal Manually
• 9.9 Summary

• 10.1 The ScrolledWindow Design Model
• 10.1.1 The Automatic Scrolling Model
• 10.1.2 The Application-defined Scrolling Model
• 10.2 Creating a ScrolledWindow
• 10.2.1 Automatic Scrolling
• 10.2.2 Application-defined Scrolling
• 10.2.3 Additional Resources
• 10.2.4 An Automatic ScrolledWindow Example
• 10.3 Working Directly With ScrollBars
• 10.3.1 Resources
• 10.3.2 Orientation
• 10.3.3 Callback Routines
• 10.4 Implementing True Application-defined Scrolling
• 10.5 Working With Keyboard Traversal in ScrolledWindows
• 10.6 Summary
• 10.7 Exercises

• 11.1 Creating a DrawingArea Widget
• 11.2 Using DrawingArea Callback Functions
• 11.2.1 Handling Input Events
• 11.2.2 Redrawing a DrawingArea
• 11.3 Using Translations on a DrawingArea
• 11.4 Using Color in a DrawingArea
• 11.5 Summary
• 11.6 Exercises

• 12.1 Labels
• 12.1.1 Creating a Label
• 12.1.2 Text Labels
• 12.1.3 Images as Labels
• 12.1.4 Label Sensitivity
• 12.1.5 Label Alignment
• 12.1.6 Multi-line and Multi-font Labels
• 12.2 PushButtons
• 12.2.1 PushButton Callbacks
• 12.2.2 Multiple Button Clicks
• 12.3 ToggleButtons
• 12.3.1 Creating ToggleButtons
• 12.3.2 ToggleButton Resources
• 12.3.3 ToggleButton Pixmaps
• 12.3.4 ToggleButton Callbacks
• 12.3.5 RadioBoxes
• 12.3.6 CheckBoxes
• 12.4 ArrowButtons
• 12.5 DrawnButtons
• 12.6 Summary
• 12.7 Exercise

• 13.1 Creating a List Widget
• 13.2 Using ScrolledLists
• 13.3 Manipulating Items
• 13.3.1 Adding Items
• 13.3.2 Finding Items
• 13.3.3 Replacing Items
• 13.3.4 Deleting Items
• 13.3.5 Selecting Items
• 13.3.6 An Example
• 13.4 Positioning the List
• 13.5 List Callback Routines
• 13.5.1 The Default Action
• 13.5.2 Browse and Single Selection Callbacks
• 13.5.3 Multiple Selection Callback
• 13.5.4 Extended Selection Callback
• 13.6 Summary
• 13.7 Exercises

• 14.1 Creating a Scale Widget
• 14.2 Scale Values
• 14.3 Scale Orientation and Movement
• 14.4 Scale Callbacks
• 14.5 Scale Tick Marks
• 14.6 Summary

• 15.1 Interacting With Text Widgets
• 15.1.1 Inserting Text
• 15.1.2 Selecting Text
• 15.2 Text Widget Basics
• 15.2.1 The Textual Data
• 15.2.2 Single and Multiple Lines
• 15.2.3 Scrollable Text
• 15.2.4 Text Positions
• 15.2.5 Output-only Text
• 15.3 Text Clipboard Functions
• 15.3.1 Getting the Selection
• 15.3.2 Modifying the Selection Mechanisms
• 15.4 A Text Editor
• 15.5 Text Callbacks
• 15.5.1 The Activation Callback
• 15.5.2 Text Modification Callbacks
• 15.5.3 The Cursor Movement Callback
• 15.5.4 Focus Callbacks
• 15.6 Text Widget Internationalization
• 15.6.1 Text Representation
• 15.6.2 Text Output
• 15.6.3 Text Input
• 15.7 Summary
• 15.8 Exercises

• 16.1 Menu Types
• 16.2 Creating Simple Menus
• 16.2.1 Popup Menus
• 16.2.2 Cascading Menus
• 16.2.3 Option Menus
• 16.3 Designing Menu Systems
• 16.3.1 Menu Titles
• 16.3.2 Menu Items
• 16.3.3 Mnemonics
• 16.3.4 Accelerators
• 16.3.5 The Help Menu
• 16.3.6 Sensitivity
• 16.3.7 Tear-Off Menus
• 16.4 General Menu Creation Techniques
• 16.4.1 Building Pulldown Menus
• 16.4.2 Building Cascading Menus
• 16.4.3 Building Popup Menus
• 16.4.4 Building Option Menus
• 16.5 Summary
• 16.6 Exercises

• 17.1 Interclient Communication
• 17.2 Shell Resources
• 17.2.1 Shell Positions
• 17.2.2 Shell Sizes
• 17.2.3 The Shell's Icon
• 17.3 VendorShell Resources
• 17.3.1 Window Manager Decorations
• 17.3.2 Window Menu Functions
• 17.4 Handling Window Manager Messages
• 17.4.1 Adding New Protocols
• 17.4.2 Saving Application State
• 17.5 Customized Protocols
• 17.6 Summary
• 17.7 Exercises

• 18.1 Simple Clipboard Copy and Retrieval
• 18.1.1 Copying Data
• 18.1.2 Retrieving Data
• 18.1.3 Querying the Clipboard for Data Size
• 18.2 Copy by Name
• 18.3 Clipboard Data Formats
• 18.4 The Primary Selection and the Clipboard
• 18.4.1 Clipboard Functions With Text Widgets
• 18.4.2 The Owner of the Selection
• 18.5 Implementation Issues
• 18.6 Summary

• 19.1 Using Drag and Drop
• 19.2 The Drag and Drop Model
• 19.2.1 The Drag Source
• 19.2.2 The Drop Site
• 19.2.3 The Drag Icon
• 19.2.4 Protocols
• 19.2.5 The Programming Model
• 19.3 Customizing Built-in Drag and Drop
• 19.3.1 Specifying the Drag Protocol
• 19.3.2 Turning Off Drag and Drop Functionality
• 19.3.3 Modifying the Visual Effects
• 19.4 Working With Drag Sources
• 19.4.1 Creating a Drag Source
• 19.4.2 Starting the Drag
• 19.4.3 Converting the Data
• 19.4.4 Modifying an Existing Drag Source
• 19.4.5 Providing Custom Drag-over Visuals
• 19.4.6 Cleaning Up
• 19.5 Working With Drop Sites
• 19.5.1 Creating a Drop Site
• 19.5.2 Modifying an Existing Drop Site
• 19.5.3 Handling the Drop
• 19.5.4 Providing Help
• 19.5.5 Providing Custom Drag-under Visuals
• 19.6 Summary

• 20.1 Internationalized Text Output
• 20.2 Creating Compound Strings
• 20.2.1 The Simple Case
• 20.2.2 Font List Tags
• 20.2.3 Compound String Segments
• 20.2.4 Multiple-font Strings
• 20.3 Manipulating Compound Strings
• 20.3.1 Compound String Functions
• 20.3.2 Compound String Retrieval
• 20.3.3 Compound String Conversion
• 20.4 Working With Font Lists
• 20.4.1 Creating Font Lists
• 20.4.2 Retrieving Font Lists
• 20.4.3 Querying Font Lists
• 20.5 Rendering Compound Strings
• 20.6 Summary

• 21.1 Handling Signals in Xlib
• 21.2 Handling Signals in Xt
• 21.3 An Example
• 21.4 Additional Issues
• 21.5 Summary

• 22.1 Help Systems
• 22.1.1 Multi-level Help
• 22.1.2 Context-sensitive Help
• 22.2 Working Dialogs
• 22.2.1 Using Work Procedures
• 22.2.2 Using Timers
• 22.2.3 Processing Events
• 22.2.4 Updating the Display
• 22.2.5 Avoiding Forks
• 22.3 Dynamic Message Symbols
• 22.4 Summary

• 23.1 Overview of UIL and Mrm
• 23.1.1 Using UIL and Mrm
• 23.1.2 Advantages and Disadvantages of UIL
• 23.2 The
• 23.3 Describing an Interface With UIL
• 23.3.1 Starting and Ending a Module
• 23.3.2 Specifying Module-wide Options
• 23.3.3 Include Files
• 23.3.4 Adding Comments
• 23.3.5 Overview of UIL Language Syntax
• 23.3.6 Sections of a UIL Module
• 23.4 Compiling the UIL Module
• 23.5 Structure of an Mrm Application
• 23.5.1 Initializing the Application
• 23.5.2 Creating the Interface
• 23.5.3 Displaying the Interface
• 23.6 Summary

• 24.1 Compiler Options
• 24.1.1 Output File
• 24.1.2 Include Path
• 24.1.3 Generate Listing
• 24.1.4 Set Locale
• 24.1.5 Suppress Warnings
• 24.1.6 Machine Listing
• 24.1.7 Use WML Description
• 24.2 Errors, Warnings, and Informational Messages
• 24.2.1 Severe Error Messages
• 24.2.2 Regular Error Messages
• 24.2.3 Warning Messages
• 24.2.4 Informational Messages
• 24.3 Summary

• 25.1 Viewing UIL Examples
• 25.2 Defining and Creating Widgets
• 25.2.1 Specifying Widget Attributes
• 25.2.2 Sharing Widgets Among Modules
• 25.2.3 The Widget Creation Process
• 25.3 Defining and Fetching Values
• 25.3.1 Sharing Values Between Modules
• 25.3.2 Fetching Values
• 25.3.3 Numeric Values
• 25.3.4 Text-related Values
• 25.3.5 Colors
• 25.3.6 Pixmaps
• 25.3.7 Widget Classes
• 25.3.8 Keysyms
• 25.3.9 Translation Tables
• 25.4 Working With Callbacks
• 25.5 Using Lists
• 25.6 Exporting Application Data
• 25.6.1 Declaring Identifiers in UIL
• 25.6.2 Exporting Identifiers From Application Code
• 25.7 Summary

• 26.1 Defining the User Interface
• 26.1.1 The Main Application Window
• 26.1.2 The Menu System
• 26.1.3 Dialog Boxes
• 26.2 Creating the Application
• 26.2.1 Widget IDs
• 26.2.2 Callbacks
• 26.2.3 The Error Dialog
• 26.3 Summary

• 27.1 Using Non-Motif Widgets
• 27.1.1 The Widget Creation Procedure
• 27.1.2 Widget Include Files
• 27.1.3 Creating User-defined Widgets
• 27.2 Organizing UIL Modules
• 27.2.1 Using Separate Modules
• 27.2.2 Organizing Within a Module
• 27.2.3 Supporting Internationalization
• 27.2.4 Organizing With Include Files
• 27.2.5 Creating Reusable Components
• 27.3 Specifying Resource Values
• 27.3.1 Resource Name Checking
• 27.3.2 Resource Type Checking
• 27.3.3 Resource Type Support
• 27.3.4 Callback Specifications
• 27.3.5 Wildcard Specification
• 27.3.6 User Customization
• 27.3.7 Dynamic Updating
• 27.3.8 Guidelines for Setting Resources
• 27.4 Using Lists Effectively
• 27.4.1 Specifying Common Resources
• 27.4.2 Reusing Components
• 27.5 Prototyping an Interface With UIL
• 27.5.1 Managing Widgets
• 27.5.2 Creating Widgets
• 27.6 Summary

• 28.1 A Postcard Interface for Mail
• 28.2 A Bitmap Display Utility
• 28.3 A Memo Calendar