# Intrinsics and Widgets

The Intrinsics are a programming library tailored to the special requirements of user interface construction within a network window system, specifically the X Window System. The Intrinsics and a widget set make up an X Toolkit.

## Intrinsics

The Intrinsics provide the base mechanism necessary to build a wide variety of interoperating widget sets and application environments. The Intrinsics are a layer on top of Xlib, the C Library X Interface. They extend the fundamental abstractions provided by the X Window System while still remaining independent of any particular user interface policy or style.

The Intrinsics use object-oriented programming techniques to supply a consistent architecture for constructing and composing user interface components, known as widgets. This allows programmers to extend a widget set in new ways, either by deriving new widgets from existing ones (subclassing) or by writing entirely new widgets following the established conventions.

When the Intrinsics were first conceived, the root of the object hierarchy was a widget class named Core. In Release 4 of the Intrinsics, three nonwidget superclasses were added above Core. These superclasses are described in Nonwidget_Objects. The name of the class now at the root of the Intrinsics class hierarchy is Object. The remainder of this specification refers uniformly to widgets and Core as if they were the base class for all Intrinsics operations. The argument descriptions for each Intrinsics procedure and Nonwidget_Objects describe which operations are defined for the nonwidget superclasses of Core. The reader may determine by context whether a specific reference to widget actually means “widget” or “object.”

## Languages

The Intrinsics are intended to be used for two programming purposes. Programmers writing widgets will be using most of the facilities provided by the Intrinsics to construct user interface components from the simple, such as buttons and scrollbars, to the complex, such as control panels and property sheets. Application programmers will use a much smaller subset of the Intrinsics procedures in combination with one or more sets of widgets to construct and present complete user interfaces on an X display. The Intrinsics programming interfaces primarily intended for application use are designed to be callable from most procedural programming languages. Therefore, most arguments are passed by reference rather than by value. The interfaces primarily intended for widget programmers are expected to be used principally from the C language. In these cases, the usual C programming conventions apply. In this specification, the term client refers to any module, widget, or application that calls an Intrinsics procedure.

Applications that use the Intrinsics mechanisms must include the header files `<X11/Intrinsic.h>` and `<X11/StringDefs.h>`, or their equivalent, and they may also include `<X11/Xatoms.h>` and `<X11/Shell.h>`. In addition, widget implementations should include `<X11/IntrinsicP.h>` instead of `<X11/Intrinsic.h>`.

The applications must also include the additional header files for each widget class that they are to use (for example, `<X11/Xaw/Label.h>` or `<X11/Xaw/Scrollbar.h>).` On a POSIX-based system, the Intrinsics object library file is named `libXt.a` and is usually referenced as -lXt when linking the application.

## Procedures and Macros

All functions defined in this specification except those specified below may be implemented as C macros with arguments. C applications may use “#undef” to remove a macro definition and ensure that the actual function is referenced. Any such macro will expand to a single expression that has the same precedence as a function call and that evaluates each of its arguments exactly once, fully protected by parentheses, so that arbitrary expressions may be used as arguments.

The following symbols are macros that do not have function equivalents and that may expand their arguments in a manner other than that described above: XtCheckSubclass, XtNew, XtNumber, XtOffsetOf, XtOffset, and XtSetArg.

## Widgets

The fundamental abstraction and data type of the X Toolkit is the widget, which is a combination of an X window and its associated input and display semantics and which is dynamically allocated and contains state information. Some widgets display information (for example, text or graphics), and others are merely containers for other widgets (for example, a menu box). Some widgets are output-only and do not react to pointer or keyboard input, and others change their display in response to input and can invoke functions that an application has attached to them.

Every widget belongs to exactly one widget class, which is statically allocated and initialized and which contains the operations allowable on widgets of that class. Logically, a widget class is the procedures and data associated with all widgets belonging to that class. These procedures and data can be inherited by subclasses. Physically, a widget class is a pointer to a structure. The contents of this structure are constant for all widgets of the widget class but will vary from class to class. (Here, “constant” means the class structure is initialized at compile time and never changed, except for a one-time class initialization and in-place compilation of resource lists, which takes place when the first widget of the class or subclass is created.) For further information, see Creating_Widgets

The distribution of the declarations and code for a new widget class among a public .h file for application programmer use, a private .h file for widget programmer use, and the implementation .c file is described in Widget_Classing The predefined widget classes adhere to these conventions.

A widget instance is composed of two parts:

- A data structure which contains instance-specific values.

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

Much of the input/output of a widget (for example, fonts, colors, sizes, or border widths) is customizable by users.

This chapter discusses the base widget classes, Core, Composite, and Constraint, and ends with a discussion of widget classing.

### Core Widgets

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.

#### CoreClassPart Structure

All widget classes contain the fields defined in the `CoreClassPart` structure.

    typedef struct {
         WidgetClass superclass;      See Widget_Classing
         String class_name;           See Resource_Management
         Cardinal widget_size;        See Widget_Classing
         XtProc class_initialize;     See Widget_Classing
         XtWidgetClassProc class_part_initialize; See Widget_Classing
         XtEnum class_inited;         See Widget_Classing
         XtInitProc initialize;       See Creating_Widgets
         XtArgsProc initialize_hook;  See Creating_Widgets
         XtRealizeProc realize;       See Realizing_Widgets
         XtActionList actions;        See Translation_Management
         Cardinal num_actions;        See Translation_Management
         XtResourceList resources;    See Resource_Management
         Cardinal num_resources;      See Resource_Management
         XrmClass xrm_class;          Private to resource manager
         Boolean compress_motion;     See X_Event_Filters
         XtEnum compress_exposure;    See X_Event_Filters
         Boolean compress_enterleave; See X_Event_Filters
         Boolean visible_interest;    See Widget_Exposure_and_Visibility
         XtWidgetProc destroy;        See Destroying_Widgets
         XtWidgetProc resize;         See Geometry_Management
         XtExposeProc expose;         See Widget_Exposure_and_Visibility
         XtSetValuesFunc set_values;  See Reading_and_Writing_Widget_State
         XtArgsFunc set_values_hook;  See Reading_and_Writing_Widget_State
         XtAlmostProc set_values_almost; See Reading_and_Writing_Widget_State
         XtArgsProc get_values_hook;  See Reading_and_Writing_Widget_State
         XtAcceptFocusProc accept_focus; See Focusing_Events_on_a_Child
         XtVersionType version;       See Widget_Classing
         XtPointer callback_private;  Private to callbacks
         String tm_table;             See Translation_Management
         XtGeometryHandler query_geometry; See Geometry_Management
         XtStringProc display_accelerator; See Translation_Management
         XtPointer extension;         See Widget_Classing
    } CoreClassPart;

All widget classes have the Core class fields as their first component. The prototypical `WidgetClass` and `CoreWidgetClass` are defined with only this set of fields.

    typedef struct {
         CoreClassPart core_class;
    } WidgetClassRec, *WidgetClass, CoreClassRec, *CoreWidgetClass;

Various routines can cast widget class pointers, as needed, to specific widget class types.

The single occurrences of the class record and pointer for creating instances of Core are

In `IntrinsicP.h`:

    extern WidgetClassRec widgetClassRec;
    #define coreClassRec widgetClassRec

In `Intrinsic.h`:

    extern WidgetClass widgetClass, coreWidgetClass;

The opaque types `Widget` and `WidgetClass` and the opaque variable `widgetClass` are defined for generic actions on widgets. In order to make these types opaque and ensure that the compiler does not allow applications to access private data, the Intrinsics use incomplete structure definitions in `Intrinsic.h`:

    typedef struct _WidgetClassRec *WidgetClass, *CoreWidgetClass;

#### CorePart Structure

All widget instances contain the fields defined in the `CorePart` structure.

    typedef struct _CorePart {
         Widget self;                 Described below
         WidgetClass widget_class;    See Widget_Classing
         Widget parent;               See Creating_Widgets
         Boolean being_destroyed;     See Destroying_Widgets
         XtCallbackList destroy_callbacks; See Destroying_Widgets
         XtPointer constraints;       See Constrained_Composite_Widgets
         Position x;                  See Geometry_Management
         Position y;                  See Geometry_Management
         Dimension width;             See Geometry_Management
         Dimension height;            See Geometry_Management
         Dimension border_width;      See Geometry_Management
         Boolean managed;             See Composite_Widgets_and_Their_Children
         Boolean sensitive;           See Setting_and_Checking_the_Sensitivity_State_of_a_Widget
         Boolean ancestor_sensitive;  See Setting_and_Checking_the_Sensitivity_State_of_a_Widget
         XtTranslations accelerators; See Translation_Management
         Pixel border_pixel;          See Realizing_Widgets
         Pixmap border_pixmap;        See Realizing_Widgets
         WidgetList popup_list;       See Pop_Up_Widgets
         Cardinal num_popups;         See Pop_Up_Widgets
         String name;                 See Resource_Management
         Screen *screen;              See Realizing_Widgets
         Colormap colormap;           See Realizing_Widgets
         Window window;               See Realizing_Widgets
         Cardinal depth;              See Realizing_Widgets
         Pixel background_pixel;      See Realizing_Widgets
         Pixmap background_pixmap;    See Realizing_Widgets
         Boolean visible;             See Widget_Exposure_and_Visibility
         Boolean mapped_when_managed; See Composite_Widgets_and_Their_Children
    } CorePart;

All widget instances have the Core fields as their first component. The prototypical type `Widget` is defined with only this set of fields.

    typedef struct {
         CorePart core;
    } WidgetRec, *Widget, CoreRec, *CoreWidget;

Various routines can cast widget pointers, as needed, to specific widget types.

In order to make these types opaque and ensure that the compiler does not allow applications to access private data, the Intrinsics use incomplete structure definitions in `Intrinsic.h`.

    typedef struct _WidgetRec *Widget, *CoreWidget;

#### Core Resources

The resource names, classes, and representation types specified in the `coreClassRec` resource list are

Name | Class | Representation
XtNaccelerators | XtCAccelerators | XtRAcceleratorTable
XtNbackground | XtCBackground | XtRPixel
XtNbackgroundPixmap | XtCPixmap | XtRPixmap
XtNborderColor | XtCBorderColor | XtRPixel
XtNborderPixmap | XtCPixmap | XtRPixmap
XtNcolormap | XtCColormap | XtRColormap
XtNdepth | XtCDepth | XtRInt
XtNmappedWhenManaged | XtCMappedWhenManaged | XtRBoolean
XtNscreen | XtCScreen | XtRScreen
XtNtranslations | XtCTranslations | XtRTranslationTable

Additional resources are defined for all widgets via the `objectClassRec` and `rectObjClassRec` resource lists; see Object_Objects and Rectangle_Objects for details.

#### CorePart Default Values

The default values for the Core fields, which are filled in by the Intrinsics, from the resource lists, and by the initialize procedures, are

Field | Default Value
self | Address of the widget structure (may not be changed).
widget_class | widget_class argument to XtCreateWidget (may not be changed).
parent | parent argument to XtCreateWidget (may not be changed).
being_destroyed | Parent's being_destroyed value.
destroy_callbacks | NULL
constraints | NULL
x | 0
y | 0
width | 0
height | 0
border_width | 1
managed | `False`
sensitive | `True`
ancestor_sensitive | logical AND of parent's sensitive and ancestor_sensitive values.
accelerators | NULL
border_pixel | `XtDefaultForeground`
border_pixmap | `XtUnspecifiedPixmap`
popup_list | NULL
num_popups | 0
name | name argument to XtCreateWidget (may not be changed).
screen | Parent's screen; top-level widget gets screen from display specifier (may not be changed).
colormap | Parent's colormap value.
window | NULL
depth | Parent's depth; top-level widget gets root window depth.
background_pixel | `XtDefaultBackground`
background_pixmap | `XtUnspecifiedPixmap`
visible | `True`
mapped_when_managed | `True`

`XtUnspecifiedPixmap` is a symbolic constant guaranteed to be unequal to any valid Pixmap id, `None`, and `ParentRelative`.

### Composite Widgets

The Composite widget class is a subclass of the Core widget class (see 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.

#### CompositeClassPart Structure

In addition to the Core class fields, widgets of the Composite class have the following class fields.

    typedef struct {
         XtGeometryHandler geometry_manager; See Geometry_Management
         XtWidgetProc change_managed; See Composite_Widgets_and_Their_Children
         XtWidgetProc insert_child;   See Composite_Widgets_and_Their_Children
         XtWidgetProc delete_child;   See Composite_Widgets_and_Their_Children
         XtPointer extension;         See Widget_Classing
    } CompositeClassPart;

The extension record defined for `CompositeClassPart` with record_type equal to NULLQUARK is `CompositeClassExtensionRec`.

    typedef struct {
         XtPointer next_extension;    See Class_Extension_Records
         XrmQuark record_type;        See Class_Extension_Records
         long version;                See Class_Extension_Records
         Cardinal record_size;        See Class_Extension_Records
         Boolean accepts_objects;     See Creating_a_Widget_Instance
         Boolean allows_change_managed_set; See Bundling_Changes_to_the_Managed_Set
    } CompositeClassExtensionRec, *CompositeClassExtension;

Composite classes have the Composite class fields immediately following the Core class fields.

    typedef struct {
         CoreClassPart core_class;
         CompositeClassPart composite_class;
    } CompositeClassRec, *CompositeWidgetClass;

The single occurrences of the class record and pointer for creating instances of Composite are

In `IntrinsicP.h`:

    extern CompositeClassRec compositeClassRec;

In `Intrinsic.h`:

    extern WidgetClass compositeWidgetClass;

The opaque types `CompositeWidget` and `CompositeWidgetClass` and the opaque variable `compositeWidgetClass` are defined for generic operations on widgets whose class is Composite or a subclass of Composite. The symbolic constant for the `CompositeClassExtension` version identifier is `XtCompositeExtensionVersion` (see Class_Extension_Records). `Intrinsic.h` uses an incomplete structure definition to ensure that the compiler catches attempts to access private data.

    typedef struct _CompositeClassRec *CompositeWidgetClass;

#### CompositePart Structure

In addition to the Core instance fields, widgets of the Composite class have the following instance fields defined in the `CompositePart` structure.

    typedef struct {
         WidgetList children;         See Composite_Widgets_and_Their_Children
         Cardinal num_children;       See Composite_Widgets_and_Their_Children
         Cardinal num_slots;          See Composite_Widgets_and_Their_Children
         XtOrderProc insert_position; See Insertion_Order_of_Children_The_insert_position_Procedure
    } CompositePart;

Composite widgets have the Composite instance fields immediately following the Core instance fields.

    typedef struct {
         CorePart core;
         CompositePart composite;
    } CompositeRec, *CompositeWidget;

`Intrinsic.h` uses an incomplete structure definition to ensure that the compiler catches attempts to access private data.

    typedef struct _CompositeRec *CompositeWidget;

#### Composite Resources

The resource names, classes, and representation types that are specified in the `compositeClassRec` resource list are

Name | Class | Representation
XtNchildren | XtCReadOnly | XtRWidgetList
XtNinsertPosition | XtCInsertPosition | XtRFunction
XtNnumChildren | XtCReadOnly | XtRCardinal

#### CompositePart Default Values

The default values for the Composite fields, which are filled in from the Composite resource list and by the Composite initialize procedure, are

Field | Default Value
children | NULL
num_children | 0
num_slots | 0
insert_position | Internal function to insert at end

The children, num_children, and insert_position fields are declared as resources; XtNinsertPosition is a settable resource, XtNchildren and XtNnumChildren may be read by any client but should only be modified by the composite widget class procedures.

### Constraint Widgets

The Constraint widget class is a subclass of the Composite widget class (see 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.

#### ConstraintClassPart Structure

In addition to the Core and Composite class fields, widgets of the Constraint class have the following class fields.

    typedef struct {
         XtResourceList resources;    See Resource_Management
         Cardinal num_resources;      See Resource_Management
         Cardinal constraint_size;    See Constrained_Composite_Widgets
         XtInitProc initialize;       See Constrained_Composite_Widgets
         XtWidgetProc destroy;        See Constrained_Composite_Widgets
         XtSetValuesFunc set_values;  See Setting_Widget_State
         XtPointer extension;         See Widget_Classing
    } ConstraintClassPart;

The extension record defined for `ConstraintClassPart` with record_type equal to NULLQUARK is `ConstraintClassExtensionRec`.

    typedef struct {
         XtPointer next_extension;    See Class_Extension_Records
         XrmQuark record_type;        See Class_Extension_Records
         long version;                See Class_Extension_Records
         Cardinal record_size;        See Class_Extension_Records
         XtArgsProc get_values_hook;  See Obtaining_Widget_State
    } ConstraintClassExtensionRec, *ConstraintClassExtension;

Constraint classes have the Constraint class fields immediately following the Composite class fields.

    typedef struct _ConstraintClassRec {
         CoreClassPart core_class;
         CompositeClassPart composite_class;
         ConstraintClassPart constraint_class;
    } ConstraintClassRec, *ConstraintWidgetClass;

The single occurrences of the class record and pointer for creating instances of Constraint are

In `IntrinsicP.h`:

    extern ConstraintClassRec constraintClassRec;

In `Intrinsic.h`:

    extern WidgetClass constraintWidgetClass;

The opaque types `ConstraintWidget` and `ConstraintWidgetClass` and the opaque variable `constraintWidgetClass` are defined for generic operations on widgets whose class is Constraint or a subclass of Constraint. The symbolic constant for the `ConstraintClassExtension` version identifier is `XtConstraintExtensionVersion` (see Class_Extension_Records). `Intrinsic.h` uses an incomplete structure definition to ensure that the compiler catches attempts to access private data.

    typedef struct _ConstraintClassRec *ConstraintWidgetClass;

#### ConstraintPart Structure

In addition to the Core and Composite instance fields, widgets of the Constraint class have the following unused instance fields defined in the `ConstraintPart` structure

    typedef struct {
            int empty;
    } ConstraintPart;

Constraint widgets have the Constraint instance fields immediately following the Composite instance fields.

    typedef struct {
         CorePart core;
         CompositePart composite;
         ConstraintPart constraint;
    } ConstraintRec, *ConstraintWidget;

`Intrinsic.h` uses an incomplete structure definition to ensure that the compiler catches attempts to access private data.

    typedef struct _ConstraintRec *ConstraintWidget;

#### Constraint Resources

The `constraintClassRec` core_class and constraint_class resources fields are NULL, and the num_resources fields are zero; no additional resources beyond those declared by the superclasses are defined for Constraint.

## Implementation-Specific Types

To increase the portability of widget and application source code between different system environments, the Intrinsics define several types whose precise representation is explicitly dependent upon, and chosen by, each individual implementation of the Intrinsics.

These implementation-defined types are

Boolean

- A datum that contains a zero or nonzero value. Unless explicitly stated, clients should not assume that the nonzero value is equal to the symbolic value `True`.

Cardinal

- An unsigned integer datum with a minimum range of [0..216-1].

Dimension

- An unsigned integer datum with a minimum range of [0..216-1].

Position

- A signed integer datum with a minimum range of [-215..215-1].

XtPointer

- A datum large enough to contain the largest of a char*, int*, function pointer, structure pointer, or long value. A pointer to any type or function, or a long value may be converted to an `XtPointer` and back again and the result will compare equal to the original value. In ANSI C environments it is expected that `XtPointer` will be defined as void*.

XtArgVal

- A datum large enough to contain an `XtPointer`, `Cardinal`, `Dimension`, or `Position` value.

XtEnum

- An integer datum large enough to encode at least 128 distinct values, two of which are the symbolic values `True` and `False`. The symbolic values TRUE and FALSE are also defined to be equal to `True` and `False`, respectively.

In addition to these specific types, the precise order of the fields within the structure declarations for any of the instance part records `ObjectPart`, `RectObjPart`, `CorePart`, `CompositePart`, `ShellPart`, `WMShellPart`, `TopLevelShellPart`, and `ApplicationShellPart` is implementation-defined. These structures may also have additional private fields internal to the implementation. The `ObjectPart`, `RectObjPart`, and `CorePart` structures must be defined so that any member with the same name appears at the same offset in `ObjectRec`, `RectObjRec`, and `CoreRec` `( WidgetRec ).` No other relations between the offsets of any two fields may be assumed.

## Widget Classing

The widget_class field of a widget points to its widget class structure, which contains information that is constant across all widgets of that class. As a consequence, widgets usually do not implement directly callable procedures; rather, they implement procedures, called methods, that are available through their widget class structure. These methods are invoked by generic procedures that envelop common actions around the methods implemented by the widget class. Such procedures are applicable to all widgets of that class and also to widgets whose classes are subclasses of that class.

All widget classes are a subclass of Core and can be subclassed further. Subclassing reduces the amount of code and declarations necessary to make a new widget class that is similar to an existing class. For example, you do not have to describe every resource your widget uses in an `XtResourceList`. Instead, you describe only the resources your widget has that its superclass does not. Subclasses usually inherit many of their superclasses' procedures (for example, the expose procedure or geometry handler).

Subclassing, however, can be taken too far. If you create a subclass that inherits none of the procedures of its superclass, you should consider whether you have chosen the most appropriate superclass.

To make good use of subclassing, widget declarations and naming conventions are highly stylized. A widget consists of three files:

- A public .h file, used by client widgets or applications.

- A private .h file, used by widgets whose classes are subclasses of the widget class.

- A .c file, which implements the widget.

### Widget Naming Conventions

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

- Use the X library naming conventions that are applicable. For example, a record component name is all lowercase and uses underscores (_) for compound words (for example, background_pixmap). Type and procedure names start with uppercase and use capitalization for compound words (for example, `ArgList` or `XtSetValues ).`

- A resource name is spelled identically to the field name except that compound names use capitalization rather than underscore. To let the compiler catch spelling errors, each resource name should have a symbolic identifier prefixed with “XtN”. For example, the background_pixmap field has the corresponding identifier XtNbackgroundPixmap, which is defined as the string “backgroundPixmap”. Many predefined names are listed in `<X11/StringDefs.h>`. Before you invent a new name, you should make sure there is not already a name that you can use.

- A resource class string starts with a capital letter and uses capitalization for compound names (for example,“BorderWidth”). Each resource class string should have a symbolic identifier prefixed with “XtC” (for example, XtCBorderWidth). Many predefined classes are listed in `<X11/StringDefs.h>`.

- A resource representation string is spelled identically to the type name (for example, “TranslationTable”). Each representation string should have a symbolic identifier prefixed with “XtR” (for example, XtRTranslationTable). Many predefined representation types are listed in `<X11/StringDefs.h>`.

- New widget classes start with a capital and use uppercase for compound words. Given a new class name AbcXyz, you should derive several names:

  - Additional widget instance structure part name AbcXyzPart.

  - Complete widget instance structure names AbcXyzRec and _AbcXyzRec.

  - Widget instance structure pointer type name AbcXyzWidget.

  - Additional class structure part name AbcXyzClassPart.

  - Complete class structure names AbcXyzClassRec and _AbcXyzClassRec.

  - Class structure pointer type name AbcXyzWidgetClass.

  - Class structure variable abcXyzClassRec.

  - Class structure pointer variable abcXyzWidgetClass.

- Action procedures available to translation specifications should follow the same naming conventions as procedures. That is, they start with a capital letter, and compound names use uppercase (for example, “Highlight” and “NotifyClient”).

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

### Widget Subclassing in Public .h Files

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

- A reference to the public .h file for the superclass.

- Symbolic identifiers for the names and classes of the new resources that this widget adds to its superclass. The definitions should have a single space between the definition name and the value and no trailing space or comment in order to reduce the possibility of compiler warnings from similar declarations in multiple classes.

- Type declarations for any new resource data types defined by the class.

- The class record pointer variable used to create widget instances.

- The C type that corresponds to widget instances of this class.

- Entry points for new class methods.

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

    #ifndef LABEL_H
    #define LABEL_H

    /* New resources */
    #define XtNjustify              "justify"
    #define XtNforeground           "foreground"
    #define XtNlabel                "label"
    #define XtNfont                 "font"
    #define XtNinternalWidth        "internalWidth"
    #define XtNinternalHeight       "internalHeight"

    /* Class record pointer */
    extern WidgetClass labelWidgetClass;

    /* C Widget type definition */
    typedef struct _LabelRec        *LabelWidget;

    /* New class method entry points */
    extern void LabelSetText(Widget w, String text);
    extern String LabelGetText(Widget w);

    #endif LABEL_H

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

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

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

- A reference to the public .h file for the class.

- A reference to the private .h file for the superclass.

- Symbolic identifiers for any new resource representation types defined by the class. The definitions should have a single space between the definition name and the value and no trailing space or comment.

- A structure part definition for the new fields that the widget instance adds to its superclass's widget structure.

- The complete widget instance structure definition for this widget.

- A structure part definition for the new fields that this widget class adds to its superclass's constraint structure if the widget class is a subclass of Constraint.

- The complete constraint structure definition if the widget class is a subclass of Constraint.

- Type definitions for any new procedure types used by class methods declared in the widget class part.

- A structure part definition for the new fields that this widget class adds to its superclass's widget class structure.

- The complete widget class structure definition for this widget.

- The complete widget class extension structure definition for this widget, if any.

- The symbolic constant identifying the class extension version, if any.

- The name of the global class structure variable containing the generic class structure for this class.

- An inherit constant for each new procedure in the widget class part structure.

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

    #ifndef LABELP_H
    #define LABELP_H

    #include <X11/Label.h>

    /* New representation types used by the Label widget */
    #define XtRJustify "Justify"

    /* New fields for the Label widget record */
    typedef struct {
    /* Settable resources */
         Pixel      foreground;
         XFontStruct *font;
         String     label; /* text to display */
         XtJustify  justify;
         Dimension  internal_width;         /* # pixels horizontal border */
         Dimension  internal_height;        /* # pixels vertical border */
    /* Data derived from resources */
         GC         normal_GC;
         GC         gray_GC;
         Pixmap     gray_pixmap;
         Position   label_x;
         Position   label_y;
         Dimension  label_width;
         Dimension  label_height;
         Cardinal   label_len;
         Boolean    display_sensitive;
    } LabelPart;

    /* Full instance record declaration */
    typedef struct _LabelRec {
         CorePart   core;
         LabelPart  label;
    } LabelRec;

    /* Types for Label class methods */
    typedef void (*LabelSetTextProc)(Widget w, String text);
    typedef String (*LabelGetTextProc)(Widget w);

    /* New fields for the Label widget class record */
    typedef struct {
         LabelSetTextProc set_text;
         LabelGetTextProc get_text;
         XtPointer extension;
    } LabelClassPart;

    /* Full class record declaration */
    typedef struct _LabelClassRec {
         CoreClassPart core_class;
         LabelClassPart label_class;
    } LabelClassRec;

    /* Class record variable */
    extern LabelClassRec labelClassRec;

    #define LabelInheritSetText((LabelSetTextProc)_XtInherit)
    #define LabelInheritGetText((LabelGetTextProc)_XtInherit)

    #endif LABELP_H

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

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

- Class information (for example, superclass, class_name, widget_size, class_initialize, and class_inited).

- Data constants (for example, resources and num_resources, actions and num_actions, visible_interest, compress_motion, compress_exposure, and version).

- Widget operations (for example, initialize, realize, destroy, resize, expose, set_values, accept_focus, and any new operations specific to the widget).

The superclass field points to the superclass global class record, declared in the superclass private .h file. For direct subclasses of the generic core widget, superclass should be initialized to the address of the `widgetClassRec` structure. The superclass is used for class chaining operations and for inheriting or enveloping a superclass's operations (see Superclass_Chaining, Initializing_a_Widget_Class, and 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 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 Resource_Management.

    /* Resources specific to Label */
    static XtResource resources[] = {
         {XtNforeground, XtCForeground, XtRPixel, sizeof(Pixel),
            XtOffset(LabelWidget, label.foreground), XtRString,
            XtDefaultForeground},
         {XtNfont, XtCFont, XtRFontStruct, sizeof(XFontStruct *),
            XtOffset(LabelWidget, label.font),XtRString,
            XtDefaultFont},
         {XtNlabel, XtCLabel, XtRString, sizeof(String),
            XtOffset(LabelWidget, label.label), XtRString, NULL},
              .
              .
              .
    }

    /* Forward declarations of procedures */
    static void ClassInitialize(void);
    static void Initialize(Widget, Widget, ArgList, Cardinal*);
    static void Realize(Widget, XtValueMask*, XSetWindowAttributes*);
    static void SetText(Widget, String);
    static void GetText(Widget);
         .
         .
         .

    /* Class record constant */
    LabelClassRec labelClassRec = {
      {
        /* core_class fields */
         /* superclass                */    (WidgetClass)&coreClassRec,
         /* class_name                */    "Label",
         /* widget_size               */    sizeof(LabelRec),
         /* class_initialize          */    ClassInitialize,
         /* class_part_initialize     */    NULL,
         /* class_inited              */    False,
         /* initialize                */    Initialize,
         /* initialize_hook           */    NULL,
         /* realize                   */    Realize,
         /* actions                   */    NULL,
         /* num_actions               */    0,
         /* resources                 */    resources,
         /* num_resources             */    XtNumber(resources),
         /* xrm_class                 */    NULLQUARK,
         /* compress_motion           */    True,
         /* compress_exposure         */    True,
         /* compress_enterleave       */    True,
         /* visible_interest          */    False,
         /* destroy                   */    NULL,
         /* resize                    */    Resize,
         /* expose                    */    Redisplay,
         /* set_values                */    SetValues,
         /* set_values_hook           */    NULL,
         /* set_values_almost         */    XtInheritSetValuesAlmost,
         /* get_values_hook           */    NULL,
         /* accept_focus              */    NULL,
         /* version                   */    XtVersion,
         /* callback_offsets          */    NULL,
         /* tm_table                  */    NULL,
         /* query_geometry            */    XtInheritQueryGeometry,
         /* display_accelerator       */    NULL,
         /* extension                 */    NULL
      },
      {
        /* Label_class fields         */
         /* get_text                  */    GetText,
         /* set_text                  */    SetText,
         /* extension                 */    NULL
      }
    };

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

    /* New method access routines */
    void LabelSetText(Widget w, String text)
    {
         LabelWidgetClass lwc = (Label WidgetClass)XtClass(w);
         XtCheckSubclass(w, labelWidgetClass, NULL);
         *(lwc->label_class.set_text)(w, text)
    }

    /* Private procedures */
         .
         .
         .

### Widget Class and Superclass Look Up

To obtain the class of a widget, use XtClass.

        WidgetClass XtClass
        Widget w

w

- Specifies the widget. Must be of class Object or any subclass thereof.

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

To obtain the superclass of a widget, use `XtSuperclass`.

      WidgetClass XtSuperClass
      Widget w

w

- Specifies the widget. Must be of class Object or any subclass thereof.

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

### Widget Subclass Verification

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

      Boolean XtIsSubclass
      Widget w
      WidgetClass widget_class

w

- Specifies the widget or object instance whose class is to be checked. Must be of class Object or any subclass thereof.

widget_class

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

The XtIsSubclass function returns `True` if the class of the specified widget is equal to or is a subclass of the specified class. The widget's class can be any number of subclasses down the chain and need not be an immediate subclass of the specified class. Composite widgets that need to restrict the class of the items they contain can use XtIsSubclass to find out if a widget belongs to the desired class of objects.

To test if a given widget belongs to a subclass of an Intrinsics-defined class, the Intrinsics define macros or functions equivalent to XtIsSubclass for each of the built-in classes. These procedures are `XtIsObject`, `XtIsRectObj`, `XtIsWidget`, `XtIsComposite`, `XtIsConstraint`, `XtIsShell`, `XtIsOverrideShell`, `XtIsWMShell`, `XtIsVendorShell`, `XtIsTransientShell`, `XtIsTopLevelShell`, `XtIsApplicationShell`, and `XtIsSessionShell`.

All these macros and functions have the same argument description.

      Boolean XtIs<class>
      Widget w

w

- Specifies the widget or object instance whose class is to be checked. Must be of class Object or any subclass thereof.

These procedures may be faster than calling XtIsSubclass directly for the built-in classes.

To check a widget's class and to generate a debugging error message, use XtCheckSubclass, defined in `<X11/IntrinsicP.h>`:

      void XtCheckSubclass
      Widget w
      WidgetClass widget_class
      String message

w

- Specifies the widget or object whose class is to be checked. Must be of class Object or any subclass thereof.

widget_class

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

message

- Specifies the message to be used.

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

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

### 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
                                             class_initialize
                                             widget_size
                                             realize
                                             visible_interest
                                             resize
                                             expose
                                             accept_focus
                                             compress_motion
                                             compress_exposure
                                             compress_enterleave
                                             set_values_almost
                                             tm_table
                                             version
                                             allocate
                                             deallocate

    In Composite widget classes:             geometry_manager
                                             change_managed
                                             insert_child
                                             delete_child
                                             accepts_objects
                                             allows_change_managed_set

    In Constraint widget classes:            constraint_size

    In Shell widget classes:                 root_geometry_manager

With downward superclass chaining, the invocation of an operation first accesses the field from the Object, RectObj, and Core class structures, then from the subclass structure, and so on down the class chain to that widget's class structure. These superclass-to-subclass fields are

                                             class_part_initialize
                                             get_values_hook
                                             initialize
                                             initialize_hook
                                             set_values
                                             set_values_hook
                                             resources

In addition, for subclasses of Constraint, the following fields of the `ConstraintClassPart` and `ConstraintClassExtensionRec` structures are chained from the Constraint class down to the subclass:

                                             resources
                                             initialize
                                             set_values
                                             get_values_hook

With upward superclass chaining, the invocation of an operation first accesses the field from the widget class structure, then from the superclass structure, and so on up the class chain to the Core, RectObj, and Object class structures. The subclass-to-superclass fields are

                                             destroy
                                             actions

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

                                             destroy

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

    static void ClassInitialize(void)
    {
         XtSetTypeConverter(XtRString, XtRJustify, CvtStringToJustify,
              NULL, 0, XtCacheNone, NULL);
    }

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

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

    #define XtInheritGeometryManager ((XtGeometryHandler) _XtInherit)
    #define XtInheritChangeManaged   ((XtWidgetProc)      _XtInherit)
    #define XtInheritInsertChild     ((XtArgsProc)        _XtInherit)
    #define XtInheritDeleteChild     ((XtWidgetProc)      _XtInherit)

Composite's class_part_initialize procedure begins as follows:

    static void CompositeClassPartInitialize(WidgetClass widgetClass)
    {
         CompositeWidgetClass wc = (CompositeWidgetClass)widgetClass;
         CompositeWidgetClass super = (CompositeWidgetClass)wc->core_class.superclass;
         if (wc->composite_class.geometry_manager == XtInheritGeometryManager) {
             wc->composite_class.geometry_manager = super->composite_class.geometry_manager;
         }
         if (wc->composite_class.change_managed == XtInheritChangeManaged) {
             wc->composite_class.change_managed = super->composite_class.change_managed;
         }
         .
         .
         .
    }

Nonprocedure fields may be inherited in the same manner as procedure fields. The class may declare any reserved value it wishes for the inheritance constant for its new fields. The following inheritance constants are defined:

For Object:

- `XtInheritAllocate`

- `XtInheritDeallocate`

For Core:

- `XtInheritRealize`

- `XtInheritResize`

- `XtInheritExpose`

- `XtInheritSetValuesAlmost`

- `XtInheritAcceptFocus`

- `XtInheritQueryGeometry`

- `XtInheritTranslations`

- `XtInheritDisplayAccelerator`

For Composite:

- `XtInheritGeometryManager`

- `XtInheritChangeManaged`

- `XtInheritInsertChild`

- `XtInheritDeleteChild`

For Shell:

- `XtInheritRootGeometryManager`

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

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.

### 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 {
         XtPointer next_extension;
         XrmQuark  record_type;
         long      version;
         Cardinal  record_size;
    };

next_extension

- Specifies the next record in the list, or NULL.

record_type

- Specifies the particular structure declaration to which each extension record instance conforms.

version

- Specifies a version id symbolic constant supplied by the definer of the structure.

record_size

- Specifies the total number of bytes allocated for the extension record.

The record_type field identifies the contents of the extension record and is used by the definer of the record to locate its particular extension record in the list. The record_type field is normally assigned the result of `XrmStringToQuark` for a registered string constant. The Intrinsics reserve all record type strings beginning with the two characters “XT” for future standard uses. The value NULLQUARK may also be used by the class part owner in extension records attached to its own class part extension field to identify the extension record unique to that particular class.

The version field is an owner-defined constant that may be used to identify binary files that have been compiled with alternate definitions of the remainder of the extension record data structure. The private header file for a widget class should provide a symbolic constant for subclasses to use to initialize this field. The record_size field value includes the four common header fields and should normally be initialized with `sizeof().`

Any value stored in the class part extension fields of `CompositeClassPart`, `ConstraintClassPart`, or `ShellClassPart` must point to an extension record conforming to this definition.

The Intrinsics provide a utility function for widget writers to locate a particular class extension record in a linked list, given a widget class and the offset of the extension field in the class record.

To locate a class extension record, use XtGetClassExtension.

      XtPointer XtGetClassExtension
      WidgetClass object_class
      Cardinal byte_offset
      XrmQuark type
      long version
      Cardinal record_size

object_class

- Specifies the object class containing the extension list to be searched.

byte_offset

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

type

- Specifies the record_type of the class extension to be located.

version

- Specifies the minimum acceptable version of the class extension required for a match.

record_size

- Specifies the minimum acceptable length of the class extension record required for a match, or 0.

The list of extension records at the specified offset in the specified object class will be searched for a match on the specified type, a version greater than or equal to the specified version, and a record size greater than or equal the specified record_size if it is nonzero. XtGetClassExtension returns a pointer to a matching extension record or NULL if no match is found. The returned extension record must not be modified or freed by the caller if the caller is not the extension owner.