MOTIF 2.1—Widget Writer’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—Widget Writer’s Guide ISBN 1-85912-129-2 Document Number M216 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 .................... xvii The Open Group ............ xvii The Development of Product Standards ....... xviii Open Group Publications .......... xix Versions and Issues of Specifications ....... xxi Corrigenda .............. xxi Ordering Information ........... xxi This Book .............. xxii Audience .............. xxii Applicability ............. xxii Purpose ............... xxii Organization ............. xxiii Related Documents ............ xxiv Typographic and Keying Conventions ....... xxv DocBook SGML Conventions ....... xxv Terminology Conventions ........ xxvi Keyboard Conventions ......... xxvi Mouse Conventions ......... xxvii Problem Reporting ............ xxvii Trademarks .............. xxvii Part 1. Widget Writer’s Guide Chapter 1. What Is Involved in Writing a Motif Widget ....... 3 1.1 Pros and Cons of Writing a Motif Widget ...... 3 MOTIF 2.1—Widget Writer’s Guide i Contents 1.2 Prerequisite Knowledge ........... 4 1.3 The Software You Will Need ......... 5 1.4 What Kinds of Widgets Can You Create? ...... 6 1.5 How Much Work Is Involved? ......... 7 1.6 Defining the Goal ............ 7 Chapter 2. A Motif Widget Writing Tutorial .......... 9 2.1 Namespace .............. 9 2.2 Recommended Files for Each Widget ....... 10 2.3 The Widget Public Header File ......... 11 2.3.1 Step 1: Ensure That the File Is Included Only Once ............. 11 2.3.2 Step 2: Include the Appropriate Header Files ... 12 2.3.3 Step 3: Allow for C++ Compilation ..... 12 2.3.4 Step 4: Specify Widget Class Names ..... 13 2.3.5 Step 5: Define String Equivalents of New Resource Names .......... 13 2.3.6 Step 6: Specify the API for This Widget .... 14 2.4 The Widget Private Header File ......... 14 2.4.1 Step 1: Ensure That the File is Included Only Once ............. 15 2.4.2 Step 2: Include the Appropriate Header Files ... 16 2.4.3 Step 3: Allow for C++ Compilation ..... 16 2.4.4 Step 4: Define Inheritable Methods...... 16 2.4.5 Step 5: Define the Widget Class Part ..... 17 2.4.6 Step 6: Declare the Full Class Record ..... 18 2.4.7 Step 7: Define the Widget Instance Part .... 19 2.4.8 Step 8: Declare the Full Widget Instance Record .. 20 2.4.9 Step 9 (Optional): Declare Constraints Structures .. 21 2.4.10 Step 10 (Optional): Declaring Private Functions .. 22 2.5 The Widget Source Code File ......... 23 2.5.1 Step 1: Include the Appropriate Header Files ... 23 2.5.2 Step 2 (Optional): Define Your Macros..... 25 2.5.3 Step 3: Declare All static Functions ..... 25 2.5.4 Step 4: Define Translations and Actions .... 26 2.5.5 Step 5: Declare Resources ........ 26 2.5.6 Step 6: Declare the Class Record ...... 27 2.5.7 Step 7: Provide the External Definitions .... 28 2.5.8 Step 8: Declare Any Static Variables ..... 28 2.5.9 Step 9: Declare Any Trait Record Variables ... 29 ii MOTIF 2.1—Widget Writer’s Guide Contents 2.5.10 Step 10: Write the Widget’s Methods ..... 29 2.6 Make the Widget Accessible to Applications ..... 31 2.7 MultiThread-Safe Motif Widgets ........ 32 2.7.1 MT-Safety in the Xt Intrinsics ....... 32 2.7.2 MT-Safe Motif Widgets ........ 34 2.7.3 MT-Safe C Library Functions ....... 40 2.7.4 MT-Safe Motif Library Functions ...... 40 2.7.5 Thread Specific Storage ........ 40 2.7.6 Live Resources .......... 41 2.7.7 CheckList ............ 41 Chapter 3. The Widget Class Record of Primitive Widgets ....... 43 3.1 The CoreClassPart Structure.......... 45 3.1.1 The superclass Field ......... 46 3.1.2 The class_name Field ......... 46 3.1.3 The widget_size Field ......... 47 3.1.4 The class_initialize Field ........ 47 3.1.5 The class_part_initialize Field (Chained) .... 47 3.1.6 The class_inited Field ......... 49 3.1.7 The initialize Field (Chained) ....... 49 3.1.8 The initialize_hook Field (Chained) ..... 50 3.1.9 The realize Field .......... 50 3.1.10 The actions Field .......... 51 3.1.11 The num_actions Field......... 51 3.1.12 The resources Field ......... 52 3.1.13 The num_resources Field ........ 52 3.1.14 The xrm_class Field ......... 52 3.1.15 The compress_motion Field ....... 52 3.1.16 The compress_exposure Field ....... 53 3.1.17 The compress_enterleave Field ....... 53 3.1.18 The visible_interest Field ........ 53 3.1.19 The destroy Field (Chained) ....... 53 3.1.20 The resize Field .......... 54 3.1.21 The expose (Redisplay) Field ....... 54 3.1.22 The set_values Field (Chained)....... 56 3.1.23 The set_values_hook Field (Chained) ..... 57 3.1.24 The set_values_almost Field ....... 57 3.1.25 The get_values_hook Field (Chained) ..... 58 3.1.26 The accept_focus Field......... 58 3.1.27 The version Field .......... 58 3.1.28 The callback_private Field ........ 59 3.1.29 The tm_table Field.......... 59 MOTIF 2.1—Widget Writer’s Guide iii Contents 3.1.30 The query_geometry Field ........ 59 3.1.31 The display_accelerator Field ....... 60 3.1.32 The Base Class extension Field ...... 60 3.2 The PrimitiveClassPart Structure ........ 60 3.2.1 The border_highlight Field ........ 60 3.2.2 The border_unhighlight Field ....... 61 3.2.3 The translations Field ......... 63 3.2.4 The arm_and_activate Field ....... 63 3.2.5 The syn_resources Field ........ 65 3.2.6 The num_syn_resources Field ....... 65 3.2.7 The extension Field ......... 65 3.3 The Primitive Class Extension Record ....... 66 3.3.1 The next_extension Field ........ 66 3.3.2 The record_type Field ......... 66 3.3.3 The version Field .......... 66 3.3.4 The record_size Field ......... 67 3.3.5 The widget_baseline Field ........ 67 3.3.6 The widget_display_rect Field ....... 68 3.3.7 The widget_margins Method ....... 69 3.4 The Instance Data Members of XmPrimitive...... 70 3.4.1 The primitive.have_traversal Field ...... 70 3.4.2 The primitive.highlighted Field....... 70 3.4.3 The primitive.highlight_GC Field ...... 71 3.4.4 The primitive.top_shadow_GC Field ..... 71 3.4.5 The primitive.bottom_shadow_GC Field .... 72 Chapter 4. The Widget Class Record of Manager Widgets ....... 75 4.1 The CoreClassPart Structure.......... 77 4.1.1 The superclass Field ......... 78 4.1.2 The class_name Field ......... 78 4.1.3 The widget_size Field ......... 79 4.1.4 The class_initialize Field .......