X Toolkit Intrinsics -- C Language Interface
X Window System
X Version 11, Release 6.4
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 documentation 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 PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE X CONSORTIUM 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 Consortium 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 documentation 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 permission 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.
Acknowledgments
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 contributors 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.
Finally, a special thanks to Mike Chow, whose extensive performance analysis of the X10 toolkit provided the justification to redesign it entirely for X11.
Joel McCormack Western Software Laboratory Digital Equipment Corporation March 1988
xii
The current design of the Intrinsics has benefited greatly from the input of several dedicated reviewers in the membership of the X Consortium. In addition to those already mentioned, 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 implementation 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.
Ralph R. Swick December 1989 and July 1991
xii
The Release 6 Intrinsics is a result of the collaborative efforts of participants in the X Consortium's intrinsics 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 contributions:
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 contributions: 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 Peterson, 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
xiii
About This Manual
X Toolkit Intrinsics -- C Language Interface 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 application 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 programmer will have to be familiar with all the information.) Therefore, all entries in the table of contents that are printed in bold indicate 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.
This document uses the following conventions:
| Global symbols are printed in this special font. These can be either function names, symbols defined in include files, data types, or structure names. Arguments to functions, procedures, or macros are printed in italics. |
| Each function is introduced by a general discussion that distinguishes it from other functions. The function 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 specifies or, in the case of multiple arguments, the word specify. The explanations for all arguments that are returned to you start with the word returns or, in the case of multiple arguments, the word return. |
i
Chapter 1
Intrinsics and Widgets
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.
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 policy or style.
The Intrinsics use object-oriented programming techniques to supply a consistent architecture for constructing and composing 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 (subclassing) or by writing entirely new widgets following the established 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 specification refers uniformly to widgets and Core 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 widget actually means ``widget'' or ``object.''
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 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 programming 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 client refers to any module, widget, or application that calls an Intrinsics procedure.
Applications that use the Intrinsics mechanisms must include the header files <X11/Intrinsic.h> and <X11/StringDefs.h>, or their equivalent, and they may also include <X11/Xatoms.h> and <X11/Shell.h>. In addition, widget implementations should include <X11/IntrinsicP.h> instead of <X11/Intrinsic.h>.
The applications must also include the additional header files for each widget class that they are to use (for example, <X11/Xaw/Label.h> or <X11/Xaw/Scrollbar.h>). On a POSIX-based system, the Intrinsics object library file is named libXt.a and is usually referenced as -lXt when linking the application.
All functions defined in this specification except those specified below may be implemented as C macros with arguments. C applications may use ``#undef'' to remove a macro definition and ensure that the actual function is referenced. 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 protected 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: XtCheckSubclass, XtNew, XtNumber, XtOffsetOf, XtOffset, and XtSetArg.
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 dynamically allocated and contains state information. Some 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 widget 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 values. |
| 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, Composite, and Constraint, and ends with a discussion of widget classing.
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 CoreClassPart and CorePart structures.
All widget classes contain the fields defined in the CoreClassPart 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 WidgetClass and CoreWidgetClass are defined with only this set of fields.
__
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 IntrinsicP.h:
__
extern WidgetClassRec widgetClassRec; #define coreClassRec widgetClassRec
__
In Intrinsic.h:
__
extern WidgetClass widgetClass, coreWidgetClass;
__
The opaque types Widget and WidgetClass and the opaque variable widgetClass are defined for generic actions on widgets. In order to make these types opaque and ensure that the compiler does not allow applications to access private data, the Intrinsics use incomplete structure definitions in Intrinsic.h:
__
typedef struct _WidgetClassRec *WidgetClass, *CoreWidgetClass;
__
All widget instances contain the fields defined in the CorePart structure.
__
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 Widget 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 compiler does not allow applications to access private data, the Intrinsics use incomplete structure definitions in Intrinsic.h.
__
typedef struct _WidgetRec *Widget, *CoreWidget;
__
The resource names, classes, and representation types specified in the coreClassRec resource list are
Additional resources are defined for all widgets via the objectClassRec and rectObjClassRec resource lists; see Sections 12.2 and 12.3 for details.
The default values for the Core fields, which are filled in by the Intrinsics, from the resource lists, and by the initialize procedures, are
XtUnspecifiedPixmap is a symbolic constant guaranteed to be unequal to any valid Pixmap id, None, and ParentRelative.
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 CompositeClassPart and CompositePart structures.
In addition to the Core class fields, widgets of the Composite class have the following class fields.
__
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 CompositeClassPart with record_type equal to NULLQUARK is CompositeClassExtensionRec.
__
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 immediately 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 IntrinsicP.h:
__
extern CompositeClassRec compositeClassRec;
__
In Intrinsic.h:
__
extern WidgetClass compositeWidgetClass;
__
The opaque types CompositeWidget and CompositeWidgetClass and the opaque variable compositeWidgetClass are defined for generic operations on widgets whose class is Composite or a subclass of Composite. The symbolic constant for the CompositeClassExtension version identifier is XtCompositeExtensionVersion (see Section 1.6.12). Intrinsic.h uses an incomplete structure definition to ensure that the compiler catches attempts to access private data.
__
typedef struct _CompositeClassRec *CompositeWidgetClass;
__
In addition to the Core instance fields, widgets of the Composite class have the following instance fields defined in the CompositePart 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 immediately following the Core instance fields.
__
typedef struct {
CorePart core;
CompositePart composite;
} CompositeRec, *CompositeWidget;
__
Intrinsic.h uses an incomplete structure definition to ensure that the compiler catches attempts to access private data.
__
typedef struct _CompositeRec *CompositeWidget;
__
The resource names, classes, and representation types that are specified in the compositeClassRec resource list are
The default values for the Composite fields, which are filled in from the Composite resource list and by the Composite initialize procedure, are
The children, num_children, and insert_position 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.
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 ConstraintClassPart and ConstraintPart structures.
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 ConstraintClassPart with record_type equal to NULLQUARK is ConstraintClassExtensionRec.
__
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 immediately 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 IntrinsicP.h:
__
extern ConstraintClassRec constraintClassRec;
__
In Intrinsic.h:
__
extern WidgetClass constraintWidgetClass;
__
The opaque types ConstraintWidget and ConstraintWidgetClass and the opaque variable constraintWidgetClass are defined for generic operations on widgets whose class is Constraint or a subclass of Constraint. The symbolic constant for the ConstraintClassExtension version identifier is XtConstraintExtensionVersion (see Section 1.6.12). Intrinsic.h uses an incomplete structure definition to ensure that the compiler catches attempts to access private data.
__
typedef struct _ConstraintClassRec *ConstraintWidgetClass;
__
In addition to the Core and Composite instance fields, widgets of the Constraint class have the following unused instance fields defined in the ConstraintPart structure
__
typedef struct {
int empty;
} ConstraintPart;
__
Constraint widgets have the Constraint instance fields immediately following the Composite instance fields.
__
typedef struct {
CorePart core;
CompositePart composite;
ConstraintPart constraint;
} ConstraintRec, *ConstraintWidget;
__
Intrinsic.h uses an incomplete structure definition to ensure that the compiler catches attempts to access private data.
__
typedef struct _ConstraintRec *ConstraintWidget;
__
The constraintClassRec core_class and constraint_class resources fields are NULL, and the num_resources fields are zero; no additional resources beyond those declared by the superclasses are defined for Constraint.
To increase the portability of widget and application source code between different system environments, the Intrinsics define several types whose precise representation is explicitly dependent upon, and chosen by, each individual implementation of the Intrinsics.
These implementation-defined types are
| Boolean | A 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 True. |
| Cardinal | An unsigned integer datum with a minimum range of [0..2^16-1]. |
| Dimension | An unsigned integer datum with a minimum range of [0..2^16-1]. |
| Position | A signed integer datum with a minimum range of [-2^15..2^15-1]. |
| XtPointer | A datum large enough to contain the largest of a char*, int*, function pointer, structure pointer, or long value. A pointer to any type or function, or a long value may be converted to an XtPointer and back again and the result will compare equal to the original value. In ANSI C environments it is expected that XtPointer will be defined as void*. |
| XtArgVal | A datum large enough to contain an XtPointer, Cardinal, Dimension, or Position value. |
| XtEnum | An integer datum large enough to encode at least 128 distinct values, two of which are the symbolic values True and False. The symbolic values TRUE and FALSE are also defined to be equal to True and False, respectively. |
In addition to these specific types, the precise order of the fields within the structure declarations for any of the instance part records ObjectPart, RectObjPart, CorePart, CompositePart, ShellPart, WMShellPart, TopLevelShellPart, and ApplicationShellPart is implementation-defined. These structures may also have additional private fields internal to the implementation. The ObjectPart, RectObjPart, and CorePart structures must be defined so that any member with the same name appears at the same offset in ObjectRec, RectObjRec, and CoreRec (WidgetRec). No other relations between the offsets of any two fields may be assumed.
The widget_class 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 methods 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 subclassed 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 XtResourceList. 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).
Subclassing, however, can be taken too far. If you create a subclass that inherits none of the procedures of its superclass, 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 applications. |
| A private .h file, used by widgets whose classes are subclasses of the widget class. |
| A .c file, which implements the widget. |
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 applicable. For example, a record component name is all lowercase and uses underscores (_) for compound words (for example, background_pixmap). Type and procedure names start with uppercase and use capitalization for compound words (for example, ArgList or XtSetValues). |
| 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 symbolic identifier prefixed with ``XtN''. For example, the background_pixmap field has the corresponding identifier XtNbackgroundPixmap, which is defined as the string ``backgroundPixmap''. Many predefined names are listed in <X11/StringDefs.h>. 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 example,``BorderWidth''). Each resource class string should have a symbolic identifier prefixed with ``XtC'' (for example, XtCBorderWidth). Many predefined classes are listed in <X11/StringDefs.h>. |
| A resource representation string is spelled identically to the type name (for example, ``TranslationTable''). Each representation string should have a symbolic identifier prefixed with ``XtR'' (for example, XtRTranslationTable). Many predefined representation types are listed in <X11/StringDefs.h>. |
| New widget classes start with a capital and use uppercase 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 AbcXyzClassPart. |
| - | Complete class structure names AbcXyzClassRec and _AbcXyzClassRec. |
| - | Class structure pointer type name AbcXyzWidgetClass. |
| - | Class structure variable abcXyzClassRec. |
| - | Class structure pointer variable abcXyzWidgetClass. |
| Action procedures available to translation specifications should follow the same naming conventions as procedures. That is, they start with a capital letter, and compound names use uppercase (for example, ``Highlight'' 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 String. 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 symbols 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.
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 possible 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 */
#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 Constraint.h.
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 representation 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 structure. |
| 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 Constraint. |
| 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. |
| The complete widget class extension structure definition for this widget, if any. |
| The symbolic constant identifying the class extension version, if any. |
| The name of the global class structure variable containing the generic class structure for this class. |
| An inherit constant for each new procedure in the widget class part structure. |
For example, the following is the private .h file for a possible Label widget:
#ifndef LABELP_H
#define LABELP_H
#include <X11/Label.h>
/* 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;
/* 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 ConstrainP.h.
The .c file for a widget contains the structure initializer for the class record variable, which contains the following parts:
| Class information (for example, superclass, class_name, widget_size, class_initialize, and class_inited). |
| Data constants (for example, resources and num_resources, actions and num_actions, visible_interest, compress_motion, compress_exposure, and version). |
| Widget operations (for example, initialize, realize, destroy, resize, expose, set_values, accept_focus, and any new operations specific to the widget). |
The superclass field points to the superclass global class record, declared in the superclass private .h file. For direct subclasses of the generic core widget, superclass should be initialized to the address of the widgetClassRec structure. The superclass is used for class chaining operations and for inheriting or enveloping a superclass's operations (see Sections 1.6.7, 1.6.9, and 1.6.10).
The class_name 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 subsequently deallocated.
The widget_size field is the size of the corresponding widget instance structure (not the size of the class structure).
The version field indicates the toolkit implementation version 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 XtVersion 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 XtVersionDontCheck in the version field to disable version checking for those widgets. If a widget needs to compile alternative code for different revisions of the Intrinsics interface definition, it may use the symbol XtSpecificationRelease, as described in Chapter 13. Use of XtVersion allows the Intrinsics implementation to recognize widget binaries that were compiled with older implementations.
The extension field is for future upward compatibility. If the widget programmer adds fields to class parts, all subclass structure layouts change, requiring complete recompilation. To allow clients to avoid recompilation, an extension 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.
/* 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,
/* 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 */
.
.
.
To obtain the class of a widget, use XtClass.
__
WidgetClass XtClass(w)
Widget w;
| w | Specifies the widget. Must be of class Object or any subclass thereof. |
__
The XtClass function returns a pointer to the widget's class structure.
To obtain the superclass of a widget, use XtSuperclass.
__
WidgetClass XtSuperclass(w)
Widget w;
| w | Specifies the widget. Must be of class Object or any subclass thereof. |
__
The XtSuperclass function returns a pointer to the widget's superclass class structure.
To check the subclass to which a widget belongs, use XtIsSubclass.
__
Boolean XtIsSubclass(w, widget_class)
Widget w;
WidgetClass widget_class;
| w | Specifies the widget or object instance whose class is to be checked. Must be of class Object or any subclass thereof. |
widget_class
| Specifies the widget class for which to test. Must be objectClass or any subclass thereof. |
__
The XtIsSubclass function returns True if the class of the specified widget is equal to or is a subclass of the specified class. The widget's class can be any number of subclasses 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 XtIsSubclass 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 XtIsSubclass for each of the built-in classes. These procedures are XtIsObject, XtIsRectObj, XtIsWidget, XtIsComposite, XtIsConstraint, XtIsShell, XtIsOverrideShell, XtIsWMShell, XtIsVendorShell, XtIsTransientShell, XtIsTopLevelShell, XtIsApplicationShell, and XtIsSessionShell.
All these macros and functions have the same argument description.
__
Boolean XtIs<class> (w)
Widget w;
| w | 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 XtIsSubclass directly for the built-in classes.
To check a widget's class and to generate a debugging error message, use XtCheckSubclass, defined in <X11/IntrinsicP.h>:
__
void XtCheckSubclass(w, widget_class, message)
Widget w;
WidgetClass widget_class;
String message;
| w | Specifies the widget or object whose class is to be checked. Must be of class Object or any subclass thereof. |
widget_class
| Specifies the widget class for which to test. Must be objectClass or any subclass thereof. |
| message | Specifies the message to be used. |
__
The XtCheckSubclass macro determines if the class of the specified widget is equal to or is a subclass of the specified class. The widget's class can be any number of subclasses down the chain and need not be an immediate subclass of the specified class. If the specified widget's class is not a subclass, XtCheckSubclass constructs an error message from the supplied message, the widget's actual class, and the expected class and calls XtErrorMsg. XtCheckSubclass 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.
XtCheckSubclass 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.
While most fields in a widget class structure are self-contained, 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-contained fields are
In all widget classes:class_name
class_initialize
widget_size
realize
visible_interest
resize
expose
accept_focus
compress_motion
compress_exposure
compress_enterleave
set_values_almost
tm_table
version
allocate
deallocate
In Composite widget classes:geometry_manager
change_managed
insert_child
delete_child
accepts_objects
allows_change_managed_set
In Constraint widget classes:constraint_size
In Shell widget classes:root_geometry_manager
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 structure. These superclass-to-subclass fields are
class_part_initialize
get_values_hook
initialize
initialize_hook
set_values
set_values_hook
resources
In addition, for subclasses of Constraint, the following
fields of the ConstraintClassPart and
ConstraintClassExtensionRec structures are chained
from the Constraint class down to the subclass:
resources
initialize
set_values
get_values_hook
With upward superclass chaining, the invocation of an operation first accesses the field from the widget class structure, then from the superclass structure, and so on up the class chain to the Core, RectObj, and Object class structures. The subclass-to-superclass fields are
destroy
actions
For subclasses of Constraint, the following field of ConstraintClassPart is chained from the subclass up to the Constraint class:
destroy
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 procedures 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 XtProc:
__
typedef void (*XtProc)(void);
__
A widget class indicates that it has no class initialization procedure by specifying NULL in the class_initialize 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 procedure, a pointer to which is stored in the class_part_initialize field. The class_part_initialize procedure pointer is of type XtWidgetClassProc.
__
typedef void (*XtWidgetClassProc)(WidgetClass);
WidgetClass widget_class;
widget_class
| 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 initializations 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 procedure. 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, Composite's class_part_initialize procedure is called to initialize 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 class_part_initialize field.
All widget classes, whether they have a class initialization procedure or not, must start with their class_inited field False.
The first time a widget of a class is created, XtCreateWidget ensures that the widget class and all superclasses are initialized, in superclass-to-subclass order, by checking each class_inited field and, if it is False, by calling the class_initialize and the class_part_initialize procedures for the class and all its superclasses. The Intrinsics then set the class_inited field to a nonzero value. After the one-time initialization, a class structure is constant.
The following example provides the class initialization procedure for a Label class.
static void ClassInitialize()
{
XtSetTypeConverter(XtRString, XtRJustify, CvtStringToJustify,
NULL, 0, XtCacheNone, NULL);
}
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 XtInitializeWidgetClass.
__
void XtInitializeWidgetClass(object_class)
WidgetClass object_class;
object_class
| Specifies the object class to initialize. May be objectClass or any subclass thereof. |
__
If the specified widget class is already initialized, XtInitializeWidgetClass returns immediately.
If the class initialization procedure registers type converters, these type converters are not available until the first object of the class or subclass is created or XtInitializeWidgetClass is called (see Section 9.6).
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 |
| realize |
| insert_child |
| delete_child |
| geometry_manager |
| set_values_almost |
To inherit an operation xyz, specify the constant XtInheritXyz 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 _XtInherit cast to the appropriate type. _XtInherit is a procedure that issues an error message if it is actually called.
For example, CompositeP.h 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 follows:
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;
}
.
.
.
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:
| XtInheritAllocate |
| XtInheritDeallocate |
For Core:
| XtInheritRealize |
| XtInheritResize |
| XtInheritExpose |
| XtInheritSetValuesAlmost |
| XtInheritAcceptFocus |
| XtInheritQueryGeometry |
| XtInheritTranslations |
| XtInheritDisplayAccelerator |
For Composite:
| XtInheritGeometryManager |
| XtInheritChangeManaged |
| XtInheritInsertChild |
| XtInheritDeleteChild |
For Shell:
| XtInheritRootGeometryManager |
A widget sometimes needs to call a superclass operation that is not chained. For example, a widget's expose procedure might call its superclass's expose 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 insert_child and then calling XtManageChild to add the child to the managed set.
Note
| A class method should not use XtSuperclass but should instead call the class method of its own specific superclass directly through the superclass record. That is, it should use its own class pointers only, not the widget's class pointers, as the widget's class may be a subclass of the class whose implementation is being referenced. |
This technique is referred to as enveloping the superclass's operation.
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 Composite, Constraint, and Shell classes, subclasses can provide values for these fields by setting the extension pointer for the appropriate part in their class structure to point to a statically declared extension record containing the additional fields. Setting the extension field is never mandatory; code that uses fields in the extension record must always check the extension 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 extension field, extension records should be declared as a linked list, and each extension record definition should contain the following four fields at the beginning of the structure declaration:
__
struct {
XtPointer next_extension;
XrmQuark record_type;
long version;
Cardinal record_size;
};
next_extension
| Specifies the next record in the list, or NULL. |
| record_type | Specifies the particular structure declaration to which each extension record instance conforms. |
| version | Specifies a version id symbolic constant supplied by the definer of the structure. |
| record_size | Specifies the total number of bytes allocated for the extension record. |
__
The record_type field identifies the contents of the extension record and is used by the definer of the record to locate its particular extension record in the list. The record_type field is normally assigned the result of XrmStringToQuark for a registered string constant. The Intrinsics reserve all record type strings beginning with the two characters ``XT'' for future standard uses. The value NULLQUARK 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 version 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 record_size field value includes the four common header fields and should normally be initialized with sizeof().
Any value stored in the class part extension fields of CompositeClassPart, ConstraintClassPart, or ShellClassPart 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 extension field in the class record.
To locate a class extension record, use XtGetClassExtension.
__
XtPointer XtGetClassExtension(object_class, byte_offset,
type, version, record_size)
WidgetClass object_class;
Cardinal byte_offset;
XrmQuark type;
long version;
Cardinal record_size;
object_class
| Specifies the object class containing the extension list to be searched. |
byte_offset
| Specifies the offset in bytes from the base of the class record of the extension field to be searched. |
| type | Specifies the record_type of the class extension to be located. |
| version | Specifies the minimum acceptable version of the class extension required for a match. |
record_size
| 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 specified version, and a record size greater than or equal the specified record_size if it is nonzero. XtGetClassExtension 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.
X Toolkit Intrinsics X11 Release 6.4
2
Chapter 2
Widget Instantiation
A hierarchy of widget instances constitutes a widget tree. The shell widget returned by XtAppCreateShell 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 interfacing between composite widgets, their children, and other clients.
Composite widgets, that is, members of the class compositeWidgetClass, 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 management methods.
In addition, the Intrinsics recursively perform many operations (for example, realization and destruction) on composite 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 functions. For example, XtRealizeWidget traverses the tree downward and recursively realizes all pop-up widgets and children of composite widgets. XtDestroyWidget traverses the tree downward and destroys all pop-up widgets and children 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. XtMakeGeometryRequest traverses the tree up one level and calls the geometry manager that is responsible for a widget child's geometry.
To facilitate upward traversal of the widget tree, each widget has a pointer to its parent widget. The Shell widget that XtAppCreateShell returns has a parent pointer of NULL.
To facilitate downward traversal of the widget tree, the children 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.
Before an application can call any Intrinsics function other than XtSetLanguageProc and XtToolkitThreadInitialize, it must initialize the Intrinsics by using
| XtToolkitInitialize, which initializes the Intrinsics internals |
| XtCreateApplicationContext, which initializes the per-application state |
| XtDisplayInitialize or XtOpenDisplay, which initializes the per-display state |
| XtAppCreateShell, which creates the root of a widget tree |
Or an application can call the convenience procedure XtOpenApplication, which combines the functions of the preceding procedures. An application wishing to use the ANSI C locale mechanism should call XtSetLanguageProc prior to calling XtDisplayInitialize, XtOpenDisplay, XtOpenApplication, or XtAppInitialize.
Multiple instances of X Toolkit applications may be implemented 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 Display pointers for that application. The Intrinsics handle all display connections within a single application context simultaneously, handling input in a round-robin fashion. The application context type XtAppContext is opaque to clients.
To initialize the Intrinsics internals, use XtToolkitInitialize.
__
void XtToolkitInitialize()
__
If XtToolkitInitialize was previously called, it returns immediately. When XtToolkitThreadInitialize is called before XtToolkitInitialize, the latter is protected against simultaneous activation by multiple threads.
To create an application context, use XtCreateApplicationContext.
__
XtAppContext XtCreateApplicationContext()
__
The XtCreateApplicationContext function returns an application 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 XtDestroyApplicationContext.
__
void XtDestroyApplicationContext(app_context)
XtAppContext app_context;
app_context
| Specifies the application context. |
__
The XtDestroyApplicationContext function destroys the specified application context. If called from within an event dispatch (for example, in a callback procedure), XtDestroyApplicationContext does not destroy the application context until the dispatch is complete.
To get the application context in which a given widget was created, use XtWidgetToApplicationContext.
__
XtAppContext XtWidgetToApplicationContext(w)
Widget w;
| w | Specifies the widget for which you want the application context. Must be of class Object or any subclass thereof. |
__
The XtWidgetToApplicationContext function returns the application context for the specified widget.
To initialize a display and add it to an application context, use XtDisplayInitialize.
__
void XtDisplayInitialize(app_context, display,
application_name, application_class,
options, num_options, argc, argv)
XtAppContext app_context;
Display *display;
String application_name;
String application_class;
XrmOptionDescRec *options;
Cardinal num_options;
int *argc;
String *argv;
| app_context | Specifies the application context. |
| display | Specifies a previously opened display connection. Note that a single display connection can be in at most one application context. |
application_name
| Specifies the name of the application instance. |
application_class
| Specifies the class name of this application, which is usually the generic name for all instances of this application. |
| options | Specifies how to parse the command line for any application-specific resources. The options argument is passed as a parameter to XrmParseCommand. For further information, see Section 15.9 in Xlib -- C Language X Interface and Section 2.4 of this specification. |
| num_options | Specifies the number of entries in the options list. |
| argc | Specifies a pointer to the number of command line parameters. |
| argv | Specifies the list of command line parameters. |
__
The XtDisplayInitialize function retrieves the language string to be used for the specified display (see Section 11.11), calls the language procedure (if set) with that language string, builds the resource database for the default screen, calls the Xlib XrmParseCommand function to parse the command line, and performs other per-display initialization. After XrmParseCommand has been called, argc and argv contain only those parameters that were not in the standard option table or in the table specified by the options argument. If the modified argc is not zero, most applications simply print out the modified argv along with a message listing the allowable options. On POSIX-based systems, the application name is usually the final component of argv[0]. If the synchronous resource is True, XtDisplayInitialize calls the Xlib XSynchronize 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 application_name, application_class, options, and num_options arguments.
XtDisplayInitialize calls XrmSetDatabase to associate the resource database of the default screen with the display before returning.
To open a display, initialize it, and then add it to an application context, use XtOpenDisplay.
__
Display *XtOpenDisplay(app_context, display_string,
application_name, application_class,
options, num_options, argc, argv)
XtAppContext app_context;
String display_string;
String application_name;
String application_class;
XrmOptionDescRec *options;
Cardinal num_options;
int *argc;
String *argv;
| app_context | Specifies the application context. |
display_string
| Specifies the display string, or NULL. |
application_name
| Specifies the name of the application instance, or NULL. |
application_class
| Specifies the class name of this application, which is usually the generic name for all instances of this application. |
| options | Specifies how to parse the command line for any application-specific resources. The options argument is passed as a parameter to XrmParseCommand. |
| num_options | Specifies the number of entries in the options list. |
| argc | Specifies a pointer to the number of command line parameters. |
| argv | Specifies the list of command line parameters. |
__
The XtOpenDisplay function calls XOpenDisplay with the specified display_string. If display_string is NULL, XtOpenDisplay uses the current value of the -display option specified in argv. If no display is specified in argv, the user's default display is retrieved from the environment. On POSIX-based systems, this is the value of the DISPLAY environment variable.
If this succeeds, XtOpenDisplay then calls XtDisplayInitialize and passes it the opened display and the value of the -name option specified in argv as the application name. If no -name option is specified and application_name is non-NULL, application_name is passed to XtDisplayInitialize. If application_name is NULL and if the environment variable RESOURCE_NAME is set, the value of RESOURCE_NAME 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 argv[0] less any directory and file type components, that is, the final component of argv[0], if specified. If argv[0] does not exist or is the empty string, the application name is ``main''. XtOpenDisplay returns the newly opened display or NULL if it failed.
See Section 7.12 for information regarding the use of XtOpenDisplay in multiple threads.
To close a display and remove it from an application context, use XtCloseDisplay.
__
void XtCloseDisplay(display)
Display *display;
| display | Specifies the display. |
__
The XtCloseDisplay function calls XCloseDisplay with the specified display as soon as it is safe to do so. If called from within an event dispatch (for example, a callback procedure), XtCloseDisplay does not close the display until the dispatch is complete. Note that applications need only call XtCloseDisplay if they are to continue executing after closing the display; otherwise, they should call XtDestroyApplicationContext.
See Section 7.12 for information regarding the use of XtCloseDisplay in multiple threads.
Resource databases are specified to be created in the current 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.
The callout procedure provided by the application is of type XtLanguageProc.
__
typedef String (*XtLanguageProc)(Display*, String, XtPointer);
Display *display;
String language;
XtPointer client_data;
| display | Passes the display. |
| language | Passes the initial language value obtained from the command line or server per-display resource specifications. |
client_data
| Passes the additional client data specified in the call to XtSetLanguageProc. |
__
The language procedure allows an application to set the locale to the value of the language resource determined by XtDisplayInitialize. The function returns a new language string that will be subsequently used by XtDisplayInitialize 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 XtDisplayInitialize, use XtSetLanguageProc.
__
XtLanguageProc XtSetLanguageProc(app_context, proc, client_data)
XtAppContext app_context;
XtLanguageProc proc;
XtPointer client_data;
app_context
| Specifies the application context in which the language procedure is to be used, or NULL. |
| proc | Specifies the language procedure. |
client_data
| Specifies additional client data to be passed to the language procedure when it is called. |
__
XtSetLanguageProc sets the language procedure that will be called from XtDisplayInitialize for all subsequent Displays initialized in the specified application context. If app_context is NULL, the specified language procedure is registered in all application contexts created by the calling process, including any future application contexts that may be created. If proc is NULL, a default language procedure is registered. XtSetLanguageProc returns the previously registered language procedure. If a language procedure has not yet been registered, the return value is unspecified, but if this return value is used in a subsequent call to XtSetLanguageProc, 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 setlocale( LC_ALL, language ). If an error is encountered, a warning message is issued with XtWarning. |
| Calls XSupportsLocale to verify that the current locale is supported. If the locale is not supported, a warning message is issued with XtWarning and the locale is set to ``C''. |
| Calls XSetLocaleModifiers 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 setlocale( LC_ALL, NULL ). |
A client wishing to use this mechanism to establish locale can do so by calling XtSetLanguageProc prior to XtDisplayInitialize, as in the following example.
Widget top;
XtSetLanguageProc(NULL, NULL, NULL);
top = XtOpenApplication(...);
...
The XtDisplayInitialize function first determines the language 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 precedence:
| Application command line (argc, argv). |
| 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 XtScreenDatabase 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 XResourceManagerString or, if XResourceManagerString 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/.Xdefaults. |
| If a language procedure has been set, XtDisplayInitialize 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 Character Set. If neither option is specified on the command line, XtDisplayInitialize queries the server resource database (which is assumed to be entirely in XPCS) for the resource name.xnlLanguage, class Class.XnlLanguage where name and Class are the application_name and application_class specified to XtDisplayInitialize. 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. |
| If a language procedure has not been set, the initial database is then queried for the resource name.xnlLanguage, class Class.XnlLanguage as 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 systems, this is done by retrieving the value of the LANG 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 environment 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 environment resource file name is specified by the value of the XENVIRONMENT environment variable. If this environment variable does not exist, the user's home directory is searched for a file named .Xdefaults-host, where host is the host name of the machine on which the application is running. |
| The per-screen resource specifications are then merged into the screen resource database, if they exist. These specifications are the string returned by XScreenResourceString 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 XrmSetDatabase with the current screen resource database, after preserving the original display-associated database, then calling XtResolvePathname with the parameters (display, NULL, NULL, NULL, path, NULL, 0, NULL), where path is defined in an operating-system-specific way. On POSIX-based systems, path is defined to be the value of the environment variable XUSERFILESEARCHPATH if this is defined. If XUSERFILESEARCHPATH is not defined, an implementation-dependent default value is used. This default value is constrained in the following manner: |
| - | If the environment variable XAPPLRESDIR is not defined, the default XUSERFILESEARCHPATH must contain at least six entries. These entries must contain $HOME as the directory prefix, plus the following 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. %NThe order of these six entries within the path must be as given above. The order and use of substitutions within a given entry are implementation-dependent. |
| - | If XAPPLRESDIR is defined, the default XUSERFILESEARCHPATH 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 %NThe order of these seven entries within the path must be as given above. The order and use of substitutions within a given entry are implementation-dependent. |
| Last, the application-specific class resource file from the local host is merged into the screen resource database. This file is owned by the application and is usually installed in a system directory when the application is installed. It may contain sitewide customizations specified by the system manager. The name of the application class resource file is found by calling XtResolvePathname with the parameters (display, ``app-defaults'', NULL, NULL, NULL, NULL, 0, NULL). This file is expected to be provided by the developer of the application and may be required for the application 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 XtAppSetFallbackResources. Note that the customization substitution string is retrieved dynamically by XtResolvePathname 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 database, even though the contents of the class resource file have lowest precedence. After calling XtResolvePathname, the original display-associated database is restored. |
To obtain the resource database for a particular screen, use XtScreenDatabase.
__
XrmDatabase XtScreenDatabase(screen)
Screen *screen;
| screen | Specifies the screen whose resource database is to be returned. |
__
The XtScreenDatabase function returns the fully merged resource database as specified above, associated with the specified screen. If the specified screen does not belong to a Display initialized by XtDisplayInitialize, the results are undefined.
To obtain the default resource database associated with a particular display, use XtDatabase.
__
XrmDatabase XtDatabase(display)
Display *display;
| display | Specifies the display. |
__
The XtDatabase function is equivalent to XrmGetDatabase. It returns the database associated with the specified display, or NULL if a database has not been set.
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 XtAppSetFallbackResources.
__
void XtAppSetFallbackResources(app_context, specification_list)
XtAppContext app_context;
String *specification_list;
| app_context | Specifies the application context in which the fallback specifications will be used. |
specification_list
| Specifies a NULL-terminated list of resource specifications to preload the database, or NULL. |
__
Each entry in specification_list points to a string in the format of XrmPutLineResource. Following a call to XtAppSetFallbackResources, 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 specification_list is not NULL, the resource specifications in specification_list will be merged into the screen resource database in place of the application-specific class resource file. XtAppSetFallbackResources is not required to copy specification_list; 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 XtAppSetFallbackResources is called again. The value NULL for specification_list removes any previous fallback resource specification 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 problem exists in finding and loading the application defaults file.
The XtOpenDisplay function first parses the command line for the following options:
| -display | Specifies the display name for XOpenDisplay. |
| -name | Sets the resource name prefix, which overrides the application name passed to XtOpenDisplay. |
-xnllanguage
| Specifies the initial language string for establishing locale and for finding application class resource files. |
XtDisplayInitialize has a table of standard command line options that are passed to XrmParseCommand for adding resources to the resource database, and it takes as a parameter additional application-specific resource abbreviations. The format of this table is described in Section 15.9 in Xlib -- C Language X Interface.
__
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;/* Locatio