MOTIF 2.1—Programmer’s Guide Desktop Product Documentation The Open Group Copyright © The Open Group, 1997. All Rights Reserved The information contained within this document is subject to change without notice. This documentation and the software to which it relates are derived in part from copyrighted materials supplied by Digital Equipment Corporation, Hewlett-Packard Company, International Business Machines, Massachusetts Institute of Technology, Microsoft Corporation, Sun Microsystems Inc., and The Santa Cruz Operation Inc. THE OPEN GROUP MAKES NO WARRANTY OF ANY KIND WITH REGARD TO THIS MATERIAL, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. The Open Group shall not be liable for errors contained herein, or for any direct or indirect, incidental, special or consequential damages in connection with the furnishing, performance, or use of this material. Desktop Product Documentation: Motif 2.1—Programmer’s Guide ISBN 1-85912-134-9 Document Number M213 Published in the U.K. by The Open Group, 1997 Any comments relating to the material contained in this document may be submitted to: The Open Group Apex Plaza Forbury Road Reading Berkshire, RG1 1AX United Kingdom or by Electronic Mail to: [email protected] OTHER NOTICES THIS DOCUMENT AND THE SOFTWARE DESCRIBED HEREIN ARE FURNISHED UNDER A LICENSE, AND MAY BE USED AND COPIED ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE AND WITH THE INCLUSION OF THE ABOVE COPYRIGHT NOTICE. TITLE TO AND OWNERSHIP OF THE DOCUMENT AND SOFTWARE REMAIN WITH THE OPEN GROUP OR ITS LICENSORS. Certain portions of CDE known as "PBMPlus" are copyrighted © 1989, 1991 by Jef Poskanzer. Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appears in all copies and that both the copyright notice and this permission notice appears in supporting documentation. This software is provided "as is" without express or implied warranty. The code and documentation for the DtComboBox and DtSpinBox widgets were contributed by Interleaf, Inc. Copyright © 1993, Interleaf, Inc. FOR U.S. GOVERNMENT CUSTOMERS REGARDING THIS DOCUMENTATION AND THE ASSOCIATED SOFTWARE These notices shall be marked on any reproduction of this data, in whole or in part. NOTICE:Notwithstanding any other lease or license that may pertain to, or accompany the delivery of, this computer software, the rights of the Government regarding its use, reproduction and disclosure are as set forth in Section 52.227-19 of the FARS Computer Software-Restricted Rights clause. RESTRICTED RIGHTS NOTICE:Use, duplication, or disclosure by the Government is subject to the restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 52.227-7013. RESTRICTED RIGHTS LEGEND:Use, duplication or disclosure by the Government is subject to restrictions as set forth in paragraph (b)(3)(B) of the rights in Technical Data and Computer Software clause in DAR 7-104.9(a). This computer software is submitted with "restricted rights." Use, duplication or disclosure is subject to the restrictions as set forth in NASA FAR SUP 18-52.227-79 (April 1985) "Commercial Computer Software-Restricted Rights (April 1985)." If the contract contains the Clause at 18-52.227-74 "Rights in Data General" then the "Alternate III" clause applies. US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract. Unpublished - All rights reserved under the Copyright Laws of the United States. This notice shall be marked on any reproduction of this data, in whole or in part. Contents Preface .................... xv The Open Group ............ xv The Development of Product Standards ....... xvi Open Group Publications .......... xvii Versions and Issues of Specifications ....... xix Corrigenda .............. xix Ordering Information ........... xix This Book .............. xx Audience .............. xx Applicability ............. xx Purpose ............... xx Organization ............. xxi Related Documents ............ xxii Typographic and Keying Conventions ....... xxiii DocBook SGML Conventions ....... xxiv Terminology Conventions ........ xxiv Keyboard Conventions ......... xxiv Mouse Conventions ......... xxv Problem Reporting ............ xxv Trademarks .............. xxv Chapter 1. Introduction................ 1 1.1 The X Window System ........... 2 1.2 Xlib, Xt, and Motif ............ 5 1.2.1 Xlib ............. 5 1.2.2 Xt .............. 6 i MOTIF 2.1—Programmer’s Guide 1.2.3 Motif ............. 10 1.2.4 Using Xlib, Xt, and Motif ........ 14 1.3 Widget Classes and Hierarchy ......... 15 1.3.1 Xt Classes ............ 15 1.3.2 Motif Classes ........... 16 1.4 Header Files and Libraries .......... 20 Chapter 2. The Motif Programming Model ........... 23 2.1 A User-Centered Model ........... 24 2.2 Separating Interface from Application ....... 27 2.3 Building Blocks: Primitive Widgets and Gadgets .... 28 2.3.1 Label and Separator ......... 29 2.3.2 Buttons ............ 29 2.3.3 ScrollBar ............ 30 2.3.4 List ............. 30 2.3.5 Text ............. 31 2.4 Managers .............. 31 2.4.1 Frame ............. 32 2.4.2 Scale ............. 32 2.4.3 PanedWindow ........... 32 2.4.4 ScrolledWindow and MainWindow ...... 33 2.4.5 RowColumn ........... 34 2.4.6 BulletinBoard, Form, MessageBox, SelectionBox .. 34 2.4.7 DrawingArea ........... 35 2.4.8 ComboBox ........... 36 2.4.9 Spin Boxes ........... 36 2.4.10 Container ............ 37 2.4.11 Notebook ............ 37 2.5 Shells ............... 37 2.5.1 VendorShell ........... 38 2.5.2 DialogShell ........... 38 2.5.3 MenuShell ............ 39 2.6 Applications, Top-Level Widgets, and Dialogs ..... 39 2.6.1 Applications ........... 40 2.6.2 Top-Level Widgets .......... 41 2.6.3 Dialogs ............ 41 2.7 Resources: User and Program Customization ..... 42 2.8 Handling Input and Output .......... 43 Chapter 3. Structure of a Motif Program ........... 45 ii Contents 3.1 Including Header Files ........... 46 3.2 Initializing the Intrinsics........... 47 3.2.1 The Initial Resource Database ....... 48 3.3 Creating Widgets ............ 53 3.3.1 Setting Resources during Widget Initialization ... 54 3.3.2 Arguments that Specify Resource Values .... 55 3.3.3 Setting Resource Values ........ 56 3.3.4 Retrieving Resource Values ....... 56 3.3.5 Resource Value Data Types ....... 57 3.3.6 Resource Values and Memory Management ... 58 3.4 Adding Callback Procedures ......... 59 3.5 Making Widgets Visible........... 62 3.5.1 Managing Widgets .......... 62 3.5.2 Realizing Widgets .......... 63 3.5.3 Mapping Widgets .......... 64 3.5.4 Multiple Screens, Displays, and Applications ... 64 3.6 Entering the Event Loop .......... 66 3.7 Writing Threaded Applications ......... 66 3.7.1 Why Multithreading? ......... 67 3.7.2 Input Processing Loop ......... 67 3.7.3 Xt Interfaces For Multithreading ...... 68 3.7.4 Initializing Xt For Use In Multiple Threads ... 68 3.7.5 Using XtAppLock and XtAppUnlock ..... 69 3.7.6 New XtAppMainLoop ......... 70 3.7.7 Destroying An Application Context ..... 71 3.7.8 Event Management In Multiple Threads .... 71 Chapter 4. Structure of a Program Using UIL and MRM ....... 73 4.1 Structure of a UIL Module .......... 75 4.1.1 The module Clause ......... 75 4.1.2 Module-Level Declarations........ 75 4.1.3 The include Directive ......... 76 4.1.4 The value Declaration ......... 77 4.1.5 The identifier Declaration ........ 78 4.1.6 The procedure Declaration ........ 78 4.1.7 The object Declaration ......... 78 4.1.8 The list Declaration ......... 82 4.1.9 The end module Clause ........ 84 4.2 Structure of a Program Using MRM........ 85 4.2.1 Including Header Files ......... 85 4.2.2 Initializing the Intrinsics ........ 85 iii MOTIF 2.1—Programmer’s Guide 4.2.3 Initializing MRM .......... 85 4.2.4 Opening UID Files.......... 86 4.2.5 Registering Callbacks and Identifiers ..... 87 4.2.6 Fetching Information from UID Files ..... 88 4.2.7 Closing the UID File ......... 90 4.2.8 Defining Callback Procedures ....... 90 4.2.9 Making Widgets Visible ........ 91 4.2.10 Entering the Event Loop ........ 92 Chapter 5. Basic Controls ............... 93 5.1 Core, RectObj, XmPrimitive, and XmGadget Classes ... 94 5.1.1 Core ............. 94 5.1.2 RectObj ............ 94 5.1.3 XmPrimitive ........... 95 5.1.4 XmGadget ............ 95 5.2 Labels, Buttons, and Separators ......... 96 5.2.1 Labels ............. 96 5.2.2 Buttons ............ 97 5.2.3 Separators ............ 100 5.3 ScrollBar .............. 100 5.4 Scale ............... 102 5.4.1 Drag and Drop in Scale ........ 103 5.4.2 Visuals Inside a Scale ......... 103 5.4.3 Tic Marks ............ 104 5.5 List ................ 104 5.6 Text and TextField ............ 106 Chapter 6. Menus and Options .............. 107 6.1 Menu Components: Buttons, RowColumn, MenuShell ... 109 6.1.1 Buttons ............ 109 6.1.2 RowColumn ........... 110 6.1.3 MenuShell ............ 111 6.2 MenuBar .............. 112 6.3 PopupMenu .............. 112 6.4 PulldownMenu ............. 114 6.5 OptionMenu ............. 115 6.6 RadioBox and CheckBox .......... 117 6.7 TearOffMenus ............. 118 iv Contents 6.8 ComboBox .............. 119 6.8.1 ComboBox Types .......... 120 6.8.2 Creating and Manipulating ComboBox ..... 120 6.8.3 ComboBox Items .......... 122 6.8.4 Controlling the Arrow ......... 123 6.8.5 ComboBox Matching Behavior....... 124