%
% BaseClass.tex -- 
%
% (c) 1996 The Hungry Programmers
% (c) 1996 Harald Albrecht (albrecht@igpm.rwth-aachen.de)
% See the file PUBLIC for details.
%
\chapter[Pandora's Box: the BaseClass Stuff]
{Pandora's Box:\\[3mm]The BaseClass Stuff}
\by{Harald Albrecht}


\section{Introduction}

\index{prehook}\index{posthook}\index{method hook}\index{hook!method}%
The ``BaseClass stuff'' -- which is nicknamed after its implementation
file \code{BaseClass.c} -- consists mainly of three basic, interleaved
parts that affect not only all widget classes of the \LessTif{}
toolkit but also ``extend'' the object-orientated design of the Xt
Intrinsics. The three parts are the so-called ``prehooks'' and
``posthooks'', the ``method wrappers'', and finally the stacks for
``widget extension data''. Beside that, the BaseClass module contains
some basic helper functions for messing around with ``secondary
resources'' that are needed especially by gadgets. If you believe in
redemption through Object Orientation, you should better skip this
chapter completely and look out for other object(ive)s. You have been
forewarned.


\section{The Method Hooks}

\index{hook!wrapper}%
\index{wrapper!method}%
The BaseClass module provides hooks that are activated before and
after a chain of widget methods have been called in
superclass-to-subclass order. Prehooks and posthooks can be registered
for arbitrary widget classes. They are available for:

\codecomposeindex{initialize}{method}%
\codecomposeindex{class\_part\_initialize}{method}%
\codecomposeindex{set\_values}{method}%
\codecomposeindex{get\_values}{method}%
\begin{itemlist}
\item the \code{initialize()} method that initializes a single widget
instance,
\item the \code{class\_part\_initialize()} method that initializes a
derived part within a class record,
\item the \code{set\_values()} method for setting resources, and finally
\item the \code{get\_values()} method that queries resources.
\end{itemlist}

\begin{figure}[!ht]
\centerline{\includegraphics[scale=1.09]{HookBasics}}
\caption{\label{HookBasics}The hook mechanism encloses superclass-to-subclass
chained widget methods like \code{initialize()}.}
\end{figure}

For example, the XmLabel class uses the hooks to do some pre- and
post-processing when initializating a new widget instance --
regardless of whether the new widget is a XmLabel or any subclass of
(like XmPushButton). But also most gadgets make heavy use of the hook
mechanism to manage their secondary objects that work as cache parts.

Unfortunately, while the concept of the hook mechanism looks
straightforward at first glance, the implementation is definitely
not.  The difficulty is that the hook concept must be merged into the
existing object orientated concept of the Xt Intrinsics without any
chance of modifying and recompiling the Xt Intrinsics. Thus, the only
way out is to twist method pointers.

But when twisting pointers, you can't simply hook up the first and
last method pointer for any widget class, for example XmLabel. If some
derived class, like XmPushButton, would hook up its method pointers
too, the posthooks would interfere with each other. The reason is that
the parameters supplied to the aforementioned four kinds of methods
aren't enough to do the check whether the end of the method-chain has
been reached and the posthook method must be called. Such a check
could only be done using code generated at run-time -- a practice
which is definitely not portable across different systems. Later on,
when looking at the wrappers for the \code{realize()}, \code{resize()}
and \code{geometry\_handler()} methods, you'll come across another
solution to a quite similiar problem, but the solution there is even
worse than what I'll present next.

\codeindex{\_XmInitializeExtensions}%
\codecomposeindex{initialize}{method}%
\codecomposeindex{class\_part\_initialize}{method}%
\codecomposeindex{get\_values}{method}%
\codecomposeindex{set\_values}{method}%
To solve the hook problem, \LessTif{} installs prehook \emph{wrappers}
as replacements for the methods \code{initialize()},
\code{class\_part\_initialize()}, \code{get\_val\-ues()} and
\code{set\_values()} of the Object class. This insures that the hook
wrappers are called first before any other subclass-method.  This
twisting of the method pointers is carried out by
\code{\_XmInitia\-lizeExtensions()} when the first VendorShell is
created. The pointers to the old methods of the Object class are
saved, so the prehook wrappers can chain them up. Note that there are
no posthook (wrappers) installed at this time.

Now let us see what is happening lateron. I'll discuss this based on
figure \ref{HookBasics} for the \code{initia\-lize()} method-chain of
the XmLabel class. For this example, I assume that there is a
prehook method \circled{2} as well as a posthook method \circled{6}
registered for the XmLabel class.

Whenever the \code{initialize()} method is invoked, the prehook
wrapper \circled{1} is called first. In turn, it calls the prehook
method \circled{2} -- if there is one present for the widget class in
question. Next, the prehook wrapper checks for the presence of a
posthook method \circled{6} -- and if there is one, the prehook
wrapper replaces the pointer to the final \code{initialize()} method
\circled{5} with a pointer to the posthook wrapper \circled{4}. The
old pointer is saved using the ``wrapper data stack'' (you can find
out more about this in the next section). Finally, the prehook wrapper
calls the original \code{initialize()} method \circled{3} of the
Object class.

After this, the \code{initialize()} methods are called (as usual) in
superclass-to-subclass order with the exception of the leaf method.
If there is a posthook method registered, then -- and only then -- will the
posthook wrapper \circled{4} be called instead of the leaf method.
The posthook wrapper restores the old method pointer, calls the leaf
method \circled{5}, and finally activates the posthook method
\circled{6}.

In one particular case the method-chains for \code{initialize()} and
\code{set\_values()} look different: whenever a widget is not a shell
and it has a Constraint parent (or any subclass of) then the leaf
method isn't the method of the widget's class but instead the parent's
constraint leaf method (\code{constraint\_initialize()} respective
\code{constraint\_set\_values()}).

If you look close at the whole hook concept then it should be clear
that this concept is error prone in certain situations when recursion
is involved. The tradegy begins as soon as you enter the \emph{same}
prehook wrapper for a second time and the widget class of the second
turn is a subclass of the widget class from the first visit to the
prehook wrapper. In this case the \emph{first} prehook wrapper method,
which belongs to the superclass, is erroneously taken instead of the
intended \emph{second} prehook wrapper. Fortunately, there is no great
chance to tap into this trap as long as you don't issue -- for example
-- from the \code{get\_values()} method of a XmLabel widget a call to
\code{XtGetValues()} using another XmPushButton widget.


\subsection{The Wrapper Data Stacks}

\index{wrapper!data stack}%
\codeindex{XmWrapperDataRec}%
The wrapper data stack plays an important role for the hook
mechanism. For example, the prehook wrapper for \code{initialize()}
etc. must keep the old pointer to the leaf method of the method-chain
when it hooks in the posthook method instead. The old pointer is
stored in a \code{XmWrapperDataRec} structure (figure
\ref{WrapperStack}). These wrapper data records are linked so that
they form a stack for every single widget class. The head of the stack
is accessible through a base class extension record. For the moment,
I'll skip the base class extension record and come back to it in the
next section.

\begin{figure}[!ht]
\centerline{\includegraphics[scale=1.09]{WrapperStack}}
\caption{\label{WrapperStack}The wrapper data stack keeps saved method
pointers for a widget class.}
\end{figure}

The layout of a \code{XmWrapperDataRec} structure is as follows:

\newpage
\begin{verbatim}
typedef struct _XmWrapperDataRec 
{
    struct _XmWrapperDataRec *next;
    WidgetClass              widgetClass;
    XtInitProc               initializeLeaf;
    XtSetValuesFunc          setValuesLeaf;
    XtArgsProc               getValuesLeaf;
    XtRealizeProc            realize;
    XtWidgetClassProc        classPartInitLeaf;
    XtWidgetProc             resize;
    XtGeometryHandler        geometry_manager;
} XmWrapperDataRec, *XmWrapperData;
\end{verbatim}

Now for a description of such a wrapper data record:

\begin{itemdescription}
\ITEM[struct \_XmWrapperDataRec *next;]
Links to the next wrapper data record, so the data records form a
stack.

\ITEM[\shortstackl{XtInitProc initializeLeaf;
\\{}XtWidgetClassProc classPartInitLeaf;
\\{}XtArgsProc getValuesLeaf;
\\{}XtArgsProc setValuesLeaf;}]
These members keep the old pointers to the appropriate leaf method of
the method-chain.

\ITEM[\shortstackl{XtRealizeProc realize;
\\{}XtWidgetProc resize;
\\{}XtGeometryHandler geometry\_manager;}]
These members keep the old pointers to methods with the same
name. They belong to the ``method wrappers'' that are discussed in more
detail in the next section.

\ITEM[WidgetClass widgetClass;]
Its use is not quite clear and it may be some leftover from an
intended \emph{full-featured} hook mechanism. At least it is currently
superflous because you already know the widget class in order to get
the most recent entry from the appropriate wrapper data stack.
\end{itemdescription}

Please note that the functions which work on wrapper data do
\textbf{not} appear in any official header file (and thus not even in
\code{BaseClassP.h}) and aren't accessible from the outside. This is true
at least for \Motif{} but unfortunately \LessTif{} doesn't declare the
wrapper functions \code{static}, so they are accessible.  Despite this
their use is strongly discouraged. I only talk about them here so you
can understand their task within the BaseClass stuff. In \Motif{}~2.0
the wrapper functions have lost their \code{\_Xm} prefix to reflect
their private state.

\begin{itemdescription}
\codeindex{\_XmPushWrapperData}%
\ITEM[XmWrapperData \_XmPushWrapperData(WidgetClass wc);]
Allocates a new wrapper data block on the heap (``free store'' for all
you ``Ceplusplusists'') and pushes it on the wrapper stack (aka LIFO)
of the widget class specified by \code{wc}. If there is already a
wrapper data block on the stack, the contents of the previous data
block are copied into the new data block. \code{\_XmPushWrapperData()}
then returns a pointer to the most recent wrapper data block.

\codeindex{\_XmPopWrapperData}%
\ITEM[XmWrapperData \_XmPopWrapperData(WidgetClass wc);]
Returns the most recent wrapper data block for the widget class
\code{wc}. The data block is also removed from the wrapper stack, but the
data is not being freed. It is the caller's responsibility to free the
wrapper data block as soon as it is not needed any longer.

\codeindex{\_XmGetWrapperData}%
\ITEM[XmWrapperData \_XmGetWrapperData(WidgetClass wc);]
Much the same as \code{\_XmPopWrapperData()} but this time the wrapper
data block is \textbf{not} removed from the wrapper stack of the widget
class \code{wc}. If the wrapper stack should be empty at the time you
call \code{\_XmGetWrapperData()}, the function will create a blank wrapper
data block on-the-fly and push it on the wrapper stack.

\codeindex{\_XmFreeWrapperData}%
\ITEM[void \_XmFreeWrapperData(XmWrapperData data);]
This is a \LessTif{}-specific curiosity. It exists only for
orthogonality reasons and is nothing more than a wrapper around
\code{XtFree()}. Its only task is to free the memory occupied by the
wrapper data structure pointed to by \code{data}.
\end{itemdescription}


\subsection{The BaseClass Extension Record}

\index{extension!record (BaseClass)}%
\index{BaseClass extension record}%
\index{BCE record}%
Every widget class that wants to take part in the BaseClass game of
hooks and wrappers must attach a data structure of type
\code{XmBaseClassExtRec} to its class record. From now on I'll use the
abbreviation ``BCE record'' (although its more an acronym) whenever I
refer to a data structure of the type \code{XmBaseClassExtRec}. A BCE
record can be used to add prehook and posthook methods to any widget
class. Beside this, a BCE record also contains information about
secondary objects, wrapper methods and other things right out of
Pandora's box.

The layout of a BCE record is as follows:

\codeindex{XmBaseClassExtRec}%
\begin{verbatim}
typedef struct _XmBaseClassExtRec 
{
    XtPointer             next_extension;
    XrmQuark              record_type;
    long                  version;
    Cardinal              record_size;
    XtInitProc            initializePrehook;
    XtSetValuesFunc       setValuesPrehook;
    XtInitProc            initializePosthook;
    XtSetValuesFunc       setValuesPosthook;
    WidgetClass           secondaryObjectClass;
    XtInitProc            secondaryObjectCreate;
    XmGetSecResDataFunc   getSecResData;
    unsigned char         flags[32];
    XtArgsProc            getValuesPrehook;
    XtArgsProc            getValuesPosthook;
    XtWidgetClassProc     classPartInitPrehook;
    XtWidgetClassProc     classPartInitPosthook;
    XtResourceList        ext_resources;
    XtResourceList        compiled_ext_resources;
    Cardinal              num_ext_resources;
    Boolean               use_sub_resources;
    XmWidgetNavigableProc widgetNavigable;
    XmFocusChangeProc     focusChange;
    XmWrapperData         wrapperData;
} XmBaseClassExtRec, *XmBaseClassExt;
\end{verbatim}

If you want to attach your own BCE record to a (may be self-written)
\Motif{} widget class, take these steps:

\begin{itemlist}
\item[\circled{1}] Within your class record, let \code{core\_class.extension}
point to your BCE record. This pointer can be set at compile-time.

\item[\circled{2}] Set the \code{version} member of your BCE record to
the value \code{XmBaseClassExtVersion} (at compile-time). This symbol
is defined as soon as you include \code{BaseClassP.h}. Currently
\code{XmBaseClassExtVersion} has the value ``2''.

\item[\circled{3}] Initialize the \code{size} member
with \code{sizeof(XmBaseClassExtRec)}.

\item[\circled{4}] Initialize the \code{record\_type} member
with \code{NULLQUARK}. This is a constant, defined in the header file
\code{X11/Xresource.h}, and is here used as a dummy for compile-time.
At run-time, within the \code{class\_initialize()} method of your
widget class you must assign the value of the global variable
\code{XmQmotif} to the \code{record\_type} member.

\item[\circled{5}] At run-time, in your widget's
\code{class\_part\_initialize()} method, set the fast subclass bit, which
represents your widget class, using \code{\_XmFastSubclassInit()}. More
on this below.
\end{itemlist}

If you don't need the BaseClass' whistles and bells for your
self-written new widget class and you subclass from any of \Motif{}'s
widget classes, then you can skip the steps mentioned above. If you
don't attach a BCE record to your widget class record you'll
automagically inherit a BCE record from your widget's superclass.

Now let's look at each member of a BCE record in more detail:

\begin{itemdescription}
\ITEM[XtPointer next\_extension;]
Used when you need to chain more than one core class
extension. Otherwise initialize with \code{NULL}.

\ITEM[XrmQuark record\_type;]
Indicates the kind of extension record.  Within the
\code{class\_initialize()} method of your widget class, assign the
value of the global variable \code{XmQmotif} to \code{record\_type}.

\ITEM[long version;]
Must be initialized with the constant \code{XmBaseClassExtVersion}.

\ITEM[Cardinal record\_size;]
Must be set to \code{sizeof(XmBaseClassExtRec)}.

\ITEM[\shortstackl{XtInitProc initializePrehook;
\\{}XtInitProc initializePosthook;}]
Pointers to the prehook and posthook methods. The prehook is called
right before the first \code{initialize()} method triggers -- that is,
before Object's \code{initialize()}. The posthook is called after the
last \code{initialize()} method has been called -- usually this is the
\code{init\-ialize()} method of your (self-written) widget class.

Instead of specifying your own prehook or posthook method, you can
use the identifiers
\code{XmInheritInitializePrehook} and
\code{XmInheritInitializePosthook}. In this \linebreak[4] case your
widget class inherits the initialize hooks from its superclass. If you
specify a \code{NULL} value as the pointer to a hook method instead,
then you effectively disable for your widget class any initialize hook
that may be present in your widget's superclass.

\ITEM[\shortstackl{XtSetValuesFunc setValuesPrehook;
\\{}XtSetValuesFunc setValuesPosthook;
\\{}XtGetValuesFunc getValuesPrehook;
\\{}XtGetValuesFunc getValuesPosthook;}]
Much the same as the initialize hooks, but this time these hooks guard
the \code{set\_values()} and \code{get\_values()} methods of your
widget class. If you want to inherit one of these hooks simply specify
the appropiate symbol \code{XmInherit[Set|Get]ValuesPrehook} or
\code{XmInherit[Set|Get]ValuesPosthook}.

\ITEM[\shortstackl{XtWidgetClassProc classPartInitPrehook;
\\{}XtWidgetClassProc classPartInitPosthook;}]
This is the fourth and last set of hooks, this time for hooking up the
\code{class\_part\_init\-ialize()} method. You surely can't imagine that
there are two predefined symbols available to be used for inheritance:
\code{XmInheritClassPartInitPrehook} and
\code{XmInher\-itClassPartInitPosthook}. What a surprise...

\index{secondary!resources}%
\index{secondary!object}\index{object!secondary}%
\ITEM[WidgetClass secondaryObjectClass;]
Specifies the widget class that is used to hold the secondary
resources.  ``Secondary objects'' are used for two main
reasons. First, they extend such widget classes that already existed
before \Motif{} and now need new resources (especially
VendorShell). Second, the secondary objects work as caches for such
gadget resources that are likely to be the same in many gadget
instances. When you specify \code{XmInheritClass} you'll inherit the
object class specified by the superclass.

\ITEM[XtInitProc secondaryObjectCreate;]
Points to the method that creates a secondary object of the class
specified in \code{secondary\-ObjectClass}. When you specify
\code{XmInheritSecObjectCreate} you'll inherit the object creation
method from the superclass.

\index{secondary!resources}%
\ITEM[XmGetSecResDataFunc getSecResData;]
Points to a function that returns descriptions about secondary
resources of a widget class. The officially documented function
\code{XmGetSecondaryResourceData()} (see the man pages from the \CSF)
uses this function pointer when an application wants to know what
secondary resources a widget class has.

\ITEM[{unsigned char flags[32];}]
Must be initialized with zeros, that is
\code{\leftbrace{}0\rightbrace}. The \code{flags} array represents a bit
field of the so-called ``fast subclass bits''. Within the \code{flags}
bit field each bit represents one \Motif{} widget class. If a bit is
set, then this widget class is a subclass of the widget class that
correspnds to the flag bit. The class identifiers look like
\code{XmPRIMITIVE\_BIT} or \code{XmTEXT\_FIELD\_BIT}, and can be found in
the header file \code{Xm/XmP.h}. Note that these identifiers are bit
numbers rather than bit masks. Use \code{\_XmIsFastSubclass()} to
check whether a given widget class has a particular fast subclass bit
set.

\ITEM[XtResourceList ext\_resources;]
-- under construction --

\ITEM[XtResourceList compiled\_ext\_resources;]
-- under construction --

\ITEM[Cardinal num\_ext\_resources;]
-- under construction --

\ITEM[Boolean use\_sub\_resources;]
-- under construction --

\ITEM[XmWidgetNavigableProc widgetNavigable;]
Points to a method that checks whether a widget is
navigable. Depending on the navigability of the widget the method
must return either \code{XmNOT\_NAVIGABLE}, \code{XmTAB\_NAVIGABLE}
or \code{XmCONTROL\_NAVIGABLE}. This method pointer is used by
\code{\_XmGetNavigability()} from the keyboard focus traversal code.
When you specify \code{XmInheritWidgetNavi\-gable} for
\code{widgetNavigable} you'll inherit the method pointer from the
superclass.

\ITEM[XmFocusChangeProc focusChange;]
Points to a method that will receive notifications from the keyboard
focus traversal code whenever the focus changes. When you set
\code{focusChange} to \code{XmInheritFocusChange} you'll inherit the
method pointer from the superclass.

\ITEM[XmWrapperData wrapperData;]
Must be initialized with \code{NULL} and will be used lateron by the
BaseClass stuff. During runtime, the \code{wrapperData} member points
to the most recent entry of the wrapper stack for this widget class.

\end{itemdescription}


\section{The Method Wrappers}

\index{wrapper!method}%
\index{method wrappers}%
\codecomposeindex{realize}{method}%
\codecomposeindex{resize}{method}%
\codecomposeindex{geometry\_handler}{method}%
In contrast to the hook methods, the method wrappers are a special set
of wrappers for the widget methods \code{realize()}, \code{resize()} and
\code{geometry\_handler()}. These three wrappers are only responsible for
a few tasks within the \LessTif{} toolkit. Therefore the BCE record has
no method wrapper hooks that could be used by widget writers. The duties
of the method wrappers are:

\begin{itemlist}
\item The wrapper of the \code{realize()} method is available only for
the VendorShell widget class and any subclass of it. The wrapper first
calls the original \code{realize()} method and then it activates all
callbacks registered in the \code{XmNrealizeCallback} resource of the
VendorShell extension object.

\codeindex{\_XmNavigResize()}%
\item The \code{resize()} wrapper is available for the ExtObject class
and any subclass of it. It first calls the original \code{resize()} method.
Afterwards, it calls \code{\_XmNavigResize()} so the keyboard focus
traversal mechanism stays in sync with the mess on the user's display.

\item The \code{geometry\_handler()} wrapper makes sure that the drag\&drop
mechanism doesn't interfere with geometry management.
\end{itemlist}

To see how the method wrappers are implemented, take a look at figure
\ref{WrapperBasics} that shows this exemplary for the \code{realize()}
method wrapper.

\begin{figure}[!ht]
\centerline{\includegraphics[scale=1.09]{WrapperBasics}}
\caption{\label{WrapperBasics}The method wrappers enclose the
non-chained widget methods like \code{realize()}.}
\end{figure}

Unfortunately, just redirecting the \code{realize()} method pointers
of all the class records to a wrapper method is not enough. How should
the wrapper know which (original) method to call later on? It can't
guess this information just from the widget identifier it got as one
parameter to the method call: the intended method could be either from
the widget's class or from one of the superclasses. A smart solution
would be to generate dynamically a short piece of machine code (called
a ``thunk'' in M\textdollar-babble) that is called before the
wrapper. This piece of code then would supply the missing information
to the wrapper method. Unfortunately, this isn't portable coding and
is therefore useless to a project like \Motif{} or \LessTif{}.

As a way out, \Motif{} as well as \LessTif{} use a set of predefined
wrapper ``gateways'' (marked with a \circled{1} in figure
\ref{WrapperBasics}) that are statically compiled into the
toolkits. In the case of the \code{realize()} method there are eight
wrapper gateways called \code{RealizeWrapper0()} through
\code{Realize\-Wrapper7()}. They all just call the real \code{realize()}
wrapper \circled{2} and supply to it an additional parameter that is
the distance between the widget class the gateway belongs to and the
VendorShell class. For example, the \code{realize()} gateway of the
VendorShell widget class has a distance of zero, whereas the
XmDialogShell widget class has a distance of two.

Armed with the distance, the wrapper can then call the right
\code{realize()} method \circled{3} by substracting the distance, that the
gateway indicated, from the distance of the class of the current
widget, then walking up the according number of superclasses, and
fetching the old method pointer from the wrapper data record of that
superclass.

The description above applies to the \code{resize()} and
\code{geometry\_handler()} wrappers as well. The only difference is
that the distance is now measured from the ExtObject class instead. In
the case of the \code{geometry\_handler()} the distance should
probable have been measured from the Constraint class and not from the
ExtObject class. But as \Motif{} can't count, we can't either for
compatibility reasons.

There are eleven gateway levels available for the \code{resize()}
method and ten levels for the \code{geom\-etry\_handler()} method. So
there is still room for larger widget class trees subclassed from
XmPrimitive (six levels) and XmManager (only four levels due to the
bug just mentioned) -- but you have to live with these built-in
limits, whether you want or not.


\section{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
\code{XContext}s (you can find \code{XCon\-text}s 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
\ref{WED_Stack}).  The stacks for their part contain pointers to the
extension data we're interested in.

\begin{figure}[ht]
\centerline{\includegraphics[scale=1.09]{WED_Stack}}
\caption{\label{WED_Stack}A close look at the widget extension data
mechanism.}
\end{figure}

There are currently five extension data tags defined -- see table
\ref{WED_tag_ids}. Gadgets use extension data that consists of a
\code{XmWidgetExtDataRec} structure, which is tagged as a
\code{XmCACHE\_EXTENSION}. VendorShells use the same
\code{XmWidgetExtDataRec} structure but tag them as a
\code{XmSHELL\_EX\-TENSION}.

\begin{table}[h]\begin{center}\begin{tabular}[h]{|l|c|}
\hline
Identifier & Value\\
\hline
\code{XmCACHE\_EXTENSION} & \code{1} \\
\code{XmDESKTOP\_EXTENSION} & \code{2} \\
\code{XmSHELL\_EXTENSION} & \code{3} \\
\code{XmPROTOCOL\_EXTENSION} & \code{4} \\
\code{XmDEFAULT\_EXTENSION} & \code{5} \\
\hline
\end{tabular}%
{\caption{\label{WED_tag_ids}Tag identifiers for widget extension data}}
\vspace*{-0.4cm}
\end{center}\end{table}

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

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

\codeindex{XmWidgetExtDataRec}%
\begin{verbatim}
typedef struct _XmWidgetExtDataRec 
{
    Widget widget;
    Widget reqWidget;
    Widget oldWidget;
} XmWidgetExtDataRec, *XmWidgetExtData;
\end{verbatim}

With Gadgets, the member \code{widget} of a \code{XmWidgetExtDataRec}
points to the secondary object that acts as a cache for a set of the
gadget's resources. The members \code{reqWidget} and \code{oldWidget}
look suspiciously like the parameters from a \code{intialize()},
\code{set\_values()} or \code{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 \ref{WED_SecObj}
illustrates this exemplary for the \code{set\_values()} method.

\begin{figure}[ht]
\centerline{\includegraphics[scale=1.09]{WED_SecObj}}
\caption{\label{WED_SecObj}The widget extension data mechanism helps
to organize and manage secondary objects within some widgets methods.}
\end{figure}

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
\code{XtCreateWidget()}. Thus it needs not to take care of
\code{reqWidget} and \code{oldWidget}.  Only the \code{widget} member
in the \code{XmWidgetExtDataRec} is used to point to the VendorShell
extension object (figure \ref{WED_Vendor}).  A link
(\code{ext.logicalParent}) within each instance of an ExtObject leads
the way back to the VendorShell.

\begin{figure}[ht]
\centerline{\includegraphics[scale=1.09]{WED_Vendor}}
\caption{\label{WED_Vendor}The widget extension data represents the
link between a VendorShell and its extension object.}
\end{figure}

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

\begin{itemdescription}
\codeindex{\_XmPushWidgetExtData}%
\ITEM[\shortstackl{void \_XmPushWidgetExtData(Widget widget, XmWidgetExtData data,
\\{}~~~~~~~~~~~~~~~~~~~~~~~~~~unsigned char extType);}]
Pushes an extension data record pointed to by \code{data} on the
appropriate stack for extension data of type \code{extType} of the
widget specified by \code{widget}.

\codeindex{\_XmPopWidgetExtData}%
\ITEM[\shortstackl{void \_XmPopWidgetExtData(Widget widget, XmWidgetExtData *dataRtn,
\\{}~~~~~~~~~~~~~~~~~~~~~~~~~unsigned char extType);}]
Pops off the most recent entry from the stack for extension data of type
\code{extType} for the widget \code{widget}. The pointer to the data
is returned in \code{dataRtn}. You are responsible to free the data
when you don't need it any longer.

\codeindex{\_XmGetWidgetExtData}%
\ITEM[\shortstackl{XmWidgetExtData \_XmGetWidgetExtData(Widget widget,
\\{}~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~unsigned char extType);}]
Nondestructively fetches an extension data record. If there is
currently no extension data of type \code{extType} on the stack of
\code{widget} then the function returns \code{NULL}. Otherwise it returns
a pointer to the most recent extension data record but does not pop it
off the stack.

\codeindex{\_XmFreeWidgetExtData}%
\ITEM[void \_XmFreeWidgetExtData(Widget widget);]
This one was surely implemented by some joker at the \CSF{}. When
called, it'll simply print out a warning that this function isn't
supported. To be compatible, \LessTif{} spits out an odd warning,
too. Maybe \code{\_XmFreeWidgetExtData()} once was intended to free
all extension data that is associated with a particular widget. Maybe
it was just a red herring.

\end{itemdescription}


\section{Other Undocumented Stuff}

There are a few undocumented functions and macros remaining that belong
to the BaseClass stuff.

\begin{itemdescription}
\codeindex{\_XmGetClassExtensionPtr}%
\ITEM[\shortstackl{XmGenericClassExt *
\\{}~~\_XmGetClassExtensionPtr(XmGenericClassExt *listHeadPtr,
\\{}~~~~~~~~~~~~~~~~~~~~~~~~~~XrmQuark owner);}]
Can be used either to query any widget extension record you like or
a BCE record. The parameter \code{listHeadPtr} must point to the
\textbf{pointer} to the head of the list. Set \code{owner} to the kind
of extension you're looking for. If you look out for a BCE record use
the macro \code{\_XmGetBaseClassExtPtr()} instead.

\codeindex{\_XmGetBaseClassExtPtr}%
\ITEM[\_XmGetBaseClassExtPtr(wc, owner)]
This macro is defined in \code{Xm/BaseClassP.h} and tries to find
a extension record of type \code{owner} and then returns a
\textbf{pointer to the pointer} to the extension record. Typically,
you'll use this macro to locate a BCE record of a particular widget
class:

\begin{verbatim}
    XmBaseClassExt *ext;
    int             version;

    ext = (XmBaseClassExt *)_XmGetBaseClassExtPtr(XtClass(w), XmQmotif);
    version = (*ext)->version; °/* access any structure member */°
\end{verbatim}

\codeindex{\_XmIsStandardMotifWidgetClass}%
\ITEM[Boolean \_XmIsStandardMotifWidgetClass(WidgetClass wc);]
Checks whether the widget class \code{wc} is a standard widget class
of \Motif{} and then returns \code{True}. If the widget class to be
tested isn't a standard widget class, the function returns
\code{False}. The test is mainly based on the fast subclass bits
within the base class extension records each widget class of \Motif{}
has. The widget class given in \code{wc} is considered to be a
standard class if either:
\begin{itempacked}
\item[--] its superclass does not have a base class extension record (like
XmPrimitve and XmManager),
\item[--] or the fast subclass bits of the widget class \code{wc} differ
in at least one bit from the fast subclass bits of \code{wc}'s
superclass. This way a self-written widget which is, for example,
derived from XmManager and uses no new fast subclass bit, won't be
considered to be from \Motif{}'s core widget set.
\end{itempacked}
Only the fast subclass bits 0--191 belong to standard \Motif{} widget
classes, whereas the bits 192--255 are application-specific. Therefore
the checks will include only the fast subclass bits in the range from bit 0
up to bit 191.

\codeindex{\_XmIsSlowSubclass}%
\ITEM[Boolean \_XmIsSlowSubclass(WidgetClass wc, unsigned int bit);]
If the widget class specified in \code{wc} has the fast subclass bit
with the bit number \code{bit} set, this function returns \code{True}.
Otherwise it returns \code{False}.

\codeindex{\_XmIsFastSubclass}%
\ITEM[\_XmIsFastSubclass(wc, bit)]
This is not a real C function but rather a macro defined in
\code{BaseClassP.h}. It checks whether the fast subclass bit with the
bit number \code{bit} is set in the base class extension record of the
widget class \code{wc}. If so, \code{\_XmIsFastSubclass()} returns
\code{True}. If the fast subclass bit is either not set or the widget
class has no base class extension record, the macro returns the value
\code{False}.

\codeindex{\_XmFastSubclassInit}%
\ITEM[\_XmFastSubclassInit(wc, bit\_field)]
This is not a real C function but rather a macro defined in
\code{BaseClassP.h}. It sets the fast subclass bit with the bit number
of \code{bit\_field}.

\codeindex{\_XmInitializeExtensions}%
\ITEM[void \_XmInitializeExtensions(void)]
This function initializes the BaseClass stuff. It is ordinarily called
when the first VendorShell widget is created (typically within
\code{XtAppInitialize()}) and sets up the \code{XmQmotif} quark. Finally,
it hooks the prehook wrappers into the ExtObject class. Normaly, you
would not need to call \code{\_XmInitializeExtensions()} directly.

\end{itemdescription}


% End of BaseClass.tex
