git update until 25 Mar 2011

xserver 
fontconfig
glproto
libXau
libXft
libXmu
libfontenc
libxcb
mesa
mkfontscale
pixman
randrproto
xkeyboard-config
xtrans
xwininfo

updated following packages:

xproto-7.0.21
xineramaproto-1.2.1
libXt-1.1.1
libxkbfile-1.0.7
libXpm-3.5.9
libXfont-1.4.3
libXaw-1.0.9
bdftopcf-1.0.3
encodings-1.0.4
fixesproto-5.0
font-adobe-100dpi-1.0.3
font-adobe-75dpi-1.0.3
font-adobe-utopia-100dpi-1.0.4
font-adobe-utopia-75dpi-1.0.4
font-adobe-utopia-type1-1.0.4
font-alias-1.0.3
font-arabic-misc-1.0.3
font-bh-100dpi-1.0.3
font-bh-75dpi-1.0.3
font-bh-lucidatypewriter-100dpi-1.0.3
font-bh-lucidatypewriter-75dpi-1.0.3
font-bh-ttf-1.0.3
font-bh-type1-1.0.3
font-bitstream-100dpi-1.0.3
font-bitstream-75dpi-1.0.3
font-bitstream-speedo-1.0.2
font-bitstream-type1-1.0.3
font-cronyx-cyrillic-1.0.3
font-cursor-misc-1.0.3
font-daewoo-misc-1.0.3
font-dec-misc-1.0.3
font-ibm-type1-1.0.3
font-isas-misc-1.0.3
font-jis-misc-1.0.3
font-micro-misc-1.0.3
font-misc-cyrillic-1.0.3
font-misc-ethiopic-1.0.3
font-misc-meltho-1.0.3
font-misc-misc-1.1.2
font-mutt-misc-1.0.3
font-schumacher-misc-1.1.2
font-screen-cyrillic-1.0.4
font-sony-misc-1.0.3
font-sun-misc-1.0.3
font-util-1.2.0
font-winitzki-cyrillic-1.0.3
font-xfree86-type1-1.0.4

1 files changed, 3211 insertions, 0 deletions

diff --git a/libXt/specs/CH09 b/libXt/specs/CH09
new file mode 100644
index 000000000..9538651bc
--- /dev/null
+++ b/libXt/specs/CH09
@@ -0,0 +1,3211 @@
+.\" $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