%
% SyntheticResources.tex -- Documents how the synthetic resources mechanism
%                           works and how to use it.
%
% (c) 1996 The Hungry Programmers
% (c) 1996 Harald Albrecht (albrecht@igpm.rwth-aachen.de)
% See the file PUBLIC for details.
%
\chapter[Synthetic Resources and Resolution Independence]
{Synthetic Resources\\[1.5mm]and Resolution Independence}
\by{Mitch Miers}

\section{Introduction}

\index{synthetic resources}%
\index{resource!synthetic}%
Synthetic resources are a mechanism included in Motif that allows a
developer to modify resource values as collected by or assigned to the
Xt resource mechanism.  That is, if a user should want to find the
value of an Xt resource, but \Motif{} would rather that the user not
see the true value, the synthetic resource mechanism allows the
\Motif{} developer to ``fake out'' the Intrinsics, and replace the
true instance variable values with modified values.  Alternatively,
the toolkit may prefer to transform a user specified value into
something more palatable by the toolkit.

\index{resolution independence}%
The more common usage of synthetic resources is to support resolution
independence (see figure \ref{SynthresPrinciple}). However, the
toolkit developers also realized that the mechanism provided a way to
protect ``delicate'' resources. For example, those that it would be
dangerous for the user to change, or those that would upset the
toolkit if they were unexpectedly modified.

\begin{figure}[h]
\centerline{\includegraphics[scale=1.09]{SynthresPrinciple}}
\caption{\label{SynthresPrinciple}Synthetic resources provide for data
conversion as well as information hiding.}
\end{figure}

The import and export direction is seen from \Motif{}'s point of
view. A user specified resource value is {\em im}ported into some
widget's instance variable. Au contraire, \Motif{} {\em ex}ports a
resource value whenever the user and/or application asks for a
resource's value by calling
\code{Xt[Va]Get\-Values()}.

\section{The Implementation of Synthetic Resources}

There are really five important classes in \Motif{}: ExtObject,
Gadget, Primitive, Manager and VendorShell. Nearly every Motif widget
class inherits behavior from one of these.  Some (\code{XmDialog\-Shell}
for example) inherit from more than one.  While this may seem a
statement of the obvious, it must be pointed out that the easiest way
for a class to inherit behavior from a superclass is to subclass from
the appropriate ``Core'' widget.  Those aforementioned classes are the
``Core'' \Motif{} classes (for objects, window-less widgets, core,
constraint, and shell widgets respectively).  Thus, if we provide the
\Motif{} ``Core'' widgets the ability to handle synthetic resources, all
subclasses will inherit that behavior.  In practice, the VendorShell
class behavior is dictated by the X specification.  Any special
behavior related to the VendorShell must be specified in the
VendorShell extension object, which is subclassed from ExtObj -- thus
the true core widget set contains only four classes.

There are only four class methods that deal with resource
manipulation. They are the \code{initia\-lize()} method, the
\code{set\_values()} method, the Constraint \code{set\_values()}
method, and the \code{get\_\-values\_hook()} method. Really there are
two more, the \code{set\_values\_almost()} method, and the
\code{set\_values\_hook()} method; the latter is obsolete, the former
is in practice never used.

In terms of resource manipulation, the Core \code{set\_values()}
method and the Constraint \code{set\_\-values()} method can be combined,
by simply checking to see if the parent is a Constraint (read Manager)
subclass. The only difference is where the resources are defined (self
or parent).  Second, the alterations that the \code{initialize()}
method and the \code{set\_values()} method perform based on the
argument lists are identical; so we can use the same function for
both.  Therefore, we really have only two cases to handle -- the case
where the user specifies the value for a resource (\code{initialize()}
and \code{set\_values()}), and the case where the user wants to find
the value of a resource (\code{get\_values\_hook()}).

Thus, there are two major sets of functions that implement the
synthetic resource behavior: four import functions with the postfix
\code{*ImportArgs()}, and five export functions ending with
\code{*Get\-ValuesHook()}. Both sets appear in \code{ResInd.c}. The
prototypes are as follows:

\codeindex{\_XmExtImportArgs}%
\codeindex{\_XmPrimitiveImportArgs}%
\codeindex{\_XmGadgetImportArgs}%
\codeindex{\_XmGadgetImportSecondaryArgs}%
\codeindex{\_XmManagerImportArgs}%
\codeindex{\_XmPrimitiveGetValuesHook}%
\codeindex{\_XmGadgetGetValuesHook}%
\codeindex{\_XmManagerGetValuesHook}%
\codeindex{\_XmExtGetValuesHook}%
\begin{verbatim}
void _XmExtImportArgs(Widget w, ArgList args, Cardinal *num_args);
void _XmPrimitiveImportArgs(Widget w, ArgList args, Cardinal *num_args);
void _XmGadgetImportArgs(Widget w, ArgList args, Cardinal *num_args);
void _XmGadgetImportSecondaryArgs(Widget w, ArgList args, Cardinal *num_args);
void _XmManagerImportArgs(Widget w, ArgList args, Cardinal *num_args);

void _XmPrimitiveGetValuesHook(Widget w, ArgList args, Cardinal *num_args);
void _XmGadgetGetValuesHook(Widget w, ArgList args, Cardinal *num_args);
void _XmManagerGetValuesHook(Widget w, ArgList args, Cardinal *num_args);
void _XmExtGetValuesHook(Widget w, ArgList args, Cardinal *num_args);
\end{verbatim}

The import functions are called from the \code{initialize()} and
\code{set\_values()} methods in the relevant widget classes directly.
The export functions are directly registered in the core
\code{get\_\-values\_hook()} method.

Note that there is an extra function
\code{\_XmGadgetImportSecondaryArgs()} unique to Gadgets. It is a
result of the ``cache'' subparts that nearly all Gadgets have. It
provides the mechanism to import and export resources from the
subpart.

The implementation of the functions is fairly ugly, and I wouldn't
mind suggestions on how to improve their efficiency.  Essentially,
they use a doubly nested loop, going through the resource request
list, and finding matches in the synthetic resource list.  If a match
is found, the import or export procedure in the synthetic resource
structure is invoked.

I'll not go into further detail about how the \Motif{} ``core'' widget
classes hook into the synthetic resource mechanism.  If you read the
code to Gadget, Primitive, or Manager, it is fairly obvious (for
example, just a call to \code{\_XmPrimitiveImportArgs()} in
Primitive's \code{set\_values\_method}).

One fairly important thing to note, is that the ``core''
\code{class\_part\_initialize()} methods combine a subclass's
synthetic resources with all of the superclass's synthetic resources.
This is done via
\code{\_XmBuildResources()}\codeindex{\_XmBuildResources}. This way,
access to inherited synthetic resources get sped up because
\Motif{} doesn't need to search for them in the superclasses. If you
subclass from a widget that has synthetic resources, but add no new
ones, you'll end up with synthetic resources after the
\code{class\_part\_init()} method has been called.

\section{How to Use Synthetic Resources}

\codeindex{XmSyntheticResource}%
\codeindex{XmImportOperator}%
\codeindex{XmImportProc}%
\codeindex{XmExportProc}%
\index{import!operator}%
\index{import!procedure}\index{export!procedure}%
The \code{XmSyntheticResource} structure looks suspiciously like the
Xt resource structure, and in fact operates in much the same way.
Here's the structure, and some associated information:

\begin{verbatim}
typedef enum { 
    XmSYNTHETIC_NONE, 
    XmSYNTHETIC_LOAD 
} XmImportOperator;

typedef void (*XmExportProc)(Widget w, int offset, XtArgVal *value);
typedef XmImportOperator (*XmImportProc)(Widget w, int offset,
                                         XtArgVal *value);

typedef struct _XmSyntheticResource {
    String       resource_name;
    Cardinal     resource_size;
    Cardinal     resource_offset;
    XmExportProc export_proc;
    XmImportProc import_proc;
} XmSyntheticResource;
\end{verbatim}

The import and export procedures (\code{import\_proc} and
\code{export\_proc} respectively) each take three parameters: the
widget for which the value has to be im- or exported, the offset of
the resource value within the widget's instance structure, and finally
a pointer. In case of a \code{XmImportProc} it points to the place
where the new resource value can be found. In the other case
(\code{XmExportProc}) the third parameter
\code{value} points to the place where the converted result should be stored.

Here's an example right from \code{Primitive.c}:

\begin{verbatim}
/* Resources of the primitive class */
static XtResource resources[] = {
    /* ... */
    {
        XmNhighlightThickness, sizeof(Dimension),
        XtOffset(XmPrimitiveWidget, primitive.highlight_thickness),
        _XmFromHorizontalPixels, _XmToHorizontalPixels
    },
    /* ... */
};
\end{verbatim}

This implements the resource \code{XmNhighlightThickness} as a
synthetic resource. The import procedure \code{\_XmToHorizontalPixels}
as well as the export procedure \code{\_XmFromHorizontal\-Pixels}
convert to/from the internal pixel based highlight thickness.

Note that the \code{XmImportProc} has a return type. This type is a
clue to the synthetic resource implementation for whether or not the
imported value should be loaded into the widget structure directly, or
just into the argument list.  Most would suspect that this should
always go into the widget structure; however, remember that many
manager widgets have associated children defined as part of their
functionality (e.g., SelectionBox), and don't have direct visibility
into some of the resources that can be specified.

\codeindex{XmSYNTHETIC\_LOAD}%
\codeindex{XmSYNTHETIC\_NONE}%
Let's go into a little more detail about that.  When an import
procedure wants a value to go directly into a resource variable, it
returns \code{XmSYNTHETIC\_LOAD} (see figure \ref{Synthres_Import}).
This is typically returned by such functions as
\code{\_XmToHorizontalPixels()}, which implements resolution
independence into widgets.  This has the effect of modifying directly
the \code{width} (or \code{x}) instance variable of a widget.

\begin{figure}[h]
\centerline{\includegraphics[scale=1.09]{SynthresImport}}
\caption{\label{Synthres_Import}The use of \code{XmSYNTHETIC\_LOAD}
and \code{XmSYNTHETIC\_NONE} when importing synthetic resource values.}
\end{figure}

However, consider the \code{XmNlistItems} in a SelectionBox.  This
import function typically wants to copy the \code{XmStringTable}
provided by the user (as a ``sensitive'' resource that the user may or
may not free). At any rate, the SelectionBox doesn't have visibility
into this resource directly.  The implementor has two choices: they
can copy the \code{XmStringTable} and store it in the subpart in the
import procedure (and return \code{XmSYNTHETIC\_LOAD}), or they can
simply make a copy of the \code{XmStringTable}, store it in the
\code{XtArgVal} pointer, and return \code{XmSYNTHETIC\_NONE}.
In practice, they'll usually want to choose the latter, as they
probably already have code in their \code{set\_values()} or
\code{initialize()} method to set the \code{ListItems} instance variable,
and the synthetic resource mechanism will take care of the nuisance of
making a copy first (at least, it will if that's how they've coded the
import procedure).  However, if they don't have code already, they can
save some simply by coding the import procedure to do it for them;
then they never need worry about the subpart (beyond checking to see
if \code{set\_values()} need return \code{True}).

For export procedures, much of the same logic applies, except that
there is no return value, so only the resource values can be modified.
The export procedures typically want to make a copy of ``sensitive''
resources, however (such as \code{XmNlabelString} in the Label widget
-- if the user frees this (as they should), it won't matter to the
instance they got the value from.  The same idea applies to things
like \code{XmStringTable}'s in the List, etc. This can be a
performance win, as well, as calls to \code{GetValues} can be avoided.

Also note that export procedures can play games. For example, consider
the Gadget class, and what it should return for the value of
\code{XmNtopShadowColor}.  Take a look at the export procedure of the
Gadget class for the \code{TopShadowColor} color:

\begin{verbatim}
static XmSyntheticResource syn_resources[] = {
    /* ... */
    {
        XmNtopShadowColor, sizeof(Pixel), XtOffset(XmGadget, object.parent),
        _XmGetParentTopShadowColor, NULL
    },
    /* ... */
};

static void
_XmGetParentTopShadowColor(Widget w, int offset, XtArgVal *value) {
    *value = XmParentTopShadowColor(w);
}
\end{verbatim}

Here, we cheat. We know that the parent is a Manager, and that the
\code{TopShadowColor} a Gadget uses is the \code{TopShadowColor}
defined by the parent, so we can just return that.  In this way, we
can specify a value, even though we don't directly have an instance
variable to define that value.

% End of SyntheticResources.tex

