4. The Widget Extension Data

The widget extension data mechanism is a set of stacks that operate on a per-widget basis. You can push ``extension data'' (that is in the end a pointer to any block of memory) on a stack which belongs to a particular widget, peek at the data at any time, and finally pop it off the stack and free it.

LESSTIF uses the extension data mechanism for managing secondary objects and protocol objects. In order that LESSTIF doesn't mix up extension data intended for different purposes the extension data is ``typed'' or ``tagged''. Each widget has a different stack for each type/tag of extension data.

The heart of the widget extension data mechanism is a set of XContexts (you can find XContexts throughout the whole LESSTIF toolkit). With the help of the contexts you can associate a particular tagged stack of extension data with a widget (figure ). The stacks for their part contain pointers to the extension data we're interested in.

Figure: A close look at the widget extension data mechanism.

There are currently five extension data tags defined - see table . Gadgets use extension data that consists of a XmWidgetExtDataRec structure, which is tagged as a XmCACHE_EXTENSION. VendorShells use the same XmWidgetExtDataRec structure but tag them as a XmSHELL_EXTENSION.

Table: Tag identifiers for widget extension data

Identifier	Value
XmCACHE_EXTENSION	1
XmDESKTOP_EXTENSION	2
XmSHELL_EXTENSION	3
XmPROTOCOL_EXTENSION	4
XmDEFAULT_EXTENSION	5

A third use of the widget extension data mechanism is to manage a list of protocol objects in a XmAllProtocolsMgrRec structure tagged as XmPROTOCOL_EXTENSION. The protocol objectes are used to store information, so VendorShells can communicate with the window manager. The identifier XmDEFAULT_EXTENSION is only used by the (generic) ExtObject class and normally not needed. The use of the XmDESKTOP_EXTENSION is currently not known - it might be related to COSE/CDE.

As you can see from the previous explanations, the data structure XmWidgetExtDataRec plays an important role for the BaseClass stuff. So let us examine it in more detail:

XmWidgetExtDataRec

typedef struct _XmWidgetExtDataRec 
{
    Widget widget;
    Widget reqWidget;
    Widget oldWidget;
} XmWidgetExtDataRec, *XmWidgetExtData;

With Gadgets, the member widget of a XmWidgetExtDataRec points to the secondary object that acts as a cache for a set of the gadget's resources. The members reqWidget and oldWidget look suspiciously like the parameters from a intialize(), set_values() or get_values() method of a widget. In fact, they are used much the same, but this time they refer to a secondary object or a copy of the secondary object. Figure illustrates this exemplary for the set_values() method.

Figure: The widget extension data mechanism helps to organize and manage secondary objects within some widgets methods.

What you've just read about gadgets and their widget extension data applies to VendorShells almost the same. The only exception is that LESSTIF is lazy and in this case it creates the secondary object - which is a VendorShell extension object - using XtCreateWidget(). Thus it needs not to take care of reqWidget and oldWidget. Only the widget member in the XmWidgetExtDataRec is used to point to the VendorShell extension object (figure ). A link (ext.logicalParent) within each instance of an ExtObject leads the way back to the VendorShell.

Figure: The widget extension data represents the link between a VendorShell and its extension object.

There are four - or rather three - functions within the BaseClass module that work with the widget wrapper extension data.