Mary Larson (Digital UEG)

Mark Manasse (Digital SRC)

Jim Gettys (Digital SRC)

Leo Treggiari (Digital SDT)

Ron Newman (Project Athena)

Bob Scheifler (MIT LCS)

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)

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)

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)

•

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.

•

A data structure which contains instance-specific values.

•

A class structure which contains information that is applicable to all widgets of that class.

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 core_class;

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 core;

border_pixel

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

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

CoreClassPart core_class;

CompositeClassPart composite_class;

WidgetList children;

See Chapter 3

Cardinal num_children;

See Chapter 3

Cardinal num_slots;

See Chapter 3

XtOrderProc insert_position;See Section 3.2

CorePart core;

CompositePart composite;

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

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

CoreClassPart core_class;

CompositeClassPart composite_class;

ConstraintClassPart constraint_class;

CorePart core;

CompositePart composite;

ConstraintPart constraint;

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.

•

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.

•

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.

1.6.2. Widget Subclassing in Public .h Files

The public .h file for a widget class is imported by clients and contains

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();

extern String LabelGetText();

#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.

1.6.3. Widget Subclassing in Private .h Files

The private .h file for a widget is imported by widget classes that are subclasses of the widget and contains

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 */

/* Data derived from resources */

} LabelPart;

/* Full instance record declaration */
typedef struct _LabelRec {

} LabelRec;

/* Types for Label class methods */
typedef void (*LabelSetTextProc)();

typedef String (*LabelGetTextProc)();

/* New fields for the Label widget class record */
typedef struct {

} LabelClassPart;

/* Full class record declaration */
typedef struct _LabelClassRec {

} 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.

1.6.4. Widget Subclassing in .c Files

The .c file for a widget contains the structure initializer for the class record variable, which contains the following parts:

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[] = {

}

/* 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 */

},
{

/* Label_class fields

}
};

/* Class record pointer */
WidgetClass labelWidgetClass = (WidgetClass) &labelClassRec;

/* New method access routines */
void LabelSetText(w, text)

{

}
/* Private procedures */

1.6.5. Widget Class and Superclass Look Up

To obtain the class of a widget, use XtClass. __ │

WidgetClass XtClass(w)
Widget w;

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;

any subclass thereof. │__

The XtSuperclass function returns a pointer to the widget’s superclass class structure.

1.6.6. Widget Subclass Verification

To check the subclass to which a widget belongs, use XtIsSubclass. __ │

Boolean XtIsSubclass(w, widget_class)
Widget w;
WidgetClass widget_class;

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;

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;

be checked. Must be of class Object or any sub-
class thereof.

widget_class
Specifies the widget class for which to test.
Must be objectClass or any subclass thereof.

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.

1.6.7. Superclass Chaining

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

In Composite widget classes:geometry_manager

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

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:

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

For subclasses of Constraint, the following field of ConstraintClassPart is chained from the subclass up to the Constraint class:

1.6.8. Class Initialization: class_initialize and class_part_initialize Procedures

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()
{

}

1.6.9. Initializing a Widget Class

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).

1.6.10. Inheritance of Superclass Operations

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)

{

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

1.6.11. Invocation of Superclass Operations

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.

1.6.12. Class Extension Records

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 {

};

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 exten-
sion list to be searched.

byte_offsetSpecifies the offset in bytes from the base of
the class record of the extension field to be
searched.

to be located.

class extension required for a match.

record_sizeSpecifies 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.

1

X Toolkit Intrinsics X11 Release 6.8

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.

2.1. Initializing the X Toolkit

Before an application can call any Intrinsics function other than XtSetLanguageProc and XtToolkitThreadInitialize, it must initialize the Intrinsics by using

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_contextSpecifies 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;

cation 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;

tion. Note that a single display connection
can be in at most one application context.

application_name
Specifies the name of the application in-
stance.

application_class
Specifies the class name of this application,
which is usually the generic name for all in-
stances of this application.

any application-specific resources. The op-
tions 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.

list.

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 ap-
plication 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;

display_stringSpecifies the display string, or NULL.

application_name
Specifies the name of the application in-
stance, or NULL.

application_class
Specifies the class name of this application,
which is usually the generic name for all in-
stances of this application.

any application-specific resources. The op-
tions argument is passed as a parameter to
XrmParseCommand.

list.

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;

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.

2.2. Establishing the Locale

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;

the command line or server per-display resource
specifications.

client_dataPasses 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_contextSpecifies the application context in which the
language procedure is to be used, or NULL.

client_dataSpecifies 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:

A client wishing to use this mechanism to establish locale can do so by calling XtSetLanguageProc prior to XtDisplayInitialize, as in the following example.

2.3. Loading the Resource Database

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:

the user preference 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:

The 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.

The 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.

To obtain the resource database for a particular screen, use XtScreenDatabase. __ │

XrmDatabase XtScreenDatabase(screen)
Screen *screen;

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;

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;

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.

2.4. Parsing the Command Line

The XtOpenDisplay function first parses the command line for the following options:

−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 {

} XrmOptionKind;

typedef struct {

} 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
−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 True, the values of XtDefaultForeground and XtDefaultBackground 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, XtDisplayInitialize makes a call to XSynchronize for all display connections currently open in the application context. Therefore, when multiple displays are initialized in the same application context, the most recent value specified 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 multiple displays are initialized in the same application context, the most recent value specified is used for all displays 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 xmh, you can start it up as

xmh −xrm ’xmh*Command.background: red’

When it parses the command line, XtDisplayInitialize merges the application option table with the standard option table before calling the Xlib XrmParseCommand function. An entry in the application table with the same name as an entry in the standard table overrides the standard table entry. If 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.

2.5. Creating Widgets

The creation of widget instances is a three-phase process:

To start the first phase, the application calls XtCreateWidget for all its widgets and adds some (usually, most or all) of its widgets to their respective parents’ managed set by calling XtManageChild. To avoid an creation process where each composite widget lays itself out each time a widget 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 XtRealizeWidget with the top-level widget to execute the second and third phases. XtRealizeWidget first recursively traverses the widget tree in a postorder (bottom-up) traversal 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 example, 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 directions through the widget tree. The parent may force some of its children to change size and position and may issue geometry requests to its own parent in order to better accommodate 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.

Finally, XtRealizeWidget 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 procedure, and finally maps the widgets that are managed.

2.5.1. Creating and Merging Argument Lists

Many Intrinsics functions may be passed pairs of resource names and values. These are passed as an arglist, a pointer to an array of Arg structures, which contains __ │

typedef struct {

} Arg, *ArgList; │__

where XtArgVal is as defined in Section 1.5.

If the size of the resource is less than or equal to the size of an XtArgVal, the resource value is stored directly in value; otherwise, a pointer to it is stored in value.

To set values in an ArgList, use XtSetArg. __ │

void XtSetArg(arg, name, value)
Arg arg;
String name;
XtArgVal value;

in an XtArgVal, else the address. │__

The XtSetArg 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;
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 XtNumber:

static Args args[] = {

};
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 XtSetArg. XtSetArg can be implemented as a macro that evaluates the first argument twice.

To merge two arglist arrays, use XtMergeArgLists. __ │

ArgList XtMergeArgLists(args1, num_args1, args2, num_args2)
ArgList args1;
Cardinal num_args1;
ArgList args2;
Cardinal num_args2;

ment list.

gument list. │__

The XtMergeArgLists 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 XtFree.

All Intrinsics interfaces that require ArgList arguments have analogs conforming to the ANSI C variable argument list (traditionally called ‘‘varargs’’) calling convention. The name of the analog is formed by prefixing ‘‘Va’’ to the name of the corresponding ArgList procedure; e.g., XtVaCreateWidget. Each procedure named XtVasomething takes as its last arguments, in place of the corresponding ArgList/ Cardinal parameters, a variable parameter list of resource name and value pairs where each name is of type String and each value is of type XtArgVal. The end of the list is identified by a name 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 ArgList and varargs forms interchangeably.

Two special names are defined for use only in varargs lists: XtVaTypedArg and XtVaNestedList. __ │

#define XtVaTypedArg "XtVaTypedArg" │__

If the name XtVaTypedArg is specified in place of a resource name, then the following four arguments are interpreted as a name/type/value/size tuple where name is of type String, type is of type String, value is of type XtArgVal, and size is of type int. When a varargs list containing XtVaTypedArg is processed, a resource type conversion (see Section 9.6) is performed if necessary to convert the value into the format required by the associated resource. If type is XtRString, then value contains a pointer to the string and size contains the number of bytes allocated, including the trailing null byte. If type is not XtRString, then if size is less than or equal to sizeof(XtArgVal), the value should be the data cast to the type XtArgVal, otherwise value 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 XtVaNestedList is specified in place of a resource name, then the following argument is interpreted as an XtVarArgsList 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 identified with a name entry containing NULL. Varargs lists may nest to any depth.

To dynamically allocate a varargs list for use with XtVaNestedList in multiple calls, use XtVaCreateArgsList. __ │

typedef XtPointer XtVarArgsList;
XtVarArgsList XtVaCreateArgsList(unused, ...)
XtPointer unused;

The XtVaCreateArgsList function allocates memory and copies its arguments into a single list pointer, which may be used with XtVaNestedList. The end of both lists is identified by a name entry containing NULL. Any entries of type XtVaTypedArg 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 XtFree when no longer needed.

Use of resource files and of the resource database is generally encouraged over lengthy arglist or varargs lists whenever possible in order to permit modification without recompilation.

2.5.2. Creating a Widget Instance

To create an instance of a widget, use XtCreateWidget. __ │

Widget XtCreateWidget(name, object_class, parent, args, num_args)
String name;
WidgetClass object_class;
Widget parent;
ArgList args;
Cardinal num_args;

ated widget, which is used for retrieving re-
sources and, for that reason, should not be the
same as any other widget that is a child of the
same parent.

object_class
Specifies the widget class pointer for the created
object. Must be objectClass or any subclass
thereof.

ject or any subclass thereof.

resource specifications.

list. │__

The XtCreateWidget function performs all the boilerplate operations of widget creation, doing the following in order:

To create an instance of a widget using varargs lists, use XtVaCreateWidget. __ │

Widget XtVaCreateWidget(name, object_class, parent, ...)
String name;
WidgetClass object_class;
Widget parent;

get.

object_class
Specifies the widget class pointer for the created
object. Must be objectClass or any subclass
thereof.

ject or any subclass thereof.

any other resource specifications. │__

The XtVaCreateWidget procedure is identical in function to XtCreateWidget with the args and num_args parameters replaced by a varargs list, as described in Section 2.5.1.

2.5.3. Creating an Application Shell Instance

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 XtAppCreateShell to create independent widget trees. __ │

Widget XtAppCreateShell(name, application_class, widget_class, display, args, num_args)
String name;
String application_class;
WidgetClass widget_class;
Display *display;
ArgList args;
Cardinal num_args;

If name is NULL, the application name passed to
XtDisplayInitialize is used.

application_class
Specifies the resource class string to be used
in place of the widget class_name string when
widget_class is applicationShellWidgetClass or a
subclass thereof.

widget_classSpecifies the widget class for the top-level
widget (e.g., applicationShellWidgetClass).

for the resource database used to retrieve the
shell widget resources.

er resource specifications.

list. │__

The XtAppCreateShell 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 args 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 name.screen, class Class.Screen where Class is the specified application_class if widget_class is applicationShellWidgetClass or a subclass thereof. If widget_class is not applicationShellWidgetClass or a subclass, Class is the class_name field from the CoreClassPart of the specified widget_class. 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 args. The widget name and Class as determined above are used as the leftmost (i.e., root) components in all fully qualified resource names for objects within this widget tree.

If the specified widget class is a subclass of WMShell, the name and Class as determined above will be stored into the WM_CLASS property on the widget’s window when it becomes realized. If the specified widget_class is applicationShellWidgetClass or a subclass thereof, the WM_COMMAND property will also be set from the values of the XtNargv and XtNargc resources.

To create multiple top-level shells within a single (logical) application, you can use one of two methods:

The first method, which is best used when there is a clear choice for what is the main window, leads to resource specifications like the following:

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 XtVaAppCreateShell. __ │

Widget XtVaAppCreateShell(name, application_class, widget_class, display, ...)
String name;
String application_class;
WidgetClass widget_class;
Display *display;

get. If name is NULL, the application name
passed to XtDisplayInitialize is used.

application_class
Specifies the resource class string to be
used in place of the widget class_name string
when widget_class is applicationShellWidget-
Class or a subclass thereof.

widget.

and for the resource database used to re-
trieve the shell widget resources.

ride any other resource specifications. │__

The XtVaAppCreateShell procedure is identical in function to XtAppCreateShell with the args and num_args parameters replaced by a varargs list, as described in Section 2.5.1.

2.5.4. Convenience Procedure to Initialize an Application

To initialize the Intrinsics internals, create an application context, open and initialize a display, and create the initial root shell instance, an application may use XtOpenApplication or XtVaOpenApplication. __ │

Widget XtOpenApplication(app_context_return, application_class, options, num_options,
argc_in_out, argv_in_out, fallback_resources, widget_class, args, num_args)
XtAppContext *app_context_return;
String application_class;
XrmOptionDescList options;
Cardinal num_options;
int *argc_in_out;
String *argv_in_out;
String *fallback_resources;
WidgetClass widget_class;
ArgList args;
Cardinal num_args;

app_context_return
Returns the application context, if non-NULL.

application_class
Specifies the class name of the application.

line arguments.

ments.

fallback_resources
Specifies resource values to be used if the
application class resource file cannot be
opened or read, or NULL.

ated. Must be shellWidgetClass or a sub-
class.

other resource specifications for the created
shell widget.

ment list. │__

The XtOpenApplication function calls XtToolkitInitialize followed by XtCreateApplicationContext, then calls XtOpenDisplay with display_string NULL and application_name NULL, and finally calls XtAppCreateShell with name NULL, the specified widget_class, an argument list and count, and returns the created shell. The recommended widget_class is sessionShellWidgetClass. The argument list and count are created by merging the specified args and num_args with a list containing the specified argc and argv. The modified argc and argv returned by XtDisplayInitialize are returned in argc_in_out and argv_in_out. If app_context_return 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 XtOpenApplication terminates the application. If fallback_resources is non-NULL, XtAppSetFallbackResources is called with the value prior to calling XtOpenDisplay. __ │

Widget XtVaOpenApplication(app_context_return, application_class, options, num_options,
argc_in_out, argv_in_out, fallback_resources, widget_class, ...)
XtAppContext *app_context_return;
String application_class;
XrmOptionDescList options;
Cardinal num_options;
int *argc_in_out;
String *argv_in_out;
String *fallback_resources;
WidgetClass widget_class;

app_context_return
Returns the application context, if non-NULL.

application_class
Specifies the class name of the application.

line arguments.

fallback_resources
Specifies resource values to be used if the
application class resource file cannot be
opened, or NULL.

ated. Must be shellWidgetClass or a sub-
class.

ride any other resource specifications for
the created shell. │__

The XtVaOpenApplication procedure is identical in function to XtOpenApplication with the args and num_args parameters replaced by a varargs list, as described in Section 2.5.1.

2.5.5. Widget Instance Allocation: The allocate Procedure

A widget class may optionally provide an instance allocation procedure in the ObjectClassExtension record.

When the call to create a widget includes a varargs list containing XtVaTypedArg, these arguments will be passed to the allocation procedure in an XtTypedArgList. __ │

typedef struct {

} XtTypedArg, *XtTypedArgList; │__

The allocate procedure pointer in the ObjectClassExtension record is of type XtAllocateProc. __ │

typedef void (*XtAllocateProc)(WidgetClass, Cardinal*, Cardinal*, ArgList, Cardinal*,
XtTypedArgList, Cardinal*, Widget*, XtPointer*);
WidgetClass widget_class;
Cardinal* constraint_size;
Cardinal* more_bytes;
ArgList args;
Cardinal* num_args;
XtTypedArgList typed_args,
Cardinal* num_typed_args;
Widget* new_return;
XtPointer* more_bytes_return;

allocate.

constraint_sizeSpecifies the size of the constraint record
to allocate, or 0.

memory to allocate.

call to create the widget.

in the call to create the widget.

stance, or NULL in case of error.

more_bytes_return
Returns the auxiliary memory if it was re-
quested, or NULL if requested and an error
occurred; otherwise, unchanged. │__

At widget allocation time, if an extension record with record_type equal to NULLQUARK is located through the object class part extension field and the allocate field is not NULL, the XtAllocateProc will be invoked to allocate memory for the widget. If no ObjectClassPart extension record is declared with record_type equal to NULLQUARK , then XtInheritAllocate and XtInheritDeallocate are assumed. If no XtAllocateProc is found, the Intrinsics will allocate memory for the widget.

An XtAllocateProc must perform the following:

A class allocation procedure that envelops the allocation procedure of a superclass must rely on the enveloped procedure to perform the instance and constraint allocation. Allocation procedures should refrain from initializing fields in the widget record except to store pointers to newly allocated additional memory. Under no circumstances should an allocation procedure that envelopes its superclass allocation procedure modify fields in the instance part of any superclass.

2.5.6. Widget Instance Initialization: The initialize Procedure

The initialize procedure pointer in a widget class is of type XtInitProc. __ │

typedef void (*XtInitProc)(Widget, Widget, ArgList, Cardinal*);
Widget request;
Widget new;
ArgList args;
Cardinal *num_args;

ues as requested by the argument list, the re-
source database, and the widget defaults.

source and nonresource, that are actually allowed.

for computing derived resource values. If the
client created the widget using a varargs form,
any resources specified via XtVaTypedArg are con-
verted to the widget representation and the list
is transformed into the ArgList format.

list. │__

An initialization procedure performs the following:

Note

It is not necessary to allocate space for or to copy callback lists.

Note

A widget may directly assign only its own width and height within the initialize, initialize_hook, set_values, and set_values_hook procedures; see Chapter 6.

An initialization procedure also can check certain fields for internal consistency. For example, it makes no sense to specify a colormap for a depth that does not support that colormap.

Initialization procedures are called in superclass-to-subclass order after all fields specified in the resource lists have been initialized. The initialize procedure does not need to examine args and num_args if all public resources are declared in the resource list. Most of the initialization code for a specific widget class deals with fields defined in that class and not with fields defined in its superclasses.

If a subclass does not need an initialization procedure because it does not need to perform any of the above operations, it can specify NULL for the initialize field in the class record.

Sometimes a subclass may want to overwrite values filled in by its superclass. In particular, size calculations of a superclass often are incorrect for a subclass, and in this case, the subclass must modify or recalculate fields declared and computed by its superclass.

As an example, a subclass can visually surround its superclass display. In this case, the width and height calculated by the superclass initialize procedure are too small and need to be incremented by the size of the surround. The subclass needs to know if its superclass’s size was calculated by the superclass or was specified explicitly. All widgets must place themselves into whatever size is explicitly given, but they should compute a reasonable size if no size is requested.

The request and new arguments provide the necessary information for a subclass to determine the difference between an explicitly specified field and a field computed by a superclass. The request widget is a copy of the widget as initialized by the arglist and resource database. The new widget starts with the values in the request, but it has been updated by all superclass initialization procedures called so far. A subclass initialize procedure can compare these two to resolve any potential conflicts.

In the above example, the subclass with the visual surround can see if the width and height in the request widget are zero. If so, it adds its surround size to the width and height fields in the new widget. If not, it must make do with the size originally specified.

The new widget will become the actual widget instance record. Therefore, the initialization procedure should do all its work on the new widget; the request widget should never be modified. If the initialize procedure needs to call any routines that operate on a widget, it should specify new as the widget instance.

2.5.7. Constraint Instance Initialization: The ConstraintClassPart initialize Procedure

The constraint initialization procedure pointer, found in the ConstraintClassPart initialize field of the widget class record, is of type XtInitProc. The values passed to the parent constraint initialization procedures are the same as those passed to the child’s class widget initialization procedures.

The constraints field of the request widget points to a copy of the constraints record as initialized by the arglist and resource database.

The constraint initialization procedure should compute any constraint fields derived from constraint resources. It can make further changes to the new widget to make the widget and any other constraint fields conform to the specified constraints, for example, changing the widget’s size or position.

If a constraint class does not need a constraint initialization procedure, it can specify NULL for the initialize field of the ConstraintClassPart in the class record.

2.5.8. Nonwidget Data Initialization: The initialize_hook Procedure

Note

The initialize_hook procedure is obsolete, as the same information is now available to the initialize procedure. The procedure has been retained for those widgets that used it in previous releases.

The initialize_hook procedure pointer is of type XtArgsProc: __ │

typedef void (*XtArgsProc)(Widget, ArgList, Cardinal*);
Widget w;
ArgList args;
Cardinal *num_args;

If the client created the widget using a varargs
form, any resources specified via XtVaTypedArg are
converted to the widget representation and the
list is transformed into the ArgList format.

list. │__

If this procedure is not NULL, it is called immediately after the corresponding initialize procedure or in its place if the initialize field is NULL.

The initialize_hook procedure allows a widget instance to initialize nonresource data using information from the specified argument list as if it were a resource.

2.6. Realizing Widgets

To realize a widget instance, use XtRealizeWidget. __ │

void XtRealizeWidget(w)
Widget w;

any subclass thereof.│__

If the widget is already realized, XtRealizeWidget simply returns. Otherwise it performs the following:

If the widget is a top-level shell widget (that is, it has no parent), and mapped_when_managed is True, XtRealizeWidget maps the widget window.

XtCreateWidget, XtVaCreateWidget, XtRealizeWidget, XtManageChildren, XtUnmanageChildren, XtUnrealizeWidget, XtSetMappedWhenManaged, and XtDestroyWidget maintain the following invariants:

All Intrinsics functions and all widget routines should accept either realized or unrealized widgets. When calling the realize or change_managed procedures for children of a composite widget, XtRealizeWidget calls the procedures in reverse order of appearance in the CompositePart children list. By default, this ordering of the realize procedures will result in the stacking order of any newly created subwindows being top-to-bottom in the order of appearance on the list, and the most recently created child will be at the bottom.

To check whether or not a widget has been realized, use XtIsRealized. __ │

Boolean XtIsRealized(w)
Widget w;

any subclass thereof. │__

The XtIsRealized function returns True if the widget has been realized, that is, if the widget has a nonzero window ID. If the specified object is not a widget, the state of the nearest widget ancestor is returned.

Some widget procedures (for example, set_values) might wish to operate differently after the widget has been realized.

2.6.1. Widget Instance Window Creation: The realize Procedure

The realize procedure pointer in a widget class is of type XtRealizeProc. __ │

typedef void (*XtRealizeProc)(Widget, XtValueMask*, XSetWindowAttributes*);
Widget w;
XtValueMask *value_mask;
XSetWindowAttributes *attributes;

value_maskSpecifies which fields in the attributes structure
are used.

attributesSpecifies the window attributes to use in the
XCreateWindow call. │__

The realize procedure must create the widget’s window.

Before calling the class realize procedure, the generic XtRealizeWidget function fills in a mask and a corresponding XSetWindowAttributes structure. It sets the following fields in attributes and corresponding bits in value_mask based on information in the widget core structure:

These or any other fields in attributes and the corresponding bits in value_mask can be set by the realize procedure.

Note that because realize is not a chained operation, the widget class realize procedure must update the XSetWindowAttributes structure with all the appropriate fields from non-Core superclasses.

A widget class can inherit its realize procedure from its superclass during class initialization. The realize procedure defined for coreWidgetClass calls XtCreateWindow with the passed value_mask and attributes and with window_class and visual set to CopyFromParent. Both compositeWidgetClass and constraintWidgetClass inherit this realize procedure, and most new widget subclasses can do the same (see Section 1.6.10).

The most common noninherited realize procedures set bit_gravity in the mask and attributes to the appropriate value and then create the window. For example, depending on its justification, Label might set bit_gravity to WestGravity, CenterGravity, or EastGravity. Consequently, shrinking it would just move the bits appropriately, and no exposure event is needed for repainting.

If a composite widget’s children should be realized in an order other than that specified (to control the stacking order, for example), it should call XtRealizeWidget on its children itself in the appropriate order from within its own realize procedure.

Widgets that have children and whose class is not a subclass of compositeWidgetClass are responsible for calling XtRealizeWidget on their children, usually from within the realize procedure.

Realize procedures cannot manage or unmanage their descendants.

2.6.2. Window Creation Convenience Routine

Rather than call the Xlib XCreateWindow function explicitly, a realize procedure should normally call the Intrinsics analog XtCreateWindow, which simplifies the creation of windows for widgets. __ │

void XtCreateWindow(w, window_class, visual, value_mask, attributes)
Widget w;
unsigned int window_class;
Visual *visual;
XtValueMask value_mask;
XSetWindowAttributes *attributes;

window attributed. Must be of class Core or any
subclass thereof.

window_class
Specifies the Xlib window class (for example, In-
putOutput, InputOnly, or CopyFromParent).

ent).

value_maskSpecifies which fields in the attributes structure
are used.

attributesSpecifies the window attributes to use in the
XCreateWindow call. │__

The XtCreateWindow function calls the Xlib XCreateWindow function with values from the widget structure and the passed parameters. Then, it assigns the created window to the widget’s window field.

XtCreateWindow evaluates the following fields of the widget core structure: depth, screen, parent->core.window, x, y, width, height, and border_width.

2.7. Obtaining Window Information from a Widget

The Core widget class definition contains the screen and window ids. The window field may be NULL for a while (see Sections 2.5 and 2.6).

The display pointer, the parent widget, screen pointer, and window of a widget are available to the widget writer by means of macros and to the application writer by means of functions. __ │

Display *XtDisplay(w)
Widget w;

any subclass thereof. │__

XtDisplay returns the display pointer for the specified widget. __ │

Widget XtParent(w)
Widget w;

any subclass thereof. │__

XtParent returns the parent object for the specified widget. The returned object will be of class Object or a subclass. __ │

Screen *XtScreen(w)
Widget w;

any subclass thereof. │__

XtScreen returns the screen pointer for the specified widget. __ │

Window XtWindow(w)
Widget w;

any subclass thereof. │__

XtWindow returns the window of the specified widget.

The display pointer, screen pointer, and window of a widget or of the closest widget ancestor of a nonwidget object are available by means of XtDisplayOfObject, XtScreenOfObject, and XtWindowOfObject. __ │

Display *XtDisplayOfObject(object)
Widget object;

any subclass thereof. │__

XtDisplayOfObject is identical in function to XtDisplay if the object is a widget; otherwise XtDisplayOfObject returns the display pointer for the nearest ancestor of object that is of class Widget or a subclass thereof. __ │

Screen *XtScreenOfObject(object)
Widget object;

any subclass thereof. │__

XtScreenOfObject is identical in function to XtScreen if the object is a widget; otherwise XtScreenOfObject returns the screen pointer for the nearest ancestor of object that is of class Widget or a subclass thereof. __ │

Window XtWindowOfObject(object)
Widget object;

any subclass thereof. │__

XtWindowOfObject is identical in function to XtWindow if the object is a widget; otherwise XtWindowOfObject returns the window for the nearest ancestor of object that is of class Widget or a subclass thereof.

To retrieve the instance name of an object, use XtName. __ │

String XtName(object)
Widget object;

be of class Object or any subclass thereof. │__

XtName returns a pointer to the instance name of the specified object. The storage is owned by the Intrinsics and must not be modified. The name is not qualified by the names of any of the object’s ancestors.

Several window attributes are locally cached in the widget instance. Thus, they can be set by the resource manager and XtSetValues as well as used by routines that derive structures from these values (for example, depth for deriving pixmaps, background_pixel for deriving GCs, and so on) or in the XtCreateWindow call.

The x, y, width, height, and border_width window attributes are available to geometry managers. These fields are maintained synchronously inside the Intrinsics. When an XConfigureWindow is issued by the Intrinsics on the widget’s window (on request of its parent), these values are updated immediately rather than some time later when the server generates a ConfigureNotify event. (In fact, most widgets do not select SubstructureNotify events.) This ensures that all geometry calculations are based on the internally consistent toolkit world rather than on either an inconsistent world updated by asynchronous ConfigureNotify events or a consistent, but slow, world in which geometry managers ask the server for window sizes whenever they need to lay out their managed children (see Chapter 6).

2.7.1. Unrealizing Widgets

To destroy the windows associated with a widget and its non-pop-up descendants, use XtUnrealizeWidget. __ │

void XtUnrealizeWidget(w)
Widget w;

any subclass thereof. │__

If the widget is currently unrealized, XtUnrealizeWidget simply returns. Otherwise it performs the following:

Any events in the queue or which arrive following a call to XtUnrealizeWidget will be dispatched as if the window(s) of the unrealized widget(s) had never existed.

2.8. Destroying Widgets

The Intrinsics provide support

To destroy a widget instance, use XtDestroyWidget. __ │

void XtDestroyWidget(w)
Widget w;

any subclass thereof. │__

The XtDestroyWidget function provides the only method of destroying a widget, including widgets that need to destroy themselves. It can be called at any time, including from an application callback routine of the widget being destroyed. This requires a two-phase destroy process in order to avoid dangling references to destroyed widgets.

In phase 1, XtDestroyWidget performs the following:

Entries on the destroy list satisfy the invariant that if w2 occurs after w1 on the destroy list, then w2 is not a descendent, either normal or pop-up, of w1.

Phase 2 occurs when all procedures that should execute as a result of the current event have been called, including all procedures registered with the event and translation managers, that is, when the current invocation of XtDispatchEvent is about to return, or immediately if not in XtDispatchEvent.

In phase 2, XtDestroyWidget performs the following on each entry in the destroy list in the order specified:

The XtDestroyWidget function then makes second traversal of the widget and all normal and pop-up descendants to perform the following three items on each widget in postorder:

2.8.1. Adding and Removing Destroy Callbacks

When an application needs to perform additional processing during the destruction of a widget, it should register a destroy callback procedure for the widget. The destroy callback procedures use the mechanism described in Chapter 8. The destroy callback list is identified by the resource name XtNdestroyCallback.

For example, the following adds an application-supplied destroy callback procedure ClientDestroy with client data to a widget by calling XtAddCallback.

XtAddCallback(w, XtNdestroyCallback, ClientDestroy, client_data)

Similarly, the following removes the application-supplied destroy callback procedure ClientDestroy by calling XtRemoveCallback.

XtRemoveCallback(w, XtNdestroyCallback, ClientDestroy, client_data)

The ClientDestroy argument is of type XtCallbackProc; see Section 8.1.

2.8.2. Dynamic Data Deallocation: The destroy Procedure

The destroy procedure pointers in the ObjectClassPart, RectObjClassPart, and CoreClassPart structures are of type XtWidgetProc. __ │

typedef void (*XtWidgetProc)(Widget);
Widget w;

The destroy procedures are called in subclass-to-superclass order. Therefore, a widget’s destroy procedure should deallocate only storage that is specific to the subclass and should ignore the storage allocated by any of its superclasses. The destroy procedure should deallocate only resources that have been explicitly created by the subclass. Any resource that was obtained from the resource database or passed in an argument list was not created by the widget and therefore should not be destroyed by it. If a widget does not need to deallocate any storage, the destroy procedure entry in its class record can be NULL.

Deallocating storage includes, but is not limited to, the following steps:

During destroy phase 2 for each widget, the Intrinsics remove the widget from the modal cascade, unregister all event handlers, remove all key, keyboard, button, and pointer grabs and remove all callback procedures registered on the widget. Any outstanding selection transfers will time out.

2.8.3. Dynamic Constraint Data Deallocation: The ConstraintClassPart destroy Procedure

The constraint destroy procedure identified in the ConstraintClassPart structure is called for a widget whose parent is a subclass of constraintWidgetClass. This constraint destroy procedure pointer is of type XtWidgetProc. The constraint destroy procedures are called in subclass-to-superclass order, starting at the class of the widget’s parent and ending at constraintWidgetClass. Therefore, a parent’s constraint destroy procedure should deallocate only storage that is specific to the constraint subclass and not storage allocated by any of its superclasses.

If a parent does not need to deallocate any constraint storage, the constraint destroy procedure entry in its class record can be NULL.

2.8.4. Widget Instance Deallocation: The deallocate Procedure

The deallocate procedure pointer in the ObjectClassExtension record is of type XtDeallocateProc. __ │

typedef void (*XtDeallocateProc)(Widget, XtPointer);
Widget widget;
XtPointer more_bytes;

more_bytesSpecifies the auxiliary memory received from the
corresponding allocator along with the widget, or
NULL. │__

When a widget is destroyed, if an ObjectClassExtension record exists in the object class part extension field with record_type NULLQUARK and the deallocate field is not NULL, the XtDeallocateProc will be called. If no ObjectClassPart extension record is declared with record_type equal to NULLQUARK , then XtInheritAllocate and XtInheritDeallocate are assumed. The responsibilities of the deallocate procedure are to deallocate the memory specified by more_bytes if it is not NULL, to deallocate the constraints record as specified by the widget’s core.constraints field if it is not NULL, and to deallocate the widget instance itself.

If no XtDeallocateProc is found, it is assumed that the Intrinsics originally allocated the memory and is responsible for freeing it.

2.9. Exiting from an Application

All X Toolkit applications should terminate by calling XtDestroyApplicationContext and then exiting using the standard method for their operating system (typically, by calling exit for POSIX-based systems). The quickest way to make the windows disappear while exiting is to call XtUnmapWidget on each top-level shell widget. The Intrinsics have no resources beyond those in the program image, and the X server will free its resources when its connection to the application is broken.

Depending upon the widget set in use, it may be necessary to explicitly destroy individual widgets or widget trees with XtDestroyWidget before calling XtDestroyApplicationContext in order to ensure that any required widget cleanup is properly executed. The application developer must refer to the widget documentation to learn if a widget needs to perform cleanup beyond that performed automatically by the operating system. If the client is a session participant (see Section 4.2), then the client may wish to resign from the session before exiting. See Section 4.2.4 for details.

2

X Toolkit Intrinsics X11 Release 6.8

Chapter 3

Composite Widgets and Their Children

Composite widgets (widgets whose class is a subclass of compositeWidgetClass) can have an arbitrary number of children. Consequently, they are responsible for much more than primitive widgets. Their responsibilities (either implemented directly by the widget class or indirectly by Intrinsics functions) include:

Overall management is handled by the generic procedures XtCreateWidget and XtDestroyWidget. XtCreateWidget adds children to their parent by calling the parent’s insert_child procedure. XtDestroyWidget removes children from their parent by calling the parent’s delete_child procedure and ensures that all children of a destroyed composite widget also get destroyed.

Only a subset of the total number of children is actually managed by the geometry manager and hence possibly visible. For example, a composite editor widget supporting multiple editing buffers might allocate one child widget for each file buffer, but it might display only a small number of the existing buffers. Widgets that are in this displayable subset are called managed widgets and enter into geometry manager calculations. The other children are called unmanaged widgets and, by definition, are not mapped by the Intrinsics.

Children are added to and removed from their parent’s managed set by using XtManageChild, XtManageChildren, XtUnmanageChild, XtUnmanageChildren, and XtChangeManagedSet, which notify the parent to recalculate the physical layout of its children by calling the parent’s change_managed procedure. The XtCreateManagedWidget convenience function calls XtCreateWidget and XtManageChild on the result.

Most managed children are mapped, but some widgets can be in a state where they take up physical space but do not show anything. Managed widgets are not mapped automatically if their map_when_managed field is False. The default is True and is changed by using XtSetMappedWhenManaged.

Each composite widget class declares a geometry manager, which is responsible for figuring out where the managed children should appear within the composite widget’s window. Geometry management techniques fall into four classes:

Homogeneous boxesHomogeneous boxes treat all children equally and apply the same geometry constraints to each child. Many clients insert and delete widgets freely.

Heterogeneous boxes
Heterogeneous boxes have a specific location where each child is placed. This location usually is not specified in pixels, because the window may be resized, but is expressed rather in terms of the relationship between a child and the parent or between the child and other specific children. The class of heterogeneous boxes is usually a subclass of Constraint.

3.1. Addition of Children to a Composite Widget: The insert_child Procedure

To add a child to the parent’s list of children, the XtCreateWidget function calls the parent’s class routine insert_child. The insert_child procedure pointer in a composite widget is of type XtWidgetProc. __ │

typedef void (*XtWidgetProc)(Widget);
Widget w;

Most composite widgets inherit their superclass’s operation. The insert_child routine in CompositeWidgetClasscalls and inserts the child at the specified position in the children list, expanding it if necessary.

Some composite widgets define their own insert_child routine so that they can order their children in some convenient way, create companion controller widgets for a new widget, or limit the number or class of their child widgets. A composite widget class that wishes to allow nonwidget children (see Chapter 12) must specify a CompositeClassExtension extension record as described in Section 1.4.2.1 and set the accepts_objects field in this record to True. If the CompositeClassExtension record is not specified or the accepts_objects field is False, the composite widget can assume that all its children are of a subclass of Core without an explicit subclass test in the insert_child procedure.

If there is not enough room to insert a new child in the children array (that is, num_children is equal to num_slots), the insert_child procedure must first reallocate the array and update num_slots. The insert_child procedure then places the child at the appropriate position in the array and increments the num_children field.

3.2. Insertion Order of Children: The insert_position Procedure

Instances of composite widgets sometimes need to specify more about the order in which their children are kept. For example, an application may want a set of command buttons in some logical order grouped by function, and it may want buttons that represent file names to be kept in alphabetical order without constraining the order in which the buttons are created.

An application controls the presentation order of a set of children by supplying an XtNinsertPosition resource. The insert_position procedure pointer in a composite widget instance is of type XtOrderProc. __ │

typedef Cardinal (*XtOrderProc)(Widget);
Widget w;

Composite widgets that allow clients to order their children (usually homogeneous boxes) can call their widget instance’s insert_position procedure from the class’s insert_child procedure to determine where a new child should go in its children array. Thus, a client using a composite class can apply different sorting criteria to widget instances of the class, passing in a different insert_position procedure resource when it creates each composite widget instance.

The return value of the insert_position procedure indicates how many children should go before the widget. Returning zero indicates that the widget should go before all other children, and returning num_children indicates that it should go after all other children. The default insert_position function returns num_children and can be overridden by a specific composite widget’s resource list or by the argument list provided when the composite widget is created.

3.3. Deletion of Children: The delete_child Procedure

To remove the child from the parent’s children list, the XtDestroyWidget function eventually causes a call to the Composite parent’s class delete_child procedure. The delete_child procedure pointer is of type XtWidgetProc. __ │

typedef void (*XtWidgetProc)(Widget);
Widget w;

Most widgets inherit the delete_child procedure from their superclass. Composite widgets that create companion widgets define their own delete_child procedure to remove these companion widgets.

3.4. Adding and Removing Children from the Managed Set

The Intrinsics provide a set of generic routines to permit the addition of widgets to or the removal of widgets from a composite widget’s managed set. These generic routines eventually call the composite widget’s change_managed procedure if the procedure pointer is non-NULL. The change_managed procedure pointer is of type XtWidgetProc. The widget argument specifies the composite widget whose managed child set has been modified.

3.4.1. Managing Children

To add a list of widgets to the geometry-managed (and hence displayable) subset of their Composite parent, use XtManageChildren. __ │

typedef Widget *WidgetList;

void XtManageChildren(children, num_children)
WidgetList children;
Cardinal num_children;

must be of class RectObj or any subclass thereof.

num_children
Specifies the number of children in the list. │__

The XtManageChildren function performs the following:

Managing children is independent of the ordering of children and independent of creating and deleting children. The layout routine of the parent should consider children whose managed field is True and should ignore all other children. Note that some composite widgets, especially fixed boxes, call XtManageChild from their insert_child procedure.

If the parent widget is realized, its change_managed procedure is called to notify it that its set of managed children has changed. The parent can reposition and resize any of its children. It moves each child as needed by calling XtMoveWidget, which first updates the x and y fields and which then calls XMoveWindow.

If the composite widget wishes to change the size or border width of any of its children, it calls XtResizeWidget, which first updates the width, height, and border_width fields and then calls XConfigureWindow. Simultaneous repositioning and resizing may be done with XtConfigureWidget; see Section 6.6.

To add a single child to its parent widget’s set of managed children, use XtManageChild. __ │

void XtManageChild(child)
Widget child;

any subclass thereof. │__

The XtManageChild function constructs a WidgetList of length 1 and calls XtManageChildren.

To create and manage a child widget in a single procedure, use XtCreateManagedWidget or XtVaCreateManagedWidget. __ │

Widget XtCreateManagedWidget(name, widget_class, parent, args, num_args)
String name;
WidgetClass widget_class;
Widget parent;
ArgList args;
Cardinal num_args;

ated widget.

widget_class
Specifies the widget class pointer for the created
widget. Must be rectObjClass or any subclass
thereof.

Composite or any subclass thereof.

resource specifications.

list. │__

The XtCreateManagedWidget function is a convenience routine that calls XtCreateWidget and XtManageChild. __ │

Widget XtVaCreateManagedWidget(name, widget_class, parent, ...)
String name;
WidgetClass widget_class;
Widget parent;

ated widget.

widget_class
Specifies the widget class pointer for the created
widget. Must be rectObjClass or any subclass
thereof.

Composite or any subclass thereof.

any other resource specifications. │__

XtVaCreateManagedWidget is identical in function to XtCreateManagedWidget with the args and num_args parameters replaced by a varargs list, as described in Section 2.5.1.

3.4.2. Unmanaging Children

To remove a list of children from a parent widget’s managed list, use XtUnmanageChildren. __ │

void XtUnmanageChildren(children, num_children)
WidgetList children;
Cardinal num_children;

must be of class RectObj or any subclass thereof.

num_children
Specifies the number of children. │__

The XtUnmanageChildren function performs the following: