\&
.sp 1
.ce 3
\s+1\fBChapter 9\fP\s-1

\s+1\fBResource Management\fP\s-1
.sp 2
.nr H1 9
.nr H2 0
.nr H3 0
.nr H4 0
.nr H5 0
.LP
.XS
Chapter 9 \- Resource Management
.XE
A resource is a field in the widget record with a corresponding
resource entry in the resource list of the widget or any of its
superclasses.
This means that the field is
settable by
.PN XtCreateWidget
(by naming the field in the argument list), by an
entry in the default resource files (by using either the name or class), and by
.PN XtSetValues .
In addition, it is readable by
.PN XtGetValues .
Not all fields in a widget record are resources.
Some are for bookkeeping use by the
generic routines (like managed and being_destroyed).
Others can be for local bookkeeping,
and still others are derived from resources 
(many graphics contexts and pixmaps).
.LP
Writers of widgets need to obtain a large set of resources at widget
creation time.
Some of the resources come from the argument list supplied in the call to
.PN XtCreateWidget ,
some from the resource database,
and some from the internal defaults specified for the widget.
Resources are obtained first from the argument list,
then from the resource database for all resources not specified
in the argument list,
and lastly from the internal default, if needed.
.NH 2
Resource Lists
.XS
\*(SN Resource Lists
.XE
.LP
.IN "Resource Management"
A resource entry specifies a field in the widget,
the textual name and class of the field that argument lists
and external resource files use to refer to the field
and a default value that the field should get if no value is specified.
The declaration for the
.PN XtResource
structure is:
.LP
.Ds 0
.TA .5i 3i
.ta .5i 3i
typedef struct {
	String resource_name;
	String resource_class;
	String resource_type;
	Cardinal resource_size;
	Cardinal resource_offset;
	String default_type;
	XtPointer default_addr;
} XtResource, *XtResourceList;
.De
.IN "XtResourceList"
.LP
The resource_name field contains the name used by clients to access the field
in the widget.
By convention, it starts with a lowercase letter
and is spelled identically to the field name,
except all underscores (_) are deleted and the next letter is replaced by its 
uppercase counterpart.
For example, the resource name for background_pixel becomes backgroundPixel.
Resource names beginning with the two-character
sequence ``xt'' and resource classes beginning with the two-character
sequence ``Xt'' are reserved to the \*(xI for future standard and
implementation-dependent uses.
Widget header files typically contain a symbolic name for each resource name.
All resource names, classes, and types used by the \*(xI are named in
.Pn < X11/StringDefs.h >.
The \*(xI symbolic resource names begin with
.PN XtN
and are followed by the string name (for example, XtNbackgroundPixel
for backgroundPixel).
.LP
A resource class provides two functions:
.IP \(bu 5
It isolates an application from different representations that widgets 
can use for a similar resource.
.IP \(bu 5
It lets you specify values for several actual resources with a single name.
A resource class should be chosen to span a group of closely related fields.
.LP
For example,
a widget can have several pixel resources: background, foreground,
border, block cursor, pointer cursor, and so on.
Typically, the background defaults to white
and everything else to black.
The resource class for each of these resources in the resource list
should be chosen so that it takes the minimal number of entries
in the resource database to make background offwhite
and everything else darkblue.
.LP
In this case, the background pixel should have a resource class of
.PN Background
and all the other pixel entries a resource class of
.PN Foreground .
Then, the resource file needs only two lines to
change all pixels to offwhite or darkblue:
.LP
.Ds 0
.TA .5i 1.5i
.ta .5i 1.5i
*Background:	offwhite
*Foreground:	darkblue
.De
.LP
Similarly, a widget may have several resource fonts (such as normal and bold),
but all fonts should have the class Font.
Thus, changing all fonts simply requires only a single line in the 
default resource file:
.LP
.Ds 0
.TA .5i 3i
.ta .5i 3i
*Font:	6x13
.De
.LP
By convention,
resource classes are always spelled starting with a capital letter.
Their symbolic names are preceded with
.PN XtC
(for example, XtCBackground).
.LP
The resource_type field is the physical representation type of the resource.
By convention, it starts with an uppercase letter and is
spelled identically to the type name of the field.
The resource type is used when resources are fetched to
convert from the resource database format (usually String) or the default
resource format (almost anything, but often String) to the desired
physical representation (see Section 9.6).
The \*(xI define the following resource types:
.TS H
lw(2.75i) lw(2.75i).
_
.sp 6p
.TB
Resource Type	Structure or Field Type
.sp 6p
_
.sp 6p
.TH
.R
T{
.PN XtRAcceleratorTable
T}	XtAccelerators
T{
.PN XtRAtom
T}	Atom
T{
.PN XtRBitmap
T}	Pixmap, depth=1
T{
.PN XtRBoolean
T}	Boolean
T{
.PN XtRBool
T}	Bool
T{
.PN XtRCallback
T}	XtCallbackList
T{
.PN XtRCardinal
T}	Cardinal
T{
.PN XtRColor
T}	XColor
T{
.PN XtRColormap
T}	Colormap
T{
.PN XtRCursor
T}	Cursor
T{
.PN XtRDimension
T}	Dimension
T{
.PN XtRDisplay
T}	Display *
T{
.PN XtREnum
T}	XtEnum
T{
.PN XtRFile
T}	FILE*
T{
.PN XtRFloat
T}	float
T{
.PN XtRFont
T}	Font
T{
.PN XtRFontStruct
T}	XFontStruct *
T{
.PN XtRFunction
T}	(*)()
T{
.PN XtRGeometry
T}	T{
char*, format as defined by
.PN XParseGeometry
T}
T{
.PN XtRInitialState
T}	int
T{
.PN XtRInt
T}	int
T{
.PN XtRLongBoolean
T}	long
T{
.PN XtRObject
T}	Object
T{
.PN XtRPixel
T}	Pixel
T{
.PN XtRPixmap
T}	Pixmap
T{
.PN XtRPointer
T}	Pointer
T{
.PN XtRPosition
T}	Position
T{
.PN XtRScreen
T}	Screen *
T{
.PN XtRShort
T}	short
T{
.PN XtRString
T}	char*
T{
.PN XtRStringArray
T}	String *
T{
.PN XtRStringTable
T}	char**
T{
.PN XtRTranslationTable
T}	XtTranslations
T{
.PN XtRUnsignedChar
T}	unsigned char
T{
.PN XtRVisual
T}	Visual *
T{
.PN XtRWidget
T}	Widget
T{
.PN XtRWidgetClass
T}	WidgetClass
T{
.PN XtRWidgetList
T}	WidgetList
T{
.PN XtRWindow
T}	Window
.TE
.LP
.Pn < X11/StringDefs.h >
also defines the following resource types as a
convenience for widgets, although they do not have any corresponding
datatype assigned:
.PN XtREditMode ,
.PN XtRJustify
and
.PN XtROrientation .
.LP
The resource_size field is the size of the physical representation in bytes;
you should specify it as ``sizeof(\fItype\fP)'' so that the
compiler fills in the value.
The resource_offset field is the offset in bytes of the field 
within the widget.
You should use the
.PN XtOffset
macro to retrieve this value.
The default_type field is the representation type of the default
resource value.
If default_type is different from resource_type and the default_type is needed,
the resource manager invokes a conversion procedure from default_type
to resource_type.
Whenever possible,
the default type should be identical to the resource type in order
to minimize widget creation time.
However, there are sometimes no values of the type that the program 
can easily specify.
In this case,
it should be a value that the converter is guaranteed to work for (for example, 
.PN XtDefaultForeground
for a pixel resource).
The default_addr field specifies the address of the default resource value.
As a special case, if the default_type is
.PN XtRString
then the value in the default_addr field is the pointer to
the string rather than a pointer to the pointer.
The default is used if a resource is not specified in the argument list
or in the resource database or if the conversion from the representation
type stored in the resource database fails,
which can happen for various reasons (for example, a misspelled entry in a
resource file).
.LP
Two special representation types 
.Pn ( XtRImmediate
and
.PN XtRCallProc )
are usable only as default resource types.
.PN XtRImmediate
indicates that the value in the default_addr field is the actual value of
the resource rather than the address of the value. 
The value must be in correct representation type for the resource.
No conversion is possible since there is no source representation type.
.PN XtRCallProc
indicates that the value in the default_addr field is a procedure
variable.
This procedure is automatically invoked with the widget,
resource_offset, and a pointer to the
.PN XrmValue
in which to store the result and is an
.PN XtResourceDefaultProc :
.FD 0
typedef void (*XtResourceDefaultProc)(Widget, int, XrmValue *)
.br
       Widget \fIw\fP\^;
.br
       int \fIoffset\fP\^;
.br
       XrmValue *\fIvalue\fP\^;
.FN
.IP \fIw\fP 1i
Specifies the widget whose resource is to be obtained.
.IP \fIoffset\fP 1i
Specifies the offset of the field in the widget record.
.IP \fIvalue\fP 1i
Specifies the resource value to fill in.
.LP
The
.PN XtResourceDefaultProc
procedure should fill in the addr field of the value with a pointer 
to the default data in its correct type.
.sp
.LP
To get the resource list structure for a particular class, use
.PN XtGetResourceList :
.IN "XtGetResourceList" "" "@DEF@"
.FD 0
void XtGetResourceList(\fIclass\fP, \fIresources_return\fP, \fInum_resources_return\fP);
.br
      WidgetClass \fIclass\fP;
.br
      XtResourceList *\fIresources_return\fP;
.br
      Cardinal *\fInum_resources_return\fP;
.FN
.IP \fIwidget_class\fP 1.5i
Specifies the object class to be queried; it may be
.PN objectClass
or any subclass thereof.
.IP \fIresources_return\fP 1.5i
Returns the resource list.
.IP \fInum_resources_return\fP 1.5i
Returns the number of entries in the resource list.
.LP
If
.PN XtGetResourceList
is called before the widget class is initialized
it returns the resource list as specified in the widget class record.
If it is called after the widget class has been initialized,
.PN XtGetResourceList
returns a merged resource list that includes the resources 
for all superclasses.
The list returned by
.PN XtGetResourceList
should be freed using
.PN XtFree
when it is no longer needed.
.sp
.LP
To get the constraint resource list structure for a particular widget
class, use
.PN XtGetConstraintResourceList .
.IN "XtGetConstraintResourceList" "" "@DEF@"
.FD 0
void XtGetConstraintResourceList(\fIclass\fP, \fIresources_return\fP, \
\fInum_resources_return\fP)
.br
      WidgetClass \fIclass\fP;
.br
      XtResourceList *\fIresources_return\fP;
.br
      Cardinal *\fInum_resources_return\fP;
.FN
.IP \fIwidget_class\fP 1.5i
Specifies the object class to be queried; it
may be
.PN objectClass
or any subclass thereof.
.IP \fIresources_return\fP 1.5i
Returns the constraint resource list.
.IP \fInum_resources_return\fP 1.5i
Returns the number of entries in the constraint resource list.
.LP
If
.PN XtGetConstraintResourceList
is called before the widget class is
initialized, the resource list as specified in the widget
class record will be returned.  If
.PN XtGetConstraintResourceList
is called after the widget class has been initialized, the merged
resource list for the class and all constraint superclasses is
returned.  If the
specified widget_class is not a subclass of
.PN constraintWidgetClass ,
*resources_return is set to NULL and *num_resources_return is set to 0.
The list returned by
.PN XtGetConstraintResourceList
should be freed using
.PN XtFree
when it is no longer needed.
.sp
.LP
The routines
.PN XtSetValues
and
.PN XtGetValues
also use the resource list to set and get widget state.
For further information, 
see Sections 9.7.1 and 9.7.2.
.LP
Here is an abbreviated version of the resource list in the Label widget:
.LP
.Ds
.TA .5i 1.5 3i
.ta .5i 1.5 3i
/* Resources specific to Label */
static XtResource resources[] = {
{XtNforeground, XtCForeground, XtRPixel, sizeof(Pixel),
   XtOffsetOf(LabelRec, label.foreground), XtRString, XtDefaultForeground},
{XtNfont,  XtCFont, XtRFontStruct, sizeof(XFontStruct *),
   XtOffsetOf(LabelRec, label.font),XtRString, XtDefaultFont},
{XtNlabel,  XtCLabel, XtRString, sizeof(String),
   XtOffsetOf(LabelRec, label.label), XtRString, NULL},
	.
	.
	.
}
.De
.LP
The complete resource name for a field of a widget instance is the
concatenation of the application shell name (from 
.PN XtAppCreateShell ),
the instance names of all the widget's parents up to the 
.PN ApplicationShellWidget ,
the instance name of the widget itself,
and the resource name of the specified field of the widget.
Likewise,
the full resource class of a field of a widget instance is the
concatenation of the application class (from
.PN XtAppCreateShell ),
the widget class names of all the widget's parents up to the 
.PN ApplicationShellWidget
(not the superclasses), the widget class name of the widget itself,
and the resource name of the specified field of the widget.
.NH 2
Byte Offset Calculations
.XS
\*(SN Byte Offset Calculations
.XE
.LP
To determine the byte offset of a field within a structure type, use
.PN XtOffsetOf .
.IN "XtOffsetOf" "" "@DEF@"
.FD 0
Cardinal XtOffsetOf(\fIstructure_type\fP, \fIfield_name\fP)
.br
      \fIType structure_type\fP;
.br
      \fIField field_name\fP;
.FN
.IP \fIstructure_type\fP 1i
Specifies a type that is declared as a structure.
.IP \fIfield_name\fP 1i
Specifies the name of a member within the structure.
.LP
The
.PN XtOffsetOf
macro expands to a constant expression that gives the
offset in bytes to the specified structure member from the beginning
of the structure.  It is normally used to statically initialize
resource lists and is more portable than
.PN XtOffset ,
which serves the same function.

.LP
To determine the byte offset of a field within a structure pointer type, use
.PN XtOffset .
.IN "XtOffset" "" "@DEF@"
.FD 0
Cardinal XtOffset(\fIpointer_type\fP, \fIfield_name\fP)
.br
      \fIType pointer_type\fP;
.br
      \fIField field_name\fP;
.FN
.IP \fIpointer_type\fP 1i
Specifies a type that is declared as a pointer to a structure.
.IP \fIfield_name\fP 1i
Specifies the name of the field for which to calculate the byte offset.
.LP
The
.PN XtOffset
macro may be used to determine the offset of various resource fields 
from the beginning of a widget and can be used at compile time in static
initializations.
.PN XtOffset
is less portable than
.PN XtOffsetOf .

.NH 2
Superclass to Subclass Chaining of Resource Lists
.XS
\*(SN Superclass to Subclass Chaining of Resource Lists
.XE
.LP
.IN "Inheritance"
.IN "Superclass Chaining"
.IN "Chaining"
The 
.PN XtCreateWidget
function gets resources as a superclass-to-subclass operation.
That is, the resources specified in 
.PN Core
resource list are fetched,
then those in the subclass, and so on down to the resources specified
for this widget's class. Within a class, resources are fetched in the order
they are declared.
.LP
In general, if a widget resource field is declared in a superclass,
that field is included in the superclass's resource list and need not be
included in the subclass's resource list.
For example, the
.PN Core 
class contains a resource entry for background_pixel.
Consequently,
the implementation of Label need not also have a resource entry
for background_pixel.
However, a subclass,
by specifying a resource entry for that field in its own resource list,
can override the resource entry for any field declared in a superclass.
This is most often done to override the defaults provided in the
superclass with new ones.
At class initialization time, 
resource lists for that class are scanned from the superclass down 
to the class to look for resources with the same offset.
A matching resource in a subclass will be reordered to override
the superclass entry.
(A copy of the superclass resource list is made to
avoid affecting other subclasses of the superclass.)
.LP
.IN "class_initialize procedure"
.IN "Widget" "class initialization"
Also at class initialization time, the \*(xI produce an
internal representation of the resource list to optimize access time
when creating widgets.  In order to save memory, the \*(xI may
over-write the storage allocated for the resource list in the class
record; therefore, widgets must allocate resource lists in writable
storage and must not access the list contents directly after the
class_initialize procedure has returned.

.NH 2
Subresources
.XS
\*(SN Subresources
.XE
.LP
A widget does not do anything to get its own resources;
instead,
.PN XtCreateWidget
does this automatically before calling the class initialize procedure.
.LP
Some widgets have subparts that are not widgets but for which the widget
would like to fetch resources.
For example, the Text widget fetches resources for its source and sink.
Such widgets call
.PN XtGetSubresources
to accomplish this.
.IN "XtGetSubresources" "" "@DEF@"
.FD 0
void XtGetSubresources(\fIw\fP, \fIbase\fP, \fIname\fP, \fIclass\fP, \
\fIresources\fP, \fInum_resources\fP, \fIargs\fP, \fInum_args\fP)
.br
      Widget \fIw\fP;
.br
      XtPointer \fIbase\fP;
.br
      String \fIname\fP;
.br
      String \fIclass\fP;
.br
      XtResourceList \fIresources\fP;
.br
      Cardinal \fInum_resources\fP;
.br
      ArgList \fIargs\fP;
.br
      Cardinal \fInum_args\fP;
.FN
.IP \fIw\fP 1i
Specifies the widget used to qualify the subpart resource name and class.
.IP \fIbase\fP 1i
Specifies the base address of the subpart data structure into which the
resources will be written.
.IP \fIname\fP 1i
Specifies the name of the subpart.
.IP \fIclass\fP 1i
Specifies the class of the subpart.
.IP \fIresources\fP 1i
Specifies the resource list for the subpart.
.IP \fInum_resources\fP 1i
Specifies the number of resources in the resource list.
.IP \fIargs\fP 1i
Specifies the argument list to override any other resource specifications.
.IP \fInum_args\fP 1i
Specifies the number of arguments in the argument list.
.LP
The
.PN XtGetSubresources
function constructs a name/class list from the application name/class,
the name/classes of all its ancestors, and the widget itself.
Then, it appends to this list the name/class pair passed in.
The resources are fetched from the argument list, the resource database,
or the default values in the resource list.
Then, they are copied into the subpart record.
If args is NULL,
num_args must be zero.
However, if num_args is zero,
the argument list is not referenced.
.LP
.PN XtGetSubresources
may over-write the specified resource list with an
equivalent representation in an internal format which optimizes access
time if the list is used repeatedly.  The resource list must be
allocated in writable storage and the caller must not modify the list
contents after the call if the same list is to be used again.
Resources fetched by
.PN XtGetSubresources
are reference counted as
if they were referenced by the specified widget.  Subresources might
therefore be freed from the conversion cache and destroyed
when the widget is destroyed, but not before then.
.sp
.LP
To fetch resources for widget subparts using varargs lists, use
.PN XtVaGetSubresources .
.IN "XtVaGetSubresources" "" "@DEF@"
.FD 0
void XtVaGetSubresources(\fIobject\fP, \fIbase\fP, \fIname\fP, \fIclass\fP, \
\fIresources\fP, \fInum_resources\fP, ...)
.br
    Widget \fIobject\fP;
.br
    XtPointer \fIbase\fP;
.br
    String \fIname\fP;
.br
    String \fIclass\fP;
.br
    XtResourceList \fIresources\fP;
.br
    Cardinal \fInum_resources\fP;
.FN
.IP \fIw\fP 1i
Specifies the widget used to qualify the subpart resource name and class.
.IP \fIbase\fP 1i
Specifies the base address of the subpart data structure into which the
resources will be written.
.IP \fIname\fP 1i
Specifies the name of the subpart.
.IP \fIclass\fP 1i
Specifies the class of the subpart.
.IP \fIresources\fP 1i
Specifies the resource list for the subpart.
.IP \fInum_resources\fP 1i
Specifies the number of resources in the resource list.
.IP ... 1i
Specifies the variable-length argument list to override any other
resource specifications.
.LP
.PN XtVaGetSubresources
is identical in function to
.PN XtGetSubresources
with the args and num_args parameters replaced by a varargs list as
described in Section 2.4.1.

.NH 2
Obtaining Application Resources
.XS
\fB\*(SN Obtaining Application Resources\fP
.XE
.LP
To retrieve resources that are not specific to a widget
but apply to the overall application, use
.PN XtGetApplicationResources .
.IN "XtGetApplicationResources" "" "@DEF@"
.FD 0
void XtGetApplicationResources(\fIobject\fP, \fIbase\fP, \fIresources\fP, \
\fInum_resources\fP, \fIargs\fP, \fInum_args\fP)
.br
      Widget \fIobject\fP;
.br
      XtPointer \fIbase\fP;
.br
      XtResourceList \fIresources\fP;
.br
      Cardinal \fInum_resources\fP;
.br
      ArgList \fIargs\fP;
.br
      Cardinal \fInum_args\fP;
.FN
.IP \fIobject\fP 1i
Specifies the object that identifies the resource database to search
(The database is that associated with the display for this object);
may be of class Object or any subclass.
.IP \fIbase\fP 1i
Specifies the base address of the subpart data structure into which
the resources will be written.
.IP \fIresources\fP 1i
Specifies the resource list for the subpart.
.IP \fInum_resources\fP 1i
Specifies the number of resources in the resource list.
.IP \fIargs\fP 1i
Specifies the argument list to override any other resource specifications.
.IP \fInum_args\fP 1i
Specifies the number of arguments in the argument list.
.LP
The
.PN XtGetApplicationResources
function first uses the passed object,
which is usually an application shell widget,
to construct a resource name and class list.
The full name and class of the specified object (that is, including its
ancestors, if any) is logically prepended to each resource name and class.
Then, it retrieves the resources from the argument list,
the resource database, or the resource list default values.
After adding base to each address,
.PN XtGetApplicationResources
copies the resources into the address given in the resource list.
If args is NULL,
num_args must be zero.
However, if num_args is zero,
the argument list is not referenced.
The portable way to specify application resources is to declare them
as members of a structure and pass the address of the structure 
as the base argument.
.LP
.PN XtGetApplicationResources
may over-write the specified resource list
with an equivalent representation in an internal format which
optimizes access time if the list is used repeatedly.  The resource
list must be allocated in writable storage and the caller must not
modify the list contents after the call if the same list is to be
use again.  Any per-display resources fetched by
.PN XtGetApplicationResources
will not be freed from the resource cache until the display is closed.
.sp
.LP
To retrieve resources for the overall application using varargs lists, use
.PN XtVaGetApplicationResources .
.IN "XtVaGetApplicationResources" "" "@DEF@"
.FD 0
void XtVaGetApplicationResources(\fIobject\fP, \fIbase\fP, \fIresources\fP, \
\fInum_resources\fP, ...)
.br
      Widget \fIobject\fP;
.br
      XtPointer \fIbase\fP;
.br
      XtResourceList \fIresources\fP;
.br
      Cardinal \fInum_resources\fP;
.FN
.IP \fIobject\fP 1i
Specifies the object that identifies the resource database to search
(The database is that associated with the display for this object);
may be of class Object or any subclass.
.IP \fIbase\fP 1i
Specifies the base address of the subpart data structure into which
the resources will be written.
.IP \fIresources\fP 1i
Specifies the resource list for the subpart.
.IP \fInum_resources\fP 1i
Specifies the number of resources in the resource list.
.IP ... 1i
Specifies the variable-length argument list to override any other
resource specifications.
.LP
.PN XtVaGetApplicationResources
is identical in function to
.PN XtGetApplicationResources
with the args and num_args parameters
replaced by a varargs list as described in Section 2.4.1.

.NH 2
Resource Conversions
.XS
\*(SN Resource Conversions
.XE
.LP
The \*(xI provide a mechanism for registering representation converters that
are automatically invoked by the resource fetching routines.
The \*(xI additionally provide and registers several commonly used converters.
This resource conversion mechanism serves several purposes:
.IP \(bu 5
It permits user and application resource files to contain ASCII
representations of nontextual values.
.IP \(bu 5
It allows textual or other representations of default resource values that
are dependent on the display, screen, or color map, and thus must be
computed at run time.
.IP \(bu 5
It caches all conversion source and result data.
Conversions that require much computation or space
(for example, string to translation table)
or that require round trips to the server
(for example, string to font or color) are performed only once.
.NH 3
Predefined Resource Converters
.XS
\*(SN Predefined Resource Converters
.XE
.LP
The \*(xI define all the representations used in the 
.PN Core , 
.PN Composite , 
.PN Constraint , 
and 
.PN Shell 
widgets.
It registers the following resource converters:
.LP
From
.PN XtRString 
to:
.IP
.PN XtRAcceleratorTable ,
.PN XtRAtom ,
.PN XtRBoolean ,
.PN XtRBool ,
.PN XtRCursor ,
.PN XtRDimension ,
.PN XtRDisplay ,
.PN XtRFile ,
.PN XtRFloat ,
.PN XtRFont ,
.PN XtRFontStruct ,
.PN XtRInt ,
.PN XtRInitialState ,
.PN XtRPixel ,
.PN XtRPosition ,
.PN XtRShort ,
.PN XtRTranslationTable ,
.PN XtRUnsignedChar ,
and
.PN XtRVisual .
.LP
From
.PN XtRColor ,
to:
.PN XtRPixel .
.LP
From
.PN XRInt ,
to:
.IP
.PN XtRBoolean ,
.PN XtRBool ,
.PN XtRColor ,
.PN XtRDimension ,
.PN XtRFloat ,
.PN XtRFont ,
.PN XtRPixel ,
.PN XtRPixmap ,
.PN XtRPosition ,
.PN XtRShort ,
and
.PN XtRUnsignedChar .
.LP
From
.PN XtRPixel ,
to:
.PN XtRColor .
.LP
The string to pixel conversion has two predefined constants that are
guaranteed to work and contrast with each other
.Pn ( XtDefaultForeground
and
.PN XtDefaultBackground ).
.IN "XtDefaultBackground" "" "@DEF@"
.IN "XtDefaultForeground" "" "@DEF@"
They evaluate the black and white pixel values of the widget's screen, 
respectively.
.IN "Resources" "reverseVideo"
For applications that run with reverse video, however,
they evaluate the white and black pixel values of the widget's screen,
respectively.
Similarly, the string to font and font structure converters recognize
the constant
.PN XtDefaultFont
.IN "XtDefaultFont" "" "@DEF@"
.IN "Resources" "xtDefaultFont"
and evaluate this in the following manner:
.IP \(bu 5
Query the resource database for the resource whose full name
is ``xtDefaultFont'', class ``XtDefaultFont'' (that is, no widget
name/class prefixes) and use a type
.PN XtRString
value returned as the font name, or a type
.PN XtRFont
or
.PN XtRFontStruct
value directly as the resource value.
.IP \(bu 5
If the resource database does not contain a value for xtDefaultFont,
class XtDefaultFont, or if the returned font name cannot be
successfully opened, an implementation-defined font in ISO8859-1
character set encoding is opened.  (One possible algorithm is to
perform an
.PN XListFonts
using a wildcard font name and use the first
font in the list.  This wildcard font name should be as broad as
possible to maximize the probability of locating a useable font;
for example, "-*-*-*-R-*-*-*-120-*-*-*-*-ISO8859-1".)
.IP \(bu 5
If no suitable ISO8859-1 font can be found, issue an error message.
.LP
The String to InitialState conversion accepts the values
.PN NormalState
or
.PN IconicState
as defined by the \fI\*(xC\fP.
.LP
The String to Visual conversion calls
.PN XMatchVisualInfo
using the
screen and depth resources from core_part and returns the first
matching Visual on the list.  The widget resource list must be certain
to specify any resource of type
.PN XtRVisual
after the depth resource.
The allowed string values are the X Protocol visual class names:
.PN StaticGray ,
.PN StaticColor ,
.PN TrueColor ,
.PN GrayScale ,
.PN PseudoColor ,
and
.PN DirectColor .

.NH 3
New Resource Converters
.XS
\*(SN New Resource Converters
.XE
.LP
Type converters use pointers to
.PN XrmValue
structures (defined in
.Pn < X11/Xresource.h >;
see \fI\*(xL\fP for details)
for input and output values.
.LP
.Ds 0
.TA .5i 3i
.ta .5i 3i
typedef struct {
	unsigned int \fIsize\fP;
	caddr_t \fIaddr\fP;
} XrmValue, *XrmValuePtr;
.De
.LP
The addr field specifies the address of the data and the size field
gives the total number of significant bytes in the data.  For values
of type
.PN String ,
addr is the address of the first character and size
includes the NULL terminating byte. 
.LP
A resource converter procedure pointer is of type
.PN XtTypeConverter .
.IN "XtTypeConverter" "" "@DEF@"
.FD 0
typedef Boolean (*XtTypeConverter)(Display* \fIdisplay\fP, \
XrmValue* \fIargs\fP, Cardinal* \fInum_args\fP,
                              XrmValue* \fIfrom\fP, XrmValue* \fIto\fP, \
XtPointer* \fIconverter_data\fP);
.FN
.IP \fIdisplay\fP 1i
Specifies the Display connection with which this conversion is associated.
.IP \fIargs\fP 1i
Specifies a list of additional
.PN XrmValue
arguments to the converter if additional context is needed
to perform the conversion or NULL.
For example, the string-to-font converter needs the widget's screen,
or the string to pixel converter needs the widget's screen and color map.
.IP \fInum_args\fP 1i
Specifies the number of additional 
.PN XrmValue 
arguments or zero.
.IP \fIfrom\fP 1i
Specifies the value to convert.
.IP \fIto\fP 1i
Specifies a descriptor for a location into which to store the converted value.
.IP \fIconverter_data\fP 1i
Specifies a location into which the converter may
store converter-specific data that is associated
with this conversion.
.LP
The display argument is normally used only when generating error
messages, to identify the application context (with the function
.PN XtDisplayToApplicationContext ).
.LP
The to argument specifies the size and location into which the
converter should store the converted value.  If the location is NULL,
the converter should allocate appropriate storage and store the size
and location into the to descriptor.  If the type converter allocates
the storage, it remains under the ownership of the converter and must
not be modified by the caller.  The type converter is permitted to use
static storage for this purpose and therefore the caller must
immediately copy the data upon return from the converter.  If the
location is not NULL, the converter must check the size field to
insure that sufficient space has been allocated before storing the
converted value.  If insufficient space is specified, the converter
should update the size field with the number of bytes required and
return
.PN False
without modifying the data at the specified location.
If sufficient space was allocated by the caller, the converter should
update the size field with the number of bytes actually occupied by the
converted value.  For converted values of type
.PN XtRString ,
the size should
include the NULL terminating byte, if any.
The converter may store any value it wishes in the location specified
in converter_data; this data will be passed to the destructor, if any,
when the resource is freed by the \*(xI.
.LP
The converter must return
.PN True
if the conversion was successful and
.PN False
otherwise.  If the conversion cannot be performed due to an
improper source value, a warning message should also be issued with
.PN XtAppWarningMsg .

.LP
Most type converters just take the data described by the specified from
argument and return data by writing into the location specified in
the to argument.
A few need other information, which is available in the specified 
argument list.
A type converter can invoke another type converter,
which allows differing sources that may convert into a common intermediate
result to make maximum use of the type converter cache.
.LP
Note that if an address is written into to->addr, it cannot be that
of a local variable of the converter because the data will not be
valid after the converter returns.  Static variables may be used,
as in the following example.
.LP
The following is an example of a converter that takes a string
and converts it to a Pixel.  Note that the display parameter is only
used to generate error messages; the Screen conversion argument is
still required to inform the \*(xI that the converted value is
a function of the particular display (and colormap).
.LP
.Ds 0
.TA .3i .7i 1i 1.3i 1.7i 2i 4i
.ta .3i .7i 1i 1.3i 1.7i 2i 4i

#define	done(type, value) \\
	{						\\
		if (toVal->addr != NULL) {		\\
			if (toVal->size < sizeof(type)) {	\\
				toVal->size = sizeof(type);	\\
				return False;	\\
			}				\\
			*(type*)(toVal->addr) = (value);	\\
		}					\\
		else {				\\
			static type static_val;	\\
			static_val = (value);	\\
			toVal->addr = (XtPointer)&static_val;	\\
		}					\\
		toVal->size = sizeof(type);	\\
		return True;			\\
	}

static Boolean CvtStringToPixel(display, args, num_args, fromVal, toVal, converter_data)
	Display	*dpy;
	XrmValue	*args;
	Cardinal		*num_args;
	XrmValue	*fromVal;
	XrmValue	*toVal;
	XtPointer	*converter_data;
{
	static XColor	screenColor;
	XColor		exactColor;
	Screen		*screen;
	Colormap		colormap;
	Status			status;
	char			message[1000];
	XrmQuark		q;
	String			params[1];
	Cardinal		num_params = 1;

	if (*num_args != 2)
		XtAppErrorMsg(XtDisplayToApplicationContext(dpy),
			"cvtStringToPixel", "wrongParameters", "XtToolkitError",
			"String to pixel conversion needs screen and colormap arguments",
			(String *)NULL, (Cardinal *)NULL);

	screen = *((Screen **) args[0].addr); /* could also use dpy now */
	colormap = *((Colormap *) args[1].addr);

	LowerCase((char *) fromVal->addr, message);

	if ( strcmp(message, "xtdefaultbackground") == 0) { done(&screen->white_pixel, Pixel); }
	if ( strcmp(message, "xtdefaultforeground") == 0) { done(&screen->black_pixel, Pixel); }

	if ((char) fromVal->addr[0] == '#') {  /* some color rgb definition */
		status = XParseColor(DisplayOfScreen(screen), colormap, (String) fromVal->addr, 
			&screenColor);
		if (status != 0) status = XAllocColor(DisplayOfScreen(screen), colormap, &screenColor);
	} else  /* some color name */
		status = XAllocNamedColor(DisplayOfScreen(screen), colormap, (String) fromVal->addr, 
			&screenColor, &exactColor);

	if (status == 0) {
		params[0]=(String)fromVal->addr;
		XtAppWarningMsg(XtDisplayToApplicationContext(dpy),
			"cvtStringToPixel", "noColormap", "XtToolkitError",
			"Cannot allocate colormap entry for \\"%s\\"", params, &num_params);
	} else {
		done( &screenColor.pixel, Pixel );
	}

	/* converter_data not used here */
};
.De
.LP
All type converters should define some set of conversion values that they
are guaranteed to succeed on so these can be used in the resource defaults.
This issue arises only with conversions, such as fonts and colors,
where there is no string representation that all server implementations
will necessarily recognize.
For resources like these,
the converter should define a symbolic constant (for example,
.PN XtDefaultForeground ,
.PN XtDefaultBackground ,
or
.PN XtDefaultFont ).
.sp
.LP
To allow the \*(xI to deallocate resources produced by type
converters, a resource destructor procedure may also be provided.
.LP
A resource destructor procedure pointer is of type
.PN XtDestructor .
.IN "XtDestructor" "" "@DEF@"
.FD 0
typedef void (*XtDestructor) (XtAppContext \fIapp\fP, XrmValue* \fIto\fP, \
XtPointer \fIconverter_data\fP,
                              XrmValue* \fIargs\fP, Cardinal* \fInum_args\fP)
.FN
.IP \fIapp\fP 1i
Specifies an application context in which the resource is being freed.
.IP \fIto\fP 1i
Specifies a descriptor for the resource produced by the type converter.
.IP \fIconverter_data\fP 1i
Specifies the converter_data returned by the type converter.
.IP \fIargs\fP 1i
Specifies the additional converter arguments as passed
to the type converter when the conversion was performed.
.IP \fInum_args\fP 1i
Specifies the number of additional converter arguments.
.LP
The destructor procedure is responsible for freeing the resource
specified by the to argument, including any auxiliary storage
associated with that resource, but not the memory directly addressed
by the size and location in the to argument nor the memory specified
by the args.

.NH 3
Issuing Conversion Warnings
.XS
\*(SN Issuing Conversion Warnings
.XE
.LP
The
.PN XtDisplayStringConversionWarning
procedure is a convenience routine for resource type converters
that convert from string values.
.IN "XtDisplayStringConversionWarning" "" "@DEF@"
.FD 0
void XtDisplayStringConversionWarning(\fIdisplay\fP, \fIfrom_value\fP, \
\fIto_type\fP)
.br
      Display *\fIdisplay\fP;
.br
      String \fIfrom_value\fP, \fIto_type\fP;
.FN
.IP \fIdisplay\fP 1i
Specifies the display connection with which the conversion is associated.
.IP \fIfrom_value\fP 1i
Specifies the string that could not be converted.
.IP \fIto_type\fP 1i
Specifies the target representation type requested.
.LP
The
.PN XtDisplayStringConversionWarning
procedure issues a warning message using
.PN XtAppWarningMsg
with name ``conversionError'',
type ``string'', class ``XtToolkitError'' and the default message string
``Cannot convert "\fIfrom_value\fP" to type \fIto_type\fP''.
.LP
To issue other types of warning or error messages, the type converter
should use
.PN XtAppWarningMsg
or
.PN XtAppErrorMsg .
.sp
.LP
To retrieve the application context associated with a Display, use
.PN XtDisplayToApplicationContext .
.IN "XtDisplayToApplicationContext" "" "@DEF@"
.FD 0
XtAppContext XtDisplayToApplicationContext( \fIdisplay\fP )
.br
      Display *\fIdisplay\fP;
.FN
.IP \fIdisplay\fP 1i
Specifies an open and initialized Display connection.
.LP
The
.PN XtDisplayToApplicationContext
function returns the application
context in which the specified display was initialized.  If the
display is not known to the \*(xI, an error message is issued.

.NH 3
Registering a New Resource Converter
.XS
\fB\*(SN Registering a New Resource Converter\fP
.XE
.LP
When registering a resource converter, the client must specify the
manner in which the conversion cache is to be used when there are multiple
calls to the converter.  Conversion cache control is specified
via an
.PN XtCacheType
.IN "XtCacheType" "" "@DEF@"
argument:
.sp
.Ds 0
typedef int	XtCacheType;
.De
.LP
An
.PN XtCacheType
field may contain one of the following values:
.br
.sp
.LP
.PN XtCacheNone
.IN "XtCacheNone" "" "@DEF@"
.IP
Specifies that the results of a previous conversion
may not be reused to satisfy any other resource
requests; the specified converter will be called
each time the converted value is required.
.br
.sp
.LP
.PN XtCacheAll
.IN "XtCacheAll" "" "@DEF@"
.IP
Specifies that the results of a previous conversion
should be reused for any resource request that depends
upon the same source value and conversion arguments.
.br
.sp
.LP
.PN XtCacheByDisplay
.IN "XtCacheByDisplay" "" "@DEF@"
.IP  
Specifies that the results of a previous conversion
should be used as for
.PN XtCacheAll
but the destructor will be called, if specified, if
.PN XtCloseDisplay
is called
for the Display associated with the converted value and
the value will be removed from the conversion cache.
.LP
The qualifier
.PN XtCacheRefCount
.IN "XtCacheRefCount" "" "@DEF@"
may be ORed with any of the values above.  If
.PN XtCacheRefCount
is specified, calls to
.PN XtCreateWidget ,
.PN XtCreateManagedWidget ,
.PN XtGetApplicationResources
and
.PN XtGetSubresources
that use the converted value will be counted.  When a widget using the
converted value is destroyed, the count is decremented and if the
count reaches zero the destructor procedure will be called and the
converted value will be removed from the conversion cache.

.LP
To register a type converter for all application contexts in a
process, use 
.PN XtSetTypeConverter
and to register a type converter in a single application context, use
.PN XtAppSetTypeConverter .
.IN "XtSetTypeConverter" "" "@DEF@"
.FD 0
void XtSetTypeConverter(\fIfrom_type\fP, \fIto_type\fP, \fIconverter\fP, \
\fIconvert_args\fP, \fInum_args\fP,
                        \fIcache_type\fP, \fIdestructor\fP)
.br
      String \fIfrom_type\fP, \fIto_type\fP;
.br
      XtTypeConverter \fIconverter\fP;
.br
      XtConvertArgList \fIconvert_args\fP;
.br
      Cardinal \fInum_args\fP;
.br
      XtCacheType \fIcache_type\fP;
.br
      XtDestructor \fIdestructor\fP;
.FN

.IN "XtAppSetTypeConverter" "" "@DEF@"
.FD 0
void XtAppSetTypeConverter(\fIapp_context\fP, \fIfrom_type\fP, \fIto_type\fP, \
\fIconverter\fP, \fIconvert_args\fP,
                           \fInum_args\fP, \fIcache_type\fP, \fIdestructor\fP)
.br
      XtAppContext \fIapp_context\fP;
.br
      String \fIfrom_type\fP;
.br
      String \fIto_type\fP;
.br
      XtConverter \fIconverter\fP;
.br
      XtConvertArgList \fIconvert_args\fP;
.br
      Cardinal \fInum_args\fP;
.br
      XtCacheType \fIcache_type\fP;
.br
      XtDestructor \fIdestructor\fP;
.FN
.IP \fIapp_context\fP 1i
Specifies the application context.
.IP \fIfrom_type\fP 1i
Specifies the source type.
.IP \fIto_type\fP 1i
Specifies the destination type.
.IP \fIconverter\fP 1i
Specifies the resource type converter procedure.
.IP \fIconvert_args\fP 1i
Specifies additional conversion arguments, or NULL.
.IP \fInum_args\fP 1i
Specifies the count of additional conversion arguments, or zero.
.IP \fIcache_type\fP 1i
Specifies whether or not resources produced by this
converter are sharable or display-specific and when
they should be freed.
.IP \fIdestructor\fP 1i
Specifies a destroy procedure for resources produced by
this conversion, or NULL if no additional action is
required to deallocate resources produced by converter.
.LP
.PN XtSetTypeConverter
registers the specified type converter and
destructor in all application contexts created by the calling process,
including any future application contexts which may be created.
.PN XtAppSetTypeConverter
registers the specified type converter in the
single application context specified.  If the same from_type and
to_type are specified in multiple calls to either function, the most
recent overrides the previous ones.
.sp
.LP
For the few type converters that need additional arguments,
the \*(xI conversion mechanism provides a method of specifying
how these arguments should be computed.
The enumerated type
.PN XtAddressMode
and the structure
.PN XtConvertArgRec
specify how each argument is derived.
These are defined in
.Pn < X11/Convert.h >.
.LP
.Ds 0
.TA .5i 2.5i
.ta .5i 2.5i
typedef enum {
	/* address mode	parameter representation */
	   XtAddress,	/* address */
	   XtBaseOffset,	/* offset */
	   XtImmediate,	/* constant */
	   XtResourceString,	/* resource name string */
	   XtResourceQuark,	/* resource name quark */
	   XtWidgetBaseOffset,	/* offset */
	   XtProcedureArg	/* procedure to call */
} XtAddressMode;

typedef struct {
	XtAddressMode address_mode;
	XtPointer address_id;
	Cardinal size;
} XtConvertArgRec, *XtConvertArgList;
.De
.LP
The size field specifies the length of the data in bytes.
The address_mode field specifies how the address_id field should be
interpreted.
.PN XtAddress
.IN "XtAddress" "" "@DEF@"
causes address_id to be interpreted as the address of the data.
.PN XtBaseOffset
.IN "XtBaseOffset" "" "@DEF@"
causes address_id to be interpreted as the offset from the widget base.
.PN XtImmediate
.IN "XtImmediate" "" "@DEF@"
causes address_id to be interpreted as a constant.
.PN XtResourceString
.IN "XtResourceString" "" "@DEF@"
causes address_id to be interpreted as the name of a resource
that is to be converted into an offset from widget base.
.PN XtResourceQuark
.IN "XtResourceQuark" "" "@DEF@"
causes address_id to be interpreted as the result of an
.PN XrmStringToQuark
conversion on the name of a resource,
which is to be converted into an offset from the widget base.
.PN XtWidgetBaseOffset
.IN "XtWidgetBaseOffset" "" "@DEF@"
is similar to
.PN XtBaseOffset
except that it
searches for the closest windowed ancestor if the object is not
a subclass of
.PN Core
(See Chapter 12).
.PN XtProcedureArg
.IN "XtProcedureArg" "" "@DEF@"
specifies that address_id is a pointer to a procedure to
be invoked to return the conversion argument.  Address_id must contain
the address of a function of type
.PN XtConvertArgProc .
.IN "XtConvertArgProc" "" "@DEF@"
.FD 0
typedef void (*XtConvertArgProc)(Widget \fIobject\fP, Cardinal* \fIsize\fP, \
XrmValue* \fIvalue\fP)
.FN
.IP \fIobject\fP 1i
Passes the object for which the resource is being
converted or NULL if the converter was invoked by
.PN XtCallConverter
or
.PN XtDirectConvert .
.IP \fIsize\fP 1i
Passes a pointer to the size field from the
.PN XtConvertArgRec .
.IP \fIvalue\fP 1i
Passes a pointer to a descriptor into which the procedure
must store the conversion argument.
.LP
When invoked, the
.PN XtConvertArgProc
procedure must derive a conversion
argument and store the address and size of the argument in the location
pointed to by the value field.
.LP
In order to permit reentrancy, the
.PN XtConvertArgProc
should should
return the address of storage whose lifetime is no shorter than the
lifetime of object.  If object is NULL, the lifetime of the conversion
argument must be no shorter than the lifetime of the resource with
which the conversion argument is associated.  The \*(xI do not
guarantee to copy this storage but do guarantee to not reference it if
the resource is removed from the conversion cache.
.LP
The following example illustrates how to register the CvtStringToPixel 
routine given earlier:
.LP
.Ds
.TA .2i 3i
.ta .2i 3i
static XtConvertArgRec colorConvertArgs[] = {
	{XtWidgetBaseOffset, (XtPointer) XtOffset(Widget, core.screen),  sizeof(Screen *)},
	{XtWidgetBaseOffset, (XtPointer) XtOffset(Widget, core.colormap),sizeof(Colormap)}
};

XtSetTypeConverter(XtRString, XtRPixel, CvtStringToPixel,
    colorConvertArgs, XtNumber(colorConvertArgs));
.De
.LP
The conversion argument descriptors
.PN colorConvertArgs
and
.PN screenConvertArg
are predefined by the \*(xI.  Both take the
values from the closest windowed ancestor if the object is not of a
subclass of
.PN Core .
The
.PN screenConvertArg
descriptor puts the widget's screen field into args[0].  The
.PN colorConvertArgs
descriptor puts the widget's screen field into args[0],
and the widget's colormap field into args[1].
.LP
Conversion routines should not just put a descriptor for the address of the
base of the widget into args[0], and use that in the routine.
They should pass in the actual values that the conversion depends on.
By keeping the dependencies of the conversion procedure specific,
it is more likely that subsequent conversions will find what they need
in the conversion cache.
This way the cache is smaller and has fewer and more widely applicable entries.
.LP
If any conversion arguments of type
.PN XtBaseOffset ,
.PN XtResourceString ,
.PN XtResourceQuark
and
.PN XtWidgetBaseOffset
are specified for conversions performed by
.PN XtGetApplicationResources ,
.PN XtGetSubresources ,
.PN XtVaGetApplicationResources
or
.PN XtVaGetSubresources ,
the arguments are
computed with respect to the specified widget, not the base address or
resource list specified in the call.

.NH 3
Resource Converter Invocation
.XS
\*(SN Resource Converter Invocation
.XE
.LP
All resource-fetching routines (for example,
.PN XtGetSubresources ,
.PN XtGetApplicationResources ,
and so on) call resource converters if the user specifies a resource
that is a different representation from the desired representation or if the
widget's default resource value representation is different from the desired
representation.
.sp
.LP
To invoke explicit resource conversions, use
.PN XtConvertAndStore
or
.PN XtCallConverter .
.sp
.Ds 0
typedef Opaque XtCacheRef;
.De
.IN "XtCallConverter" "" "@DEF@"
.FD 0
Boolean XtCallConverter( \fIdisplay\fP, \fIconverter\fP, \fIargs\fP, \
\fInum_args\fP, \fIfrom\fP, \fIto_in_out\fP, \fIcache_ref_return\fP )
.br
      Display* \fIdisplay\fP;
.br
      XtTypeConverter \fIconverter\fP;
.br
      XrmValuePtr \fIargs\fP;
.br
      Cardinal \fInum_args\fP;
.br
      XrmValuePtr \fIfrom\fP;
.br
      XrmValuePtr \fIto_in_out\fP;
.br
      XtCacheRef *\fIcache_ref_return\fP;
.FN
.IP \fIdisplay\fP 1i
Specifies the display with which the conversion is to be associated.
.IP \fIconverter\fP 1i
Specifies the conversion procedure that is to be called.
.IP \fIargs\fP 1i
Specifies the additional conversion arguments needed
to perform the conversion, or NULL.
.IP \fInum_args\fP 1i
Specifies the count of additional arguments, or zero.
.IP \fIfrom\fP 1i
Specifies a descriptor for the source value.
.IP \fIto_in_out\fP 1i
Returns the converted value.
.IP \fIcache_ref\fP 1i
Returns a conversion cache id.
.LP
The
.PN XtCallConverter
function looks up the
specified type converter in the application context associated with
the display and if the converter was not registered or was registered
with cache type
.PN XtCacheAll
or
.PN XtCacheByDisplay
looks in the conversion cache to see if this conversion procedure
has been called with the specified arguments.  If so, it
checks the success status of the prior call and if
the conversion failed,
.PN XtCallConverter
returns
.PN False
immediately;
otherwise it checks the size specified in the to argument and if it is
greater than or equal to the size stored in the cache, copies the
information stored in the cache into the location specified by the
to argument, stores the cache size into to->size and returns
.PN True .
If the size specified in the to argument is smaller than the size stored
in the cache,
.PN XtCallConverter
copies the cache size into to->size and returns
.PN False .
If the converter was registered with cache type
.PN XtCacheNone
or no value was found in the conversion cache,
.PN XtCallConverter
calls the converter and if it was not registered with cache type
.PN XtCacheNone
enters the result in the cache.  
.PN XtCallConverter
then returns what the converter returned.
.LP
Cache_ref_return specifies storage allocated by the caller in which
an opaque value will be stored.  If the type converter has been
registered with the
.PN XtCacheRefCount
modifier and if the value returned
in cache_ref_return is non-NULL then the caller should store the
cache_ref_return value in order to decrement the reference count when
the converted value is no longer required.  Cache_ref_return should be
specified as NULL if the caller is unwilling or unable to store the
value.
.sp
.LP
To explicitly decrement the reference counts for resources obtained
from
.PN XtCallConverter ,
use
.PN XtAppReleaseCacheRefs .
.IN "XtAppReleaseCacheRefs" "" "@DEF@"
.FD 0
void XtAppReleaseCacheRefs(\fIapp\fP, \fIrefs\fP)
.br
      XtAppContext \fIapp\fP;
.br
      XtCacheRef *\fIrefs\fP;
.FN
.IP \fIapp\fP 1i
Specifies the application context.
.IP \fIrefs\fP 1i
Specifies the list of cache references to be released.
.LP
.PN XtAppReleaseCacheRefs
decrements the reference count for the
conversion entries identified by the refs argument.  Refs is a
pointer to a NULL-terminated list of
.PN XtCacheRef
values.  If any reference
count reaches zero, the destructor, if any, will be called and
the resource removed from the conversion cache.
.sp
.LP
As a convenience to clients needing to explicitly decrement reference
counts via a callback function, the \*(xI define two callback
procedures
.PN XtCallbackReleaseCacheRef
and
.PN XtCallbackReleaseCacheRefList .
.IN "XtCallbackReleaseCacheRef" "" "@DEF@"
.FD 0
void XtCallbackReleaseCacheRef(\fIobject\fP, \fIclient_data\fP, \fIcall_data\fP)
.br
      Widget \fIobject\fP;
.br
      XtPointer \fIclient_data\fP;
.br
      XtPointer \fIcall_data\fP;
.FN
.IP \fIobject\fP 1i
Specifies the object with which the resource is associated.
.IP \fIclient_data\fP 1i
Specifies the conversion cache entry to be released.
.IP \fIcall_data\fP 1i
Is ignored.
.LP
This callback procedure may be added to a callback list to release a
previously returned
.PN XtCacheRef
value.  When adding the callback, the
callback client_data argument must be specified as the value of the
.PN XtCacheRef
data cast to
.PN XtPointer .
.sp
.IN "XtCallbackReleaseCacheRefList" "" "@DEF@"
.FD 0
void XtCallbackReleaseCacheRefList(\fIobject\fP, \fIclosure\fP, \fIcall_data\fP)
.br
      Widget \fIobject\fP;
.br
      XtPointer \fIclient_data\fP;
.br
      XtPointer \fIcall_data\fP;
.FN
.IP \fIobject\fP 1i
Specifies the object with which the resources are associated.
.IP \fIclient_data\fP 1i
Specifies the conversion cache entries to be released.
.IP \fIcall_data\fP 1i
Is ignored.
.LP
This callback procedure may be added to a callback list to release a
list of previously returned
.PN XtCacheRef
values.  When adding the
callback, the callback client_data argument must be specified as a
pointer to a NULL-terminated list of
.PN XtCacheRef
values.
.sp
.LP
To lookup and call a resource converter, copy the resulting value,
and free a cached resource when a widget is destroyed, use
.PN XtConvertAndStore .
.IN "XtConvertAndStore" "" "@DEF@"
.FD 0
Boolean XtConvertAndStore(\fIobject\fP, \fIfrom_type\fP, \fIfrom\fP, \
\fIto_type\fP, \fIto_in_out\fP)
.br
      Widget \fIobject\fP;
.br
      String \fIfrom_type\fP;
.br
      XrmValuePtr \fIfrom\fP;
.br
      String \fIto_type\fP;
.br
      XrmValuePtr \fIto_in_out\fP;
.FN
.IP \fIobject\fP 1i
Specifies the object to use for additional arguments, if any are needed,
and the destroy callback list; it may be of class
.PN Object
or any subclass thereof.
.IP \fIfrom_type\fP 1i
Specifies the source type.
.IP \fIfrom\fP 1i
Specifies the value to be converted.
.IP \fIto_type\fP 1i
Specifies the destination type.
.IP \fIto_in_out\fP 1i
Specifies a descriptor for storage into which the converted value
will be returned.
.LP
The
.PN XtConvertAndStore
function looks up the type converter registered
to convert from_type to to_type, computes any additional arguments
needed, and then calls
.PN XtCallConverter
(or
.PN XtDirectConvert
if an old-style converter was registered with
.PN XtAddConverter
or
.PN XtAppAddConverter ;
see Appendix C) with the from and to_in_out arguments.  The
to_in_out argument specifies the size and location into which the
converted value will be stored and is passed directly to the
converter.  If the location is specified as NULL, it will be replaced
with a pointer to private storage and the size will be returned in the
descriptor.  The caller is expected to copy this private storage
immediately and must not modify it in any way.  If a non-NULL location
is specified, the caller must allocate sufficient storage to hold the
converted value and must also specify the size of that storage in the
descriptor.  If the conversion succeeds,
.PN XtConvertAndStore
returns
.PN True ;
otherwise it returns
.PN False .
.LP
.PN XtConvertAndStore
adds
.PN XtCallbackReleaseCacheRef
.IN "destroyCallback"
to the destroyCallback list of the specified widget if the conversion
returns an
.PN XtCacheRef
value.  The resulting resource should not be referenced
after the widget has been destroyed.
.LP
.PN XtCreateWidget
performs processing equivalent to
.PN XtConvertAndStore
when initializing the widget instance.  Because there is extra memory
overhead required to implement reference counting, clients may
distinguish those widgets which are never destroyed before the
application exits from those which may be destroyed and whose
resources should be deallocated.
.LP
To specify whether or not reference counting is to be enabled for the
resources of a particular widget when the widget is created, the
client can specify a value for the
.PN Boolean
resource
.PN XtNinitialResourcesPersistent ,
.IN "XtNinitialResourcesPersistent" "" "@DEF@"
class
.PN XtCInitialResourcesPersistent .
.LP
When
.PN XtCreateWidget
is called, if this resource is not specified as
.PN False
in either the arg list or the resource database, then the
resources referenced by this widget are not reference counted, regardless of
how the type converter may have been registered.  The effective
default value is
.PN True ;
thus clients which expect to destroy one or
more widgets and want resources deallocated must explicitly specify
.PN False
for
.PN XtNinitialResourcesPersistent .
.LP
The resources are still freed and destructors called when
.PN XtCloseDisplay
is called if the conversion was registered as
.PN XtCacheByDisplay .

.NH 2
Reading and Writing Widget State
.XS
\fB\*(SN Reading and Writing Widget State\fP
.XE
.LP
Any resource field in a widget can be read or written by a client.
On a write operation,
the widget decides what changes it will actually allow and updates all
derived fields appropriately.
.NH 3
Obtaining Widget State
.XS
\fB\*(SN Obtaining Widget State\fP
.XE
.LP
To retrieve the current values of resources associated with a
widget instance, use
.PN XtGetValues .
.IN "XtGetValues" "" "@DEF@"
.FD 0
void XtGetValues(\fIobject\fP, \fIargs\fP, \fInum_args\fP)
.br
      Widget \fIobject\fP;
.br
      ArgList \fIargs\fP;
.br
      Cardinal \fInum_args\fP;
.FN
.IP \fIobject\fP 1i
Specifies the object whose resource values are to be returned.
.IP \fIargs\fP 1i
Specifies the argument list of name/address pairs that contain the
resource names and the addresses into which the resource values are to
be stored.
The resource names are widget-dependent.
.IP \fInum_args\fP 1i
Specifies the number of arguments in the argument list.
.LP
The
.PN XtGetValues
function starts with the resources specified for the core widget fields
and proceeds down the subclass chain to the widget.
The value field of a passed argument list should contain the
address into which to store the corresponding resource value.
It is the caller's responsibility
to allocate and deallocate this storage according to the size of the
resource representation type used within the widget.
.LP
If the widget's parent is a subclass of
.PN constraintWidgetClass ,
.PN XtGetValues
then fetches the values for any constraint resources requested.
It starts with the constraint resources specified for
.PN constraintWidgetClass
and proceeds down to the subclass chain to the parent's constraint resources.
If the argument list contains a resource name that is not found in any of the
resource lists searched, 
the value at the corresponding address is not modified.
.IN "get_values_hook procedure"
If any get_values_hook procedures in the
widget's class or superclass records are non-NULL, 
they are called in superclass-to-subclass order after
all the resource values have been fetched by
.PN XtGetValues .
Finally, if the widget's parent is a
subclass of
.PN constraintWidgetClass
and if any of the parent's class or
superclass records have declared
.PN ConstraintClassExtension
records in
the constraint class part extension fields with a record type of
.PN \s-1NULLQUARK\s+1
and if the get_values_hook field in the extension record is non-NULL,
.PN XtGetValues
calls the get_values_hook procedures in superclass-to-subclass order.
This permits a subclass and constraint parent to provide nonwidget
resource data to
.PN XtGetValues .
.sp
.LP
To retrieve the current values of resources associated with a widget
instance using varargs lists, use
.PN XtVaGetValues .
.IN "XtVaGetValues" "" "@DEF@"
.FD 0
void XtVaGetValues(\fIobject\fP, ...)
.br
      Widget \fIobject\fP;
.FN
.IP \fIobject\fP 1i
Specifies the object whose resource values are to be returned.
.IP ... 1i
Specifies the variable-length argument list for the resources to
be returned.
.LP
.PN XtVaGetValues
is identical in function to
.PN XtGetValues
with the args
and num_args parameters replaced by a varargs list as described in
Section 2.4.1.  All value entries in the list must specify pointers to
storage allocated by the caller to which the resource value will be
copied.  It is the caller's responsibility to ensure that sufficient
storage is allocated.  If
.PN XtVaTypedArg
is specified, the type field
specifies the representation desired by the caller and the size field
specifies the number of bytes allocated to store the result of the
conversion.  If the size is insufficient, a warning message is issued
and the list entry is skipped.

.NH 4
Widget Subpart Resource Data: the get_values_hook Procedure
.XS
\*(SN Widget Subpart Resource Data: the get_values_hook Procedure
.XE
.LP
Widgets that have subparts can return resource values from them for
.PN XtGetValues
by supplying a get_values_hook procedure.
The get_values_hook procedure pointer is of type
.PN XtArgsProc :
.IN "get_values_hook procedure" "" "@DEF@"
.FD 0
typedef void (*XtArgsProc)(Widget, ArgList, Cardinal *);
.br
     Widget \fIw\fP;
.br
     ArgList \fIargs\fP;
.br
     Cardinal *\fInum_args\fP;
.FN
.IP \fIw\fP 1i
Specifies the widget whose nonwidget resource values are to be retrieved.
.IP \fIargs\fP 1i
Specifies the argument list that was passed to
.PN XtGetValues .
.IP \fInum_args\fP 1i
Specifies the number of arguments in the argument list.
.LP
The widget should call
.PN XtGetSubvalues
and pass in its subresource list and the arg and num_args parameters.
.NH 4
Widget Subpart State
.XS
\*(SN Widget Subpart State
.XE
.LP
To retrieve the current values of nonwidget resource data associated with a
widget instance, use
.PN XtGetSubvalues .
For a discussion of nonwidget subclass resources,
see Section 9.4.
.IN "XtGetSubvalues" "" "@DEF@"
.FD 0
void XtGetSubvalues(\fIbase\fP, \fIresources\fP, \fInum_resources\fP, \
\fIargs\fP, \fInum_args\fP)
.br
      XtPointer \fIbase\fP;
.br
      XtResourceList \fIresources\fP;
.br
      Cardinal \fInum_resources\fP;
.br
      ArgList \fIargs\fP;
.br
      Cardinal \fInum_args\fP;
.FN
.IP \fIbase\fP 1i
Specifies the base address of the subpart data structure for which the
resources should be retrieved.
.IP \fIresources\fP 1i
Specifies the nonwidget resource list.
.IP \fInum_resources\fP 1i
Specifies the number of resources in the resource list.
.IP \fIargs\fP 1i
Specifies the argument list of name/address pairs that contain the
resource names and the addresses into which the resource values are to
be stored.
The arguments and values are dependent on the subpart.
The storage for argument values that are pointed to by the
argument list must be deallocated by the application when no longer needed.
.IP \fInum_args\fP 1i
Specifies the number of arguments in the argument list.
.LP
The
.PN XtGetSubvalues
function obtains resource values from the structure identified by base.
.sp
.LP
To retrieve the current values of nonwidget resources associated with
a widget instance using varargs lists, use
.PN XtVaGetSubvalues .
.IN "XtVaGetSubvalues" "" "@DEF@"
.FD 0
void XtVaGetSubvalues(\fIbase\fP, \fIresources\fP, \fInum_resources\fP, ...)
.br
      XtPointer \fIbase\fP;
.br
      XtResourceList \fIresources\fP;
.br
      Cardinal \fInum_resources\fP;
.FN
.IP \fIbase\fP 1i
Specifies the base address of the subpart data structure for which the
resources should be retrieved.
.IP \fIresources\fP 1i
Specifies the nonwidget resource list.
.IP \fInum_resources\fP 1i
Specifies the number of resources in the resource list.
.IP ... 1i
Specifies a variable-length argument list of name/address pairs that
contain the resource names and the addresses into which the resource
values are to be stored.
The arguments and values are dependent on the subpart.
.LP
.PN XtVaGetSubvalues
is identical in function to
.PN XtGetSubvalues
with the
args and num_args parameters replaced by a varargs list as described
in Section 2.4.1.
.PN XtVaTypedArg
is not supported for
.PN XtVaGetSubvalues .
If
.PN XtVaTypedArg
is specified in the list a warning message is issued
and the entry is then ignored.

.NH 3
Setting Widget State
.XS
\fB\*(SN Setting Widget State\fP
.XE
.LP
To modify the current values of resources associated with a widget
instance, use
.PN XtSetValues .
.IN "XtSetValues" "" "@DEF@"
.FD 0
void XtSetValues(\fIobject\fP, \fIargs\fP, \fInum_args\fP)
.br
      Widget \fIobject\fP;
.br
      ArgList \fIargs\fP;
.br
      Cardinal \fInum_args\fP;
.FN
.IP \fIobject\fP 1i
Specifies the object whose resources are to be modified.
.IP \fIargs\fP 1i
Specifies the argument list of name/value pairs that contain the
resources to be modified and their new values.
The resources and values passed are dependent on
the widget being modified.
.IP \fInum_args\fP 1i
Specifies the number of arguments in the argument list.
.LP
The
.PN XtSetValues
function starts with the resources specified for the 
.PN Core 
widget fields and proceeds down the subclass chain to the widget.
At each stage,
it writes the new value (if specified by one of the arguments) or the existing
value (if no new value is specified) to a new widget data record.
.PN XtSetValues
then calls the set_values procedures for the widget in superclass-to-subclass 
order.
.IN "set_values_hook procedure"
If the widget has any non-NULL set_values_hook fields,
these are called immediately after the
corresponding set_values procedure.
This procedure permits subclasses to set nonwidget data for
.PN XtSetValues .
.LP
If the widget's parent is a subclass of
.PN constraintWidgetClass ,
.PN XtSetValues
also updates the widget's constraints.
It starts with the constraint resources specified for
.PN constraintWidgetClass
and proceeds down the subclass chain to the parent's class.
At each stage,
it writes the new value or the existing value to a new constraint record.
It then calls the constraint set_values procedures from
.PN constraintWidgetClass
down to the parent's class.
The constraint set_values procedures are called with widget arguments,
as for all set_values procedures, not just the constraint record arguments,
so that they can make adjustments to the desired values based
on full information about the widget.
.LP
.PN XtSetValues
determines if a geometry request is needed by comparing the current widget to
the new widget.
If any geometry changes are required,
it makes the request, and the geometry manager returns
.PN XtGeometryYes ,
.PN XtGeometryAlmost ,
or
.PN XtGeometryNo .
If
.PN XtGeometryYes ,
.PN XtSetValues
calls the widget's resize procedure.
If
.PN XtGeometryNo ,
.PN XtSetValues
resets the geometry fields to their original values.
If
.PN XtGeometryAlmost ,
.PN XtSetValues
calls the set_values_almost procedure,
which determines what should be done and writes new values for the
geometry fields into the new widget.
.PN XtSetValues
then repeats this process,
deciding once more whether the geometry manager should be called.
.LP
Finally, if any of the set_values procedures returned 
.PN True ,
.PN XtSetValues
causes the widget's expose procedure to be invoked by calling the Xlib
.PN XClearArea
function on the widget's window.
.sp
.LP
To modify the current values of resources associated with a widget
instance using varargs lists, use
.PN XtVaSetValues .
.IN "XtVaSetValues" "" "@DEF@"
.FD 0
void XtVaSetValues(\fIobject\fP, ...)
.br
      Widget \fIobject\fP;
.FN
.IP \fIobject\fP 1i
Specifies the object whose resources are to be modified.
.IP ... 1i
Specifies the variable-length argument list of name/value pairs that
contain the resources to be modified and their new values.
The resources and values passed are dependent on
the widget being modified.
.LP
.PN XtVaSetValues
is identical in function to
.PN XtSetValues
with the args and num_args parameters replaced by a varargs list as
described in Section 2.4.1.

.NH 4
Widget State: the set_values Procedure
.XS
\*(SN Widget State: the set_values Procedure
.XE
.LP
The set_values procedure pointer in a widget class is of type
.PN XtSetValuesFunc :
.IN "XtSetValuesFunc" "" "@DEF@"
.IN "set_values procedure" "" "@DEF@"
.FD 0
typedef Boolean (*XtSetValuesFunc)(Widget \fIcurrent\fP, \
Widget \fIrequest\fP, Widget \fInew\fP,
                                   ArgList \fIargs\fP, \
Cardinal* \fInum_args\fP);
.FN
.IP \fIcurrent\fP 1i
Specifies a copy of the widget as it was before the
.PN XtSetValues
call.
.IP \fIrequest\fP 1i
Specifies a copy of the widget with all values changed as asked for by the
.PN XtSetValues
call before any class set_values procedures have been called.
.IP \fInew\fP 1i
Specifies the widget with the new values that are actually allowed.
.IP \fIargs\fP 1i
Specifies the argument list passed to
.PN XtSetValues .
.IP \fInum_args\fP 1i
Specifies the count of arguments in the argument list.
.LP
The set_values procedure should recompute any field
derived from resources that are changed
(for example, many GCs depend on foreground and background).
If no recomputation is necessary and if none of the resources specific to a
subclass require the window to be redisplayed when their values are changed,
you can specify NULL for the set_values field in the class record.
.LP
Like the initialize procedure,
set_values mostly deals only with the fields defined in the subclass,
but it has to resolve conflicts with its superclass,
especially conflicts over width and height.
.LP
Sometimes a subclass may want to overwrite values filled in by its
superclass.
In particular, size calculations of a superclass are often
incorrect for a subclass and in this case,
the subclass must modify or recalculate fields declared
and computed by its superclass.
.LP
As an example,
a subclass can visually surround its superclass display.
In this case, the width and height calculated by the superclass set_values
procedure are too small and need to be incremented by the size of the surround.
The subclass needs to know if its superclass's size was calculated by the
superclass or was specified explicitly.
All widgets must place themselves into whatever size is explicitly given,
but they should compute a reasonable size if no size is requested.
How does a subclass know the difference between a specified size
and a size computed by a superclass?
.LP
The request and new parameters provide the necessary information.
The request widget is the widget as originally requested.
The new widget starts with the values in the request,
but it has been updated by all superclass set_values procedures called
so far.
A subclass set_values procedure can compare these two to resolve
any potential conflicts.
.LP
In the above example,
the subclass with the visual surround can see
if the width and height in the request widget are zero.
If so,
it adds its surround size to the width and height fields in the new widget.
If not, it must make do with the size originally specified.
.LP
The new widget is the actual widget instance record.
Therefore,
the set_values procedure should do all its work on the new widget
(the request widget should never be modified),
and if it needs to call any routines that operate on a widget,
it should specify new as the widget instance.
.LP
Before calling the set_values procedures, the \*(xI modify the
resources of the request widget according to the contents of the arglist;
if the widget names all its resources in the class resource list, it is
never necessary to examine the contents of args.
.LP
The widget specified by new starts with the values of that specified by request
but has been modified by any superclass set_values procedures.
A widget need not refer to the request widget,
unless it must resolve conflicts between the current and new widgets.
Any changes that the widget needs to make, including geometry changes,
should be made in the new widget.
.LP
Finally, the set_values procedure must return a Boolean that indicates whether
the widget needs to be redisplayed.
Note that a change in the geometry fields alone does not require
the set_values procedure to return 
.PN True ;
the X server will eventually generate an
.PN Expose
event, if necessary.
After calling all the set_values procedures,
.PN XtSetValues
forces a redisplay by calling the Xlib
.PN XClearArea
function if any of the set_values procedures returned 
.PN True .
Therefore, a set_values procedure should not try to do its own redisplaying.
.LP
Set_values procedures should not do any work in response to changes in
geometry because
.PN XtSetValues
eventually will perform a geometry request, and that request might be denied.
If the widget actually changes size in response to a
.PN XtSetValues ,
its resize procedure is called.
Widgets should do any geometry-related work in their resize procedure.
.LP
Note that it is permissible to call
.PN XtSetValues
before a widget is realized.
Therefore, the set_values proc must not assume that the widget is realized.
.NH 4
Widget State: the set_values_almost Procedure
.XS
\*(SN Widget State: the set_values_almost Procedure
.XE
.LP
The set_values_almost procedure pointer in a widget class is of type
.PN XtAlmostProc :
.IN "set_values_almost procedure" "" "@DEF@"
.IN "XtAlmostProc" "" "@DEF@"
.FD 0
typedef void (*XtAlmostProc)(Widget \fIold\fP, Widget \fInew\fP, \
XtWidgetGeometry* \fIrequest\fP,
                             XtWidgetGeometry* \fIreply\fP);
.FN
.IP \fIold\fP 1i
Specifies a copy of the object as it was before the
.PN XtSetValues
call.
.IP \fInew\fP 1i
Specifies the object instance record.
.IP \fIrequest\fP 1i
Specifies the original geometry request that was sent to the geometry
manager that caused
.PN XtGeometryAlmost
to be returned.
.IP \fIreply\fP 1i
Specifies the compromise geometry that was returned by the geometry
manager with
.PN XtGeometryAlmost .
.LP
Most classes inherit the set_values_almost procedure from their superclass by
specifying 
.PN XtInheritSetValuesAlmost 
in the class initialization.
The 
.PN Core 
set_values_almost procedure accepts the compromise suggested.
.LP
The set_values_almost procedure is called when a client tries to set a widget's
geometry by means of a call to
.PN XtSetValues ,
and the geometry manager cannot
satisfy the request but instead returns
.PN XtGeometryNo
or
.PN XtGeometryAlmost
and a compromise geometry.
The new object is the actual instance record.  The x, y, width, height
and border_width fields contain the original values as they were
before the
.PN XtSetValues
call and all other fields contain the new
values.  The request parameter contains the new geometry request that
was made to the parent.  The reply parameter contains
reply->request_mode equal to zero if the parent returned
.PN XtGeometryNo
and contains the parent's compromise geometry otherwise.  The
set_values_almost procedure takes the original geometry and the 
compromise geometry and determines whether the compromise is acceptable or a
different compromise might work.
It returns its results in the request parameter,
which is then sent back to the geometry manager for another try.
To accept the compromise, the procedure must copy the contents
of the reply geometry into the request geometry; to attempt an
alternate geometry, the procedure may modify any part of the request
argument; to terminate the geometry negotiation and retain the
original geometry, the procedure must set request->request_mode to
zero.  The geometry fields of the new instance must not be modified
directly.

.NH 4
Widget State: the constraint set_values Procedure
.XS
\*(SN Widget State: the constraint set_values Procedure
.XE
.IN "set_values procedure"
.LP
The constraint set_values procedure pointer is of type
.PN XtSetValuesFunc .
The values passed to the parent's constraint set_values procedure
are the same as those passed to the child's class
set_values procedure.
A class can specify NULL for the set_values field of the
.PN ConstraintPart
if it need not compute anything.
.LP
The constraint set_values procedure should recompute any constraint fields
derived from constraint resource that are changed.
Further, it should modify the widget fields as appropriate.
For example, if a constraint for the maximum height of a widget is changed
to a value smaller than the widget's current height,
the constraint set_values procedure should reset the height field in the
widget.
.NH 4
Widget Subpart State
.XS
\*(SN Setting Widget Subpart State
.XE
.LP
To set the current values of nonwidget resources associated with a
widget instance, use
.PN XtSetSubvalues .
For a discussion of nonwidget subclass resources,
see Section 9.4.
.IN "XtSetSubvalues" "" "@DEF@"
.FD 0
void XtSetSubvalues(\fIbase\fP, \fIresources\fP, \fInum_resources\fP, \
\fIargs\fP, \fInum_args\fP)
.br
      XtPointer \fIbase\fP;
.br
      XtResourceList \fIresources\fP;
.br
      Cardinal \fInum_resources\fP;
.br
      ArgList \fIargs\fP;
.br
      Cardinal \fInum_args\fP;
.FN
.IP \fIbase\fP 1i
Specifies the base address of the subpart data structure into which the
resources should be written.
.IP \fIresources\fP 1i
Specifies the nonwidget resource list.
.IP \fInum_resources\fP 1i
Specifies the number of resources in the resource list.
.IP \fIargs\fP 1i
Specifies the argument list of name/value pairs that contain the
resources to be modified and their new values.
The resources and values passed are dependent on
the subpart of the widget being modified.
.IP \fInum_args\fP 1i
Specifies the number of arguments in the argument list.
.LP
The
.PN XtSetSubvalues
function stores resources into the structure identified by base.
.sp
.LP
To set the current values of nonwidget resources associated with
a widget instance using varargs lists, use
.PN XtVaSetSubvalues .
.IN "XtVaSetSubvalues" "" "@DEF@"
.FD 0 
void XtVaSetSubvalues(\fIbase\fP, \fIresources\fP, \fInum_resources\fP, ...)
.br
      XtPointer \fIbase\fP;
.br
      XtResourceList \fIresources\fP;
.br
      Cardinal \fInum_resources\fP;
.FN
.IP \fIbase\fP 1i
Specifies the base address of the subpart data structure into which the
resources should be written.
.IP \fIresources\fP 1i
Specifies the nonwidget resource list.
.IP \fInum_resources\fP 1i
Specifies the number of resources in the resource list.
.IP ... 1i
Specifies the variable-length argument list of name/value pairs that
contain the resources to be modified and their new values.
The resources and values passed are dependent on
the subpart of the widget being modified.
.LP
.PN XtVaSetSubvalues
is identical in function to
.PN XtSetSubvalues
with the args and num_args parameters replaced by a varargs list as
described in Section 2.4.1.
.PN XtVaTypedArg
is not supported for
.PN XtVaSetSubvalues .
If
.PN XtVaTypedArg
is specified in the list a warning message is issued
and the entry is then ignored.

.NH 4
Widget Subpart Resource Data: the set_values_hook Procedure
.XS
\*(SN Widget Subpart Resource Data: the set_values_hook Procedure
.XE
.IN "set_values_hook procedure"
.NT
The set_values_hook procedure is obsolete, as the same information
is now available to the set_values procedure.  The procedure has been
retained for those widgets which used it in versions prior to Release 4.
.NE
.LP
Widgets that have a subpart can set the resource values by using
.PN XtSetValues
and supplying a set_values_hook procedure.
The set_values_hook procedure pointer in a widget class is of type
.PN XtArgsFunc :
.IN "set_values_hook procedure" "" "@DEF@"
.IN "XtArgsFunc" "" "@DEF@"
.FD 0
typedef Boolean (*XtArgsFunc)(Widget, Arglist, Cardinal *);
.br
     Widget \fIw\fP;
.br
     ArgList \fIargs\fP;
.br
     Cardinal *\fInum_args\fP;
.FN
.IP \fIw\fP 1i
Specifies the widget whose nonwidget resource values are to be changed.
.IP \fIargs\fP 1i
Specifies the argument list that was passed to
.PN XtSetValues .
.IP \fInum_args\fP 1i
Specifies the number of arguments in the argument list.
.bp
