1mX Toolkit Intrinsics -- C Language Interface0m 1mX Window System0m 1mX Version 11, Release 6.40m First Revision - April, 1994 Joel McCormack Digital Equipment Corporation Western Software Laboratory Paul Asente Digital Equipment Corporation Western Software Laboratory Ralph R. Swick Digital Equipment Corporation External Research Group MIT X Consortium version 6 edited by Donna Converse X Consortium, Inc. X Window System is a trademark of X Consortium, Inc. Copyright © 1985, 1986, 1987, 1988, 1991, 1994 X Consortium Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documenta- tion files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PUR- POSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE X CONSOR- TIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. Except as contained in this notice, the name of the X Con- sortium shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization from the X Consortium. Copyright © 1985, 1986, 1987, 1988, 1991, 1994 Digital Equipment Corporation, Maynard, Massachusetts. Permission to use, copy, modify and distribute this documen- tation for any purpose and without fee is hereby granted, provided that the above copyright notice appears in all copies and that both that copyright notice and this permis- sion notice appear in supporting documentation, and that the name of Digital not be used in in advertising or publicity pertaining to distribution of the software without specific, written prior permission. Digital makes no representations about the suitability of the software described herein for any purpose. It is provided ``as is'' without express or implied warranty. 1mAcknowledgments0m The design of the X11 Intrinsics was done primarily by Joel McCormack of Digital WSL. Major contributions to the design and implementation also were done by Charles Haynes, Mike Chow, and Paul Asente of Digital WSL. Additional contribu- tors to the design and/or implementation were: Loretta Guarino-Reid (Digital WSL)Rich Hyde (Digital WSL) Susan Angebranndt (Digital WSL)Terry Weissman (Digital WSL) Mary Larson (Digital UEG) Mark Manasse (Digital SRC) Jim Gettys (Digital SRC) Leo Treggiari (Digital SDT) Ralph Swick (Project Athena and Digital ERP)Mark Ackerman (Project Athena) Ron Newman (Project Athena) Bob Scheifler (MIT LCS) The contributors to the X10 toolkit also deserve mention. Although the X11 Intrinsics present an entirely different programming style, they borrow heavily from the implicit and explicit concepts in the X10 toolkit. The design and implementation of the X10 Intrinsics were done by: Terry Weissman (Digital WSL) Smokey Wallace (Digital WSL) Phil Karlton (Digital WSL) Charles Haynes (Digital WSL) Frank Hall (HP) The design and implementation of the X10 toolkit's sample widgets were by the above, as well as by: Ram Rao (Digital UEG) Mary Larson (Digital UEG) Mike Gancarz (Digital UEG) Kathleen Langone (Digital UEG) These widgets provided a checklist of requirements that we had to address in the X11 Intrinsics. Thanks go to Al Mento of Digital's UEG Documentation Group for formatting and generally improving this document and to John Ousterhout of Berkeley for extensively reviewing early drafts of it. 1mxi0m Finally, a special thanks to Mike Chow, whose extensive per- formance analysis of the X10 toolkit provided the justifica- tion to redesign it entirely for X11. Joel McCormack Western Software Laboratory Digital Equipment Corporation March 1988 1mxii0m The current design of the Intrinsics has benefited greatly from the input of several dedicated reviewers in the member- ship of the X Consortium. In addition to those already men- tioned, the following individuals have dedicated significant time to suggesting improvements to the Intrinsics: Steve Pitschke (Stellar) C. Doug Blewett (AT&T) Bob Miller (HP) David Schiferl (Tektronix) Fred Taft (HP) Michael Squires (Sequent) Marcel Meth (AT&T) Jim Fulton (MIT) Mike Collins (Digital) Kerry Kimbrough (Texas Instruments) Scott McGregor (Digital) Phil Karlton (Digital) Julian Payne (ESS) Jacques Davy (Bull) Gabriel Beged-Dov (HP) Glenn Widener (Tektronix) Thanks go to each of them for the countless hours spent reviewing drafts and code. Ralph R. Swick External Research Group Digital Equipment Corporation MIT Project Athena June 1988 From Release 3 to Release 4, several new members joined the design team. We greatly appreciate the thoughtful comments, suggestions, lengthy discussions, and in some cases imple- mentation code contributed by each of the following: Don Alecci (AT&T) Ellis Cohen (OSF) Donna Converse (MIT) Clive Feather (IXI) Nayeem Islam (Sun) Dana Laursen (HP) Keith Packard (MIT) Chris Peterson (MIT) Richard Probst (Sun) Larry Cable (Sun) In Release 5, the effort to define the internationalization additions was headed by Bill McMahon of Hewlett Packard and Frank Rojas of IBM. This has been an educational process for many of us, and Bill and Frank's tutelage has carried us through. Vania Joloboff of the OSF also contributed to the internationalization additions. The implementation efforts of Bill, Gabe Beged-Dov, and especially Donna Converse for this release are also gratefully acknowledged. 1mxiii0m Ralph R. Swick December 1989 and July 1991 1mxiv0m The Release 6 Intrinsics is a result of the collaborative efforts of participants in the X Consortium's 1mintrinsics0m working group. A few individuals contributed substantial design proposals, participated in lengthy discussions, reviewed final specifications, and in most cases, were also responsible for sections of the implementation. They deserve recognition and thanks for their major contribu- tions: Paul Asente (Adobe) Larry Cable (SunSoft) Ellis Cohen (OSF) Daniel Dardailler (OSF) Vania Joloboff (OSF) Kaleb Keithley (X Consortium) Courtney Loomis (HP) Douglas Rand (OSF) Bob Scheifler (X Consortium) Ajay Vohra (SunSoft) Many others analyzed designs, offered useful comments and suggestions, and participated in a significant subset of the process. The following people deserve thanks for their con- tributions: Andy Bovingdon, Sam Chang, Chris Craig, George Erwin-Grotsky, Keith Edwards, Clive Feather, Stephen Gildea, Dan Heller, Steve Humphrey, David Kaelbling, Jaime Lau, Rob Lembree, Stuart Marks, Beth Mynatt, Tom Paquin, Chris Peter- son, Kamesh Ramakrishna, Tom Rodriguez, Jim VanGilder, Will Walker, and Mike Wexler. I am especially grateful to two of my colleagues: Ralph Swick for expert editorial guidance, and Kaleb Keithley for leadership in the implementation and the specification work. Donna Converse X Consortium April 1994 1mxv0m 1mAbout This Manual0m 4mX24m 4mToolkit24m 4mIntrinsics24m 4m--24m 4mC24m 4mLanguage24m 4mInterface24m is intended to be read by both application programmers who will use one or more of the many widget sets built with the Intrinsics and by widget programmers who will use the Intrinsics to build widgets for one of the widget sets. Not all the information in this manual, however, applies to both audiences. That is, because the application programmer is likely to use only a number of the Intrinsics functions in writing an applica- tion and because the widget programmer is likely to use many more, if not all, of the Intrinsics functions in building a widget, an attempt has been made to highlight those areas of information that are deemed to be of special interest for the application programmer. (It is assumed the widget pro- grammer will have to be familiar with all the information.) Therefore, all entries in the table of contents that are printed in 1mbold 22mindicate the information that should be of special interest to an application programmer. It is also assumed that, as application programmers become more familiar with the concepts discussed in this manual, they will find it more convenient to implement portions of their applications as special-purpose or custom widgets. It is possible, nonetheless, to use widgets without knowing how to build them. 1mConventions Used in this Manual0m This document uses the following conventions: · Global symbols are printed in 4mthis24m 4mspecial24m 4mfont24m. These can be either function names, symbols defined in include files, data types, or structure names. Argu- ments to functions, procedures, or macros are printed in 4mitalics24m. · Each function is introduced by a general discussion that distinguishes it from other functions. The func- tion declaration itself follows, and each argument is specifically explained. General discussion of the function, if any is required, follows the arguments. · To eliminate any ambiguity between those arguments that you pass and those that a function returns to you, the explanations for all arguments that you pass start with the word 4mspecifies24m or, in the case of multiple argu- ments, the word 4mspecify24m. The explanations for all arguments that are returned to you start with the word 4mreturns24m or, in the case of multiple arguments, the word 1mxvi0m 4mreturn24m. 1mxvii0m 1mChapter 10m 1mIntrinsics and Widgets0m The Intrinsics are a programming library tailored to the special requirements of user interface construction within a network window system, specifically the X Window System. The Intrinsics and a widget set make up an X Toolkit. 1m1.1. Intrinsics0m The Intrinsics provide the base mechanism necessary to build a wide variety of interoperating widget sets and application environments. The Intrinsics are a layer on top of Xlib, the C Library X Interface. They extend the fundamental abstractions provided by the X Window System while still remaining independent of any particular user interface pol- icy or style. The Intrinsics use object-oriented programming techniques to supply a consistent architecture for constructing and com- posing user interface components, known as widgets. This allows programmers to extend a widget set in new ways, either by deriving new widgets from existing ones (subclass- ing) or by writing entirely new widgets following the estab- lished conventions. When the Intrinsics were first conceived, the root of the object hierarchy was a widget class named Core. In Release 4 of the Intrinsics, three nonwidget superclasses were added above Core. These superclasses are described in Chapter 12. The name of the class now at the root of the Intrinsics class hierarchy is Object. The remainder of this specifica- tion refers uniformly to 4mwidgets24m and 4mCore24m as if they were the base class for all Intrinsics operations. The argument descriptions for each Intrinsics procedure and Chapter 12 describe which operations are defined for the nonwidget superclasses of Core. The reader may determine by context whether a specific reference to 4mwidget24m actually means ``wid- get'' or ``object.'' 1m1.2. Languages0m The Intrinsics are intended to be used for two programming purposes. Programmers writing widgets will be using most of the facilities provided by the Intrinsics to construct user interface components from the simple, such as buttons and scrollbars, to the complex, such as control panels and 1m10m 1mX Toolkit Intrinsics X11 Release 6.40m property sheets. Application programmers will use a much smaller subset of the Intrinsics procedures in combination with one or more sets of widgets to construct and present complete user interfaces on an X display. The Intrinsics programming interfaces primarily intended for application use are designed to be callable from most procedural pro- gramming languages. Therefore, most arguments are passed by reference rather than by value. The interfaces primarily intended for widget programmers are expected to be used principally from the C language. In these cases, the usual C programming conventions apply. In this specification, the term 4mclient24m refers to any module, widget, or application that calls an Intrinsics procedure. Applications that use the Intrinsics mechanisms must include the header files <4mX11/Intrinsic.h24m> and <4mX11/StringDefs.h24m>, or their equivalent, and they may also include <4mX11/Xatoms.h24m> and <4mX11/Shell.h24m>. In addition, widget implementations should include <4mX11/IntrinsicP.h24m> instead of <4mX11/Intrinsic.h24m>. The applications must also include the additional header files for each widget class that they are to use (for exam- ple, <4mX11/Xaw/Label.h24m> or <4mX11/Xaw/Scrollbar.h24m>). On a POSIX-based system, the Intrinsics object library file is named 4mlibXt.a24m and is usually referenced as -lXt when linking the application. 1m1.3. Procedures and Macros0m All functions defined in this specification except those specified below may be implemented as C macros with argu- ments. C applications may use ``#undef'' to remove a macro definition and ensure that the actual function is refer- enced. Any such macro will expand to a single expression that has the same precedence as a function call and that evaluates each of its arguments exactly once, fully pro- tected by parentheses, so that arbitrary expressions may be used as arguments. The following symbols are macros that do not have function equivalents and that may expand their arguments in a manner other than that described above: 4mXtCheckSubclass24m, 4mXtNew24m, 4mXtNumber24m, 4mXtOffsetOf24m, 4mXtOffset24m, and 4mXtSetArg24m. 1m1.4. Widgets0m The fundamental abstraction and data type of the X Toolkit is the widget, which is a combination of an X window and its associated input and display semantics and which is dynami- cally allocated and contains state information. Some 1m20m 1mX Toolkit Intrinsics X11 Release 6.40m widgets display information (for example, text or graphics), and others are merely containers for other widgets (for example, a menu box). Some widgets are output-only and do not react to pointer or keyboard input, and others change their display in response to input and can invoke functions that an application has attached to them. Every widget belongs to exactly one widget class, which is statically allocated and initialized and which contains the operations allowable on widgets of that class. Logically, a widget class is the procedures and data associated with all widgets belonging to that class. These procedures and data can be inherited by subclasses. Physically, a widget class is a pointer to a structure. The contents of this structure are constant for all widgets of the widget class but will vary from class to class. (Here, ``constant'' means the class structure is initialized at compile time and never changed, except for a one-time class initialization and in- place compilation of resource lists, which takes place when the first widget of the class or subclass is created.) For further information, see Section 2.5. The distribution of the declarations and code for a new wid- get class among a public .h file for application programmer use, a private .h file for widget programmer use, and the implementation .c file is described in Section 1.6. The predefined widget classes adhere to these conventions. A widget instance is composed of two parts: · A data structure which contains instance-specific val- ues. · A class structure which contains information that is applicable to all widgets of that class. Much of the input/output of a widget (for example, fonts, colors, sizes, or border widths) is customizable by users. This chapter discusses the base widget classes, Core, Com- posite, and Constraint, and ends with a discussion of widget classing. 1m1.4.1. Core Widgets0m The Core widget class contains the definitions of fields common to all widgets. All widgets classes are subclasses of the Core class, which is defined by the 4mCoreClassPart24m and 4mCorePart24m structures. 1m30m 1mX Toolkit Intrinsics X11 Release 6.40m 1m1.4.1.1. CoreClassPart Structure0m All widget classes contain the fields defined in the 4mCore-0m 4mClassPart24m structure. __ | typedef struct { WidgetClass superclass; See Section 1.6 String class_name; See Chapter 9 Cardinal widget_size; See Section 1.6 XtProc class_initialize; See Section 1.6 XtWidgetClassProc class_part_initialize;See Section 1.6 XtEnum class_inited; See Section 1.6 XtInitProc initialize; See Section 2.5 XtArgsProc initialize_hook; See Section 2.5 XtRealizeProc realize; See Section 2.6 XtActionList actions; See Chapter 10 Cardinal num_actions; See Chapter 10 XtResourceList resources; See Chapter 9 Cardinal num_resources; See Chapter 9 XrmClass xrm_class; Private to resource manager Boolean compress_motion; See Section 7.9 XtEnum compress_exposure; See Section 7.9 Boolean compress_enterleave; See Section 7.9 Boolean visible_interest; See Section 7.10 XtWidgetProc destroy; See Section 2.8 XtWidgetProc resize; See Chapter 6 XtExposeProc expose; See Section 7.10 XtSetValuesFunc set_values; See Section 9.7 XtArgsFunc set_values_hook; See Section 9.7 XtAlmostProc set_values_almost;See Section 9.7 XtArgsProc get_values_hook; See Section 9.7 XtAcceptFocusProc accept_focus;See Section 7.3 XtVersionType version; See Section 1.6 XtPointer callback_private; Private to callbacks String tm_table; See Chapter 10 XtGeometryHandler query_geometry;See Chapter 6 XtStringProc display_accelerator;See Chapter 10 XtPointer extension; See Section 1.6 } CoreClassPart; |__ All widget classes have the Core class fields as their first component. The prototypical 4mWidgetClass24m and 4mCoreWidgetClass0m are defined with only this set of fields. 1m40m 1mX Toolkit Intrinsics X11 Release 6.40m __ | typedef struct { CoreClassPart core_class; } WidgetClassRec, *WidgetClass, CoreClassRec, *CoreWidgetClass; |__ Various routines can cast widget class pointers, as needed, to specific widget class types. The single occurrences of the class record and pointer for creating instances of Core are In 4mIntrinsicP.h24m: __ | extern WidgetClassRec widgetClassRec; #define coreClassRec widgetClassRec |__ In 4mIntrinsic.h24m: __ | extern WidgetClass widgetClass, coreWidgetClass; |__ The opaque types 4mWidget24m and 4mWidgetClass24m and the opaque vari- able 4mwidgetClass24m are defined for generic actions on widgets. In order to make these types opaque and ensure that the com- piler does not allow applications to access private data, the Intrinsics use incomplete structure definitions in 4mIntrinsic.h24m: __ | typedef struct _WidgetClassRec *WidgetClass, *CoreWidgetClass; |__ 1m1.4.1.2. CorePart Structure0m All widget instances contain the fields defined in the 4mCorePart24m structure. 1m50m 1mX Toolkit Intrinsics X11 Release 6.40m __ | typedef struct _CorePart { Widget self; Described below WidgetClass widget_class;See Section 1.6 Widget parent; See Section 2.5 Boolean being_destroyed; See Section 2.8 XtCallbackList destroy_callbacks;See Section 2.8 XtPointer constraints; See Section 3.6 Position x; See Chapter 6 Position y; See Chapter 6 Dimension width; See Chapter 6 Dimension height; See Chapter 6 Dimension border_width; See Chapter 6 Boolean managed; See Chapter 3 Boolean sensitive; See Section 7.7 Boolean ancestor_sensitive;See Section 7.7 XtTranslations accelerators;See Chapter 10 Pixel border_pixel; See Section 2.6 Pixmap border_pixmap; See Section 2.6 WidgetList popup_list; See Chapter 5 Cardinal num_popups; See Chapter 5 String name; See Chapter 9 Screen *screen; See Section 2.6 Colormap colormap; See Section 2.6 Window window; See Section 2.6 Cardinal depth; See Section 2.6 Pixel background_pixel; See Section 2.6 Pixmap background_pixmap;See Section 2.6 Boolean visible; See Section 7.10 Boolean mapped_when_managed;See Chapter 3 } CorePart; |__ All widget instances have the Core fields as their first component. The prototypical type 4mWidget24m is defined with only this set of fields. __ | typedef struct { CorePart core; } WidgetRec, *Widget, CoreRec, *CoreWidget; |__ Various routines can cast widget pointers, as needed, to specific widget types. In order to make these types opaque and ensure that the com- piler does not allow applications to access private data, the Intrinsics use incomplete structure definitions in 4mIntrinsic.h24m. 1m60m 1mX Toolkit Intrinsics X11 Release 6.40m __ | typedef struct _WidgetRec *Widget, *CoreWidget; |__ 1m1.4.1.3. Core Resources0m The resource names, classes, and representation types speci- fied in the 4mcoreClassRec24m resource list are ------------------------------------------------------------------------ Name Class Representation ------------------------------------------------------------------------ XtNaccelerators XtCAccelerators XtRAcceleratorTable XtNbackground XtCBackground XtRPixel XtNbackgroundPixmap XtCPixmap XtRPixmap XtNborderColor XtCBorderColor XtRPixel XtNborderPixmap XtCPixmap XtRPixmap XtNcolormap XtCColormap XtRColormap XtNdepth XtCDepth XtRInt XtNmappedWhenManaged XtCMappedWhenManaged XtRBoolean XtNscreen XtCScreen XtRScreen XtNtranslations XtCTranslations XtRTranslationTable ------------------------------------------------------------------------ Additional resources are defined for all widgets via the 4mobjectClassRec24m and 4mrectObjClassRec24m resource lists; see Sec- tions 12.2 and 12.3 for details. 1m1.4.1.4. CorePart Default Values0m The default values for the Core fields, which are filled in by the Intrinsics, from the resource lists, and by the ini- tialize procedures, are ------------------------------------------------------------------------------ Field Default Value ------------------------------------------------------------------------------ self Address of the widget structure (may not be changed). widget_class 4mwidget_class24m argument to 4mXtCreateWidget24m (may not be changed). parent 4mparent24m argument to 4mXtCreateWidget24m (may not be changed). being_destroyed Parent's 4mbeing_destroyed24m value. destroy_callbacks NULL constraints NULL x 0 y 0 1m70m 1mX Toolkit Intrinsics X11 Release 6.40m width 0 height 0 border_width 1 managed 4mFalse0m sensitive 4mTrue0m ancestor_sensitive logical AND of parent's 4msensitive24m and 4mancestor_sensitive0m values. accelerators NULL border_pixel 4mXtDefaultForeground0m border_pixmap 4mXtUnspecifiedPixmap0m popup_list NULL num_popups 0 name 4mname24m argument to 4mXtCreateWidget24m (may not be changed). screen Parent's 4mscreen24m; top-level widget gets screen from dis- play specifier (may not be changed). colormap Parent's 4mcolormap24m value. window NULL depth Parent's 4mdepth24m; top-level widget gets root window depth. background_pixel 4mXtDefaultBackground0m background_pixmap 4mXtUnspecifiedPixmap0m visible 4mTrue0m mapped_when_man- 4mTrue0m aged ------------------------------------------------------------------------------ 4mXtUnspecifiedPixmap24m is a symbolic constant guaranteed to be unequal to any valid Pixmap id, 4mNone24m, and 4mParentRelative24m. 1m1.4.2. Composite Widgets0m The Composite widget class is a subclass of the Core widget class (see Chapter 3). Composite widgets are intended to be containers for other widgets. The additional data used by composite widgets are defined by the 4mCompositeClassPart24m and 4mCompositePart24m structures. 1m1.4.2.1. CompositeClassPart Structure0m In addition to the Core class fields, widgets of the Compos- ite class have the following class fields. 1m80m 1mX Toolkit Intrinsics X11 Release 6.40m __ | typedef struct { XtGeometryHandler geometry_manager;See Chapter 6 XtWidgetProc change_managed; See Chapter 3 XtWidgetProc insert_child; See Chapter 3 XtWidgetProc delete_child; See Chapter 3 XtPointer extension; See Section 1.6 } CompositeClassPart; |__ The extension record defined for 4mCompositeClassPart24m with 4mrecord_type24m equal to 4mNULLQUARK24m is 4mCompositeClassExtension-0m 4mRec24m. __ | typedef struct { XtPointer next_extension; See Section 1.6.12 XrmQuark record_type; See Section 1.6.12 long version; See Section 1.6.12 Cardinal record_size; See Section 1.6.12 Boolean accepts_objects; See Section 2.5.2 Boolean allows_change_managed_set;See Section 3.4.3 } CompositeClassExtensionRec, *CompositeClassExtension; |__ Composite classes have the Composite class fields immedi- ately following the Core class fields. __ | typedef struct { CoreClassPart core_class; CompositeClassPart composite_class; } CompositeClassRec, *CompositeWidgetClass; |__ The single occurrences of the class record and pointer for creating instances of Composite are In 4mIntrinsicP.h24m: __ | extern CompositeClassRec compositeClassRec; |__ In 4mIntrinsic.h24m: 1m90m 1mX Toolkit Intrinsics X11 Release 6.40m __ | extern WidgetClass compositeWidgetClass; |__ The opaque types 4mCompositeWidget24m and 4mCompositeWidgetClass0m and the opaque variable 4mcompositeWidgetClass24m are defined for generic operations on widgets whose class is Composite or a subclass of Composite. The symbolic constant for the 4mCom-0m 4mpositeClassExtension24m version identifier is 4mXtCompositeExten-0m 4msionVersion24m (see Section 1.6.12). 4mIntrinsic.h24m uses an incomplete structure definition to ensure that the compiler catches attempts to access private data. __ | typedef struct _CompositeClassRec *CompositeWidgetClass; |__ 1m1.4.2.2. CompositePart Structure0m In addition to the Core instance fields, widgets of the Com- posite class have the following instance fields defined in the 4mCompositePart24m structure. __ | typedef struct { WidgetList children; See Chapter 3 Cardinal num_children; See Chapter 3 Cardinal num_slots; See Chapter 3 XtOrderProc insert_position;See Section 3.2 } CompositePart; |__ Composite widgets have the Composite instance fields immedi- ately following the Core instance fields. __ | typedef struct { CorePart core; CompositePart composite; } CompositeRec, *CompositeWidget; |__ 4mIntrinsic.h24m uses an incomplete structure definition to ensure that the compiler catches attempts to access private data. 1m100m 1mX Toolkit Intrinsics X11 Release 6.40m __ | typedef struct _CompositeRec *CompositeWidget; |__ 1m1.4.2.3. Composite Resources0m The resource names, classes, and representation types that are specified in the 4mcompositeClassRec24m resource list are ------------------------------------------------------------- Name Class Representation ------------------------------------------------------------- XtNchildren XtCReadOnly XtRWidgetList XtNinsertPosition XtCInsertPosition XtRFunction XtNnumChildren XtCReadOnly XtRCardinal ------------------------------------------------------------- 1m1.4.2.4. CompositePart Default Values0m The default values for the Composite fields, which are filled in from the Composite resource list and by the Com- posite initialize procedure, are ----------------------------------------------------- Field Default Value ----------------------------------------------------- children NULL num_children 0 num_slots 0 insert_position Internal function to insert at end ----------------------------------------------------- The 4mchildren24m, 4mnum_children24m, and 4minsert_position24m fields are declared as resources; XtNinsertPosition is a settable resource, XtNchildren and XtNnumChildren may be read by any client but should only be modified by the composite widget class procedures. 1m1.4.3. Constraint Widgets0m The Constraint widget class is a subclass of the Composite widget class (see Section 3.6). Constraint widgets maintain additional state data for each child; for example, client- defined constraints on the child's geometry. The additional data used by constraint widgets are defined by the 4mCon-0m 4mstraintClassPart24m and 4mConstraintPart24m structures. 1m110m 1mX Toolkit Intrinsics X11 Release 6.40m 1m1.4.3.1. ConstraintClassPart Structure0m In addition to the Core and Composite class fields, widgets of the Constraint class have the following class fields. __ | typedef struct { XtResourceList resources;See Chapter 9 Cardinal num_resources; See Chapter 9 Cardinal constraint_size;See Section 3.6 XtInitProc initialize; See Section 3.6 XtWidgetProc destroy; See Section 3.6 XtSetValuesFunc set_values;See Section 9.7.2 XtPointer extension; See Section 1.6 } ConstraintClassPart; |__ The extension record defined for 4mConstraintClassPart24m with 4mrecord_type24m equal to 4mNULLQUARK24m is 4mConstraintClassExtension-0m 4mRec24m. __ | typedef struct { XtPointer next_extension;See Section 1.6.12 XrmQuark record_type; See Section 1.6.12 long version; See Section 1.6.12 Cardinal record_size; See Section 1.6.12 XtArgsProc get_values_hook;See Section 9.7.1 } ConstraintClassExtensionRec, *ConstraintClassExtension; |__ Constraint classes have the Constraint class fields immedi- ately following the Composite class fields. __ | typedef struct _ConstraintClassRec { CoreClassPart core_class; CompositeClassPart composite_class; ConstraintClassPart constraint_class; } ConstraintClassRec, *ConstraintWidgetClass; |__ The single occurrences of the class record and pointer for creating instances of Constraint are In 4mIntrinsicP.h24m: 1m120m 1mX Toolkit Intrinsics X11 Release 6.40m __ | extern ConstraintClassRec constraintClassRec; |__ In 4mIntrinsic.h24m: __ | extern WidgetClass constraintWidgetClass; |__ The opaque types 4mConstraintWidget24m and 4mConstraintWidgetClass0m and the opaque variable 4mconstraintWidgetClass24m are defined for generic operations on widgets whose class is Constraint or a subclass of Constraint. The symbolic constant for the 4mConstraintClassExtension24m version identifier is 4mXtConstrain-0m 4mtExtensionVersion24m (see Section 1.6.12). 4mIntrinsic.h24m uses an incomplete structure definition to ensure that the compiler catches attempts to access private data. __ | typedef struct _ConstraintClassRec *ConstraintWidgetClass; |__ 1m1.4.3.2. ConstraintPart Structure0m In addition to the Core and Composite instance fields, wid- gets of the Constraint class have the following unused instance fields defined in the 4mConstraintPart24m structure __ | typedef struct { int empty; } ConstraintPart; |__ Constraint widgets have the Constraint instance fields imme- diately following the Composite instance fields. 1m130m 1mX Toolkit Intrinsics X11 Release 6.40m __ | typedef struct { CorePart core; CompositePart composite; ConstraintPart constraint; } ConstraintRec, *ConstraintWidget; |__ 4mIntrinsic.h24m uses an incomplete structure definition to ensure that the compiler catches attempts to access private data. __ | typedef struct _ConstraintRec *ConstraintWidget; |__ 1m1.4.3.3. Constraint Resources0m The 4mconstraintClassRec24m 4mcore_class24m and 4mconstraint_class0m 4mresources24m fields are NULL, and the 4mnum_resources24m fields are zero; no additional resources beyond those declared by the superclasses are defined for Constraint. 1m1.5. Implementation-Specific Types0m To increase the portability of widget and application source code between different system environments, the Intrinsics define several types whose precise representation is explic- itly dependent upon, and chosen by, each individual imple- mentation of the Intrinsics. These implementation-defined types are 1mBoolean 22mA datum that contains a zero or nonzero value. Unless explicitly stated, clients should not assume that the nonzero value is equal to the symbolic value 4mTrue24m. 1mCardinal 22mAn unsigned integer datum with a minimum range of [0..2^16-1]. 1mDimension 22mAn unsigned integer datum with a minimum range of [0..2^16-1]. 1mPosition 22mA signed integer datum with a minimum range of [-2^15..2^15-1]. 1mXtPointer 22mA datum large enough to contain the largest of a char*, int*, function pointer, structure pointer, 1m140m 1mX Toolkit Intrinsics X11 Release 6.40m or long value. A pointer to any type or func- tion, or a long value may be converted to an 4mXtPointer24m and back again and the result will com- pare equal to the original value. In ANSI C environments it is expected that 4mXtPointer24m will be defined as void*. 1mXtArgVal 22mA datum large enough to contain an 4mXtPointer24m, 4mCardinal24m, 4mDimension24m, or 4mPosition24m value. 1mXtEnum 22mAn integer datum large enough to encode at least 128 distinct values, two of which are the sym- bolic values 4mTrue24m and 4mFalse24m. The symbolic values 4mTRUE24m and 4mFALSE24m are also defined to be equal to 4mTrue24m and 4mFalse24m, respectively. In addition to these specific types, the precise order of the fields within the structure declarations for any of the instance part records 4mObjectPart24m, 4mRectObjPart24m, 4mCorePart24m, 4mCompositePart24m, 4mShellPart24m, 4mWMShellPart24m, 4mTopLevelShellPart24m, and 4mApplicationShellPart24m is implementation-defined. These structures may also have additional private fields internal to the implementation. The 4mObjectPart24m, 4mRectObjPart24m, and 4mCorePart24m structures must be defined so that any member with the same name appears at the same offset in 4mObjectRec24m, 4mRect-0m 4mObjRec24m, and 4mCoreRec24m (4mWidgetRec24m). No other relations between the offsets of any two fields may be assumed. 1m1.6. Widget Classing0m The 4mwidget_class24m field of a widget points to its widget class structure, which contains information that is constant across all widgets of that class. As a consequence, widgets usually do not implement directly callable procedures; rather, they implement procedures, called methods, that are available through their widget class structure. These meth- ods are invoked by generic procedures that envelop common actions around the methods implemented by the widget class. Such procedures are applicable to all widgets of that class and also to widgets whose classes are subclasses of that class. All widget classes are a subclass of Core and can be sub- classed further. Subclassing reduces the amount of code and declarations necessary to make a new widget class that is similar to an existing class. For example, you do not have to describe every resource your widget uses in an 4mXtRe-0m 4msourceList24m. Instead, you describe only the resources your widget has that its superclass does not. Subclasses usually inherit many of their superclasses' procedures (for example, the expose procedure or geometry handler). 1m150m 1mX Toolkit Intrinsics X11 Release 6.40m Subclassing, however, can be taken too far. If you create a subclass that inherits none of the procedures of its super- class, you should consider whether you have chosen the most appropriate superclass. To make good use of subclassing, widget declarations and naming conventions are highly stylized. A widget consists of three files: · A public .h file, used by client widgets or applica- tions. · A private .h file, used by widgets whose classes are subclasses of the widget class. · A .c file, which implements the widget. 1m1.6.1. Widget Naming Conventions0m The Intrinsics provide a vehicle by which programmers can create new widgets and organize a collection of widgets into an application. To ensure that applications need not deal with as many styles of capitalization and spelling as the number of widget classes it uses, the following guidelines should be followed when writing new widgets: · Use the X library naming conventions that are applica- ble. For example, a record component name is all low- ercase and uses underscores (_) for compound words (for example, background_pixmap). Type and procedure names start with uppercase and use capitalization for com- pound words (for example, 4mArgList24m or 4mXtSetValues24m). · A resource name is spelled identically to the field name except that compound names use capitalization rather than underscore. To let the compiler catch spelling errors, each resource name should have a sym- bolic identifier prefixed with ``XtN''. For example, the 4mbackground_pixmap24m field has the corresponding iden- tifier XtNbackgroundPixmap, which is defined as the string ``backgroundPixmap''. Many predefined names are listed in <4mX11/StringDefs.h24m>. Before you invent a new name, you should make sure there is not already a name that you can use. · A resource class string starts with a capital letter and uses capitalization for compound names (for exam- ple,``BorderWidth''). Each resource class string should have a symbolic identifier prefixed with ``XtC'' (for example, XtCBorderWidth). Many predefined classes are listed in <4mX11/StringDefs.h24m>. 1m160m 1mX Toolkit Intrinsics X11 Release 6.40m · A resource representation string is spelled identically to the type name (for example, ``TranslationTable''). Each representation string should have a symbolic iden- tifier prefixed with ``XtR'' (for example, XtRTransla- tionTable). Many predefined representation types are listed in <4mX11/StringDefs.h24m>. · New widget classes start with a capital and use upper- case for compound words. Given a new class name AbcXyz, you should derive several names: - Additional widget instance structure part name AbcXyzPart. - Complete widget instance structure names AbcXyzRec and _AbcXyzRec. - Widget instance structure pointer type name AbcXyzWidget. - Additional class structure part name AbcXyzClass- Part. - Complete class structure names AbcXyzClassRec and _AbcXyzClassRec. - Class structure pointer type name AbcXyzWidget- Class. - Class structure variable abcXyzClassRec. - Class structure pointer variable abcXyzWidget- Class. · Action procedures available to translation specifica- tions should follow the same naming conventions as pro- cedures. That is, they start with a capital letter, and compound names use uppercase (for example, ``High- light'' and ``NotifyClient''). The symbolic identifiers XtN..., XtC..., and XtR... may be implemented as macros, as global symbols, or as a mixture of the two. The (implicit) type of the identifier is 4mString24m. The pointer value itself is not significant; clients must not assume that inequality of two identifiers implies inequality of the resource name, class, or representation string. Clients should also note that although global sym- bols permit savings in literal storage in some environments, they also introduce the possibility of multiple definition conflicts when applications attempt to use independently developed widgets simultaneously. 1m170m 1mX Toolkit Intrinsics X11 Release 6.40m 1m1.6.2. Widget Subclassing in Public .h Files0m The public .h file for a widget class is imported by clients and contains · A reference to the public .h file for the superclass. · Symbolic identifiers for the names and classes of the new resources that this widget adds to its superclass. The definitions should have a single space between the definition name and the value and no trailing space or comment in order to reduce the possibility of compiler warnings from similar declarations in multiple classes. · Type declarations for any new resource data types defined by the class. · The class record pointer variable used to create widget instances. · The C type that corresponds to widget instances of this class. · Entry points for new class methods. For example, the following is the public .h file for a pos- sible implementation of a Label widget: #ifndef LABEL_H #define LABEL_H /* New resources */ #define XtNjustify "justify" #define XtNforeground "foreground" #define XtNlabel "label" #define XtNfont "font" #define XtNinternalWidth "internalWidth" #define XtNinternalHeight "internalHeight" /* Class record pointer */ extern WidgetClass labelWidgetClass; /* C Widget type definition */ typedef struct _LabelRec *LabelWidget; /* New class method entry points */ extern void LabelSetText(); /* Widget w */ /* String text */ extern String LabelGetText(); /* Widget w */ 1m180m 1mX Toolkit Intrinsics X11 Release 6.40m #endif LABEL_H The conditional inclusion of the text allows the application to include header files for different widgets without being concerned that they already may be included as a superclass of another widget. To accommodate operating systems with file name length restrictions, the name of the public .h file is the first ten characters of the widget class. For example, the public .h file for the Constraint widget class is 4mConstraint.h24m. 1m1.6.3. Widget Subclassing in Private .h Files0m The private .h file for a widget is imported by widget classes that are subclasses of the widget and contains · A reference to the public .h file for the class. · A reference to the private .h file for the superclass. · Symbolic identifiers for any new resource representa- tion types defined by the class. The definitions should have a single space between the definition name and the value and no trailing space or comment. · A structure part definition for the new fields that the widget instance adds to its superclass's widget struc- ture. · The complete widget instance structure definition for this widget. · A structure part definition for the new fields that this widget class adds to its superclass's constraint structure if the widget class is a subclass of Con- straint. · The complete constraint structure definition if the widget class is a subclass of Constraint. · Type definitions for any new procedure types used by class methods declared in the widget class part. · A structure part definition for the new fields that this widget class adds to its superclass's widget class structure. · The complete widget class structure definition for this widget. 1m190m 1mX Toolkit Intrinsics X11 Release 6.40m · The complete widget class extension structure defini- tion for this widget, if any. · The symbolic constant identifying the class extension version, if any. · The name of the global class structure variable con- taining the generic class structure for this class. · An inherit constant for each new procedure in the wid- get class part structure. For example, the following is the private .h file for a pos- sible Label widget: #ifndef LABELP_H #define LABELP_H #include /* New representation types used by the Label widget */ #define XtRJustify "Justify" /* New fields for the Label widget record */ typedef struct { /* Settable resources */ Pixel foreground; XFontStruct *font; String label; /* text to display */ XtJustify justify; Dimension internal_width;/* # pixels horizontal border */ Dimension internal_height;/* # pixels vertical border */ /* Data derived from resources */ GC normal_GC; GC gray_GC; Pixmap gray_pixmap; Position label_x; Position label_y; Dimension label_width; Dimension label_height; Cardinal label_len; Boolean display_sensitive; } LabelPart; /* Full instance record declaration */ typedef struct _LabelRec { CorePart core; LabelPart label; } LabelRec; 1m200m 1mX Toolkit Intrinsics X11 Release 6.40m /* Types for Label class methods */ typedef void (*LabelSetTextProc)(); /* Widget w */ /* String text */ typedef String (*LabelGetTextProc)(); /* Widget w */ /* New fields for the Label widget class record */ typedef struct { LabelSetTextProc set_text; LabelGetTextProc get_text; XtPointer extension; } LabelClassPart; /* Full class record declaration */ typedef struct _LabelClassRec { CoreClassPart core_class; LabelClassPart label_class; } LabelClassRec; /* Class record variable */ extern LabelClassRec labelClassRec; #define LabelInheritSetText((LabelSetTextProc)_XtInherit) #define LabelInheritGetText((LabelGetTextProc)_XtInherit) #endif LABELP_H To accommodate operating systems with file name length restrictions, the name of the private .h file is the first nine characters of the widget class followed by a capital P. For example, the private .h file for the Constraint widget class is 4mConstrainP.h24m. 1m1.6.4. Widget Subclassing in .c Files0m The .c file for a widget contains the structure initializer for the class record variable, which contains the following parts: · Class information (for example, 4msuperclass24m, 4mclass_name24m, 4mwidget_size24m, 4mclass_initialize24m, and 4mclass_inited24m). · Data constants (for example, 4mresources24m and 4mnum_resources24m, 4mactions24m and 4mnum_actions24m, 4mvisible_inter-0m 4mest24m, 4mcompress_motion24m, 4mcompress_exposure24m, and 4mversion24m). · Widget operations (for example, 4minitialize24m, 4mrealize24m, 4mdestroy24m, 4mresize24m, 4mexpose24m, 4mset_values24m, 4maccept_focus24m, and any new operations specific to the widget). 1m210m 1mX Toolkit Intrinsics X11 Release 6.40m The 4msuperclass24m field points to the superclass global class record, declared in the superclass private .h file. For direct subclasses of the generic core widget, 4msuperclass0m should be initialized to the address of the 4mwidgetClassRec0m structure. The superclass is used for class chaining opera- tions and for inheriting or enveloping a superclass's opera- tions (see Sections 1.6.7, 1.6.9, and 1.6.10). The 4mclass_name24m field contains the text name for this class, which is used by the resource manager. For example, the Label widget has the string ``Label''. More than one widget class can share the same text class name. This string must be permanently allocated prior to or during the execution of the class initialization procedure and must not be subse- quently deallocated. The 4mwidget_size24m field is the size of the corresponding wid- get instance structure (not the size of the class struc- ture). The 4mversion24m field indicates the toolkit implementation ver- sion number and is used for runtime consistency checking of the X Toolkit and widgets in an application. Widget writers must set it to the implementation-defined symbolic value 4mXtVersion24m in the widget class structure initialization. Those widget writers who believe that their widget binaries are compatible with other implementations of the Intrinsics can put the special value 4mXtVersionDontCheck24m in the 4mversion0m field to disable version checking for those widgets. If a widget needs to compile alternative code for different revi- sions of the Intrinsics interface definition, it may use the symbol 4mXtSpecificationRelease24m, as described in Chapter 13. Use of 4mXtVersion24m allows the Intrinsics implementation to recognize widget binaries that were compiled with older implementations. The 4mextension24m field is for future upward compatibility. If the widget programmer adds fields to class parts, all sub- class structure layouts change, requiring complete recompi- lation. To allow clients to avoid recompilation, an exten- sion field at the end of each class part can point to a record that contains any additional class information required. All other fields are described in their respective sections. The .c file also contains the declaration of the global class structure pointer variable used to create instances of the class. The following is an abbreviated version of the .c file for a Label widget. The resources table is described in Chapter 9. 1m220m 1mX Toolkit Intrinsics X11 Release 6.40m /* Resources specific to Label */ static XtResource resources[] = { {XtNforeground, XtCForeground, XtRPixel, sizeof(Pixel), XtOffset(LabelWidget, label.foreground), XtRString, XtDefaultForeground}, {XtNfont, XtCFont, XtRFontStruct, sizeof(XFontStruct *), XtOffset(LabelWidget, label.font),XtRString, XtDefaultFont}, {XtNlabel, XtCLabel, XtRString, sizeof(String), XtOffset(LabelWidget, label.label), XtRString, NULL}, . . . } /* Forward declarations of procedures */ static void ClassInitialize(); static void Initialize(); static void Realize(); static void SetText(); static void GetText(); . . . /* Class record constant */ LabelClassRec labelClassRec = { { /* core_class fields */ /* superclass */ (WidgetClass)&coreClassRec, /* class_name */ "Label", /* widget_size */ sizeof(LabelRec), /* class_initialize */ClassInitialize, /* class_part_initialize */NULL, /* class_inited */False, /* initialize */ Initialize, /* initialize_hook */NULL, /* realize */ Realize, /* actions */ NULL, /* num_actions */ 0, /* resources */ resources, /* num_resources */XtNumber(resources), /* xrm_class */ NULLQUARK, /* compress_motion */True, /* compress_exposure */True, /* compress_enterleave */True, /* visible_interest */False, /* destroy */ NULL, /* resize */ Resize, /* expose */ Redisplay, /* set_values */ SetValues, /* set_values_hook */NULL, 1m230m 1mX Toolkit Intrinsics X11 Release 6.40m /* set_values_almost */XtInheritSetValuesAlmost, /* get_values_hook */NULL, /* accept_focus */NULL, /* version */ XtVersion, /* callback_offsets */NULL, /* tm_table */ NULL, /* query_geometry */XtInheritQueryGeometry, /* display_accelerator */NULL, /* extension */ NULL }, { /* Label_class fields */ /* get_text */ GetText, /* set_text */ SetText, /* extension */ NULL } }; /* Class record pointer */ WidgetClass labelWidgetClass = (WidgetClass) &labelClassRec; /* New method access routines */ void LabelSetText(w, text) Widget w; String text; { Label WidgetClass lwc = (Label WidgetClass)XtClass(w); XtCheckSubclass(w, labelWidgetClass, NULL); *(lwc->label_class.set_text)(w, text) } /* Private procedures */ . . . 1m1.6.5. Widget Class and Superclass Look Up0m To obtain the class of a widget, use 4mXtClass24m. __ | WidgetClass XtClass(4mw24m) Widget 4mw24m; 4mw24m Specifies the widget. Must be of class Object or any subclass thereof. |__ The 4mXtClass24m function returns a pointer to the widget's class structure. 1m240m 1mX Toolkit Intrinsics X11 Release 6.40m To obtain the superclass of a widget, use 4mXtSuperclass24m. __ | WidgetClass XtSuperclass(4mw24m) Widget 4mw24m; 4mw24m Specifies the widget. Must be of class Object or any subclass thereof. |__ The 4mXtSuperclass24m function returns a pointer to the widget's superclass class structure. 1m1.6.6. Widget Subclass Verification0m To check the subclass to which a widget belongs, use 4mXtIs-0m 4mSubclass24m. __ | Boolean XtIsSubclass(4mw24m, 4mwidget_class24m) Widget 4mw24m; WidgetClass 4mwidget_class24m; 4mw24m Specifies the widget or object instance whose class is to be checked. Must be of class Object or any subclass thereof. 4mwidget_class0m Specifies the widget class for which to test. Must be 1mobjectClass 22mor any subclass thereof. |__ The 4mXtIsSubclass24m function returns 4mTrue24m if the class of the specified widget is equal to or is a subclass of the speci- fied class. The widget's class can be any number of sub- classes down the chain and need not be an immediate subclass of the specified class. Composite widgets that need to restrict the class of the items they contain can use 4mXtIs-0m 4mSubclass24m to find out if a widget belongs to the desired class of objects. To test if a given widget belongs to a subclass of an Intrinsics-defined class, the Intrinsics define macros or functions equivalent to 4mXtIsSubclass24m for each of the built- in classes. These procedures are 4mXtIsObject24m, 4mXtIsRectObj24m, 4mXtIsWidget24m, 4mXtIsComposite24m, 4mXtIsConstraint24m, 4mXtIsShell24m, 4mXtIsOverrideShell24m, 4mXtIsWMShell24m, 4mXtIsVendorShell24m, 4mXtIsTran-0m 4msientShell24m, 4mXtIsTopLevelShell24m, 4mXtIsApplicationShell24m, and 1m250m 1mX Toolkit Intrinsics X11 Release 6.40m 4mXtIsSessionShell24m. All these macros and functions have the same argument description. __ | Boolean XtIs4m24m (4mw24m) Widget 4mw24m; 4mw24m Specifies the widget or object instance whose class is to be checked. Must be of class Object or any subclass thereof. |__ These procedures may be faster than calling 4mXtIsSubclass0m directly for the built-in classes. To check a widget's class and to generate a debugging error message, use 4mXtCheckSubclass24m, defined in <4mX11/IntrinsicP.h24m>: __ | void XtCheckSubclass(4mw24m, 4mwidget_class24m, 4mmessage24m) Widget 4mw24m; WidgetClass 4mwidget_class24m; String 4mmessage24m; 4mw24m Specifies the widget or object whose class is to be checked. Must be of class Object or any sub- class thereof. 4mwidget_class0m Specifies the widget class for which to test. Must be 1mobjectClass 22mor any subclass thereof. 4mmessage24m Specifies the message to be used. |__ The 4mXtCheckSubclass24m macro determines if the class of the specified widget is equal to or is a subclass of the speci- fied class. The widget's class can be any number of sub- classes down the chain and need not be an immediate subclass of the specified class. If the specified widget's class is not a subclass, 4mXtCheckSubclass24m constructs an error message from the supplied message, the widget's actual class, and the expected class and calls 4mXtErrorMsg24m. 4mXtCheckSubclass0m should be used at the entry point of exported routines to ensure that the client has passed in a valid widget class for the exported operation. 1m260m 1mX Toolkit Intrinsics X11 Release 6.40m 4mXtCheckSubclass24m is only executed when the module has been compiled with the compiler symbol DEBUG defined; otherwise, it is defined as the empty string and generates no code. 1m1.6.7. Superclass Chaining0m While most fields in a widget class structure are self-con- tained, some fields are linked to their corresponding fields in their superclass structures. With a linked field, the Intrinsics access the field's value only after accessing its corresponding superclass value (called downward superclass chaining) or before accessing its corresponding superclass value (called upward superclass chaining). The self-con- tained fields are In all widget classes:4mclass_name0m 4mclass_initialize0m 4mwidget_size0m 4mrealize0m 4mvisible_interest0m 4mresize0m 4mexpose0m 4maccept_focus0m 4mcompress_motion0m 4mcompress_exposure0m 4mcompress_enterleave0m 4mset_values_almost0m 4mtm_table0m 4mversion0m 4mallocate0m 4mdeallocate0m In Composite widget classes:4mgeometry_manager0m 4mchange_managed0m 4minsert_child0m 4mdelete_child0m 4maccepts_objects0m 4mallows_change_managed_set0m In Constraint widget classes:4mconstraint_size0m In Shell widget classes:4mroot_geometry_manager0m With downward superclass chaining, the invocation of an operation first accesses the field from the Object, RectObj, and Core class structures, then from the subclass structure, and so on down the class chain to that widget's class struc- ture. These superclass-to-subclass fields are 4mclass_part_initialize0m 4mget_values_hook0m 4minitialize0m 1m270m 1mX Toolkit Intrinsics X11 Release 6.40m 4minitialize_hook0m 4mset_values0m 4mset_values_hook0m 4mresources0m In addition, for subclasses of Constraint, the following fields of the 4mConstraintClassPart24m and 4mConstraintClassExten-0m 4msionRec24m structures are chained from the Constraint class down to the subclass: 4mresources0m 4minitialize0m 4mset_values0m 4mget_values_hook0m With upward superclass chaining, the invocation of an opera- tion first accesses the field from the widget class struc- ture, then from the superclass structure, and so on up the class chain to the Core, RectObj, and Object class struc- tures. The subclass-to-superclass fields are 4mdestroy0m 4mactions0m For subclasses of Constraint, the following field of 4mCon-0m 4mstraintClassPart24m is chained from the subclass up to the Con- straint class: 4mdestroy0m 1m1.6.8. Class Initialization: class_initialize and0m 1mclass_part_initialize Procedures0m Many class records can be initialized completely at compile or link time. In some cases, however, a class may need to register type converters or perform other sorts of once-only runtime initialization. Because the C language does not have initialization proce- dures that are invoked automatically when a program starts up, a widget class can declare a class_initialize procedure that will be automatically called exactly once by the Intrinsics. A class initialization procedure pointer is of type 4mXtProc24m: 1m280m 1mX Toolkit Intrinsics X11 Release 6.40m __ | typedef void (*XtProc)(void); |__ A widget class indicates that it has no class initialization procedure by specifying NULL in the 4mclass_initialize24m field. In addition to the class initialization that is done exactly once, some classes perform initialization for fields in their parts of the class record. These are performed not just for the particular class, but for subclasses as well, and are done in the class's class part initialization proce- dure, a pointer to which is stored in the 4mclass_part_ini-0m 4mtialize24m field. The class_part_initialize procedure pointer is of type 4mXtWidgetClassProc24m. __ | typedef void (*XtWidgetClassProc)(WidgetClass); WidgetClass 4mwidget_class24m; 4mwidget_class0m Points to the class structure for the class being initialized. |__ During class initialization, the class part initialization procedures for the class and all its superclasses are called in superclass-to-subclass order on the class record. These procedures have the responsibility of doing any dynamic ini- tializations necessary to their class's part of the record. The most common is the resolution of any inherited methods defined in the class. For example, if a widget class C has superclasses Core, Composite, A, and B, the class record for C first is passed to Core 's class_part_initialize proce- dure. This resolves any inherited Core methods and compiles the textual representations of the resource list and action table that are defined in the class record. Next, Compos- ite's class_part_initialize procedure is called to initial- ize the composite part of C's class record. Finally, the class_part_initialize procedures for A, B, and C, in that order, are called. For further information, see Section 1.6.9. Classes that do not define any new class fields or that need no extra processing for them can specify NULL in the 4mclass_part_initialize24m field. All widget classes, whether they have a class initialization procedure or not, must start with their 4mclass_inited24m field 4mFalse24m. The first time a widget of a class is created, 4mXtCreateWid-0m 4mget24m ensures that the widget class and all superclasses are 1m290m 1mX Toolkit Intrinsics X11 Release 6.40m initialized, in superclass-to-subclass order, by checking each 4mclass_inited24m field and, if it is 4mFalse24m, by calling the class_initialize and the class_part_initialize procedures for the class and all its superclasses. The Intrinsics then set the 4mclass_inited24m field to a nonzero value. After the one-time initialization, a class structure is constant. The following example provides the class initialization pro- cedure for a Label class. static void ClassInitialize() { XtSetTypeConverter(XtRString, XtRJustify, CvtStringToJustify, NULL, 0, XtCacheNone, NULL); } 1m1.6.9. Initializing a Widget Class0m A class is initialized when the first widget of that class or any subclass is created. To initialize a widget class without creating any widgets, use 4mXtInitializeWidgetClass24m. __ | void XtInitializeWidgetClass(4mobject_class24m) WidgetClass 4mobject_class24m; 4mobject_class0m Specifies the object class to initialize. May be 4mobjectClass24m or any subclass thereof. |__ If the specified widget class is already initialized, 4mXtIni-0m 4mtializeWidgetClass24m returns immediately. If the class initialization procedure registers type con- verters, these type converters are not available until the first object of the class or subclass is created or 4mXtIni-0m 4mtializeWidgetClass24m is called (see Section 9.6). 1m1.6.10. Inheritance of Superclass Operations0m A widget class is free to use any of its superclass's self- contained operations rather than implementing its own code. The most frequently inherited operations are expose 1m300m 1mX Toolkit Intrinsics X11 Release 6.40m realize insert_child delete_child geometry_manager set_values_almost To inherit an operation 4mxyz24m, specify the constant 4mXtIn-0m 4mheritXyz24m in your class record. Every class that declares a new procedure in its widget class part must provide for inheriting the procedure in its class_part_initialize procedure. The chained operations declared in Core and Constraint records are never inherited. Widget classes that do nothing beyond what their superclass does specify NULL for chained procedures in their class records. Inheriting works by comparing the value of the field with a known, special value and by copying in the superclass's value for that field if a match occurs. This special value, called the inheritance constant, is usually the Intrinsics internal value 4m_XtInherit24m cast to the appropriate type. 4m_XtInherit24m is a procedure that issues an error message if it is actually called. For example, 4mCompositeP.h24m contains these definitions: #define XtInheritGeometryManager ((XtGeometryHandler) _XtInherit) #define XtInheritChangeManaged ((XtWidgetProc) _XtInherit) #define XtInheritInsertChild ((XtArgsProc) _XtInherit) #define XtInheritDeleteChild ((XtWidgetProc) _XtInherit) Composite's class_part_initialize procedure begins as fol- lows: static void CompositeClassPartInitialize(widgetClass) WidgetClass widgetClass; { CompositeWidgetClass wc = (CompositeWidgetClass)widgetClass; CompositeWidgetClass super = (CompositeWidgetClass)wc->core_class.superclass; if (wc->composite_class.geometry_manager == XtInheritGeometryManager) { wc->composite_class.geometry_manager = super->composite_class.geometry_manager; } if (wc->composite_class.change_managed == XtInheritChangeManaged) { wc->composite_class.change_managed = super->composite_class.change_managed; 1m310m 1mX Toolkit Intrinsics X11 Release 6.40m } . . . Nonprocedure fields may be inherited in the same manner as procedure fields. The class may declare any reserved value it wishes for the inheritance constant for its new fields. The following inheritance constants are defined: For Object: 4mXtInheritAllocate0m 4mXtInheritDeallocate0m For Core: 4mXtInheritRealize0m 4mXtInheritResize0m 4mXtInheritExpose0m 4mXtInheritSetValuesAlmost0m 4mXtInheritAcceptFocus0m 4mXtInheritQueryGeometry0m 4mXtInheritTranslations0m 4mXtInheritDisplayAccelerator0m For Composite: 4mXtInheritGeometryManager0m 4mXtInheritChangeManaged0m 4mXtInheritInsertChild0m 4mXtInheritDeleteChild0m For Shell: 4mXtInheritRootGeometryManager0m 1m1.6.11. Invocation of Superclass Operations0m A widget sometimes needs to call a superclass operation that is not chained. For example, a widget's expose procedure 1m320m 1mX Toolkit Intrinsics X11 Release 6.40m might call its superclass's 4mexpose24m and then perform a little more work on its own. For example, a Composite class with predefined managed children can implement insert_child by first calling its superclass's 4minsert_child24m and then calling 4mXtManageChild24m to add the child to the managed set. Note A class method should not use 4mXtSuperclass24m but should instead call the class method of its own specific superclass directly through the super- class record. That is, it should use its own class pointers only, not the widget's class point- ers, as the widget's class may be a subclass of the class whose implementation is being refer- enced. This technique is referred to as 4menveloping24m the superclass's operation. 1m1.6.12. Class Extension Records0m It may be necessary at times to add new fields to already existing widget class structures. To permit this to be done without requiring recompilation of all subclasses, the last field in a class part structure should be an extension pointer. If no extension fields for a class have yet been defined, subclasses should initialize the value of the extension pointer to NULL. If extension fields exist, as is the case with the Compos- ite, Constraint, and Shell classes, subclasses can provide values for these fields by setting the 4mextension24m pointer for the appropriate part in their class structure to point to a statically declared extension record containing the addi- tional fields. Setting the 4mextension24m field is never manda- tory; code that uses fields in the extension record must always check the 4mextension24m field and take some appropriate default action if it is NULL. In order to permit multiple subclasses and libraries to chain extension records from a single 4mextension24m field, extension records should be declared as a linked list, and each extension record definition should contain the follow- ing four fields at the beginning of the structure declara- tion: 1m330m 1mX Toolkit Intrinsics X11 Release 6.40m __ | struct { XtPointer next_extension; XrmQuark record_type; long version; Cardinal record_size; }; 4mnext_extension0m Specifies the next record in the list, or NULL. 4mrecord_type24m Specifies the particular structure declaration to which each extension record instance con- forms. 4mversion24m Specifies a version id symbolic constant sup- plied by the definer of the structure. 4mrecord_size24m Specifies the total number of bytes allocated for the extension record. |__ The 4mrecord_type24m field identifies the contents of the exten- sion record and is used by the definer of the record to locate its particular extension record in the list. The 4mrecord_type24m field is normally assigned the result of 4mXrm-0m 4mStringToQuark24m for a registered string constant. The Intrin- sics reserve all record type strings beginning with the two characters ``XT'' for future standard uses. The value 4mNUL-0m 4mLQUARK24m may also be used by the class part owner in extension records attached to its own class part extension field to identify the extension record unique to that particular class. The 4mversion24m field is an owner-defined constant that may be used to identify binary files that have been compiled with alternate definitions of the remainder of the extension record data structure. The private header file for a widget class should provide a symbolic constant for subclasses to use to initialize this field. The 4mrecord_size24m field value includes the four common header fields and should normally be initialized with 4msizeof24m(). Any value stored in the class part extension fields of 4mCom-0m 4mpositeClassPart24m, 4mConstraintClassPart24m, or 4mShellClassPart24m must point to an extension record conforming to this definition. The Intrinsics provide a utility function for widget writers to locate a particular class extension record in a linked list, given a widget class and the offset of the 4mextension0m field in the class record. 1m340m 1mX Toolkit Intrinsics X11 Release 6.40m To locate a class extension record, use 4mXtGetClassExtension24m. __ | XtPointer XtGetClassExtension(4mobject_class24m, 4mbyte_offset24m, 4mtype24m, 4mversion24m, 4mrecord_size24m) WidgetClass 4mobject_class24m; Cardinal 4mbyte_offset24m; XrmQuark 4mtype24m; long 4mversion24m; Cardinal 4mrecord_size24m; 4mobject_class0m Specifies the object class containing the exten- sion list to be searched. 4mbyte_offset0m Specifies the offset in bytes from the base of the class record of the extension field to be searched. 4mtype24m Specifies the record_type of the class extension to be located. 4mversion24m Specifies the minimum acceptable version of the class extension required for a match. 4mrecord_size0m Specifies the minimum acceptable length of the class extension record required for a match, or 0. |__ The list of extension records at the specified offset in the specified object class will be searched for a match on the specified type, a version greater than or equal to the spec- ified version, and a record size greater than or equal the specified record_size if it is nonzero. 4mXtGetClassExtension0m returns a pointer to a matching extension record or NULL if no match is found. The returned extension record must not be modified or freed by the caller if the caller is not the extension owner. 1m350m 1mX Toolkit Intrinsics X11 Release 6.40m 1mChapter 20m 1mWidget Instantiation0m A hierarchy of widget instances constitutes a widget tree. The shell widget returned by 4mXtAppCreateShell24m is the root of the widget tree instance. The widgets with one or more children are the intermediate nodes of that tree, and the widgets with no children of any kind are the leaves of the widget tree. With the exception of pop-up children (see Chapter 5), this widget tree instance defines the associated X Window tree. Widgets can be either composite or primitive. Both kinds of widgets can contain children, but the Intrinsics provide a set of management mechanisms for constructing and interfac- ing between composite widgets, their children, and other clients. Composite widgets, that is, members of the class 4mcompos-0m 4miteWidgetClass24m, are containers for an arbitrary, but widget implementation-defined, collection of children, which may be instantiated by the composite widget itself, by other clients, or by a combination of the two. Composite widgets also contain methods for managing the geometry (layout) of any child widget. Under unusual circumstances, a composite widget may have zero children, but it usually has at least one. By contrast, primitive widgets that contain children typically instantiate specific children of known classes themselves and do not expect external clients to do so. Primitive widgets also do not have general geometry manage- ment methods. In addition, the Intrinsics recursively perform many opera- tions (for example, realization and destruction) on compos- ite widgets and all their children. Primitive widgets that have children must be prepared to perform the recursive operations themselves on behalf of their children. A widget tree is manipulated by several Intrinsics func- tions. For example, 4mXtRealizeWidget24m traverses the tree downward and recursively realizes all pop-up widgets and children of composite widgets. 4mXtDestroyWidget24m traverses the tree downward and destroys all pop-up widgets and chil- dren of composite widgets. The functions that fetch and modify resources traverse the tree upward and determine the inheritance of resources from a widget's ancestors. 4mXtMake-0m 4mGeometryRequest24m traverses the tree up one level and calls the geometry manager that is responsible for a widget child's geometry. 1m360m 1mX Toolkit Intrinsics X11 Release 6.40m To facilitate upward traversal of the widget tree, each wid- get has a pointer to its parent widget. The Shell widget that 4mXtAppCreateShell24m returns has a 4mparent24m pointer of NULL. To facilitate downward traversal of the widget tree, the 4mchildren24m field of each composite widget is a pointer to an array of child widgets, which includes all normal children created, not just the subset of children that are managed by the composite widget's geometry manager. Primitive widgets that instantiate children are entirely responsible for all operations that require downward traversal below themselves. In addition, every widget has a pointer to an array of pop- up children. 1m2.1. Initializing the X Toolkit0m Before an application can call any Intrinsics function other than 4mXtSetLanguageProc24m and 4mXtToolkitThreadInitialize24m, it must initialize the Intrinsics by using · 4mXtToolkitInitialize24m, which initializes the Intrinsics internals · 4mXtCreateApplicationContext24m, which initializes the per- application state · 4mXtDisplayInitialize24m or 4mXtOpenDisplay24m, which initializes the per-display state · 4mXtAppCreateShell24m, which creates the root of a widget tree Or an application can call the convenience procedure 4mXtOpe-0m 4mnApplication24m, which combines the functions of the preceding procedures. An application wishing to use the ANSI C locale mechanism should call 4mXtSetLanguageProc24m prior to calling 4mXtDisplayInitialize24m, 4mXtOpenDisplay24m, 4mXtOpenApplication24m, or 4mXtAppInitialize24m. Multiple instances of X Toolkit applications may be imple- mented in a single address space. Each instance needs to be able to read input and dispatch events independently of any other instance. Further, an application instance may need multiple display connections to have widgets on multiple displays. From the application's point of view, multiple display connections usually are treated together as a single unit for purposes of event dispatching. To accommodate both requirements, the Intrinsics define application contexts, each of which provides the information needed to distinguish one application instance from another. The major component of an application context is a list of one or more X 4mDisplay0m pointers for that application. The Intrinsics handle all display connections within a single application context 1m370m 1mX Toolkit Intrinsics X11 Release 6.40m simultaneously, handling input in a round-robin fashion. The application context type 4mXtAppContext24m is opaque to clients. To initialize the Intrinsics internals, use 4mXtToolkitIni-0m 4mtialize24m. __ | void XtToolkitInitialize() |__ If 4mXtToolkitInitialize24m was previously called, it returns immediately. When 4mXtToolkitThreadInitialize24m is called before 4mXtToolkitInitialize24m, the latter is protected against simultaneous activation by multiple threads. To create an application context, use 4mXtCreateApplication-0m 4mContext24m. __ | XtAppContext XtCreateApplicationContext() |__ The 4mXtCreateApplicationContext24m function returns an applica- tion context, which is an opaque type. Every application must have at least one application context. To destroy an application context and close any remaining display connections in it, use 4mXtDestroyApplicationContext24m. __ | void XtDestroyApplicationContext(4mapp_context24m) XtAppContext 4mapp_context24m; 4mapp_context0m Specifies the application context. |__ The 4mXtDestroyApplicationContext24m function destroys the speci- fied application context. If called from within an event dispatch (for example, in a callback procedure), 4mXtDestroy-0m 4mApplicationContext24m does not destroy the application context until the dispatch is complete. 1m380m 1mX Toolkit Intrinsics X11 Release 6.40m To get the application context in which a given widget was created, use 4mXtWidgetToApplicationContext24m. __ | XtAppContext XtWidgetToApplicationContext(4mw24m) Widget 4mw24m; 4mw24m Specifies the widget for which you want the appli- cation context. Must be of class Object or any subclass thereof. |__ The 4mXtWidgetToApplicationContext24m function returns the appli- cation context for the specified widget. To initialize a display and add it to an application con- text, use 4mXtDisplayInitialize24m. 1m390m 1mX Toolkit Intrinsics X11 Release 6.40m __ | void XtDisplayInitialize(4mapp_context24m, 4mdisplay24m, 4mapplication_name24m, 4mapplication_class24m, 4moptions24m, 4mnum_options24m, 4margc24m, 4margv24m) XtAppContext 4mapp_context24m; Display *4mdisplay24m; String 4mapplication_name24m; String 4mapplication_class24m; XrmOptionDescRec *4moptions24m; Cardinal 4mnum_options24m; int *4margc24m; String *4margv24m; 4mapp_context24m Specifies the application context. 4mdisplay24m Specifies a previously opened display connec- tion. Note that a single display connection can be in at most one application context. 4mapplication_name0m Specifies the name of the application instance. 4mapplication_class0m Specifies the class name of this application, which is usually the generic name for all instances of this application. 4moptions24m Specifies how to parse the command line for any application-specific resources. The 4moptions24m argument is passed as a parameter to 4mXrmParseCommand24m. For further information, see Section 15.9 in 4mXlib24m 4m--24m 4mC24m 4mLanguage24m 4mX24m 4mInterface0m and Section 2.4 of this specification. 4mnum_options24m Specifies the number of entries in the options list. 4margc24m Specifies a pointer to the number of command line parameters. 4margv24m Specifies the list of command line parameters. |__ The 4mXtDisplayInitialize24m function retrieves the language string to be used for the specified display (see Section 11.11), calls the language procedure (if set) with that lan- guage string, builds the resource database for the default screen, calls the Xlib 4mXrmParseCommand24m function to parse the command line, and performs other per-display initialization. After 4mXrmParseCommand24m has been called, 4margc24m and 4margv24m contain only those parameters that were not in the standard option table or in the table specified by the 4moptions24m argument. If the modified 4margc24m is not zero, most applications simply 1m400m 1mX Toolkit Intrinsics X11 Release 6.40m print out the modified 4margv24m along with a message listing the allowable options. On POSIX-based systems, the application name is usually the final component of 4margv24m[0]. If the syn- chronous resource is 4mTrue24m, 4mXtDisplayInitialize24m calls the Xlib 4mXSynchronize24m function to put Xlib into synchronous mode for this display connection and any others currently open in the application context. See Sections 2.3 and 2.4 for details on the 4mapplication_name24m, 4mapplication_class24m, 4moptions24m, and 4mnum_options24m arguments. 4mXtDisplayInitialize24m calls 4mXrmSetDatabase24m to associate the resource database of the default screen with the display before returning. 1m410m 1mX Toolkit Intrinsics X11 Release 6.40m To open a display, initialize it, and then add it to an application context, use 4mXtOpenDisplay24m. __ | Display *XtOpenDisplay(4mapp_context24m, 4mdisplay_string24m, 4mapplication_name24m, 4mapplication_class24m, 4moptions24m, 4mnum_options24m, 4margc24m, 4margv24m) XtAppContext 4mapp_context24m; String 4mdisplay_string24m; String 4mapplication_name24m; String 4mapplication_class24m; XrmOptionDescRec *4moptions24m; Cardinal 4mnum_options24m; int *4margc24m; String *4margv24m; 4mapp_context24m Specifies the application context. 4mdisplay_string0m Specifies the display string, or NULL. 4mapplication_name0m Specifies the name of the application instance, or NULL. 4mapplication_class0m Specifies the class name of this application, which is usually the generic name for all instances of this application. 4moptions24m Specifies how to parse the command line for any application-specific resources. The options argument is passed as a parameter to 4mXrmParseCommand24m. 4mnum_options24m Specifies the number of entries in the options list. 4margc24m Specifies a pointer to the number of command line parameters. 4margv24m Specifies the list of command line parameters. |__ The 4mXtOpenDisplay24m function calls 4mXOpenDisplay24m with the spec- ified 4mdisplay_string24m. If 4mdisplay_string24m is NULL, 4mXtOpenDis-0m 4mplay24m uses the current value of the -display option specified in 4margv24m. If no display is specified in 4margv24m, the user's default display is retrieved from the environment. On POSIX-based systems, this is the value of the 4mDISPLAY24m envi- ronment variable. 1m420m 1mX Toolkit Intrinsics X11 Release 6.40m If this succeeds, 4mXtOpenDisplay24m then calls 4mXtDisplayInitial-0m 4mize24m and passes it the opened display and the value of the -name option specified in 4margv24m as the application name. If no -name option is specified and 4mapplication_name24m is non- NULL, 4mapplication_name24m is passed to 4mXtDisplayInitialize24m. If 4mapplication_name24m is NULL and if the environment variable 4mRESOURCE_NAME24m is set, the value of 4mRESOURCE_NAME24m is used. Otherwise, the application name is the name used to invoke the program. On implementations that conform to ANSI C Hosted Environment support, the application name will be 4margv24m[0] less any directory and file type components, that is, the final component of 4margv24m[0], if specified. If 4margv24m[0] does not exist or is the empty string, the applica- tion name is ``main''. 4mXtOpenDisplay24m returns the newly opened display or NULL if it failed. See Section 7.12 for information regarding the use of 4mXtOpenDisplay24m in multiple threads. To close a display and remove it from an application con- text, use 4mXtCloseDisplay24m. __ | void XtCloseDisplay(4mdisplay24m) Display *4mdisplay24m; 4mdisplay24m Specifies the display. |__ The 4mXtCloseDisplay24m function calls 4mXCloseDisplay24m with the specified 4mdisplay24m as soon as it is safe to do so. If called from within an event dispatch (for example, a callback pro- cedure), 4mXtCloseDisplay24m does not close the display until the dispatch is complete. Note that applications need only call 4mXtCloseDisplay24m if they are to continue executing after clos- ing the display; otherwise, they should call 4mXtDestroyAppli-0m 4mcationContext24m. See Section 7.12 for information regarding the use of 4mXtCloseDisplay24m in multiple threads. 1m2.2. Establishing the Locale0m Resource databases are specified to be created in the cur- rent process locale. During display initialization prior to creating the per-screen resource database, the Intrinsics will call out to a specified application procedure to set the locale according to options found on the command line or in the per-display resource specifications. 1m430m 1mX Toolkit Intrinsics X11 Release 6.40m The callout procedure provided by the application is of type 4mXtLanguageProc24m. __ | typedef String (*XtLanguageProc)(Display*, String, XtPointer); Display *4mdisplay24m; String 4mlanguage24m; XtPointer 4mclient_data24m; 4mdisplay24m Passes the display. 4mlanguage24m Passes the initial language value obtained from the command line or server per-display resource specifications. 4mclient_data0m Passes the additional client data specified in the call to 4mXtSetLanguageProc24m. |__ The language procedure allows an application to set the locale to the value of the language resource determined by 4mXtDisplayInitialize24m. The function returns a new language string that will be subsequently used by 4mXtDisplayInitialize0m to establish the path for loading resource files. The returned string will be copied by the Intrinsics into new memory. Initially, no language procedure is set by the Intrinsics. To set the language procedure for use by 4mXtDisplayInitial-0m 4mize24m, use 4mXtSetLanguageProc24m. __ | XtLanguageProc XtSetLanguageProc(4mapp_context24m, 4mproc24m, 4mclient_data24m) XtAppContext 4mapp_context24m; XtLanguageProc 4mproc24m; XtPointer 4mclient_data24m; 4mapp_context0m Specifies the application context in which the language procedure is to be used, or NULL. 4mproc24m Specifies the language procedure. 4mclient_data0m Specifies additional client data to be passed to the language procedure when it is called. |__ 4mXtSetLanguageProc24m sets the language procedure that will be 1m440m 1mX Toolkit Intrinsics X11 Release 6.40m called from 4mXtDisplayInitialize24m for all subsequent Displays initialized in the specified application context. If 4mapp_context24m is NULL, the specified language procedure is registered in all application contexts created by the call- ing process, including any future application contexts that may be created. If 4mproc24m is NULL, a default language proce- dure is registered. 4mXtSetLanguageProc24m returns the previ- ously registered language procedure. If a language proce- dure has not yet been registered, the return value is unspecified, but if this return value is used in a subse- quent call to 4mXtSetLanguageProc24m, it will cause the default language procedure to be registered. The default language procedure does the following: · Sets the locale according to the environment. On ANSI C-based systems this is done by calling 4msetlocale24m( 4mLC_ALL24m, 4mlanguage24m ). If an error is encountered, a warning message is issued with 4mXtWarning24m. · Calls 4mXSupportsLocale24m to verify that the current locale is supported. If the locale is not supported, a warn- ing message is issued with 4mXtWarning24m and the locale is set to ``C''. · Calls 4mXSetLocaleModifiers24m specifying the empty string. · Returns the value of the current locale. On ANSI C- based systems this is the return value from a final call to 4msetlocale24m( 4mLC_ALL24m, NULL ). A client wishing to use this mechanism to establish locale can do so by calling 4mXtSetLanguageProc24m prior to 4mXtDis-0m 4mplayInitialize24m, as in the following example. Widget top; XtSetLanguageProc(NULL, NULL, NULL); top = XtOpenApplication(...); ... 1m2.3. Loading the Resource Database0m The 4mXtDisplayInitialize24m function first determines the lan- guage string to be used for the specified display. It then creates a resource database for the default screen of the display by combining the following sources in order, with the entries in the first named source having highest prece- dence: 1m450m 1mX Toolkit Intrinsics X11 Release 6.40m · Application command line (4margc24m, 4margv24m). · Per-host user environment resource file on the local host. · Per-screen resource specifications from the server. · Per-display resource specifications from the server or from the user preference file on the local host. · Application-specific user resource file on the local host. · Application-specific class resource file on the local host. When the resource database for a particular screen on the display is needed (either internally, or when 4mXtScreen-0m 4mDatabase24m is called), it is created in the following manner using the sources listed above in the same order: · A temporary database, the ``server resource database'', is created from the string returned by 4mXResourceMan-0m 4magerString24m or, if 4mXResourceManagerString24m returns NULL, the contents of a resource file in the user's home directory. On POSIX-based systems, the usual name for this user preference resource file is $HOME/1m.Xdefaults22m. · If a language procedure has been set, 4mXtDisplayInitial-0m 4mize24m first searches the command line for the option ``-xnlLanguage'', or for a -xrm option that specifies the xnlLanguage/XnlLanguage resource, as specified by Section 2.4. If such a resource is found, the value is assumed to be entirely in XPCS, the X Portable Charac- ter Set. If neither option is specified on the command line, 4mXtDisplayInitialize24m queries the server resource database (which is assumed to be entirely in XPCS) for the resource 4mname24m1m.xnlLanguage22m, class 4mClass24m1m.XnlLanguage0m where 4mname24m and 4mClass24m are the 4mapplication_name24m and 4mapplication_class24m specified to 4mXtDisplayInitialize24m. The language procedure is then invoked with the resource value if found, else the empty string. The string returned from the language procedure is saved for all future references in the Intrinsics that require the per-display language string. · The screen resource database is initialized by parsing the command line in the manner specified by Section 2.4. 1m460m 1mX Toolkit Intrinsics X11 Release 6.40m · If a language procedure has not been set, the initial database is then queried for the resource 4mname24m1m.xnlLan-0m 1mguage22m, class 4mClass24m1m.XnlLanguage 22mas specified above. If this database query fails, the server resource database is queried; if this query also fails, the language is determined from the environment; on POSIX-based sys- tems, this is done by retrieving the value of the 4mLANG0m environment variable. If no language string is found, the empty string is used. This language string is saved for all future references in the Intrinsics that require the per-display language string. · After determining the language string, the user's envi- ronment resource file is then merged into the initial resource database if the file exists. This file is user-, host-, and process-specific and is expected to contain user preferences that are to override those specifications in the per-display and per-screen resources. On POSIX-based systems, the user's environ- ment resource file name is specified by the value of the 4mXENVIRONMENT24m environment variable. If this envi- ronment variable does not exist, the user's home direc- tory is searched for a file named 4m.Xdefaults-host,0m 4mwhere24m 4mhost24m 4mis24m 4mthe24m 4mhost24m 4mname24m 4mof24m 4mthe24m 4mmachine24m 4mon24m 4mwhich24m 4mthe0m 4mapplication24m 4mis24m 4mrunning.0m · The per-screen resource specifications are then merged into the screen resource database, if they exist. These specifications are the string returned by 4mXScreenResourceString24m for the respective screen and are owned entirely by the user. · Next, the server resource database created earlier is merged into the screen resource database. The server property, and corresponding user preference file, are owned and constructed entirely by the user. · The application-specific user resource file from the local host is then merged into the screen resource database. This file contains user customizations and is stored in a directory owned by the user. Either the user or the application or both can store resource specifications in the file. Each should be prepared to find and respect entries made by the other. The file name is found by calling 4mXrmSetDatabase24m with the cur- rent screen resource database, after preserving the original display-associated database, then calling 4mXtResolvePathname24m with the parameters (4mdisplay24m, NULL, NULL, NULL, 4mpath24m, NULL, 0, NULL), where 4mpath24m is defined in an operating-system-specific way. On POSIX-based 1m470m 1mX Toolkit Intrinsics X11 Release 6.40m systems, 4mpath24m is defined to be the value of the envi- ronment variable 4mXUSERFILESEARCHPATH24m if this is defined. If 4mXUSERFILESEARCHPATH24m is not defined, an implementation-dependent default value is used. This default value is constrained in the following manner: - If the environment variable 4mXAPPLRESDIR24m is not defined, the default 4mXUSERFILESEARCHPATH24m must con- tain at least six entries. These entries must con- tain $HOME as the directory prefix, plus the follow- ing substitutions: 1. %C, %N, %L or %C, %N, %l, %t, %c 2. %C, %N, %l 3. %C, %N 4. %N, %L or %N, %l, %t, %c 5. %N, %l 6. %N The order of these six entries within the path must be as given above. The order and use of substitu- tions within a given entry are implementation-depen- dent. - If 4mXAPPLRESDIR24m is defined, the default 4mXUSERFILE-0m 4mSEARCHPATH24m must contain at least seven entries. These entries must contain the following directory prefixes and substitutions: 1. $XAPPLRESDIR with %C, %N, %L or %C, %N, %l, %t, %c 2. $XAPPLRESDIR with %C, %N, %l 3. $XAPPLRESDIR with %C, %N 4. $XAPPLRESDIR with %N, %L or %N, %l, %t, %c 5. $XAPPLRESDIR with %N, %l 6. $XAPPLRESDIR with %N 7. $HOME with %N The order of these seven entries within the path must be as given above. The order and use of sub- stitutions within a given entry are implementation- dependent. · Last, the application-specific class resource file from the local host is merged into the screen resource data- base. This file is owned by the application and is usually installed in a system directory when the appli- cation is installed. It may contain sitewide cus- tomizations specified by the system manager. The name of the application class resource file is found by calling 4mXtResolvePathname24m with the parameters (4mdisplay24m, ``app-defaults'', NULL, NULL, NULL, NULL, 0, NULL). 1m480m 1mX Toolkit Intrinsics X11 Release 6.40m This file is expected to be provided by the developer of the application and may be required for the applica- tion to function properly. A simple application that wants to be assured of having a minimal set of resources in the absence of its class resource file can declare fallback resource specifications with 4mXtAppSet-0m 4mFallbackResources24m. Note that the customization substi- tution string is retrieved dynamically by 4mXtRe-0m 4msolvePathname24m so that the resolved file name of the application class resource file can be affected by any of the earlier sources for the screen resource data- base, even though the contents of the class resource file have lowest precedence. After calling 4mXtRe-0m 4msolvePathname24m, the original display-associated database is restored. To obtain the resource database for a particular screen, use 4mXtScreenDatabase24m. __ | XrmDatabase XtScreenDatabase(4mscreen24m) Screen *4mscreen24m; 4mscreen24m Specifies the screen whose resource database is to be returned. |__ The 4mXtScreenDatabase24m function returns the fully merged resource database as specified above, associated with the specified screen. If the specified 4mscreen24m does not belong to a 4mDisplay24m initialized by 4mXtDisplayInitialize24m, the results are undefined. To obtain the default resource database associated with a particular display, use 4mXtDatabase24m. __ | XrmDatabase XtDatabase(4mdisplay24m) Display *4mdisplay24m; 4mdisplay24m Specifies the display. |__ The 4mXtDatabase24m function is equivalent to 4mXrmGetDatabase24m. It returns the database associated with the specified display, or NULL if a database has not been set. 1m490m 1mX Toolkit Intrinsics X11 Release 6.40m To specify a default set of resource values that will be used to initialize the resource database if no application- specific class resource file is found (the last of the six sources listed above), use 4mXtAppSetFallbackResources24m. __ | void XtAppSetFallbackResources(4mapp_context24m, 4mspecification_list24m) XtAppContext 4mapp_context24m; String *4mspecification_list24m; 4mapp_context24m Specifies the application context in which the fallback specifications will be used. 4mspecification_list0m Specifies a NULL-terminated list of resource specifications to preload the database, or NULL. |__ Each entry in 4mspecification_list24m points to a string in the format of 4mXrmPutLineResource24m. Following a call to 4mXtAppSet-0m 4mFallbackResources24m, when a resource database is being created for a particular screen and the Intrinsics are not able to find or read an application-specific class resource file according to the rules given above and if 4mspecification_list0m is not NULL, the resource specifications in 4mspecifica-0m 4mtion_list24m will be merged into the screen resource database in place of the application-specific class resource file. 4mXtAppSetFallbackResources24m is not required to copy 4mspecifica-0m 4mtion_list24m; the caller must ensure that the contents of the list and of the strings addressed by the list remain valid until all displays are initialized or until 4mXtAppSetFall-0m 4mbackResources24m is called again. The value NULL for 4mspecifi-0m 4mcation_list24m removes any previous fallback resource specifi- cation for the application context. The intended use for fallback resources is to provide a minimal number of resources that will make the application usable (or at least terminate with helpful diagnostic messages) when some prob- lem exists in finding and loading the application defaults file. 1m2.4. Parsing the Command Line0m The 4mXtOpenDisplay24m function first parses the command line for the following options: -display Specifies the display name for 4mXOpenDisplay24m. -name Sets the resource name prefix, which overrides the application name passed to 4mXtOpenDisplay24m. 1m500m 1mX Toolkit Intrinsics X11 Release 6.40m -xnllanguage Specifies the initial language string for estab- lishing locale and for finding application class resource files. 4mXtDisplayInitialize24m has a table of standard command line options that are passed to 4mXrmParseCommand24m for adding resources to the resource database, and it takes as a param- eter additional application-specific resource abbreviations. The format of this table is described in Section 15.9 in 4mXlib24m 4m--24m 4mC24m 4mLanguage24m 4mX24m 4mInterface24m. __ | typedef enum { XrmoptionNoArg, /* Value is specified in OptionDescRec.value */ XrmoptionIsArg, /* Value is the option string itself */ XrmoptionStickyArg, /* Value is characters immediately following option */ XrmoptionSepArg, /* Value is next argument in argv */ XrmoptionResArg, /* Use the next argument as input to XrmPutLineResource*/ XrmoptionSkipArg, /* Ignore this option and the next argument in argv */ XrmoptionSkipNArgs, /* Ignore this option and the next */ /* OptionDescRec.value arguments in argv */ XrmoptionSkipLine /* Ignore this option and the rest of argv */ } XrmOptionKind; typedef struct { char *option; /* Option name in argv */ char *specifier; /* Resource name (without application name) */ XrmOptionKind argKind;/* Location of the resource value */ XPointer value; /* Value to provide if XrmoptionNoArg */ } XrmOptionDescRec, *XrmOptionDescList; |__ The standard table contains the following entries: ----------------------------------------------------------------------- Option String Resource Name Argument Kind Resource Value ----------------------------------------------------------------------- -background *background SepArg next argument -bd *borderColor SepArg next argument -bg *background SepArg next argument -borderwidth .borderWidth SepArg next argument -bordercolor *borderColor SepArg next argument -bw .borderWidth SepArg next argument -display .display SepArg next argument -fg *foreground SepArg next argument -fn *font SepArg next argument -font *font SepArg next argument -foreground *foreground SepArg next argument -geometry .geometry SepArg next argument 1m510m 1mX Toolkit Intrinsics X11 Release 6.40m ----------------------------------------------------------------------- -iconic .iconic NoArg ``true'' -name .name SepArg next argument -reverse .reverseVideo NoArg ``on'' -rv .reverseVideo NoArg ``on'' +rv .reverseVideo NoArg ``off'' -selectionTimeout .selectionTimeout SepArg next argument -synchronous .synchronous NoArg ``on'' +synchronous .synchronous NoArg ``off'' -title .title SepArg next argument -xnllanguage .xnlLanguage SepArg next argument -xrm next argument ResArg next argument -xtsessionID .sessionID SepArg next argument ----------------------------------------------------------------------- Note that any unique abbreviation for an option name in the standard table or in the application table is accepted. If reverseVideo is 4mTrue24m, the values of 4mXtDefaultForeground0m and 4mXtDefaultBackground24m are exchanged for all screens on the Display. The value of the synchronous resource specifies whether or not Xlib is put into synchronous mode. If a value is found in the resource database during display initialization, 4mXtDisplayInitialize24m makes a call to 4mXSynchronize24m for all display connections currently open in the application con- text. Therefore, when multiple displays are initialized in the same application context, the most recent value speci- fied for the synchronous resource is used for all displays in the application context. The value of the selectionTimeout resource applies to all displays opened in the same application context. When mul- tiple displays are initialized in the same application con- text, the most recent value specified is used for all dis- plays in the application context. The -xrm option provides a method of setting any resource in an application. The next argument should be a quoted string identical in format to a line in the user resource file. For example, to give a red background to all command buttons in an application named 4mxmh24m, you can start it up as xmh -xrm 'xmh*Command.background: red' When it parses the command line, 4mXtDisplayInitialize24m merges the application option table with the standard option table before calling the Xlib 4mXrmParseCommand24m function. An entry in the application table with the same name as an entry in the standard table overrides the standard table entry. If 1m520m 1mX Toolkit Intrinsics X11 Release 6.40m an option name is a prefix of another option name, both names are kept in the merged table. The Intrinsics reserve all option names beginning with the characters ``-xt'' for future standard uses. 1m2.5. Creating Widgets0m The creation of widget instances is a three-phase process: 1. The widgets are allocated and initialized with resources and are optionally added to the managed sub- set of their parent. 2. All composite widgets are notified of their managed children in a bottom-up traversal of the widget tree. 3. The widgets create X windows, which then are mapped. To start the first phase, the application calls 4mXtCreateWid-0m 4mget24m for all its widgets and adds some (usually, most or all) of its widgets to their respective parents' managed set by calling 4mXtManageChild24m. To avoid an 4mO24m(4mn24m2) creation process where each composite widget lays itself out each time a wid- get is created and managed, parent widgets are not notified of changes in their managed set during this phase. After all widgets have been created, the application calls 4mXtRealizeWidget24m with the top-level widget to execute the second and third phases. 4mXtRealizeWidget24m first recursively traverses the widget tree in a postorder (bottom-up) traver- sal and then notifies each composite widget with one or more managed children by means of its change_managed procedure. Notifying a parent about its managed set involves geometry layout and possibly geometry negotiation. A parent deals with constraints on its size imposed from above (for exam- ple, when a user specifies the application window size) and suggestions made from below (for example, when a primitive child computes its preferred size). One difference between the two can cause geometry changes to ripple in both direc- tions through the widget tree. The parent may force some of its children to change size and position and may issue geom- etry requests to its own parent in order to better accommo- date all its children. You cannot predict where anything will go on the screen until this process finishes. Consequently, in the first and second phases, no X windows are actually created, because it is likely that they will get moved around after creation. This avoids unnecessary requests to the X server. 1m530m 1mX Toolkit Intrinsics X11 Release 6.40m Finally, 4mXtRealizeWidget24m starts the third phase by making a preorder (top-down) traversal of the widget tree, allocates an X window to each widget by means of its realize proce- dure, and finally maps the widgets that are managed. 1m2.5.1. Creating and Merging Argument Lists0m Many Intrinsics functions may be passed pairs of resource names and values. These are passed as an arglist, a pointer to an array of 4mArg24m structures, which contains __ | typedef struct { String name; XtArgVal value; } Arg, *ArgList; |__ where 4mXtArgVal24m is as defined in Section 1.5. If the size of the resource is less than or equal to the size of an 4mXtArgVal24m, the resource value is stored directly in 4mvalue24m; otherwise, a pointer to it is stored in 4mvalue24m. To set values in an 4mArgList24m, use 4mXtSetArg24m. __ | void XtSetArg(4marg24m, 4mname24m, 4mvalue24m) Arg 4marg24m; String 4mname24m; XtArgVal 4mvalue24m; 4marg24m Specifies the 4mname/value24m pair to set. 4mname24m Specifies the name of the resource. 4mvalue24m Specifies the value of the resource if it will fit in an 4mXtArgVal24m, else the address. |__ The 4mXtSetArg24m function is usually used in a highly stylized manner to minimize the probability of making a mistake; for example: Arg args[20]; int n; n = 0; 1m540m 1mX Toolkit Intrinsics X11 Release 6.40m XtSetArg(args[n], XtNheight, 100);n++; XtSetArg(args[n], XtNwidth, 200);n++; XtSetValues(widget, args, n); Alternatively, an application can statically declare the argument list and use 4mXtNumber24m: static Args args[] = { {XtNheight, (XtArgVal) 100}, {XtNwidth, (XtArgVal) 200}, }; XtSetValues(Widget, args, XtNumber(args)); Note that you should not use expressions with side effects such as auto-increment or auto-decrement within the first argument to 4mXtSetArg24m. 4mXtSetArg24m can be implemented as a macro that evaluates the first argument twice. To merge two arglist arrays, use 4mXtMergeArgLists24m. __ | ArgList XtMergeArgLists(4margs124m, 4mnum_args124m, 4margs224m, 4mnum_args224m) ArgList 4margs124m; Cardinal 4mnum_args124m; ArgList 4margs224m; Cardinal 4mnum_args224m; 4margs124m Specifies the first argument list. 4mnum_args124m Specifies the number of entries in the first argu- ment list. 4margs224m Specifies the second argument list. 4mnum_args224m Specifies the number of entries in the second argument list. |__ The 4mXtMergeArgLists24m function allocates enough storage to hold the combined arglist arrays and copies them into it. Note that it does not check for duplicate entries. The length of the returned list is the sum of the lengths of the specified lists. When it is no longer needed, free the returned storage by using 4mXtFree24m. All Intrinsics interfaces that require 4mArgList24m arguments have analogs conforming to the ANSI C variable argument list 1m550m 1mX Toolkit Intrinsics X11 Release 6.40m (traditionally called ``varargs'') calling convention. The name of the analog is formed by prefixing ``Va'' to the name of the corresponding 4mArgList24m procedure; e.g., 4mXtVaCreateWid-0m 4mget24m. Each procedure named 1mXtVa4m22msomething24m takes as its last arguments, in place of the corresponding 4mArgList24m/ 4mCardinal0m parameters, a variable parameter list of resource name and value pairs where each name is of type 4mString24m and each value is of type 4mXtArgVal24m. The end of the list is identified by a 4mname24m entry containing NULL. Developers writing in the C language wishing to pass resource name and value pairs to any of these interfaces may use the 4mArgList24m and varargs forms interchangeably. Two special names are defined for use only in varargs lists: 4mXtVaTypedArg24m and 4mXtVaNestedList24m. __ | #define XtVaTypedArg "XtVaTypedArg" |__ If the name 4mXtVaTypedArg24m is specified in place of a resource name, then the following four arguments are interpreted as a 4mname/type/value/size24m tuple 4mwhere24m name is of type 4mString24m, 4mtype24m is of type 4mString24m, 4mvalue24m is of type 4mXtArgVal24m, and 4msize0m is of type int. When a varargs list containing 4mXtVaTypedArg0m is processed, a resource type conversion (see Section 9.6) is performed if necessary to convert the value into the for- mat required by the associated resource. If 4mtype24m is XtRString, then 4mvalue24m contains a pointer to the string and 4msize24m contains the number of bytes allocated, including the trailing null byte. If 4mtype24m is not XtRString, then 4mif24m size is less than or equal to 1msizeof22m(1mXtArgVal22m), the value should be the data cast to the type 4mXtArgVal24m, otherwise 4mvalue24m is a pointer to the data. If the type conversion fails for any reason, a warning message is issued and the list entry is skipped. __ | #define XtVaNestedList "XtVaNestedList" |__ If the name 4mXtVaNestedList24m is specified in place of a resource name, then the following argument is interpreted as an 4mXtVarArgsList24m value, which specifies another varargs list that is logically inserted into the original list at the point of declaration. The end of the nested list is identi- fied with a name entry containing NULL. Varargs lists may nest to any depth. 1m560m 1mX Toolkit Intrinsics X11 Release 6.40m To dynamically allocate a varargs list for use with 4mXtVaNestedList24m in multiple calls, use 4mXtVaCreateArgsList24m. __ | typedef XtPointer XtVarArgsList; XtVarArgsList XtVaCreateArgsList(4munused24m, ...) XtPointer 4munused24m; 4munused24m This argument is not currently used and must be specified as NULL. ... Specifies a variable parameter list of resource name and value pairs. |__ The 4mXtVaCreateArgsList24m function allocates memory and copies its arguments into a single list pointer, which may be used with 4mXtVaNestedList24m. The end of both lists is identified by a 4mname24m entry containing NULL. Any entries of type 4mXtVaType-0m 4mdArg24m are copied as specified without applying conversions. Data passed by reference (including Strings) are not copied, only the pointers themselves; the caller must ensure that the data remain valid for the lifetime of the created varargs list. The list should be freed using 4mXtFree24m when no longer needed. Use of resource files and of the resource database is gener- ally encouraged over lengthy arglist or varargs lists when- ever possible in order to permit modification without recom- pilation. 1m2.5.2. Creating a Widget Instance0m To create an instance of a widget, use 4mXtCreateWidget24m. 1m570m 1mX Toolkit Intrinsics X11 Release 6.40m __ | Widget XtCreateWidget(4mname24m, 4mobject_class24m, 4mparent24m, 4margs24m, 4mnum_args24m) String 4mname24m; WidgetClass 4mobject_class24m; Widget 4mparent24m; ArgList 4margs24m; Cardinal 4mnum_args24m; 4mname24m Specifies the resource instance name for the cre- ated widget, which is used for retrieving resources and, for that reason, should not be the same as any other widget that is a child of the same parent. 4mobject_class0m Specifies the widget class pointer for the created object. Must be 1mobjectClass 22mor any subclass thereof. 4mparent24m Specifies the parent widget. Must be of class Object or any subclass thereof. 4margs24m Specifies the argument list to override any other resource specifications. 4mnum_args24m Specifies the number of entries in the argument list. |__ The 4mXtCreateWidget24m function performs all the boilerplate operations of widget creation, doing the following in order: · Checks to see if the class_initialize procedure has been called for this class and for all superclasses and, if not, calls those necessary in a superclass-to- subclass order. · If the specified class is not 4mcoreWidgetClass24m or a sub- class thereof, and the parent's class is a subclass of 4mcompositeWidgetClass24m and either no extension record in the parent's composite class part extension field exists with the 4mrecord_type24m 4mNULLQUARK24m or the 4maccepts_objects24m field in the extension record is 4mFalse24m, 4mXtCreateWidget24m issues a fatal error; see Section 3.1 and Chapter 12. · If the specified class contains an extension record in the object class part 4mextension24m field with 4mrecord_type0m 4mNULLQUARK24m and the 4mallocate24m field is not NULL, the pro- cedure is invoked to allocate memory for the widget instance. If the parent is a member of the class 4mcon-0m 4mstraintWidgetClass24m, the procedure also allocates memory for the parent's constraints and stores the address of 1m580m 1mX Toolkit Intrinsics X11 Release 6.40m this memory into the 4mconstraints24m field. If no allocate procedure is found, the Intrinsics allocate memory for the widget and, when applicable, the constraints, and initializes the 4mconstraints24m field. · Initializes the Core nonresource data fields 4mself24m, 4mpar-0m 4ment24m, 4mwidget_class24m, 4mbeing_destroyed24m, 4mname24m, 4mmanaged24m, 4mwin-0m 4mdow24m, 4mvisible24m, 4mpopup_list24m, and 4mnum_popups24m. · Initializes the resource fields (for example, 4mback-0m 4mground_pixel24m) by using the 4mCoreClassPart24m resource lists specified for this class and all superclasses. · If the parent is a member of the class 4mconstraintWid-0m 4mgetClass24m, initializes the resource fields of the con- straints record by using the 4mConstraintClassPart0m resource lists specified for the parent's class and all superclasses up to 4mconstraintWidgetClass24m. · Calls the initialize procedures for the widget starting at the Object initialize procedure on down to the wid- get's initialize procedure. · If the parent is a member of the class 4mconstraintWid-0m 4mgetClass24m, calls the 4mConstraintClassPart24m initialize pro- cedures, starting at 4mconstraintWidgetClass24m on down to the parent's 4mConstraintClassPart24m initialize procedure. · If the parent is a member of the class 4mcompositeWidget-0m 4mClass24m, puts the widget into its parent's children list by calling its parent's insert_child procedure. For further information, see Section 3.1. To create an instance of a widget using varargs lists, use 4mXtVaCreateWidget24m. 1m590m 1mX Toolkit Intrinsics X11 Release 6.40m __ | Widget XtVaCreateWidget(4mname24m, 4mobject_class24m, 4mparent24m, ...) String 4mname24m; WidgetClass 4mobject_class24m; Widget 4mparent24m; 4mname24m Specifies the resource name for the created wid- get. 4mobject_class0m Specifies the widget class pointer for the created object. Must be 1mobjectClass 22mor any subclass thereof. 4mparent24m Specifies the parent widget. Must be of class Object or any subclass thereof. ... Specifies the variable argument list to override any other resource specifications. |__ The 4mXtVaCreateWidget24m procedure is identical in function to 4mXtCreateWidget24m with the 4margs24m and 4mnum_args24m parameters replaced by a varargs list, as described in Section 2.5.1. 1m2.5.3. Creating an Application Shell Instance0m An application can have multiple top-level widgets, each of which specifies a unique widget tree that can potentially be on different screens or displays. An application uses 4mXtAp-0m 4mpCreateShell24m to create independent widget trees. 1m600m 1mX Toolkit Intrinsics X11 Release 6.40m __ | Widget XtAppCreateShell(4mname24m, 4mapplication_class24m, 4mwidget_class24m, 4mdisplay24m, 4margs24m, 4mnum_args24m) String 4mname24m; String 4mapplication_class24m; WidgetClass 4mwidget_class24m; Display *4mdisplay24m; ArgList 4margs24m; Cardinal 4mnum_args24m; 4mname24m Specifies the instance name of the shell widget. If 4mname24m is NULL, the application name passed to 4mXtDisplayInitialize24m is used. 4mapplication_class0m Specifies the resource class string to be used in place of the widget 4mclass_name24m string when 4mwidget_class24m is 4mapplicationShellWidgetClass24m or a subclass thereof. 4mwidget_class0m Specifies the widget class for the top-level widget (e.g., 4mapplicationShellWidgetClass24m). 4mdisplay24m Specifies the display for the default screen and for the resource database used to retrieve the shell widget resources. 4margs24m Specifies the argument list to override any other resource specifications. 4mnum_args24m Specifies the number of entries in the argument list. |__ The 4mXtAppCreateShell24m function creates a new shell widget instance as the root of a widget tree. The screen resource for this widget is determined by first scanning 4margs24m for the XtNscreen argument. If no XtNscreen argument is found, the resource database associated with the default screen of the specified display is queried for the resource 4mname24m.screen, class 4mClass24m.Screen where 4mClass24m is the specified 4mapplica-0m 4mtion_class24m if 4mwidget_class24m is 4mapplicationShellWidgetClass24m or a subclass thereof. If 4mwidget_class24m is not 4mapplication-0m 4mShellWidgetClass24m or a subclass, 4mClass24m is the 4mclass_name0m field from the 4mCoreClassPart24m of the specified 4mwidget_class24m. If this query fails, the default screen of the specified display is used. Once the screen is determined, the resource database associated with that screen is used to retrieve all remaining resources for the shell widget not specified in 4margs24m. The widget name and 4mClass24m as determined above are used as the leftmost (i.e., root) components in all fully qualified resource names for objects within this widget tree. 1m610m 1mX Toolkit Intrinsics X11 Release 6.40m If the specified widget class is a subclass of WMShell, the name and 4mClass24m as determined above will be stored into the 4mWM_CLASS24m property on the widget's window when it becomes realized. If the specified 4mwidget_class24m is 4mapplication-0m 4mShellWidgetClass24m or a subclass thereof, the 4mWM_COMMAND24m prop- erty will also be set from the values of the XtNargv and XtNargc resources. To create multiple top-level shells within a single (logi- cal) application, you can use one of two methods: · Designate one shell as the real top-level shell and create the others as pop-up children of it by using 4mXtCreatePopupShell24m. · Have all shells as pop-up children of an unrealized top-level shell. The first method, which is best used when there is a clear choice for what is the main window, leads to resource speci- fications like the following: xmail.geometry:... (the main window) xmail.read.geometry:...(the read window) xmail.compose.geometry:...(the compose window) The second method, which is best if there is no main window, leads to resource specifications like the following: xmail.headers.geometry:...(the headers window) xmail.read.geometry:...(the read window) xmail.compose.geometry:...(the compose window) To create a top-level widget that is the root of a widget tree using varargs lists, use 4mXtVaAppCreateShell24m. 1m620m 1mX Toolkit Intrinsics X11 Release 6.40m __ | Widget XtVaAppCreateShell(4mname24m, 4mapplication_class24m, 4mwidget_class24m, 4mdisplay24m, ...) String 4mname24m; String 4mapplication_class24m; WidgetClass 4mwidget_class24m; Display *4mdisplay24m; 4mname24m Specifies the instance name of the shell wid- get. If 4mname24m is NULL, the application name passed to 4mXtDisplayInitialize24m is used. 4mapplication_class0m Specifies the resource class string to be used in place of the widget 4mclass_name24m string when 4mwidget_class24m is 4mapplicationShellWidget-0m 4mClass24m or a subclass thereof. 4mwidget_class24m Specifies the widget class for the top-level widget. 4mdisplay24m Specifies the display for the default screen and for the resource database used to retrieve the shell widget resources. ... Specifies the variable argument list to over- ride any other resource specifications. |__ The 4mXtVaAppCreateShell24m procedure is identical in function to 4mXtAppCreateShell24m with the 4margs24m and 4mnum_args24m parameters replaced by a varargs list, as described in Section 2.5.1. 1m2.5.4. Convenience Procedure to Initialize an Application0m To initialize the Intrinsics internals, create an applica- tion context, open and initialize a display, and create the initial root shell instance, an application may use 4mXtOpe-0m 4mnApplication24m or 4mXtVaOpenApplication24m. 1m630m 1mX Toolkit Intrinsics X11 Release 6.40m __ | Widget XtOpenApplication(4mapp_context_return24m, 4mapplication_class24m, 4moptions24m, 4mnum_options24m, 4margc_in_out24m, 4margv_in_out24m, 4mfallback_resources24m, 4mwidget_class24m, 4margs24m, 4mnum_args24m) XtAppContext *4mapp_context_return24m; String 4mapplication_class24m; XrmOptionDescList 4moptions24m; Cardinal 4mnum_options24m; int *4margc_in_out24m; String *4margv_in_out24m; String *4mfallback_resources24m; WidgetClass 4mwidget_class24m; ArgList 4margs24m; Cardinal 4mnum_args24m; 4mapp_context_return0m Returns the application context, if non-NULL. 4mapplication_class0m Specifies the class name of the application. 4moptions24m Specifies the command line options table. 4mnum_options24m Specifies the number of entries in 4moptions24m. 4margc_in_out24m Specifies a pointer to the number of command line arguments. 4margv_in_out24m Specifies a pointer to the command line argu- ments. 4mfallback_resources0m Specifies resource values to be used if the application class resource file cannot be opened or read, or NULL. 4mwidget_class24m Specifies the class of the widget to be cre- ated. Must be shellWidgetClass or a sub- class. 4margs24m Specifies the argument list to override any other resource specifications for the created shell widget. 4mnum_args24m Specifies the number of entries in the argu- ment list. |__ The 4mXtOpenApplication24m function calls 4mXtToolkitInitialize0m followed by 4mXtCreateApplicationContext24m, then calls 4mXtOpenDisplay24m with 4mdisplay_string24m NULL and 4mapplication_name0m NULL, and finally calls 4mXtAppCreateShell24m with 4mname24m NULL, the specified 4mwidget_class24m, an argument list and count, and returns the created shell. The recommended 4mwidget_class24m is 1m640m 1mX Toolkit Intrinsics X11 Release 6.40m 4msessionShellWidgetClass24m. The argument list and count are created by merging the specified 4margs24m and 4mnum_args24m with a list containing the specified 4margc24m and 4margv24m. The modified 4margc24m and 4margv24m returned by 4mXtDisplayInitialize24m are returned in 4margc_in_out24m and 4margv_in_out24m. If 4mapp_context_return24m is not NULL, the created application context is also returned. If the display specified by the command line cannot be opened, an error message is issued and 4mXtOpenApplication0m terminates the application. If 4mfallback_resources24m is non- NULL, 4mXtAppSetFallbackResources24m is called with the value prior to calling 4mXtOpenDisplay24m. 1m650m 1mX Toolkit Intrinsics X11 Release 6.40m __ | Widget XtVaOpenApplication(4mapp_context_return24m, 4mapplication_class24m, 4moptions24m, 4mnum_options24m, 4margc_in_out24m, 4margv_in_out24m, 4mfallback_resources24m, 4mwidget_class24m, ...) XtAppContext *4mapp_context_return24m; String 4mapplication_class24m; XrmOptionDescList 4moptions24m; Cardinal 4mnum_options24m; int *4margc_in_out24m; String *4margv_in_out24m; String *4mfallback_resources24m; WidgetClass 4mwidget_class24m; 4