X Toolkit Intrinsics - C Language Interface

The Core widget class contains the definitions of fields common to all widgets. All widgets classes are subclasses of the Core class, which is defined by the CoreClassPart and CorePart structures.

The Composite widget class is a subclass of the Core widget class (see Chapter 3, Composite Widgets and Their Children). Composite widgets are intended to be containers for other widgets. The additional data used by composite widgets are defined by the CompositeClassPart and CompositePart structures.

The Constraint widget class is a subclass of the Composite widget class (see the section called “Constrained Composite Widgets”). Constraint widgets maintain additional state data for each child; for example, client-defined constraints on the child's geometry. The additional data used by constraint widgets are defined by the ConstraintClassPart and ConstraintPart structures.

The Intrinsics provide a vehicle by which programmers can create new widgets and organize a collection of widgets into an application. To ensure that applications need not deal with as many styles of capitalization and spelling as the number of widget classes it uses, the following guidelines should be followed when writing new widgets:

The symbolic identifiers XtN..., XtC..., and XtR... may be implemented as macros, as global symbols, or as a mixture of the two. The (implicit) type of the identifier is String. The pointer value itself is not significant; clients must not assume that inequality of two identifiers implies inequality of the resource name, class, or representation string. Clients should also note that although global symbols permit savings in literal storage in some environments, they also introduce the possibility of multiple definition conflicts when applications attempt to use independently developed widgets simultaneously.

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

For example, the following is the public .h file for a possible implementation of a Label widget:

The conditional inclusion of the text allows the application to include header files for different widgets without being concerned that they already may be included as a superclass of another widget.

To accommodate operating systems with file name length restrictions, the name of the public .h file is the first ten characters of the widget class. For example, the public .h file for the Constraint widget class is Constraint.h.

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

For example, the following is the private .h file for a possible Label widget:

To accommodate operating systems with file name length restrictions, the name of the private .h file is the first nine characters of the widget class followed by a capital P. For example, the private .h file for the Constraint widget class is ConstrainP.h.

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

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 the section called “Superclass Chaining”, the section called “Initializing a Widget Class”, and the section called “Inheritance of Superclass Operations”.

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, Evolution of the Intrinsics. 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, Resource Management.

To obtain the class of a widget, use XtClass.

The XtClass function returns a pointer to the widget's class structure.

To obtain the superclass of a widget, use XtSuperclass.

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

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

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.

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

The XtCheckSubclass macro determines if the class of the specified widget is equal to or is a subclass of the specified class. The widget's class can be any number of subclasses down the chain and need not be an immediate subclass of the specified class. If the specified widget's class is not a subclass, XtCheckSubclass constructs an error message from the supplied message, the widget's actual class, and the expected class and calls XtErrorMsg. XtCheckSubclass should be used at the entry point of exported routines to ensure that the client has passed in a valid widget class for the exported operation.

XtCheckSubclass is only executed when the module has been compiled with the compiler symbol DEBUG defined; otherwise, it is defined as the empty string and generates no code.

While most fields in a widget class structure are self-contained, some fields are linked to their corresponding fields in their superclass structures. With a linked field, the Intrinsics access the field's value only after accessing its corresponding superclass value (called downward superclass chaining) or before accessing its corresponding superclass value (called upward superclass chaining). The self-contained fields are

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

Many class records can be initialized completely at compile or link time. In some cases, however, a class may need to register type converters or perform other sorts of once-only runtime initialization.

Because the C language does not have initialization procedures that are invoked automatically when a program starts up, a widget class can declare a class_initialize procedure that will be automatically called exactly once by the Intrinsics. A class initialization procedure pointer is of type XtProc:

typedef void (*XtProc)(void);

A widget class indicates that it has no class initialization procedure by specifying NULL in the class_initialize field.

In addition to the class initialization that is done exactly once, some classes perform initialization for fields in their parts of the class record. These are performed not just for the particular class, but for subclasses as well, and are done in the class's class part initialization procedure, a pointer to which is stored in the class_part_initialize field. The class_part_initialize procedure pointer is of type XtWidgetClassProc.

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 the section called “Initializing a Widget Class” 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.

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.

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 the section called “Resource Conversions”).

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

To inherit an operation xyz, specify the constant XtInherit Xyz 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:

Composite's class_part_initialize procedure begins as follows:

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:

For Core:

For Composite:

For Shell:

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.

This technique is referred to as enveloping the superclass's operation.

It may be necessary at times to add new fields to already existing widget class structures. To permit this to be done without requiring recompilation of all subclasses, the last field in a class part structure should be an extension pointer. If no extension fields for a class have yet been defined, subclasses should initialize the value of the extension pointer to NULL.

If extension fields exist, as is the case with the Composite, Constraint, and Shell classes, subclasses can provide values for these fields by setting the extension pointer for the appropriate part in their class structure to point to a statically declared extension record containing the additional fields. Setting the extension field is never mandatory; code that uses fields in the extension record must always check the extension field and take some appropriate default action if it is NULL.

In order to permit multiple subclasses and libraries to chain extension records from a single extension field, extension records should be declared as a linked list, and each extension record definition should contain the following four fields at the beginning of the structure declaration:

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.

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.

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

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.

The XtSetArg function is usually used in a highly stylized manner to minimize the probability of making a mistake; for example:

Alternatively, an application can statically declare the argument list and use XtNumber:

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.

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.

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 the section called “Resource Conversions”) 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.

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.

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.

To create an instance of a widget, use XtCreateWidget.

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.

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.

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.

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 application\%Shell\%Widget\%Class 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:

The second method, which is best if there is no main window, leads to resource specifications like the following:

To create a top-level widget that is the root of a widget tree using varargs lists, use XtVaAppCreateShell.

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.

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.

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.

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.

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.

The allocate procedure pointer in the ObjectClassExtension record is of type (*AllocateProc).

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 (*AllocateProc) 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 (*AllocateProc) is found, the Intrinsics will allocate memory for the widget.

An (*AllocateProc) 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.

The initialize procedure pointer in a widget class is of type (*XtInitProc).

An initialization procedure performs the following:

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.

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.

The initialize_hook procedure pointer is of type (*XtArgsProc):

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.

The realize procedure pointer in a widget class is of type (*XtRealizeProc).

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 the section called “Inheritance of Superclass Operations”).

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.

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.

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.

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

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.

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, Callbacks. 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.

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

The ClientDestroy argument is of type (*XtCallbackProc); see the section called “Using Callback Procedure and Callback List Definitions”.

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

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.

The constraint destroy procedure identified in the ConstraintClassPart 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 constraint\%WidgetClass. 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.

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

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.

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

typedef Widget *WidgetList;

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 the section called “Widget Placement and Sizing”.

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

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.

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

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.

To remove a list of children from a parent widget's managed list, use XtUnmanageChildren.

The XtUnmanageChildren function performs the following:

XtUnmanageChildren does not destroy the child widgets. Removing widgets from a parent's managed set is often a temporary banishment, and some time later the client may manage the children again. To destroy widgets entirely, XtDestroyWidget should be called instead; see the section called “Exiting from an Application”.

To remove a single child from its parent widget's managed set, use XtUnmanageChild.

The XtUnmanageChild function constructs a widget list of length 1 and calls XtUnmanageChildren.

These functions are low-level routines that are used by generic composite widget building routines. In addition, composite widgets can provide widget-specific, high-level convenience procedures.

A client may simultaneously unmanage and manage children with a single call to the Intrinsics. In this same call the client may provide a callback procedure that can modify the geometries of one or more children. The composite widget class defines whether this single client call results in separate invocations of the change_managed method, one to unmanage and the other to manage, or in just a single invocation.

To simultaneously remove from and add to the geometry-managed set of children of a composite parent, use XtChangeManagedSet.

The XtChangeManagedSet function performs the following:

If no CompositeClassExtension record is found in the parent's composite class part extension field with record type NULLQUARK and version greater than 1, and if XtInheritChangeManaged was specified in the parent's class record during class initialization, the value of the allows_change_managed_set field is inherited from the superclass. The value inherited from compositeWidgetClass for the allows_change_managed_set field is False.

It is not an error to include a child in both the unmanage_children and the manage_children lists. The effect of such a call is that the child remains managed following the call, but the do_change_proc is able to affect the child while it is in an unmanaged state.

The do_change_proc is of type *XtDoChangeProc.

The do_change_proc procedure is used by the caller of XtChangeManagedSet to make changes to one or more children at the point when the managed set contains the fewest entries. These changes may involve geometry requests, and in this case the caller of XtChangeManagedSet may take advantage of the fact that the Intrinsics internally grant geometry requests made by unmanaged children without invoking the parent's geometry manager. To achieve this advantage, if the do_change_proc procedure changes the geometry of a child or of a descendant of a child, then that child should be included in the unmanage_children and manage_children lists.

To determine the managed state of a given child widget, use XtIsManaged.

The XtIsManaged function returns True if the specified widget is of class RectObj or any subclass thereof and is managed, or False otherwise.

Only the Shell class has additional class fields, which are all contained in the ShellClassExtensionRec. None of the other Shell classes have any additional class fields:

The full Shell class record definitions are:

The single occurrences of the class records and pointers for creating instances of shells are:

The following opaque types and opaque variables are defined for generic operations on widgets whose class is a subclass of Shell.