Merge remote-tracking branch 'origin/released'

1 files changed, 0 insertions, 3211 deletions

diff --git a/libXt/specs/CH09 b/libXt/specs/CH09
deleted file mode 100644
index 9538651bc..000000000
--- a/libXt/specs/CH09
+++ /dev/null
@@ -1,3211 +0,0 @@
-.\" $Xorg: CH09,v 1.3 2000/08/17 19:42:46 cpqbld Exp $
-.\" Copyright \(co 1985, 1986, 1987, 1988, 1991, 1994
-.\" X Consortium
-.\" 
-.\" Permission is hereby granted, free of charge, to any person obtaining
-.\" a copy of this software and associated documentation files (the
-.\" "Software"), to deal in the Software without restriction, including
-.\" without limitation the rights to use, copy, modify, merge, publish,
-.\" distribute, sublicense, and/or sell copies of the Software, and to
-.\" permit persons to whom the Software is furnished to do so, subject to
-.\" the following conditions:
-.\" 
-.\" The above copyright notice and this permission notice shall be included
-.\" in all copies or substantial portions of the Software.
-.\" 
-.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
-.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
-.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
-.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-.\" OTHER DEALINGS IN THE SOFTWARE.
-.\" 
-.\" Except as contained in this notice, the name of the X Consortium shall
-.\" not be used in advertising or otherwise to promote the sale, use or
-.\" other dealings in this Software without prior written authorization
-.\" from the X Consortium.
-.\" 
-.\" Copyright \(co 1985, 1986, 1987, 1988, 1991, 1994
-.\" Digital Equipment Corporation, Maynard, Massachusetts.
-.\" 
-.\" Permission to use, copy, modify and distribute this documentation for any
-.\" purpose and without fee is hereby granted, provided that the above copyright
-.\" notice appears in all copies and that both that copyright notice and this
-.\" permission notice appear in supporting documentation, and that the name of
-.\" Digital not be used in in advertising or publicity pertaining
-.\" to distribution of the software without specific, written prior permission.
-.\" Digital makes no representations about the suitability of the
-.\" software described herein for any purpose.
-.\" It is provided ``as is'' without express or implied warranty.
-.\"
-\&
-.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 \(em Resource Management
-.XE
-A resource is a field in the widget record with a corresponding
-resource entry in the \fIresources\fP 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 a resource file (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 \fImanaged\fP and \fIbeing_destroyed\fP).
-Others can be for local bookkeeping,
-and still others are derived from resources 
-(many graphics contexts and pixmaps).
-.LP
-Widgets typically 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 by 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 last, 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
-.sM
-.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"
-.eM
-
-.LP
-When the resource list is specified as the
-.PN CoreClassPart ,
-.PN ObjectClassPart ,
-.PN RectObjClassPart ,
-or
-.PN ConstraintClassPart
-\fIresources\fP field, the strings pointed to by \fIresource_name\fP,
-\fIresource_class\fP, \fIresource_type\fP, and \fIdefault_type\fP must
-be permanently allocated prior to or during the execution of the class
-initialization procedure and must not be subsequently deallocated.
-
-.LP
-The \fIresource_name\fP 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 exactly like 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's symbolic resource names begin with
-``XtN''
-and are followed by the string name (for example, XtNbackgroundPixel
-for backgroundPixel).
-
-.LP
-The \fIresource_class\fP field contains the class string used in resource
-specification files to identify the field.
-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 the background ivory
-and everything else darkblue.
-.LP
-In this case, the background pixel should have a resource class of
-``Background''
-and all the other pixel entries a resource class of
-``Foreground''.
-Then, the resource file needs only two lines to
-change all pixels to ivory or darkblue:
-.LP
-.Ds 5
-.TA .5i 1.5i
-.ta .5i 1.5i
-*Background:	ivory
-*Foreground:	darkblue
-.De
-.LP
-Similarly, a widget may have several font resources (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 5
-.TA .5i 3i
-.ta .5i 3i
-*Font:	6x13
-.De
-.LP
-By convention,
-resource classes are always spelled starting with a capital letter
-to distinguish them from resource names.
-Their symbolic names are preceded with
-``XtC''
-(for example, XtCBackground).
-.LP
-The \fIresource_type\fP field gives the physical representation type of the resource
-and also encodes information about the specific usage of the field.
-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
-.PN String )
-or the format of the resource default value
-(almost anything, but often
-.PN String )
-to the desired
-physical representation (see Section 9.6).
-The \*(xI define the following resource types:
-.TS H
-lw(2.5i) lw(2.5i).
-_
-.sp 6p
-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 XtRCommandArgArray
-T}	String*
-T{
-.PN XtRCursor
-T}	Cursor
-T{
-.PN XtRDimension
-T}	Dimension
-T{
-.PN XtRDirectoryString
-T}	String
-T{
-.PN XtRDisplay
-T}	Display*
-T{
-.PN XtREnum
-T}	XtEnum
-T{
-.PN XtREnvironmentArray
-T}	String*
-T{
-.PN XtRFile
-T}	FILE*
-T{
-.PN XtRFloat
-T}	float
-T{
-.PN XtRFont
-T}	Font
-T{
-.PN XtRFontSet
-T}	XFontSet
-T{
-.PN XtRFontStruct
-T}	XFontStruct*
-T{
-.PN XtRFunction
-T}	(*)()
-T{
-.PN XtRGeometry
-T}	T{
-char*, format as defined by
-.PN XParseGeometry
-T}
-T{
-.PN XtRGravity
-T}	int
-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}	XtPointer
-T{
-.PN XtRPosition
-T}	Position
-T{
-.PN XtRRestartStyle
-T}	unsigned char
-T{
-.PN XtRScreen
-T}	Screen*
-T{
-.PN XtRShort
-T}	short
-T{
-.PN XtRSmcConn
-T}	XtPointer
-T{
-.PN XtRString
-T}	String
-T{
-.PN XtRStringArray
-T}	String*
-T{
-.PN XtRStringTable
-T}	String*
-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
-.sp 6p
-_
-.TE
-.sp
-.LP
-.Pn < X11/StringDefs.h >
-also defines the following resource types as a
-convenience for widgets, although they do not have any corresponding
-data type assigned:
-.PN XtREditMode ,
-.PN XtRJustify ,
-and
-.PN XtROrientation .
-.LP
-The \fIresource_size\fP field is the size of the physical representation in bytes;
-you should specify it as
-.PN sizeof (\fItype\fP)
-so that the
-compiler fills in the value.
-The \fIresource_offset\fP field is the offset in bytes of the field 
-within the widget.
-You should use the
-.PN XtOffsetOf
-macro to retrieve this value.
-The \fIdefault_type\fP field is the representation type of the default
-resource value.
-If \fIdefault_type\fP is different from \fIresource_type\fP and the default value
-is needed,
-the resource manager invokes a conversion procedure from \fIdefault_type\fP
-to \fIresource_type\fP.
-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 for which the converter is guaranteed to work (for example, 
-.PN XtDefaultForeground
-for a pixel resource).
-The \fIdefault_addr\fP field specifies the address of the default resource value.
-As a special case, if \fIdefault_type\fP is
-.PN XtRString ,
-then the value in the \fIdefault_addr\fP 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 
-(XtRImmediate
-and
-XtRCallProc)
-are usable only as default resource types.
-XtRImmediate
-indicates that the value in the \fIdefault_addr\fP field is the actual value of
-the resource rather than the address of the value. 
-The value must be in the correct representation type for the resource,
-coerced to an
-.PN XtPointer .
-No conversion is possible, since there is no source representation type.
-XtRCallProc
-indicates that the value in the \fIdefault_addr\fP field is a procedure
-pointer.
-This procedure is automatically invoked with the widget,
-\fIresource_offset\fP, and a pointer to an
-.PN XrmValue
-in which to store the result.
-XtRCallProc
-procedure pointers are of type
-.PN XtResourceDefaultProc .
-.LP
-.sM
-.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 value 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 descriptor to return.
-.LP
-.eM
-The
-.PN XtResourceDefaultProc
-procedure should fill in the \fIvalue->addr\fP field with a pointer 
-to the resource value in its correct representation type.
-.sp
-.LP
-To get the resource list structure for a particular class, use
-.PN XtGetResourceList .
-.LP
-.IN "XtGetResourceList" "" "@DEF@"
-.sM
-.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 \fIclass\fP 1.5i
-Specifies the object class to be queried.  It must 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
-.eM
-If
-.PN XtGetResourceList
-is called before the class is initialized,
-it returns the resource list as specified in the class record.
-If it is called after the 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 .
-.LP
-.IN "XtGetConstraintResourceList" "" "@DEF@"
-.sM
-.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 \fIclass\fP 1.5i
-Specifies the object class to be queried.  It must 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
-.eM
-If
-.PN XtGetConstraintResourceList
-is called before the widget class is
-initialized, the resource list as specified in the widget
-class Constraint part is 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 class is not a subclass of
-.PN constraintWidgetClass ,
-*\fIresources_return\fP is set to NULL
-and *\fInum_resources_return\fP is set to zero.
-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;
-see Sections 9.7.1 and 9.7.2.
-.LP
-Here is an abbreviated version of a possible resource list for a Label widget:
-.LP
-.Ds
-.TA .5i 1.5i 3i
-.ta .5i 1.5i 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 
-top of the widget tree,
-the instance name of the widget itself,
-and the resource name of the specified field of the widget.
-Similarly,
-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 
-top of the widget tree,
-the widget class name of the widget itself,
-and the resource class 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 .
-.LP
-.IN "XtOffsetOf" "" "@DEF@"
-.sM
-.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
-.eM
-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 .
-.LP
-.IN "XtOffset" "" "@DEF@"
-.sM
-.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 a member within the structure.
-.LP
-.eM
-The
-.PN XtOffset
-macro expands to a constant expression that gives the
-offset in bytes to the specified structure member from the beginning
-of the structure.  It may be used to statically initialize
-resource lists.
-.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 chained operation.
-That is, the resources specified in the
-.PN objectClass
-resource list are fetched,
-then those in
-.PN rectObjClass ,
-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
-Core 
-class contains a resource entry for \fIbackground_pixel\fP.
-Consequently,
-the implementation of Label need not also have a resource entry
-for \fIbackground_pixel\fP.
-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.
-If reordering is necessary, 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
-overwrite 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 retrieve 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.
-Such widgets call
-.PN XtGetSubresources
-to accomplish this.
-.LP
-.IN "XtGetSubresources" "" "@DEF@"
-.sM
-.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 object used to qualify the subpart resource name and
-class.  \*(oI
-.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 entries 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 entries in the argument list.
-.LP
-.eM
-The
-.PN XtGetSubresources
-function constructs a name and class list from the application name and class,
-the names and classes of all the object's ancestors, and the object itself.
-Then it appends to this list the \fIname\fP and \fIclass\fP 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 \fIargs\fP is NULL,
-\fInum_args\fP must be zero.
-However, if \fInum_args\fP is zero,
-the argument list is not referenced.
-.LP
-.PN XtGetSubresources
-may overwrite 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 object.  Subresources might
-therefore be freed from the conversion cache and destroyed
-when the object is destroyed, but not before then.
-.sp
-.LP
-To fetch resources for widget subparts using varargs lists, use
-.PN XtVaGetSubresources .
-.LP
-.IN "XtVaGetSubresources" "" "@DEF@"
-.sM
-.FD 0
-void XtVaGetSubresources(\fIw\fP, \fIbase\fP, \fIname\fP, \fIclass\fP, \
-\fIresources\fP, \fInum_resources\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;
-.FN
-.IP \fIw\fP 1i
-Specifies the object used to qualify the subpart resource name and
-class.  \*(oI
-.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 entries in the resource list.
-.IP ... 1i
-Specifies the variable argument list to override any other
-resource specifications.
-.LP
-.eM
-.PN XtVaGetSubresources
-is identical in function to
-.PN XtGetSubresources
-with the \fIargs\fP and \fInum_args\fP parameters replaced by a varargs list, as
-described in Section 2.5.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 .
-.LP
-.IN "XtGetApplicationResources" "" "@DEF@"
-.sM
-.FD 0
-void XtGetApplicationResources(\fIw\fP, \fIbase\fP, \fIresources\fP, \
-\fInum_resources\fP, \fIargs\fP, \fInum_args\fP)
-.br
-      Widget \fIw\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 \fIw\fP 1i
-Specifies the object that identifies the resource database to search
-(the database is that associated with the display for this object).  \*(oI
-.IP \fIbase\fP 1i
-Specifies the base address into which
-the resource values will be written.
-.IP \fIresources\fP 1i
-Specifies the resource list.
-.IP \fInum_resources\fP 1i
-Specifies the number of entries 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 entries in the argument list.
-.LP
-.eM
-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 added to the
-front of 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 addresses
-obtained by adding \fIbase\fP to each \fIoffset\fP in the resource list.
-If \fIargs\fP is NULL,
-\fInum_args\fP must be zero.
-However, if \fInum_args\fP 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 \fIbase\fP argument.
-.LP
-.PN XtGetApplicationResources
-may overwrite 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.  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 .
-.LP
-.IN "XtVaGetApplicationResources" "" "@DEF@"
-.sM
-.FD 0
-void XtVaGetApplicationResources(\fIw\fP, \fIbase\fP, \fIresources\fP, \
-\fInum_resources\fP, ...)
-.br
-      Widget \fIw\fP;
-.br
-      XtPointer \fIbase\fP;
-.br
-      XtResourceList \fIresources\fP;
-.br
-      Cardinal \fInum_resources\fP;
-.FN
-.IP \fIw\fP 1i
-Specifies the object that identifies the resource database to search
-(the database is that associated with the display for this object).  \*(oI
-.IP \fIbase\fP 1i
-Specifies the base address into which
-the resource values will be written.
-.IP \fIresources\fP 1i
-Specifies the resource list for the subpart.
-.IP \fInum_resources\fP 1i
-Specifies the number of entries in the resource list.
-.IP ... 1i
-Specifies the variable argument list to override any other
-resource specifications.
-.LP
-.eM
-.PN XtVaGetApplicationResources
-is identical in function to
-.PN XtGetApplicationResources
-with the \fIargs\fP and \fInum_args\fP parameters
-replaced by a varargs list, as described in Section 2.5.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 register several commonly used converters.
-This resource conversion mechanism serves several purposes:
-.IP \(bu 5
-It permits user and application resource files to contain textual
-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 colormap, and thus must be
-computed at runtime.
-.IP \(bu 5
-It caches 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 string-to-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 
-Object,
-RectObj,
-Core, 
-Composite, 
-Constraint, 
-and 
-Shell 
-widget classes.
-The \*(xI register the following resource converters that accept
-input values of representation type
-.PN XtRString .
-.LP
-.TS
-lw(1.7i) lw(2.4i) lw(1.5i) .
-_
-.sp 6p
-Target Representation	Converter Name	Additional Args
-.sp 6p
-_
-.sp 6p
-T{
-.PN XtRAcceleratorTable
-T}	T{
-.PN XtCvtStringToAcceleratorTable
-T}
-T{
-.PN XtRAtom
-T}	T{
-.PN XtCvtStringToAtom
-T}	Display*
-T{
-.PN XtRBoolean
-T}	T{
-.PN XtCvtStringToBoolean
-T}
-T{
-.PN XtRBool
-T}	T{
-.PN XtCvtStringToBool
-T}
-T{
-.PN XtRCommandArgArray
-T}	T{
-.PN XtCvtStringToCommandArgArray
-T}
-T{
-.PN XtRCursor
-T}	T{
-.PN XtCvtStringToCursor
-T}	Display*
-T{
-.PN XtRDimension
-T}	T{
-.PN XtCvtStringToDimension
-T}
-T{
-.PN XtRDirectoryString
-T}	T{
-.PN XtCvtStringToDirectoryString
-T}
-T{
-.PN XtRDisplay
-T}	T{
-.PN XtCvtStringToDisplay
-T}
-T{
-.PN XtRFile
-T}	T{
-.PN XtCvtStringToFile
-T}
-T{
-.PN XtRFloat
-T}	T{
-.PN XtCvtStringToFloat
-T}
-T{
-.PN XtRFont
-T}	T{
-.PN XtCvtStringToFont
-T}	Display*
-T{
-.PN XtRFontSet
-T}	T{
-.PN XtCvtStringToFontSet
-T}	Display*, String \fIlocale\fP
-T{
-.PN XtRFontStruct
-T}	T{
-.PN XtCvtStringToFontStruct
-T}	Display*
-T{
-.PN XtRGravity
-T}	T{
-.PN XtCvtStringToGravity
-T}
-T{
-.PN XtRInitialState
-T}	T{
-.PN XtCvtStringToInitialState
-T}
-T{
-.PN XtRInt
-T}	T{
-.PN XtCvtStringToInt
-T}
-T{
-.PN XtRPixel
-T}	T{
-.PN XtCvtStringToPixel
-T}	T{
-.PN colorConvertArgs
-T}
-T{
-.PN XtRPosition
-T}	T{
-.PN XtCvtStringToPosition
-T}
-T{
-.PN XtRRestartStyle
-T}	T{
-.PN XtCvtStringToRestartStyle
-T}
-T{
-.PN XtRShort
-T}	T{
-.PN XtCvtStringToShort
-T}
-T{
-.PN XtRTranslationTable
-T}	T{
-.PN XtCvtStringToTranslationTable
-T}
-T{
-.PN XtRUnsignedChar
-T}	T{
-.PN XtCvtStringToUnsignedChar
-T}
-T{
-.PN XtRVisual
-T}	T{
-.PN XtCvtStringToVisual
-T}	Screen*, Cardinal \fIdepth\fP
-.sp 6p
-_
-.TE
-
-.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 to the black and white pixel values of the widget's screen, 
-respectively.
-.IN "Resources" "reverseVideo"
-If the application resource reverseVideo is
-.PN True ,
-they evaluate to the white and black pixel values of the widget's screen,
-respectively.
-Similarly, the String-to-Font and String-to-FontStruct 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 a warning message
-and return
-.PN False .
-.LP
-The String-to-FontSet converter recognizes the constant
-.PN XtDefaultFontSet
-.IN "XtDefaultFontSet" "" "@DEF@"
-.IN "Resources" "xtDefaultFontSet"
-and evaluate this in the following manner:
-.IP \(bu 5
-Query the resource database for the resource whose full name
-is ``xtDefaultFontSet'', class ``XtDefaultFontSet'' (that is, no widget
-name/class prefixes), and use a type
-.PN XtRString
-value returned as the base font name list or a type
-.PN XtRFontSet
-value directly as the resource value.
-.IP \(bu 5
-If the resource database does not contain a value for xtDefaultFontSet,
-class XtDefaultFontSet, or if a font set cannot be
-successfully created from this resource,
-an implementation-defined font set is created.
-(One possible algorithm is to
-perform an
-.PN XCreateFontSet
-using a wildcard base font name.
-This wildcard base font name should be as broad as
-possible to maximize the probability of locating a useable font;
-for example, "-*-*-*-R-*-*-*-120-*-*-*-*".)
-.IP \(bu 5
-If no suitable font set can be created, issue a warning message
-and return
-.PN False .
-.LP
-If a font set is created but \fImissing_charset_list\fP is not
-empty, a warning is issued and the partial font set is returned.
-The \*(xI register the String-to-FontSet converter with
-a conversion argument list that extracts the current process
-locale at the time the converter is invoked.   This ensures
-that the converter is invoked again if the same conversion
-is required in a different locale.
-.LP
-The String-to-Gravity conversion accepts string values that are the
-names of window and bit gravities and their numerical equivalents,
-as defined in \fI\*(xL\fP:
-.PN ForgetGravity ,
-.PN UnmapGravity ,
-.PN NorthWestGravity ,
-.PN NorthGravity ,
-.PN NorthEastGravity ,
-.PN WestGravity ,
-.PN CenterGravity ,
-.PN EastGravity ,
-.PN SouthWestGravity ,
-.PN SouthGravity , 
-.PN SouthEastGravity , 
-and
-.PN StaticGravity .
-Alphabetic case is not significant in the conversion.
-.LP
-The String-to-CommandArgArray conversion parses a String into an
-array of strings.
-White space characters separate elements of the command line.
-The converter recognizes the backslash character ``\\'' as an escape
-character to allow the following white space character to be part of the
-array element.
-.LP
-.IN "XtCurrentDirectory" "" "@DEF@"
-The String-to-DirectoryString conversion recognizes the
-string ``XtCurrentDirectory'' and returns the result of a call
-to the operating system to get the current directory.
-.LP
-The String-to-RestartStyle conversion accepts the values 
-.PN RestartIfRunning ,
-.PN RestartAnyway ,
-.PN RestartImmediately ,
-and
-.PN RestartNever
-as defined by the \fIX Session Management Protocol\fP.
-.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
-\fIscreen\fP and \fIdepth\fP fields from the 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 visual class names defined in \fI\*(xP\fP,
-Section 8;
-.PN StaticGray ,
-.PN StaticColor ,
-.PN TrueColor ,
-.PN GrayScale ,
-.PN PseudoColor ,
-and
-.PN DirectColor .
-
-.LP
-The \*(xI register the following resource converter that accepts
-an input value of representation type
-.PN XtRColor .
-.LP
-.TS
-lw(1.5i) lw(2.25i) lw(1.5i) .
-_
-.sp 6p
-Target Representation	Converter Name	Additional Args
-.sp 6p
-_
-.sp 6p
-T{
-.PN XtRPixel
-T}	T{
-.PN XtCvtColorToPixel
-T}
-.sp 6p
-_
-.TE
-
-.LP
-The \*(xI register the following resource converters that accept
-input values of representation type
-.PN XtRInt .
-.LP
-.TS
-lw(1.5i) lw(2.25i) lw(1.5i) .
-_
-.sp 6p
-Target Representation	Converter Name	Additional Args
-.sp 6p
-_
-.sp 6p
-T{
-.PN XtRBoolean
-T}	T{
-.PN XtCvtIntToBoolean
-T}
-T{
-.PN XtRBool
-T}	T{
-.PN XtCvtIntToBool
-T}
-T{
-.PN XtRColor
-T}	T{
-.PN XtCvtIntToColor
-T}	T{
-.PN colorConvertArgs
-T}
-T{
-.PN XtRDimension
-T}	T{
-.PN XtCvtIntToDimension
-T}
-T{
-.PN XtRFloat
-T}	T{
-.PN XtCvtIntToFloat
-T}
-T{
-.PN XtRFont
-T}	T{
-.PN XtCvtIntToFont
-T}
-T{
-.PN XtRPixel
-T}	T{
-.PN XtCvtIntToPixel
-T}
-T{
-.PN XtRPixmap
-T}	T{
-.PN XtCvtIntToPixmap
-T}
-T{
-.PN XtRPosition
-T}	T{
-.PN XtCvtIntToPosition
-T}
-T{
-.PN XtRShort
-T}	T{
-.PN XtCvtIntToShort
-T}
-T{
-.PN XtRUnsignedChar
-T}	T{
-.PN XtCvtIntToUnsignedChar
-T}
-.sp 6p
-_
-.TE
-
-.LP
-The \*(xI register the following resource converter that accepts
-an input value of representation type
-.PN XtRPixel .
-.LP
-.TS
-lw(1.5i) lw(2.25i) lw(1.5i) .
-_
-.sp 6p
-Target Representation	Converter Name	Additional Args
-.sp 6p
-_
-.sp 6p
-T{
-.PN XtRColor
-T}	T{
-.PN XtCvtPixelToColor
-T}
-.sp 6p
-_
-.TE
-
-.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 Section 15.4 in \fI\*(xL\fP)
-for input and output values.
-.LP
-.sM
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-typedef struct {
-	unsigned int size;
-	XPointer addr;
-} XrmValue, *XrmValuePtr;
-.De
-.LP
-.eM
-The \fIaddr\fP field specifies the address of the data, and the \fIsize\fP
-field gives the total number of significant bytes in the data.
-For values of type
-.PN String ,
-\fIaddr\fP is the address of the first character and \fIsize\fP
-includes the NULL-terminating byte. 
-.LP
-A resource converter procedure pointer is of type
-.PN XtTypeConverter .
-.LP
-.IN "XtTypeConverter" "" "@DEF@"
-.sM
-.FD 0
-typedef Boolean (*XtTypeConverter)(Display*, XrmValue*, Cardinal*,
-                              XrmValue*, XrmValue*, XtPointer*);
-.br
-      Display *\fIdisplay\fP;
-.br
-      XrmValue *\fIargs\fP;
-.br
-      Cardinal *\fInum_args\fP;
-.br
-      XrmValue *\fIfrom\fP;
-.br
-      XrmValue *\fIto\fP;
-.br
-      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 \fIdisplay\fP,
-and the String-to-Pixel converter needs the widget's \fIscreen\fP and \fIcolormap\fP.
-.IP \fInum_args\fP 1i
-Specifies the number of entries in \fIargs\fP.
-.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 associated
-with this conversion.
-.LP
-.eM
-The \fIdisplay\fP argument is normally used only when generating error
-messages, to identify the application context (with the function
-.PN XtDisplayToApplicationContext ).
-.LP
-The \fIto\fP argument specifies the size and location into which the
-converter should store the converted value.  If the \fIaddr\fP field is NULL,
-the converter should allocate appropriate storage and store the size
-and location into the \fIto\fP 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
-\fIaddr\fP field is not NULL, the converter must check the \fIsize\fP field to
-ensure that sufficient space has been allocated before storing the
-converted value.  If insufficient space is specified, the converter
-should update the \fIsize\fP 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 \fIsize\fP 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 in the location specified
-in \fIconverter_data\fP; this value 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 because of 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 \fIfrom\fP
-argument and return data by writing into the location specified in
-the \fIto\fP argument.
-A few need other information, which is available in \fIargs\fP.
-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 \fIto->addr\fP, 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.
-If the converter modifies the resource database,
-the changes affect any in-progress widget creation,
-.PN XtGetApplicationResources ,
-or
-.PN XtGetSubresources
-in an implementation-defined manner; however, insertion of new entries
-or changes to existing entries is allowed and will not directly cause
-an error.
-
-.LP
-The following is an example of a converter that takes a
-.PN string
-and converts it to a
-.PN Pixel .
-Note that the \fIdisplay\fP parameter is
-used only to generate error messages; the
-.PN 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 = (XPointer)&static_val;	\\
-		}					\\
-		toVal->size = sizeof(type);	\\
-		return True;			\\
-	}
-
-static Boolean CvtStringToPixel(dpy, 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;
-
-	if (*num_args != 2)
-		XtAppWarningMsg(XtDisplayToApplicationContext(dpy),
-			"wrongParameters", "cvtStringToPixel", "XtToolkitError",
-			"String to pixel conversion needs screen and colormap arguments",
-			(String *)NULL, (Cardinal *)NULL);
-
-	screen = *((Screen**) args[0].addr);
-	colormap = *((Colormap *) args[1].addr);
-
-	if (CompareISOLatin1(str, XtDefaultBackground) == 0) {
-		*closure_ret = False;
-		done(Pixel, WhitePixelOfScreen(screen));
-	}
-	if (CompareISOLatin1(str, XtDefaultForeground) == 0) {
-		*closure_ret = False;
-		done(Pixel, BlackPixelOfScreen(screen));
-	}
-
-
-	status = XAllocNamedColor(DisplayOfScreen(screen), colormap, (char*)fromVal->addr, 
-				               &screenColor, &exactColor);
-
-	if (status == 0) {
-		String params[1];
-		Cardinal num_params = 1;
-		params[0] = (String)fromVal->addr;
-		XtAppWarningMsg(XtDisplayToApplicationContext(dpy),
-			"noColormap", "cvtStringToPixel", "XtToolkitError",
-			"Cannot allocate colormap entry for \\"%s\\"", params,\
- &num_params);
-	        *converter_data = (char *) False;
-                return False;
-	} else {
-                *converter_data = (char *) True;
-		done(Pixel, &screenColor.pixel);
-	}
-}
-.De
-.LP
-All type converters should define some set of conversion values for which they
-are guaranteed to succeed 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
-in the same manner as
-.PN XtDefaultForeground ,
-.PN XtDefaultBackground ,
-and
-.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 .
-.LP
-.IN "XtDestructor" "" "@DEF@"
-.sM
-.FD 0
-typedef void (*XtDestructor) (XtAppContext, XrmValue*, XtPointer, XrmValue*, \
-Cardinal*);
-.br
-      XtAppContext \fIapp\fP;
-.br
-      XrmValue *\fIto\fP;
-.br
-      XtPointer \fIconverter_data\fP;
-.br
-      XrmValue *\fIargs\fP;
-.br
-      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-specific 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 entries in \fIargs\fP.
-.LP
-.eM
-The destructor procedure is responsible for freeing the resource
-specified by the \fIto\fP argument, including any auxiliary storage
-associated with that resource, but not the memory directly addressed
-by the size and location in the \fIto\fP argument or the memory specified
-by \fIargs\fP.
-
-.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.
-.LP
-.IN "XtDisplayStringConversionWarning" "" "@DEF@"
-.sM
-.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
-.eM
-The
-.PN XtDisplayStringConversionWarning
-procedure issues a warning message using
-.PN XtAppWarningMsg
-with \fIname\fP ``conversionError'',
-\fItype\fP ``string'', \fIclass\fP ``XtToolkitError'', and the default message
-``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 given
-display connection, use
-.PN XtDisplayToApplicationContext .
-.LP
-.IN "XtDisplayToApplicationContext" "" "@DEF@"
-.sM
-.FD 0
-XtAppContext XtDisplayToApplicationContext( \fIdisplay\fP )
-.br
-      Display *\fIdisplay\fP;
-.FN
-.IP \fIdisplay\fP 1i
-Specifies an open and initialized display connection.
-.LP
-.eM
-The
-.PN XtDisplayToApplicationContext
-function returns the application
-context in which the specified \fIdisplay\fP 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
-.LP
-.IN "XtCacheType" "" "@DEF@"
-argument.
-.sM
-.Ds 0
-typedef int XtCacheType;
-.De
-.LP
-.eM
-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 connection 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 above values.  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 .
-.LP
-.IN "XtSetTypeConverter" "" "@DEF@"
-.sM
-.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;
-.br
-      String \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
-.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 number of entries in \fIconvert_args\fP.
-.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 the converter.
-.LP
-.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
-      XtTypeConverter \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 number of entries in \fIconvert_args\fP.
-.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 the converter.
-.LP
-.eM
-.PN XtSetTypeConverter
-registers the specified type converter and
-destructor in all application contexts created by the calling process,
-including any future application contexts that may be created.
-.PN XtAppSetTypeConverter
-registers the specified type converter in the
-single application context specified.  If the same \fIfrom_type\fP and
-\fIto_type\fP 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/Intrinsic.h >.
-.LP
-.sM
-.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;
-.sp
-typedef struct {
-	XtAddressMode address_mode;
-	XtPointer address_id;
-	Cardinal size;
-} XtConvertArgRec, *XtConvertArgList;
-.De
-.eM
-.LP
-The \fIsize\fP field specifies the length of the data in bytes.
-The \fIaddress_mode\fP field specifies how the \fIaddress_id\fP field should be
-interpreted.
-.PN XtAddress
-.IN "XtAddress" "" "@DEF@"
-causes \fIaddress_id\fP to be interpreted as the address of the data.
-.PN XtBaseOffset
-.IN "XtBaseOffset" "" "@DEF@"
-causes \fIaddress_id\fP to be interpreted as the offset from the widget base.
-.PN XtImmediate
-.IN "XtImmediate" "" "@DEF@"
-causes \fIaddress_id\fP to be interpreted as a constant.
-.PN XtResourceString
-.IN "XtResourceString" "" "@DEF@"
-causes \fIaddress_id\fP to be interpreted as the name of a resource
-that is to be converted into an offset from the widget base.
-.PN XtResourceQuark
-.IN "XtResourceQuark" "" "@DEF@"
-causes \fIaddress_id\fP 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
-of a subclass of
-Core
-(see Chapter 12).
-.PN XtProcedureArg
-.IN "XtProcedureArg" "" "@DEF@"
-specifies that \fIaddress_id\fP is a pointer to a procedure to
-be invoked to return the conversion argument.  If
-.PN XtProcedureArg
-is specified, \fIaddress_id\fP must contain
-the address of a function of type
-.PN XtConvertArgProc .
-.LP
-.IN "XtConvertArgProc" "" "@DEF@"
-.sM
-.FD 0
-typedef void (*XtConvertArgProc)(Widget, Cardinal*, XrmValue*);
-.br
-      Widget \fIobject\fP;
-.br
-      Cardinal *\fIsize\fP;
-.br
-      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 \fIsize\fP 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
-.eM
-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 \fIvalue\fP.
-.LP
-In order to permit reentrancy, the
-.PN XtConvertArgProc
-should return the address of storage whose lifetime is no shorter than the
-lifetime of \fIobject\fP.  If \fIobject\fP 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 not to 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), XtCacheByDisplay, NULL);
-.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
-Core.
-The
-.PN screenConvertArg
-descriptor puts the widget's \fIscreen\fP field into \fIargs\fP[0].  The
-.PN colorConvertArgs
-descriptor puts the widget's \fIscreen\fP field into \fIargs\fP[0],
-and the widget's \fIcolormap\fP field into \fIargs\fP[1].
-.LP
-Conversion routines should not just put a descriptor for the address of the
-base of the widget into \fIargs\fP[0], and use that in the routine.
-They should pass in the actual values on which the conversion depends.
-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.
-.LP
-If the
-.PN XtConvertArgProc
-modifies the resource database,
-the changes affect any in-progress widget creation,
-.PN XtGetApplicationResources ,
-or
-.PN XtGetSubresources
-in an implementation-defined manner; however, insertion of new entries
-or changes to existing entries are allowed and will not directly cause
-an error.
-
-.NH 3
-Resource Converter Invocation
-.XS
-\fB\*(SN Resource Converter Invocation\fP
-.XE
-.LP
-All resource-fetching routines (for example,
-.PN XtGetSubresources ,
-.PN XtGetApplicationResources ,
-and so on) call resource converters if the resource database or
-varargs list specifies a value
-that has 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 .
-.LP
-.sM
-.Ds 0
-typedef XtPointer XtCacheRef;
-.De
-.IN "XtCallConverter" "" "@DEF@"
-.FD 0
-Boolean XtCallConverter(\fIdisplay\fP, \fIconverter\fP, \
-\fIconversion_args\fP, \fInum_args\fP, \fIfrom\fP, \fIto_in_out\fP,
-                                              \fIcache_ref_return\fP)
-.br
-      Display* \fIdisplay\fP;
-.br
-      XtTypeConverter \fIconverter\fP;
-.br
-      XrmValuePtr \fIconversion_args\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 1.5i
-Specifies the display with which the conversion is to be associated.
-.IP \fIconverter\fP 1.5i
-Specifies the conversion procedure to be called.
-.IP \fIconversion_args\fP 1.5i
-Specifies the additional conversion arguments needed
-to perform the conversion, or NULL.
-.IP \fInum_args\fP 1.5i
-Specifies the number of entries in \fIconversion_args\fP.
-.IP \fIfrom\fP 1.5i
-Specifies a descriptor for the source value.
-.IP \fIto_in_out\fP 1.5i
-Returns the converted value.
-.IP \fIcache_ref_return\fP 1.5i
-Returns a conversion cache id.
-.LP
-.eM
-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 conversion 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 \fIto\fP 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
-\fIto->addr\fP, stores the cache size into \fIto->size\fP, and returns
-.PN True .
-If the size specified in the \fIto\fP argument is smaller than the size stored
-in the cache,
-.PN XtCallConverter
-copies the cache size into \fIto->size\fP 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
-The \fIcache_ref_return\fP field 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 \fIcache_ref_return\fP is non-NULL, then the caller should store the
-\fIcache_ref_return\fP value in order to decrement the reference count when
-the converted value is no longer required.  The \fIcache_ref_return\fP
-argument should be
-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 .
-.LP
-.IN "XtAppReleaseCacheRefs" "" "@DEF@"
-.sM
-.FD 0
-void XtAppReleaseCacheRefs(\fIapp_context\fP, \fIrefs\fP)
-.br
-      XtAppContext \fIapp_context\fP;
-.br
-      XtCacheRef *\fIrefs\fP;
-.FN
-.IP \fIapp_context\fP 1i
-Specifies the application context.
-.IP \fIrefs\fP 1i
-Specifies the list of cache references to be released.
-.LP
-.eM
-.PN XtAppReleaseCacheRefs
-decrements the reference count for the
-conversion entries identified by the \fIrefs\fP argument.
-This argument 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 .
-.LP
-.IN "XtCallbackReleaseCacheRef" "" "@DEF@"
-.sM
-.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
-.eM
-This callback procedure may be added to a callback list to release a
-previously returned
-.PN XtCacheRef
-value.  When adding the callback, the
-callback \fIclient_data\fP argument must be specified as the value of the
-.PN XtCacheRef
-data cast to type
-.PN XtPointer .
-.LP
-.IN "XtCallbackReleaseCacheRefList" "" "@DEF@"
-.sM
-.FD 0
-void XtCallbackReleaseCacheRefList(\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 resources are associated.
-.IP \fIclient_data\fP 1i
-Specifies the conversion cache entries to be released.
-.IP \fIcall_data\fP 1i
-Is ignored.
-.LP
-.eM
-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 \fIclient_data\fP 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 .
-.LP
-.IN "XtConvertAndStore" "" "@DEF@"
-.sM
-.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.  \*(oI
-.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
-.eM
-The
-.PN XtConvertAndStore
-function looks up the type converter registered
-to convert \fIfrom_type\fP to \fIto_type\fP, 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 \fIfrom\fP and \fIto_in_out\fP arguments.  The
-\fIto_in_out\fP 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.
-The \fIsize\fP field will be modified on return to indicate the actual
-size of the converted data.
-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 object if the conversion
-returns an
-.PN XtCacheRef
-value.  The resulting resource should not be referenced
-after the object has been destroyed.
-.LP
-.PN XtCreateWidget
-performs processing equivalent to
-.PN XtConvertAndStore
-when initializing the object instance.  Because there is extra memory
-overhead required to implement reference counting, clients may
-distinguish those objects that are never destroyed before the
-application exits from those that may be destroyed and whose
-resources should be deallocated.
-.LP
-To specify whether reference counting is to be enabled for the
-resources of a particular object when the object is created, the
-client can specify a value for the
-.PN Boolean
-resource
-XtNinitialResourcesPersistent,
-.IN "XtNinitialResourcesPersistent" "" "@DEF@"
-class
-XtCInitialResourcesPersistent.
-.LP
-When
-.PN XtCreateWidget
-is called, if this resource is not specified as
-.PN False
-in either the arglist or the resource database, then the
-resources referenced by this object are not reference-counted, regardless of
-how the type converter may have been registered.  The effective
-default value is
-.PN True ;
-thus clients that expect to destroy one or
-more objects and want resources deallocated must explicitly specify
-.PN False
-for
-.IN XtNinitialResourcesPersistent
-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 .
-.LP
-.IN "XtGetValues" "" "@DEF@"
-.sM
-.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.  \*(oI
-.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 entries in the argument list.
-.LP
-.eM
-The
-.PN XtGetValues
-function starts with the resources specified for the Object class
-and proceeds down the subclass chain to the class of the object.
-The \fIvalue\fP field of a passed argument list must contain the
-address into which to copy the contents of the corresponding
-object instance field.  If the field is a pointer type, the lifetime
-of the pointed-to data is defined by the object class.  For the
-\*(xI-defined resources, the following lifetimes apply:
-.IP \(bu 3
-Not valid following any operation that modifies the resource:
-.RS
-.IP \- 3
-XtNchildren resource of composite widgets.
-.IP \- 3
-All resources of representation type XtRCallback.
-.RE
-.IP \(bu 3
-Remain valid at least until the widget is destroyed:
-.RS
-.IP \- 3
-XtNaccelerators, XtNtranslations.
-.RE
-.IP \(bu 3
-Remain valid until the Display is closed:
-.RS
-.IP \- 3
-XtNscreen.
-.RE
-.LP
-It is the caller's responsibility
-to allocate and deallocate storage for the copied data
-according to the size of the
-resource representation type used within the object.
-.LP
-If the class of the object'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 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
-object'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 object'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 \fIextension\fP field with a record type of
-.PN \s-1NULLQUARK\s+1 ,
-and if the \fIget_values_hook\fP field in the extension record is non-NULL,
-.PN XtGetValues
-calls the get_values_hook procedures in superclass-to-subclass order.
-This permits a Constraint parent to provide
-nonresource data via
-.PN XtGetValues .
-.LP
-Get_values_hook procedures may modify the data stored at the
-location addressed by the \fIvalue\fP field, including (but not
-limited to) making a copy of data whose resource representation is a
-pointer.  None of the \*(xI-defined object classes copy
-data in this manner.  Any operation that modifies the queried
-object resource may invalidate the pointed-to data.
-
-.sp
-.LP
-To retrieve the current values of resources associated with a widget
-instance using varargs lists, use
-.PN XtVaGetValues .
-.LP
-.IN "XtVaGetValues" "" "@DEF@"
-.sM
-.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.  \*(oI
-.IP ... 1i
-Specifies the variable argument list for the resources to
-be returned.
-.LP
-.eM
-.PN XtVaGetValues
-is identical in function to
-.PN XtGetValues
-with the \fIargs\fP
-and \fInum_args\fP parameters replaced by a varargs list, as described in
-Section 2.5.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 \fItype\fP argument
-specifies the representation desired by the caller and \fIthe\fP size argument
-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 through
-.PN XtGetValues
-by supplying a get_values_hook procedure.
-The get_values_hook procedure pointer is of type
-.PN XtArgsProc .
-.LP
-.IN "get_values_hook procedure" "" "@DEF@"
-.sM
-.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 subpart resource values are to be retrieved.
-.IP \fIargs\fP 1i
-Specifies the argument list that was passed to
-.PN XtGetValues
-or the transformed varargs list passed to
-.PN XtVaGetValues .
-.IP \fInum_args\fP 1i
-Specifies the number of entries in the argument list.
-.LP
-.eM
-The widget with subpart resources should call
-.PN XtGetSubvalues
-in the get_values_hook procedure
-and pass in its subresource list and the \fIargs\fP and \fInum_args\fP parameters.
-
-.NH 4
-Widget Subpart State
-.XS
-\*(SN Widget Subpart State
-.XE
-.LP
-To retrieve the current values of subpart resource data associated with a
-widget instance, use
-.PN XtGetSubvalues .
-For a discussion of subpart resources,
-see Section 9.4.
-.LP
-.IN "XtGetSubvalues" "" "@DEF@"
-.sM
-.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 subpart resource list.
-.IP \fInum_resources\fP 1i
-Specifies the number of entries 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.
-.IP \fInum_args\fP 1i
-Specifies the number of entries in the argument list.
-.LP
-.eM
-The
-.PN XtGetSubvalues
-function obtains resource values from the structure identified by \fIbase\fP.
-The \fIvalue\fP field in each argument entry must 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 subpart.
-If the argument list contains a resource name that is not found in the
-resource list, the value at the corresponding address is not modified.
-
-.sp
-.LP
-To retrieve the current values of subpart resources associated with
-a widget instance using varargs lists, use
-.PN XtVaGetSubvalues .
-.LP
-.IN "XtVaGetSubvalues" "" "@DEF@"
-.sM
-.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 subpart resource list.
-.IP \fInum_resources\fP 1i
-Specifies the number of entries in the resource list.
-.IP ... 1i
-Specifies a variable argument list of name/address pairs that
-contain the resource names and the addresses into which the resource
-values are to be stored.
-.LP
-.eM
-.PN XtVaGetSubvalues
-is identical in function to
-.PN XtGetSubvalues
-with the
-\fIargs\fP and \fInum_args\fP parameters replaced by a varargs list, as described
-in Section 2.5.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 .
-.LP
-.IN "XtSetValues" "" "@DEF@"
-.sM
-.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.  \*(oI
-.IP \fIargs\fP 1i
-Specifies the argument list of name/value pairs that contain the
-resources to be modified and their new values.
-.IP \fInum_args\fP 1i
-Specifies the number of entries in the argument list.
-.LP
-.eM
-The
-.PN XtSetValues
-function starts with the resources specified for the 
-Object
-class fields and proceeds down the subclass chain to the object.
-At each stage, it replaces the \fIobject\fP resource fields with any values
-specified in the argument list.
-.PN XtSetValues
-then calls the set_values procedures for the object in superclass-to-subclass 
-order.
-.IN "set_values_hook procedure"
-If the object has any non-NULL \fIset_values_hook\fP fields,
-these are called immediately after the
-corresponding set_values procedure.
-This procedure permits subclasses to set subpart data via
-.PN XtSetValues .
-.LP
-If the class of the object's parent is a subclass of
-.PN constraintWidgetClass ,
-.PN XtSetValues
-also updates the object'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 replaces the constraint resource fields with any
-values specified in the argument list.
-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 records,
-so that they can make adjustments to the desired values based
-on full information about the widget.  Any arguments specified that
-do not match a resource list entry are silently ignored.
-.LP
-If the object is of a subclass of
-RectObj,
-.PN XtSetValues
-determines if a geometry request is needed by comparing the old object to
-the new object.
-If any geometry changes are required,
-.PN XtSetValues
-restores the original geometry and makes the request on behalf of the widget.
-If the geometry manager returns
-.PN XtGeometryYes ,
-.PN XtSetValues
-calls the object's resize procedure.
-If the geometry manager returns
-.PN XtGeometryDone ,
-.PN XtSetValues
-continues, as the object's resize procedure should have been called
-by the geometry manager.
-If the geometry manager returns
-.PN XtGeometryNo ,
-.PN XtSetValues
-ignores the geometry request and continues.
-If the geometry manager returns
-.PN XtGeometryAlmost ,
-.PN XtSetValues
-calls the set_values_almost procedure,
-which determines what should be done.
-.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 ,
-and the widget is realized,
-.PN XtSetValues
-causes the widget's expose procedure to be invoked by calling
-.PN XClearArea
-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 .
-.LP
-.IN "XtVaSetValues" "" "@DEF@"
-.sM
-.FD 0
-void XtVaSetValues(\fIobject\fP, ...)
-.br
-      Widget \fIobject\fP;
-.FN
-.IP \fIobject\fP 1i
-Specifies the object whose resources are to be modified.  \*(oI
-.IP ... 1i
-Specifies the variable argument list of name/value pairs that
-contain the resources to be modified and their new values.
-.LP
-.eM
-.PN XtVaSetValues
-is identical in function to
-.PN XtSetValues
-with the \fIargs\fP and \fInum_args\fP parameters replaced by a varargs list, as
-described in Section 2.5.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 .
-.LP
-.IN "XtSetValuesFunc" "" "@DEF@"
-.IN "set_values procedure" "" "@DEF@"
-.sM
-.FD 0
-typedef Boolean (*XtSetValuesFunc)(Widget, Widget, Widget, ArgList, Cardinal*);
-.br
-      Widget \fIcurrent\fP;
-.br
-      Widget \fIrequest\fP;
-.br
-      Widget \fInew\fP;
-.br
-      ArgList \fIargs\fP;
-.br
-      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
-or the transformed argument list passed to
-.PN XtVaSetValues .
-.IP \fInum_args\fP 1i
-Specifies the number of entries in the argument list.
-.LP
-.eM
-The set_values procedure should recompute any field
-derived from resources that are changed
-(for example, many GCs depend on foreground and background pixels).
-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 \fIset_values\fP 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 \fIrequest\fP and \fInew\fP parameters provide the necessary information.
-The \fIrequest\fP widget is a copy of the widget, updated as originally requested.
-The \fInew\fP widget starts with the values in the request,
-but it has additionally 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.
-The set_values procedure need not refer to the \fIrequest\fP widget
-unless it must resolve conflicts between the \fIcurrent\fP and \fInew\fP widgets.
-Any changes the widget needs to make, including geometry changes,
-should be made in the \fInew\fP widget.
-.LP
-In the above example,
-the subclass with the visual surround can see
-if the \fIwidth\fP and \fIheight\fP in the \fIrequest\fP widget are zero.
-If so,
-it adds its surround size to the \fIwidth\fP and
-\fIheight\fP fields in the \fInew\fP widget.
-If not, it must make do with the size originally specified.
-In this case, zero is a special value defined by the class to permit
-the application to invoke this behavior.
-.LP
-The \fInew\fP widget is the actual widget instance record.
-Therefore,
-the set_values procedure should do all its work on the \fInew\fP widget;
-the \fIrequest\fP widget should never be modified.
-If the set_values procedure needs to call any routines that operate on
-a widget, it should specify \fInew\fP as the widget instance.
-.LP
-Before calling the set_values procedures, the \*(xI modify the
-resources of the \fIrequest\fP 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 \fIargs\fP.
-.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
-.PN XClearArea
-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
-call to
-.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 procedure 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 the widget class record is of type
-.PN XtAlmostProc .
-.LP
-.IN "set_values_almost procedure" "" "@DEF@"
-.IN "XtAlmostProc" "" "@DEF@"
-.sM
-.FD 0
-typedef void (*XtAlmostProc)(Widget, Widget, XtWidgetGeometry*, \
-XtWidgetGeometry*);
-.br
-      Widget \fIold\fP;
-.br
-      Widget \fInew\fP;
-.br
-      XtWidgetGeometry *\fIrequest\fP;
-.br
-      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
-.eM
-Most classes inherit the set_values_almost procedure from their superclass by
-specifying 
-.PN XtInheritSetValuesAlmost 
-in the class initialization.
-The
-set_values_almost procedure in
-.PN rectObjClass
-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 \fInew\fP object is the actual instance record.  The \fIx\fP, \fIy\fP,
-\fIwidth\fP, \fIheight\fP,
-and \fIborder_width\fP fields contain the original values as they were
-before the
-.PN XtSetValues
-call, and all other fields contain the new
-values.  The \fIrequest\fP parameter contains the new geometry request that
-was made to the parent.  The \fIreply\fP parameter contains
-\fIreply->request_mode\fP 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 if the compromise is
-acceptable or whether
-to try a different compromise.
-It returns its results in the \fIrequest\fP 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 \fIreply\fP geometry into the \fIrequest\fP geometry; to attempt an
-alternative geometry, the procedure may modify any part of the \fIrequest\fP
-argument; to terminate the geometry negotiation and retain the
-original geometry, the procedure must set \fIrequest->request_mode\fP to
-zero.  The geometry fields of the \fIold\fP and \fInew\fP instances must not be modified
-directly.
-
-.NH 4
-Widget State: The ConstraintClassPart set_values Procedure
-.XS
-\*(SN Widget State: The ConstraintClassPart 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 \fIset_values\fP 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 resources that are changed.
-Furthermore, it may modify other 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 may reset the \fIheight\fP field in the
-widget.
-
-.NH 4
-Widget Subpart State
-.XS
-\*(SN Widget Subpart State
-.XE
-.LP
-To set the current values of subpart resources associated with a
-widget instance, use
-.PN XtSetSubvalues .
-For a discussion of subpart resources,
-see Section 9.4.
-.LP
-.IN "XtSetSubvalues" "" "@DEF@"
-.sM
-.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 subpart resource list.
-.IP \fInum_resources\fP 1i
-Specifies the number of entries 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.
-.IP \fInum_args\fP 1i
-Specifies the number of entries in the argument list.
-.LP
-.eM
-The
-.PN XtSetSubvalues
-function updates the resource fields of the structure identified by
-\fIbase\fP.  Any specified arguments that do not match an entry in the
-resource list are silently ignored.
-.sp
-.LP
-To set the current values of subpart resources associated with
-a widget instance using varargs lists, use
-.PN XtVaSetSubvalues .
-.LP
-.IN "XtVaSetSubvalues" "" "@DEF@"
-.sM
-.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 subpart resource list.
-.IP \fInum_resources\fP 1i
-Specifies the number of entries in the resource list.
-.IP ... 1i
-Specifies the variable argument list of name/value pairs that
-contain the resources to be modified and their new values.
-.LP
-.eM
-.PN XtVaSetSubvalues
-is identical in function to
-.PN XtSetSubvalues
-with the \fIargs\fP and \fInum_args\fP parameters replaced by a varargs list, as
-described in Section 2.5.1.
-.PN XtVaTypedArg
-is not supported for
-.PN XtVaSetSubvalues .
-If an entry containing
-.PN XtVaTypedArg
-is specified in the list, a warning message is issued
-and the entry is 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 that used it in versions prior to Release 4.
-.NE
-.LP
-Widgets that have a subpart can set the subpart resource values through
-.PN XtSetValues
-by supplying a set_values_hook procedure.
-The set_values_hook procedure pointer in a widget class is of type
-.PN XtArgsFunc .
-.LP
-.IN "set_values_hook procedure" "" "@DEF@"
-.IN "XtArgsFunc" "" "@DEF@"
-.sM
-.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 subpart resource values are to be changed.
-.IP \fIargs\fP 1i
-Specifies the argument list that was passed to
-.PN XtSetValues
-or the transformed varargs list passed to
-.PN XtVaSetValues .
-.IP \fInum_args\fP 1i
-Specifies the number of entries in the argument list.
-.LP
-.eM
-The widget with subpart resources may call
-.PN XtSetValues
-from the set_values_hook procedure
-and pass in its subresource list and the
-\fIargs\fP and \fInum_args\fP parameters.
-.bp