Motif Widget Writer's Guide


Table of Contents

Preface
Audience
Applicability
Purpose
Document Usage
Related Documents
What DocBook SGML Markup Means
Problem Reporting

1. What Is Involved in Writing a Motif Widget
Pros and Cons of Writing a Motif Widget
Prerequisite Knowledge
The Software You Will Need
What Kinds of Widgets Can You Create?
How Much Work Is Involved?
Defining the Goal

2. A Motif Widget Writing Tutorial
Namespace
Recommended Files for Each Widget
The Widget Public Header File
The Widget Private Header File
The Widget Source Code File
Make the Widget Accessible to Applications
MultiThread-Safe Motif Widgets

3. The Widget Class Record of Primitive Widgets
The CoreClassPart Structure
The PrimitiveClassPart Structure
The Primitive Class Extension Record
The Instance Data Members of XmPrimitive

4. The Widget Class Record of Manager Widgets
The CoreClassPart Structure
The CompositeClassPart Structure
The ConstraintClassPart Structure
The ManagerClassPart Structure
The Manager Class Extension Record
The Instance Data Members of XmManager

5. Traits
What Is a Trait?
Why Use Traits?
Installing a Trait
Accessing Traits
Overriding a Trait Record Variable

6. Resources
Defining Motif Resources
Synthetic Resources
Representation Types
Enumerated Representation Types
Nonenumerated Representation Types
Motif Representation Types in XmPrimitive and XmManager

7. Translations and Actions
Defining Translations in the Class Record
Conflicts Between tm_table and translations
Virtual Keysyms
Enter Actions
Leave Actions
Mouse Bindings
Keyboard Traversal

8. Using Xme Functions Within a Widget
Calling an Xme function
Xme Trait Functions
Rendering Geometric Objects
Xme Resolution Independence Functions
Xme String Functions
Implementing Data Transfer
Xme Geometry Functions
Xme Focus/Traversal Functions
Xme Miscellaneous Functions

9. Handling Textual Data
Text Versus Compound Strings
Editable Versus Noneditable Text
Recommended Resources for Compound String Widgets
Rendering the Compound String
The XmQTaccessTextual Trait

10. Data Transfer Between Widgets with UTM
A Data Transfer Tutorial
Overview of Implementing UTM
UTM and the Application
Primary Transfer Details
Clipboard Transfer Details
Drag and Drop Transfer Details
Writing a Conversion Routine
Writing a Destination Routine
Writing a Transfer Procedure
Timestamps
Transferring Multiple Targets

11. How to Write a Motif Button Widget
Buttons to Write and Buttons to Avoid Writing
Writing Your Own DialogBox Button
Writing Your Own Menu Button Widget
Writing Your Own Tab Button

12. Geometry Management
Overview
The Parent's changed_managed Method
The Parent's geometry_manager Method
The initialize Method
The Child's set_values and set_values_almost Method
The Child's resize Method
The child's query_geometry Method
Exposure and Redisplay
A Widget Case Study: ExmSimple

13. UIL and WML Compatibility
Strategies
Providing UIL Access Through Three Small Files
What is WML?
A WML File Example
Building a WMD File from Your WML File
UIL Compiling with Your WMD File

14. Miscellany
Internationalization
Binary Compatibility

15. Widget Printing

I. Xme Reference Pages
XmeAddFocusChangeCallback - Registers a callback for focus changes
XmeClearBorder - Clears the window decorations that border a given widget
XmeClipboardSink - A toolkit function that transfers data from the clipboard to a widget
XmeClipboardSource - A toolkit function that places data on the clipboard
XmeGetDesktopColorCells - return desktop pixel data in XColor[] format
XmeGetColorObjData - access ColorObject desktop and pixel data
XmeConfigureObject - Changes a child's position, size, or border width
XmeConvertMerge - A toolkit function that merges data converted during a transfer operation
XmeCreateClassDialog - Creates a DialogShell containing a widget of the specified class
XmeDragSource - A toolkit function that starts a drag and drop operation
XmeDrawArrow - Draws a Motif-style, three-dimensional arrow
XmeDrawCircle - Draws a Motif-style, three-dimensional circle
XmeDrawDiamond - Draws a Motif-style, three-dimensional diamond
XmeDrawHighlight - Draws a Motif-style highlight around a given widget to show that it has been selected
XmeDrawIndicator - Draws a Motif-style indicator (either a check mark or a cross) at the specified location in the drawable
XmeDrawPolygonShadow - Draws a Motif-style, three-dimensional shadow around a polygon
XmeDrawSeparator - Draws several different types of line-based separators
XmeDrawShadows - Draws a Motif-style, three-dimensional shadow around a widget
XmeDropSink - A toolkit function that establishes a widget as a drop site
XmeFocusIsInShell - Returns a Boolean value to indicate whether the parent shell of a specified widget has the keyboard focus.
XmeFromHorizontalPixels - Converts from pixels to real-world dimensions based on horizontal resolution of the screen
XmeFromVerticalPixels - Converts from pixels to real-world dimensions based on vertical resolution of the screen
XmeGetDefaultPixel - Generates colors based on the screen background color
XmeGetDefaultRenderTable - Returns the default render table associated with a specified widget
XmeGetDirection - A compound string parse procedure to insert a direction component
XmeGetEncodingAtom - A toolkit function that returns the encoding of the locale
XmeGetHomeDirName - Returns the pathname of the user's home directory
XmeGetLocalizedString - Returns a localized version of the input string
XmeGetNextCharacter - A compound string parse procedure to insert a character
XmeGetNullCursor - Returns the null cursor associated with a given display
XmeGetPixmapData - Returns details about a cached pixmap
XmeGetTextualDragIcon - Returns an icon widget symbolizing a textual drag operation in progress
XmeMicroSleep - Suspends execution for a specified number of microseconds
XmeNamedSink - A toolkit function that transfers data from the named selection to a widget
XmeNamedSource - A toolkit function that takes ownership of a named selection
XmeNamesAreEqual - Compares two strings for equality
XmeNavigChangeManaged - Helps a change_managed method establish the correct keyboard traversal policy
XmePrimarySink - A toolkit function that transfers data from the primary selection to a widget
XmePrimarySource - A toolkit function that takes ownership of the primary selection
XmeQueryBestCursorSize - Finds the best cursor size
XmeRedisplayGadgets - Redisplays all the gadget children of a manager
XmeRemoveFocusChangeCallback - Removes a focus change callback
XmeRenderTableGetDefaultFont - Gets information on the default font associated with a specified render table
XmeReplyToQueryGeometry - Handles standard geometry requests
XmeResolvePartOffsets - Allows writing of upward-compatible applications and widgets
XmeSecondarySink - A toolkit function that establishes a widget as the destination for secondary transfer
XmeSecondarySource - A toolkit function that takes ownership of the secondary selection
XmeSecondaryTransfer - A toolkit function that transfers data from the secondary selection to the destination widget
XmeSetWMShellTitle - A compound string function that updates the window manager title
XmeStandardConvert - A toolkit function that converts selections to standard targets
XmeStandardTargets - A toolkit function that returns a list of standard targets
XmeToHorizontalPixels - Converts from real-world dimensions to pixels
XmeToVerticalPixels - Converts from real-world dimensions to pixels
XmeTraitGet - Returns the trait record associated with a given object
XmeTraitSet - Installs a trait on a specified object
XmeTransferAddDoneProc - A toolkit function that establishes a procedure to be called when data transfer is complete
XmeVirtualToActualKeysyms - Finds the physical keysyms associated with a given virtual keysym.
XmeWarning - Writes a warning message to the standard error stream

II. Traits Reference Pages
XmQTaccessTextual - A widget holding this trait can display textual data
XmQTactivatable - A widget holding this trait will be treated as a command button in a DialogBox or as a major tab in a Notebook
XmQTcareParentVisual - A child widget holding this trait wants to be notified whenever its parent's visual state changes
XmQTcontainer - A widget holding this trait can manage widgets holding the XmQTcontainerItem trait
XmQTcontainerItem - A widget holding this trait can serve as a child of a widget holding the XmQTcontainer trait
XmQTdialogShellSavvy - A dialog widget holding this trait can become a child of the XmDialogShell widget
XmQTjoinSide - A child widget holding this trait can be attached to one side of a suitable parent widget
XmQTmenuSavvy - A widget holding this trait can become a menu child
XmQTmenuSystem - A widget holding this trait can serve as a menu system
XmQTnavigator - A widget holding this trait can act as a navigator
XmQTscrollFrame - A widget holding this trait can handle one or more navigator widgets
XmQTspecifyRenderTable - A widget holding this trait can supply the names of its default render tables to any requestor
XmQTtakesDefault - A button widget holding this trait can change its appearance to show that it is the default button
XmQTtransfer - A trait that implements data transfer to and from a widget

III. Exm Demonstration Widgets Reference Pages
ExmCommandButton - The ExmCommandButton widget class
ExmGrid - The Grid widget class
ExmMenuButton - The MenuButton widget class demonstration widget
ExmPanner - The Panner widget class
ExmSimple - The Simple widget class demonstration widget
ExmString - The String widget class
ExmStringTransfer - The StringTransfer widget class
ExmTabButton - The TabButton widget class demonstration widget

Glossary