2.1. Introduction   

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

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

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

2.1.1.1. CoreClassPart Structure   

All widget classes contain the fields defined in the CoreClassPart structure (see over page).

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;

     typedef struct {

         WidgetClass superclass;

         String class_name;

         Cardinal widget_size;

         XtProc class_initialize;

         XtWidgetClassProc class_part_initialize;

         XtEnum class_inited;

         XtInitProc initialize;

         XtArgsProc initialize_hook;

         XtRealizeProc realize;

         XtActionList actions;

         Cardinal num_actions;

         XtResourceList resources;

         Cardinal num_resources;

         XrmClass xrm_class;

         Boolean compress_motion;

         XtEnum compress_exposure;

         Boolean compress_enterleave;

         Boolean visible_interest;

         XtWidgetProc destroy;

         XtWidgetProc resize;

         XtExposeProc expose;

         XtSetValuesFunc set_values;

         XtArgsFunc set_values_hook;

         XtAlmostProc set_values_almost;

         XtArgsProc get_values_hook;

         XtAcceptFocusProc accept_focus;

         XtVersionType version;

         XtPointer callback_private;

         String tm_table;

         XtGeometryHandler query_geometry;

         XtStringProc display_accelerator;

         XtPointer extension;

     } CoreClassPart;

    extern WidgetClassRec widgetClassRec;

    #define coreClassRec widgetClassRec

    extern WidgetClass widgetClass, coreWidgetClass;

    typedef struct _WidgetClassRec *WidgetClass, *CoreWidgetClass;

2.1.1.2. CorePart Structure   

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

     typedef struct _CorePart {

         Widget self;

         WidgetClass widget_class;

         Widget parent;

         Boolean being_destroyed;

         XtCallbackList destroy_callbacks;

         XtPointer constraints;

         Position x;

         Position y;

         Dimension width;

         Dimension height;

         Dimension border_width;

         Boolean managed;

         Boolean sensitive;

         Boolean ancestor_sensitive;

         XtTranslations accelerators;

         Pixel border_pixel;

         Pixmap border_pixmap;

         WidgetList popup_list;

         Cardinal num_popups;

         String name;

         Screen *screen;

         Colormap colormap;

         Window window;

         Cardinal depth;

         Pixel background_pixel;

         Pixmap background_pixmap;

         Boolean visible;

         Boolean mapped_when_managed;

     } CorePart;

    typedef struct {

         CorePart core;

    } WidgetRec, *Widget, CoreRec, *CoreWidget;

    typedef struct _WidgetRec *Widget, *CoreWidget;

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

2.1.1.4. CorePart Default Values   

The default values for the Core fields, which are filled in 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

    bor- 

    der_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 dis- 

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

2.1.2. Composite Widgets   

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

2.1.2.1. CompositeClassPart Structure   

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

     typedef struct {

         XtGeometryHandler geometry_manager;

         XtWidgetProc change_managed;

         XtWidgetProc insert_child;

         XtWidgetProc delete_child;

         XtPointer extension;

     } CompositeClassPart;

     typedef struct {

         XtPointer next_extension;

         XrmQuark record_type;

         long version;

         Cardinal record_size;

         Boolean accepts_objects;

     } CompositeClassExtensionRec, *CompositeClassExtension;

    typedef struct {

         CoreClassPart core_class;

         CompositeClassPart composite_class;

    } CompositeClassRec, *CompositeWidgetClass;

In IntrinsicP.h:

    extern CompositeClassRec compositeClassRec;

    extern WidgetClass compositeWidgetClass;

    typedef struct _CompositeClassRec *CompositeWidgetClass;

2.1.2.2. 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;

        Cardinal num_children;

        Cardinal num_slots;

        XtOrderProc insert_position;

     } CompositePart;

    typedef struct {

         CorePart core;

         CompositePart composite;

    } CompositeRec, *CompositeWidget;

    typedef struct _CompositeRec *CompositeWidget;

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

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

2.1.3. Constraint Widgets   

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

2.1.3.1. ConstraintClassPart Structure   

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

     typedef struct {

         XtResourceList resources;

         Cardinal num_resources;

         Cardinal constraint_size;

         XtInitProc initialize;

         XtWidgetProc destroy;

         XtSetValuesFunc set_values;

         XtPointer extension;

     } ConstraintClassPart;

     typedef struct {

         XtPointer next_extension;

         XrmQuark record_type;

         long version;

         Cardinal record_size;

         XtArgsProc get_values_hook;

     } ConstraintClassExtensionRec, *ConstraintClassExtension;

    typedef struct _ConstraintClassRec {

         CoreClassPart core_class;

         CompositeClassPart composite_class;

         ConstraintClassPart constraint_class;

    } ConstraintClassRec, *ConstraintWidgetClass;

    extern ConstraintClassRec constraintClassRec;

    extern WidgetClass constraintWidgetClass;

    typedef struct _ConstraintClassRec *ConstraintWidgetClass;

2.1.3.2. 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;

    typedef struct {

         CorePart core;

         CompositePart composite;

         ConstraintPart constraint;

    } ConstraintRec, *ConstraintWidget;

    typedef struct _ConstraintRec *ConstraintWidget;

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