diff options
Diffstat (limited to 'libXt/specs/CH09.xml')
| -rw-r--r-- | libXt/specs/CH09.xml | 4326 |
1 files changed, 4326 insertions, 0 deletions
diff --git a/libXt/specs/CH09.xml b/libXt/specs/CH09.xml new file mode 100644 index 000000000..1f64de593 --- /dev/null +++ b/libXt/specs/CH09.xml @@ -0,0 +1,4326 @@ +<chapter id='Resource_Management'> +<title>Resource Management</title> +<para> +A resource is a field in the widget record with a corresponding +resource entry in the <emphasis remap='I'>resources</emphasis> list of the widget or any of its +superclasses. +This means that the field is +settable by +<xref linkend='XtCreateWidget' xrefstyle='select: title'/> +(by naming the field in the argument list), by an +entry in a resource file (by using either the name or class), and by +<xref linkend='XtSetValues' xrefstyle='select: title'/>. +In addition, it is readable by +<xref linkend='XtGetValues' xrefstyle='select: title'/>. +Not all fields in a widget record are resources. +Some are for bookkeeping use by the +generic routines (like <emphasis remap='I'>managed</emphasis> and <emphasis remap='I'>being_destroyed</emphasis>). +Others can be for local bookkeeping, +and still others are derived from resources +(many graphics contexts and pixmaps). +</para> + +<para> +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 +<xref linkend='XtCreateWidget' xrefstyle='select: title'/>, +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. +</para> +<sect1 id="Resource_Lists"> +<title>Resource Lists</title> +<para> +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 +<function>XtResource</function> +structure is +</para> +<literallayout > +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; +</literallayout> +<para> +When the resource list is specified as the +<function>CoreClassPart</function>, +<function>ObjectClassPart</function>, +<function>RectObjClassPart</function>, +or +<function>ConstraintClassPart</function> +<emphasis remap='I'>resources</emphasis> field, the strings pointed to by <emphasis remap='I'>resource_name</emphasis>, +<emphasis remap='I'>resource_class</emphasis>, <emphasis remap='I'>resource_type</emphasis>, and <emphasis remap='I'>default_type</emphasis> must +be permanently allocated prior to or during the execution of the class +initialization procedure and must not be subsequently deallocated. +</para> + +<para> +The <emphasis remap='I'>resource_name</emphasis> 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 Intrinsics 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 Intrinsics are named in +<function><X11/StringDefs.h></function>. +The Intrinsics's symbolic resource names begin with +``XtN'' +and are followed by the string name (for example, XtNbackgroundPixel +for backgroundPixel). +</para> + +<para> +The <emphasis remap='I'>resource_class</emphasis> field contains the class string used in resource +specification files to identify the field. +A resource class provides two functions: +</para> +<itemizedlist spacing='compact'> + <listitem> + <para> +It isolates an application from different representations that widgets +can use for a similar resource. + </para> + </listitem> + <listitem> + <para> +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. + </para> + </listitem> +</itemizedlist> +<para> +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. +</para> + +<para> +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: +</para> +<literallayout > +*Background: ivory +*Foreground: darkblue +</literallayout> +<para> +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: +</para> +<literallayout > +*Font: 6x13 +</literallayout> +<para> +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). +</para> + +<para> +The <emphasis remap='I'>resource_type</emphasis> 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 +<function>String</function>) +or the format of the resource default value +(almost anything, but often +<function>String</function>) +to the desired +physical representation (see <xref linkend='Resource_Conversions' />). +The Intrinsics define the following resource types: +</para> + +<informaltable frame='topbot'> + <?dbfo keep-together="auto" ?> + <tgroup cols='2' align='left' colsep='0' rowsep='0'> + <colspec colwidth='1.0*' colname='c1'/> + <colspec colwidth='1.0*' colname='c2'/> + <thead> + <row rowsep='1'> + <entry>Resource Type</entry> + <entry>Structure or Field Type</entry> + </row> + </thead> + <tbody> + <row> + <entry><function>XtRAcceleratorTable</function></entry> + <entry>XtAccelerators</entry> + </row> + <row> + <entry><function>XtRAtom</function></entry> + <entry>Atom</entry> + </row> + <row> + <entry><function>XtRBitmap</function></entry> + <entry>Pixmap, depth=1</entry> + </row> + <row> + <entry><function>XtRBoolean</function></entry> + <entry>Boolean</entry> + </row> + <row> + <entry><function>XtRBool</function></entry> + <entry>Bool</entry> + </row> + <row> + <entry><function>XtRCallback</function></entry> + <entry>XtCallbackList</entry> + </row> + <row> + <entry><function>XtRCardinal</function></entry> + <entry>Cardinal</entry> + </row> + <row> + <entry><function>XtRColor</function></entry> + <entry>XColor</entry> + </row> + <row> + <entry><function>XtRColormap</function></entry> + <entry>Colormap</entry> + </row> + <row> + <entry><function>XtRCommandArgArray</function></entry> + <entry>String*</entry> + </row> + <row> + <entry><function>XtRCursor</function></entry> + <entry>Cursor</entry> + </row> + <row> + <entry><function>XtRDimension</function></entry> + <entry>Dimension</entry> + </row> + <row> + <entry><function>XtRDirectoryString</function></entry> + <entry>String</entry> + </row> + <row> + <entry><function>XtRDisplay</function></entry> + <entry>Display*</entry> + </row> + <row> + <entry><function>XtREnum</function></entry> + <entry>XtEnum</entry> + </row> + <row> + <entry><function>XtREnvironmentArray</function></entry> + <entry>String*</entry> + </row> + <row> + <entry><function>XtRFile</function></entry> + <entry>FILE*</entry> + </row> + <row> + <entry><function>XtRFloat</function></entry> + <entry>float</entry> + </row> + <row> + <entry><function>XtRFont</function></entry> + <entry>Font</entry> + </row> + <row> + <entry><function>XtRFontSet</function></entry> + <entry>XFontSet</entry> + </row> + <row> + <entry><function>XtRFontStruct</function></entry> + <entry>XFontStruct*</entry> + </row> + <row> + <entry><function>XtRFunction</function></entry> + <entry>(*)()</entry> + </row> + <row> + <entry><function>XtRGeometry</function></entry> + <entry>char*, format as defined by + <function>XParseGeometry</function></entry> + </row> + <row> + <entry><function>XtRGravity</function></entry> + <entry>int</entry> + </row> + <row> + <entry><function>XtRInitialState</function></entry> + <entry>int</entry> + </row> + <row> + <entry><function>XtRInt</function></entry> + <entry>int</entry> + </row> + <row> + <entry><function>XtRLongBoolean</function></entry> + <entry>long</entry> + </row> + <row> + <entry><function>XtRObject</function></entry> + <entry>Object</entry> + </row> + <row> + <entry><function>XtRPixel</function></entry> + <entry>Pixel</entry> + </row> + <row> + <entry><function>XtRPixmap</function></entry> + <entry>Pixmap</entry> + </row> + <row> + <entry><function>XtRPointer</function></entry> + <entry>XtPointer</entry> + </row> + <row> + <entry><function>XtRPosition</function></entry> + <entry>Position</entry> + </row> + <row> + <entry><function>XtRRestartStyle</function></entry> + <entry>unsigned char</entry> + </row> + <row> + <entry><function>XtRScreen</function></entry> + <entry>Screen*</entry> + </row> + <row> + <entry><function>XtRShort</function></entry> + <entry>short</entry> + </row> + <row> + <entry><function>XtRSmcConn</function></entry> + <entry>XtPointer</entry> + </row> + <row> + <entry><function>XtRString</function></entry> + <entry>String</entry> + </row> + <row> + <entry><function>XtRStringArray</function></entry> + <entry>String*</entry> + </row> + <row> + <entry><function>XtRStringTable</function></entry> + <entry>String*</entry> + </row> + <row> + <entry><function>XtRTranslationTable</function></entry> + <entry>XtTranslations</entry> + </row> + <row> + <entry><function>XtRUnsignedChar</function></entry> + <entry>unsigned char</entry> + </row> + <row> + <entry><function>XtRVisual</function></entry> + <entry>Visual*</entry> + </row> + <row> + <entry><function>XtRWidget</function></entry> + <entry>Widget</entry> + </row> + <row> + <entry><function>XtRWidgetClass</function></entry> + <entry>WidgetClass</entry> + </row> + <row> + <entry><function>XtRWidgetList</function></entry> + <entry>WidgetList</entry> + </row> + <row> + <entry><function>XtRWindow</function></entry> + <entry>Window</entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<para> +<function><X11/StringDefs.h></function> +also defines the following resource types as a +convenience for widgets, although they do not have any corresponding +data type assigned: +<function>XtREditMode</function>, +<function>XtRJustify</function>, +and +<function>XtROrientation</function>. +</para> + +<para> +The <emphasis remap='I'>resource_size</emphasis> field is the size of the physical representation in bytes; +you should specify it as +<function>sizeof</function>(type) so that the +compiler fills in the value. +The <emphasis remap='I'>resource_offset</emphasis> field is the offset in bytes of the field +within the widget. +You should use the +<xref linkend='XtOffsetOf' xrefstyle='select: title'/> +macro to retrieve this value. +The <emphasis remap='I'>default_type</emphasis> field is the representation type of the default +resource value. +If <emphasis remap='I'>default_type</emphasis> is different from <emphasis remap='I'>resource_type</emphasis> and the default value +is needed, +the resource manager invokes a conversion procedure from <emphasis remap='I'>default_type</emphasis> +to <emphasis remap='I'>resource_type</emphasis>. +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, +<function>XtDefaultForeground</function> +for a pixel resource). +The <emphasis remap='I'>default_addr</emphasis> field specifies the address of the default resource value. +As a special case, if <emphasis remap='I'>default_type</emphasis> is +<function>XtRString</function>, +then the value in the <emphasis remap='I'>default_addr</emphasis> 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). +</para> + +<para> +Two special representation types +(XtRImmediate +and +XtRCallProc) +are usable only as default resource types. +XtRImmediate +indicates that the value in the <emphasis remap='I'>default_addr</emphasis> 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 +<function>XtPointer</function>. +No conversion is possible, since there is no source representation type. +XtRCallProc +indicates that the value in the <emphasis remap='I'>default_addr</emphasis> field is a procedure +pointer. +This procedure is automatically invoked with the widget, +<emphasis remap='I'>resource_offset</emphasis>, and a pointer to an +<function>XrmValue</function> +in which to store the result. +XtRCallProc +procedure pointers are of type +<xref linkend='XtResourceDefaultProc' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtResourceDefaultProc'> +<funcprototype> +<funcdef>typedef void <function>(*XtResourceDefaultProc)</function></funcdef> + <paramdef>Widget <parameter>w</parameter></paramdef> + <paramdef>int <parameter>offset</parameter></paramdef> + <paramdef>XrmValue *<parameter>value</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the widget whose resource value is to be obtained. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>offset</emphasis> + </term> + <listitem> + <para> +Specifies the offset of the field in the widget record. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>value</emphasis> + </term> + <listitem> + <para> +Specifies the resource value descriptor to return. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The +<xref linkend='XtResourceDefaultProc' xrefstyle='select: title'/> +procedure should fill in the <emphasis remap='I'>value->addr</emphasis> field with a pointer +to the resource value in its correct representation type. +</para> + +<para> +To get the resource list structure for a particular class, use +<xref linkend='XtGetResourceList' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtGetResourceList'> +<funcprototype> +<funcdef>void <function>XtGetResourceList</function></funcdef> + + <paramdef>WidgetClass <parameter>class</parameter></paramdef> + <paramdef>XtResourceList *<parameter>resources_return</parameter></paramdef> + <paramdef>Cardinal *<parameter>num_resources_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>class</emphasis> + </term> + <listitem> + <para> +Specifies the object class to be queried. It must be +<function>objectClass</function> +or any subclass thereof. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>resources_return</emphasis> + </term> + <listitem> + <para> +Returns the resource list. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_resources_return</emphasis> + </term> + <listitem> + <para> +Returns the number of entries in the resource list. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +If +<xref linkend='XtGetResourceList' xrefstyle='select: title'/> +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, +<xref linkend='XtGetResourceList' xrefstyle='select: title'/> +returns a merged resource list that includes the resources +for all superclasses. +The list returned by +<xref linkend='XtGetResourceList' xrefstyle='select: title'/> +should be freed using +<xref linkend='XtFree' xrefstyle='select: title'/> +when it is no longer needed. +</para> + +<para> +To get the constraint resource list structure for a particular widget +class, use +<xref linkend='XtGetConstraintResourceList' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtGetConstraintResourceList'> +<funcprototype> +<funcdef>void <function>XtGetConstraintResourceList</function></funcdef> + <paramdef>WidgetClass <parameter>class</parameter></paramdef> + <paramdef>XtResourceList *<parameter>resources_return</parameter></paramdef> + <paramdef>Cardinal *<parameter>num_resources_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>class</emphasis> + </term> + <listitem> + <para> +Specifies the object class to be queried. It must be +<function>objectClass</function> +or any subclass thereof. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>resources_return</emphasis> + </term> + <listitem> + <para> +Returns the constraint resource list. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_resources_return</emphasis> + </term> + <listitem> + <para> +Returns the number of entries in the constraint resource list. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +If +<xref linkend='XtGetConstraintResourceList' xrefstyle='select: title'/> +is called before the widget class is +initialized, the resource list as specified in the widget +class Constraint part is returned. If +<xref linkend='XtGetConstraintResourceList' xrefstyle='select: title'/> +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 +<function>constraintWidgetClass</function>, +*<emphasis remap='I'>resources_return</emphasis> is set to NULL +and *<emphasis remap='I'>num_resources_return</emphasis> is set to zero. +The list returned by +<xref linkend='XtGetConstraintResourceList' xrefstyle='select: title'/> +should be freed using +<xref linkend='XtFree' xrefstyle='select: title'/> +when it is no longer needed. +</para> + +<para> +The routines +<xref linkend='XtSetValues' xrefstyle='select: title'/> +and +<xref linkend='XtGetValues' xrefstyle='select: title'/> +also use the resource list to set and get widget state; +see <xref linkend='Obtaining_Widget_State' /> and +<xref linkend='Setting_Widget_State' />. +</para> + +<para> +Here is an abbreviated version of a possible resource list for a Label widget: +</para> +<literallayout > +/* 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}, + . + . + . +} +</literallayout> +<para> +The complete resource name for a field of a widget instance is the +concatenation of the application shell name (from +<function>XtAppCreateShell ),</function> +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 +<function>XtAppCreateShell ),</function> +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. +</para> +</sect1> + +<sect1 id="Byte_Offset_Calculations"> +<title>Byte Offset Calculations</title> +<para> +To determine the byte offset of a field within a structure type, use +<xref linkend='XtOffsetOf' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtOffsetOf'> +<funcprototype> +<funcdef>Cardinal <function>XtOffsetOf</function></funcdef> + <paramdef>Type <parameter>structure_type</parameter></paramdef> + <paramdef>Field <parameter>field_name</parameter></paramdef> +</funcprototype> +</funcsynopsis> + + + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>structure_type</emphasis> + </term> + <listitem> + <para> +Specifies a type that is declared as a structure. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>field_name</emphasis> + </term> + <listitem> + <para> +Specifies the name of a member within the structure. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The +<xref linkend='XtOffsetOf' xrefstyle='select: title'/> +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 +<xref linkend='XtOffset' xrefstyle='select: title'/>, +which serves the same function. +</para> + +<para> +To determine the byte offset of a field within a structure pointer type, use +<xref linkend='XtOffset' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtOffset'> +<funcprototype> +<funcdef>Cardinal <function>XtOffset</function></funcdef> + <paramdef>Type <parameter> pointer_type</parameter></paramdef> + <paramdef>Field <parameter> field_name</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>pointer_type</emphasis> + </term> + <listitem> + <para> +Specifies a type that is declared as a pointer to a structure. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>field_name</emphasis> + </term> + <listitem> + <para> +Specifies the name of a member within the structure. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The +<xref linkend='XtOffset' xrefstyle='select: title'/> +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. +<xref linkend='XtOffset' xrefstyle='select: title'/> +is less portable than +<xref linkend='XtOffsetOf' xrefstyle='select: title'/>. +</para> +</sect1> + +<sect1 id="Superclass_to_Subclass_Chaining_of_Resource_Lists"> +<title>Superclass-to-Subclass Chaining of Resource Lists</title> +<para> +The +<xref linkend='XtCreateWidget' xrefstyle='select: title'/> +function gets resources as a superclass-to-subclass chained operation. +That is, the resources specified in the +<function>objectClass</function> +resource list are fetched, +then those in +<function>rectObjClass</function>, +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. +</para> + +<para> +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 <emphasis remap='I'>background_pixel</emphasis>. +Consequently, +the implementation of Label need not also have a resource entry +for <emphasis remap='I'>background_pixel</emphasis>. +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. +</para> + +<para> +Also at class initialization time, the Intrinsics produce an +internal representation of the resource list to optimize access time +when creating widgets. In order to save memory, the Intrinsics 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. +</para> +</sect1> + +<sect1 id="Subresources"> +<title>Subresources</title> +<para> +A widget does not do anything to retrieve its own resources; +instead, +<xref linkend='XtCreateWidget' xrefstyle='select: title'/> +does this automatically before calling the class initialize procedure. +</para> + +<para> +Some widgets have subparts that are not widgets but for which the widget +would like to fetch resources. +Such widgets call +<xref linkend='XtGetSubresources' xrefstyle='select: title'/> +to accomplish this. +</para> + +<funcsynopsis id='XtGetSubresources'> +<funcprototype> +<funcdef>void <function>XtGetSubresources</function></funcdef> + <paramdef>Widget <parameter>w</parameter></paramdef> + <paramdef>XtPointer <parameter>base</parameter></paramdef> + <paramdef>String <parameter>name</parameter></paramdef> + <paramdef>String <parameter>class</parameter></paramdef> + <paramdef>XtResourceList <parameter>resources</parameter></paramdef> + <paramdef>Cardinal <parameter>num_resources</parameter></paramdef> + <paramdef>ArgList <parameter>args</parameter></paramdef> + <paramdef>Cardinal <parameter>num_args</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the object used to qualify the subpart resource name and +class. Must be of class Object or any subclass thereof. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>base</emphasis> + </term> + <listitem> + <para> +Specifies the base address of the subpart data structure into which the +resources will be written. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>name</emphasis> + </term> + <listitem> + <para> +Specifies the name of the subpart. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>class</emphasis> + </term> + <listitem> + <para> +Specifies the class of the subpart. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>resources</emphasis> + </term> + <listitem> + <para> +Specifies the resource list for the subpart. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_resources</emphasis> + </term> + <listitem> + <para> +Specifies the number of entries in the resource list. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>args</emphasis> + </term> + <listitem> + <para> +Specifies the argument list to override any other resource specifications. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_args</emphasis> + </term> + <listitem> + <para> +Specifies the number of entries in the argument list. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The +<xref linkend='XtGetSubresources' xrefstyle='select: title'/> +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 <emphasis remap='I'>name</emphasis> and <emphasis remap='I'>class</emphasis> 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 <emphasis remap='I'>args</emphasis> is NULL, +<emphasis remap='I'>num_args</emphasis> must be zero. +However, if <emphasis remap='I'>num_args</emphasis> is zero, +the argument list is not referenced. +</para> + +<para> +<xref linkend='XtGetSubresources' xrefstyle='select: title'/> +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 +<xref linkend='XtGetSubresources' xrefstyle='select: title'/> +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. +</para> + +<para> +To fetch resources for widget subparts using varargs lists, use +<xref linkend='XtVaGetSubresources' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtVaGetSubresources'> +<funcprototype> +<funcdef>void <function>XtVaGetSubresources</function></funcdef> + <paramdef>Widget <parameter>w</parameter></paramdef> + <paramdef>XtPointer <parameter>base</parameter></paramdef> + <paramdef>String <parameter>name</parameter></paramdef> + <paramdef>String <parameter>class</parameter></paramdef> + <paramdef>XtResourceList <parameter>resources</parameter></paramdef> + <paramdef>Cardinal <parameter>num_resources</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the object used to qualify the subpart resource name and +class. Must be of class Object or any subclass thereof. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>base</emphasis> + </term> + <listitem> + <para> +Specifies the base address of the subpart data structure into which the +resources will be written. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>name</emphasis> + </term> + <listitem> + <para> +Specifies the name of the subpart. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>class</emphasis> + </term> + <listitem> + <para> +Specifies the class of the subpart. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>resources</emphasis> + </term> + <listitem> + <para> +Specifies the resource list for the subpart. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_resources</emphasis> + </term> + <listitem> + <para> +Specifies the number of entries in the resource list. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + ... + </term> + <listitem> + <para> +Specifies the variable argument list to override any other +resource specifications. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<xref linkend='XtVaGetSubresources' xrefstyle='select: title'/> +is identical in function to +<xref linkend='XtGetSubresources' xrefstyle='select: title'/> +with the <emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis> parameters replaced by a varargs list, as +described in Section 2.5.1. +</para> +</sect1> + +<sect1 id="Obtaining_Application_Resources"> +<title>Obtaining Application Resources</title> +<para> +To retrieve resources that are not specific to a widget +but apply to the overall application, use +<xref linkend='XtGetApplicationResources' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtGetApplicationResources'> +<funcprototype> +<funcdef>void <function>XtGetApplicationResources</function></funcdef> + <paramdef>Widget <parameter>w</parameter></paramdef> + <paramdef>XtPointer <parameter>base</parameter></paramdef> + <paramdef>XtResourceList <parameter>resources</parameter></paramdef> + <paramdef>Cardinal <parameter>num_resources</parameter></paramdef> + <paramdef>ArgList <parameter>args</parameter></paramdef> + <paramdef>Cardinal <parameter>num_args</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the object that identifies the resource database to search +(the database is that associated with the display for this object). Must be of class Object or any subclass thereof. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>base</emphasis> + </term> + <listitem> + <para> +Specifies the base address into which +the resource values will be written. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>resources</emphasis> + </term> + <listitem> + <para> +Specifies the resource list. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_resources</emphasis> + </term> + <listitem> + <para> +Specifies the number of entries in the resource list. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>args</emphasis> + </term> + <listitem> + <para> +Specifies the argument list to override any other resource specifications. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_args</emphasis> + </term> + <listitem> + <para> +Specifies the number of entries in the argument list. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The +<xref linkend='XtGetApplicationResources' xrefstyle='select: title'/> +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, +<xref linkend='XtGetApplicationResources' xrefstyle='select: title'/> +copies the resources into the addresses +obtained by adding <emphasis remap='I'>base</emphasis> to each <emphasis remap='I'>offset</emphasis> in the resource list. +If <emphasis remap='I'>args</emphasis> is NULL, +<emphasis remap='I'>num_args</emphasis> must be zero. +However, if <emphasis remap='I'>num_args</emphasis> 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 <emphasis remap='I'>base</emphasis> argument. +</para> + +<para> +<xref linkend='XtGetApplicationResources' xrefstyle='select: title'/> +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 +<xref linkend='XtGetApplicationResources' xrefstyle='select: title'/> +will not be freed from the resource cache until the display is closed. +</para> + +<para> +To retrieve resources for the overall application using varargs lists, use +<xref linkend='XtVaGetApplicationResources' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtVaGetApplicationResources'> +<funcprototype> +<funcdef>void <function>XtVaGetApplicationResources</function></funcdef> + <paramdef>Widget <parameter>w</parameter></paramdef> + <paramdef>XtPointer <parameter>base</parameter></paramdef> + <paramdef>XtResourceList <parameter>resources</parameter></paramdef> + <paramdef>Cardinal <parameter>num_resources</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the object that identifies the resource database to search +(the database is that associated with the display for this object). Must be of class Object or any subclass thereof. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>base</emphasis> + </term> + <listitem> + <para> +Specifies the base address into which +the resource values will be written. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>resources</emphasis> + </term> + <listitem> + <para> +Specifies the resource list for the subpart. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_resources</emphasis> + </term> + <listitem> + <para> +Specifies the number of entries in the resource list. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + ... + </term> + <listitem> + <para> +Specifies the variable argument list to override any other +resource specifications. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<xref linkend='XtVaGetApplicationResources' xrefstyle='select: title'/> +is identical in function to +<xref linkend='XtGetApplicationResources' xrefstyle='select: title'/> +with the <emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis> parameters +replaced by a varargs list, as described in Section 2.5.1. +</para> +</sect1> + +<sect1 id="Resource_Conversions"> +<title>Resource Conversions</title> +<para> +The Intrinsics provide a mechanism for registering representation converters that +are automatically invoked by the resource-fetching routines. +The Intrinsics additionally provide and register several commonly used converters. +This resource conversion mechanism serves several purposes: +</para> +<itemizedlist spacing='compact'> + <listitem> + <para> +It permits user and application resource files to contain textual +representations of nontextual values. + </para> + </listitem> + <listitem> + <para> +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. + </para> + </listitem> + <listitem> + <para> +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. + </para> + </listitem> +</itemizedlist> +<sect2 id="Predefined_Resource_Converters"> +<title>Predefined Resource Converters</title> +<para> +The Intrinsics define all the representations used in the +Object, +RectObj, +Core, +Composite, +Constraint, +and +Shell +widget classes. +The Intrinsics register the following resource converters that accept +input values of representation type +<function>XtRString</function>. +</para> + +<informaltable frame='topbot'> + <?dbfo keep-together="auto" ?> + <tgroup cols='3' align='left' rowsep='0' colsep='0'> + <colspec colwidth='0.7*' colname='c1'/> + <colspec colwidth='1.0*' colname='c2'/> + <colspec colwidth='0.6*' colname='c3'/> + <thead> + <row rowsep='1'> + <entry>Target Representation</entry> + <entry>Converter Name</entry> + <entry>Additional Args</entry> + </row> + </thead> + <tbody> + <row> + <entry><function>XtRAcceleratorTable</function></entry> + <entry><function>XtCvtStringToAcceleratorTable</function></entry> + </row> + <row> + <entry><function>XtRAtom</function></entry> + <entry><function>XtCvtStringToAtom</function></entry> + <entry>Display*</entry> + </row> + <row> + <entry><function>XtRBoolean</function></entry> + <entry><function>XtCvtStringToBoolean</function></entry> + </row> + <row> + <entry><function>XtRBool</function></entry> + <entry><function>XtCvtStringToBool</function></entry> + </row> + <row> + <entry><function>XtRCommandArgArray</function></entry> + <entry><function>XtCvtStringToCommandArgArray</function></entry> + </row> + <row> + <entry><function>XtRCursor</function></entry> + <entry><function>XtCvtStringToCursor</function></entry> + <entry>Display*</entry> + </row> + <row> + <entry><function>XtRDimension</function></entry> + <entry><function>XtCvtStringToDimension</function></entry> + </row> + <row> + <entry><function>XtRDirectoryString</function></entry> + <entry><function>XtCvtStringToDirectoryString</function></entry> + </row> + <row> + <entry><function>XtRDisplay</function></entry> + <entry><function>XtCvtStringToDisplay</function></entry> + </row> + <row> + <entry><function>XtRFile</function></entry> + <entry><function>XtCvtStringToFile</function></entry> + </row> + <row> + <entry><function>XtRFloat</function></entry> + <entry><function>XtCvtStringToFloat</function></entry> + </row> + <row> + <entry><function>XtRFont</function></entry> + <entry><function>XtCvtStringToFont</function></entry> + <entry>Display*</entry> + </row> + <row> + <entry><function>XtRFontSet</function></entry> + <entry><function>XtCvtStringToFontSet</function></entry> + <entry>Display*, String <emphasis remap='I'>locale</emphasis></entry> + </row> + <row> + <entry><function>XtRFontStruct</function></entry> + <entry><function>XtCvtStringToFontStruct</function></entry> + <entry>Display*</entry> + </row> + <row> + <entry><function>XtRGravity</function></entry> + <entry><function>XtCvtStringToGravity</function></entry> + </row> + <row> + <entry><function>XtRInitialState</function></entry> + <entry><function>XtCvtStringToInitialState</function></entry> + </row> + <row> + <entry><function>XtRInt</function></entry> + <entry><function>XtCvtStringToInt</function></entry> + </row> + <row> + <entry><function>XtRPixel</function></entry> + <entry><function>XtCvtStringToPixel</function></entry> + <entry><function>colorConvertArgs</function></entry> + </row> + <row> + <entry><function>XtRPosition</function></entry> + <entry><function>XtCvtStringToPosition</function></entry> + </row> + <row> + <entry><function>XtRRestartStyle</function></entry> + <entry><function>XtCvtStringToRestartStyle</function></entry> + </row> + <row> + <entry><function>XtRShort</function></entry> + <entry><function>XtCvtStringToShort</function></entry> + </row> + <row> + <entry><function>XtRTranslationTable</function></entry> + <entry><function>XtCvtStringToTranslationTable</function></entry> + </row> + <row> + <entry><function>XtRUnsignedChar</function></entry> + <entry><function>XtCvtStringToUnsignedChar</function></entry> + </row> + <row> + <entry><function>XtRVisual</function></entry> + <entry><function>XtCvtStringToVisual</function></entry> + <entry>Screen*, Cardinal <emphasis remap='I'>depth</emphasis></entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<para> +The String-to-Pixel conversion has two predefined constants that are +guaranteed to work and contrast with each other: +<function>XtDefaultForeground</function> +and +<function>XtDefaultBackground</function>. +They evaluate to the black and white pixel values of the widget's screen, +respectively. +If the application resource reverseVideo is +<function>True</function>, +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 +<function>XtDefaultFont</function> +and evaluate this in the following manner: +</para> +<itemizedlist spacing='compact'> + <listitem> + <para> +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 +<function>XtRString</function> +value returned as the font name or a type +<function>XtRFont</function> +or +<function>XtRFontStruct</function> +value directly as the resource value. + </para> + </listitem> + <listitem> + <para> +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 +<function>XListFonts</function> +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".) + </para> + </listitem> + <listitem> + <para> +If no suitable ISO8859-1 font can be found, issue a warning message +and return +<function>False</function>. + </para> + </listitem> +</itemizedlist> +<para> +The String-to-FontSet converter recognizes the constant +<function>XtDefaultFontSet</function> +and evaluate this in the following manner: +</para> +<itemizedlist spacing='compact'> + <listitem> + <para> +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 +<function>XtRString</function> +value returned as the base font name list or a type +<function>XtRFontSet</function> +value directly as the resource value. + </para> + </listitem> + <listitem> + <para> +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 +<function>XCreateFontSet</function> +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-*-*-*-*".) + </para> + </listitem> + <listitem> + <para> +If no suitable font set can be created, issue a warning message +and return +<function>False</function>. + </para> + </listitem> +</itemizedlist> +<para> +If a font set is created but <emphasis remap='I'>missing_charset_list</emphasis> is not +empty, a warning is issued and the partial font set is returned. +The Intrinsics 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. +</para> + +<para> +The String-to-Gravity conversion accepts string values that are the +names of window and bit gravities and their numerical equivalents, +as defined in <emphasis remap='I'>Xlib — C Language X Interface.</emphasis>: +<function>ForgetGravity</function>, +<function>UnmapGravity</function>, +<function>NorthWestGravity</function>, +<function>NorthGravity</function>, +<function>NorthEastGravity</function>, +<function>WestGravity</function>, +<function>CenterGravity</function>, +<function>EastGravity</function>, +<function>SouthWestGravity</function>, +<function>SouthGravity</function>, +<function>SouthEastGravity</function>, +and +<function>StaticGravity</function>. +Alphabetic case is not significant in the conversion. +</para> + +<para> +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. +</para> + +<para> +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. +</para> + +<para> +The String-to-RestartStyle conversion accepts the values +<function>RestartIfRunning</function>, +<function>RestartAnyway</function>, +<function>RestartImmediately</function>, +and +<function>RestartNever</function> +as defined by the <emphasis remap='I'>X Session Management Protocol</emphasis>. +</para> + +<para> +The String-to-InitialState conversion accepts the values +<function>NormalState</function> +or +<function>IconicState</function> +as defined by the <emphasis remap='I'>Inter-Client Communication Conventions Manual.</emphasis>. +</para> + +<para> +The String-to-Visual conversion calls +<function>XMatchVisualInfo</function> +using the +<emphasis remap='I'>screen</emphasis> and <emphasis remap='I'>depth</emphasis> 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 +<function>XtRVisual</function> +after the depth resource. +The allowed string values are the visual class names defined in <emphasis remap='I'>X Window System Protocol</emphasis>, +Section 8; +<function>StaticGray</function>, +<function>StaticColor</function>, +<function>TrueColor</function>, +<function>GrayScale</function>, +<function>PseudoColor</function>, +and +<function>DirectColor</function>. +</para> + +<para> +The Intrinsics register the following resource converter that accepts +an input value of representation type +<function>XtRColor</function>. +</para> + +<informaltable frame='topbot'> + <?dbfo keep-together="auto" ?> + <tgroup cols='3' align='left' rowsep='0' colsep='0'> + <colspec colwidth='1.0*' colname='c1'/> + <colspec colwidth='1.0*' colname='c2'/> + <colspec colwidth='1.0*' colname='c3'/> + <thead> + <row rowsep='1'> + <entry>Target Representation</entry> + <entry>Converter Name</entry> + <entry>Additional Args</entry> + </row> + </thead> + <tbody> + <row> + <entry><function>XtRPixel</function></entry> + <entry><function>XtCvtColorToPixel</function></entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<para> +The Intrinsics register the following resource converters that accept +input values of representation type +<function>XtRInt</function>. +</para> + +<informaltable frame='topbot'> + <?dbfo keep-together="auto" ?> + <tgroup cols='3' align='left' rowsep='0' colsep='0'> + <colspec colwidth='1.0*' colname='c1'/> + <colspec colwidth='1.0*' colname='c2'/> + <colspec colwidth='1.0*' colname='c3'/> + <thead> + <row rowsep='1'> + <entry>Target Representation</entry> + <entry>Converter Name</entry> + <entry>Additional Args</entry> + </row> + </thead> + <tbody> + <row> + <entry><function>XtRBoolean</function></entry> + <entry><function>XtCvtIntToBoolean</function></entry> + </row> + <row> + <entry><function>XtRBool</function></entry> + <entry><function>XtCvtIntToBool</function></entry> + </row> + <row> + <entry><function>XtRColor</function></entry> + <entry><function>XtCvtIntToColor</function></entry> + <entry><function>colorConvertArgs</function></entry> + </row> + <row> + <entry><function>XtRDimension</function></entry> + <entry><function>XtCvtIntToDimension</function></entry> + </row> + <row> + <entry><function>XtRFloat</function></entry> + <entry><function>XtCvtIntToFloat</function></entry> + </row> + <row> + <entry><function>XtRFont</function></entry> + <entry><function>XtCvtIntToFont</function></entry> + </row> + <row> + <entry><function>XtRPixel</function></entry> + <entry><function>XtCvtIntToPixel</function></entry> + </row> + <row> + <entry><function>XtRPixmap</function></entry> + <entry><function>XtCvtIntToPixmap</function></entry> + </row> + <row> + <entry><function>XtRPosition</function></entry> + <entry><function>XtCvtIntToPosition</function></entry> + </row> + <row> + <entry><function>XtRShort</function></entry> + <entry><function>XtCvtIntToShort</function></entry> + </row> + <row> + <entry><function>XtRUnsignedChar</function></entry> + <entry><function>XtCvtIntToUnsignedChar</function></entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<para> +The Intrinsics register the following resource converter that accepts +an input value of representation type +<function>XtRPixel</function>. +</para> + +<informaltable frame='topbot'> + <?dbfo keep-together="auto" ?> + <tgroup cols='3' align='left' rowsep='0' colsep='0'> + <colspec colwidth='1.0*' colname='c1'/> + <colspec colwidth='1.0*' colname='c2'/> + <colspec colwidth='1.0*' colname='c3'/> + <thead> + <row rowsep='1'> + <entry>Target Representation</entry> + <entry>Converter Name</entry> + <entry>Additional Args</entry> + </row> + </thead> + <tbody> + <row> + <entry><function>XtRColor</function></entry> + <entry><function>XtCvtPixelToColor</function></entry> + </row> + </tbody> + </tgroup> +</informaltable> +</sect2> + +<sect2 id="New_Resource_Converters"> +<title>New Resource Converters</title> +<para> +Type converters use pointers to +<function>XrmValue</function> +structures (defined in +<function><X11/Xresource.h>;</function> +see <olink targetdoc='libX11' targetptr='Creating_and_Storing_Databases'>Section 15.4</olink> in +<olink targetdoc='libX11' targetptr='libX11'>Xlib — C Language X Interface.</olink>) +for input and output values. +</para> +<literallayout > +typedef struct { + unsigned int size; + XPointer addr; +} XrmValue, *XrmValuePtr; +</literallayout> +<para> +The <emphasis remap='I'>addr</emphasis> field specifies the address of the data, and the <emphasis remap='I'>size</emphasis> +field gives the total number of significant bytes in the data. +For values of type +<function>String</function>, +<emphasis remap='I'>addr</emphasis> is the address of the first character and <emphasis remap='I'>size</emphasis> +includes the NULL-terminating byte. +</para> + +<para> +A resource converter procedure pointer is of type +<xref linkend='XtTypeConverter' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtTypeConverter'> +<funcprototype> +<funcdef>typedef Boolean <function>(*XtTypeConverter)</function></funcdef> + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>XrmValue *<parameter>args</parameter></paramdef> + <paramdef>Cardinal *<parameter>num_args</parameter></paramdef> + <paramdef>XrmValue *<parameter>from</parameter></paramdef> + <paramdef>XrmValue *<parameter>to</parameter></paramdef> + <paramdef>XtPointer *<parameter>converter_data</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the display connection with which this conversion is associated. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>args</emphasis> + </term> + <listitem> + <para> +Specifies a list of additional +<function>XrmValue</function> +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 <emphasis remap='I'>display</emphasis>, +and the String-to-Pixel converter needs the widget's <emphasis remap='I'>screen</emphasis> and <emphasis remap='I'>colormap</emphasis>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_args</emphasis> + </term> + <listitem> + <para> +Specifies the number of entries in <emphasis remap='I'>args</emphasis>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>from</emphasis> + </term> + <listitem> + <para> +Specifies the value to convert. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>to</emphasis> + </term> + <listitem> + <para> +Specifies a descriptor for a location into which to store the converted value. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>converter_data</emphasis> + </term> + <listitem> + <para> +Specifies a location into which the converter may +store converter-specific data associated +with this conversion. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The <emphasis remap='I'>display</emphasis> argument is normally used only when generating error +messages, to identify the application context (with the function +<function>XtDisplayToApplicationContext ).</function> +</para> + +<para> +The <emphasis remap='I'>to</emphasis> argument specifies the size and location into which the +converter should store the converted value. If the <emphasis remap='I'>addr</emphasis> field is NULL, +the converter should allocate appropriate storage and store the size +and location into the <emphasis remap='I'>to</emphasis> 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 +<emphasis remap='I'>addr</emphasis> field is not NULL, the converter must check the <emphasis remap='I'>size</emphasis> field to +ensure that sufficient space has been allocated before storing the +converted value. If insufficient space is specified, the converter +should update the <emphasis remap='I'>size</emphasis> field with the number of bytes required and +return +<function>False</function> +without modifying the data at the specified location. +If sufficient space was allocated by the caller, the converter should +update the <emphasis remap='I'>size</emphasis> field with the number of bytes actually occupied by the +converted value. For converted values of type +<function>XtRString</function>, +the size should +include the NULL-terminating byte, if any. +The converter may store any value in the location specified +in <emphasis remap='I'>converter_data</emphasis>; this value will be passed to the destructor, if any, +when the resource is freed by the Intrinsics. +</para> + +<para> +The converter must return +<function>True</function> +if the conversion was successful and +<function>False</function> +otherwise. If the conversion cannot be performed because of an +improper source value, a warning message should also be issued with +<xref linkend='XtAppWarningMsg' xrefstyle='select: title'/>. +</para> + +<para> +Most type converters just take the data described by the specified <emphasis remap='I'>from</emphasis> +argument and return data by writing into the location specified in +the <emphasis remap='I'>to</emphasis> argument. +A few need other information, which is available in <emphasis remap='I'>args</emphasis>. +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. +</para> + +<para> +Note that if an address is written into <emphasis remap='I'>to->addr</emphasis>, 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, +<xref linkend='XtGetApplicationResources' xrefstyle='select: title'/>, +or +<xref linkend='XtGetSubresources' xrefstyle='select: title'/> +in an implementation-defined manner; however, insertion of new entries +or changes to existing entries is allowed and will not directly cause +an error. +</para> + +<para> +The following is an example of a converter that takes a +<function>string</function> +and converts it to a +<function>Pixel</function>. +Note that the <emphasis remap='I'>display</emphasis> parameter is +used only to generate error messages; the +<function>Screen</function> +conversion argument is +still required to inform the Intrinsics that the converted value is +a function of the particular display (and colormap). +</para> + +<literallayout > +#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); + } +} +</literallayout> + +<para> +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 +<function>XtDefaultForeground</function>, +<function>XtDefaultBackground</function>, +and +<function>XtDefaultFont</function>. +</para> + +<para> +To allow the Intrinsics to deallocate resources produced by type +converters, a resource destructor procedure may also be provided. +</para> + +<para> +A resource destructor procedure pointer is of type +<xref linkend='XtDestructor' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtDestructor'> +<funcprototype> + <funcdef>typedef void <function>(*XtDestructor)</function></funcdef> + <paramdef>XtAppContext <parameter>app</parameter></paramdef> + <paramdef>XrmValue *<parameter>to</parameter></paramdef> + <paramdef>XtPointer <parameter>converter_data</parameter></paramdef> + <paramdef>XrmValue *<parameter>args</parameter></paramdef> + <paramdef>Cardinal *<parameter>num_args</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>app</emphasis> + </term> + <listitem> + <para> +Specifies an application context in which the resource is being freed. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>to</emphasis> + </term> + <listitem> + <para> +Specifies a descriptor for the resource produced by the type converter. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>converter_data</emphasis> + </term> + <listitem> + <para> +Specifies the converter-specific data returned by the type converter. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>args</emphasis> + </term> + <listitem> + <para> +Specifies the additional converter arguments as passed +to the type converter when the conversion was performed. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_args</emphasis> + </term> + <listitem> + <para> +Specifies the number of entries in <emphasis remap='I'>args</emphasis>. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The destructor procedure is responsible for freeing the resource +specified by the <emphasis remap='I'>to</emphasis> argument, including any auxiliary storage +associated with that resource, but not the memory directly addressed +by the size and location in the <emphasis remap='I'>to</emphasis> argument or the memory specified +by <emphasis remap='I'>args</emphasis>. +</para> +</sect2> + +<sect2 id="Issuing_Conversion_Warnings"> +<title>Issuing Conversion Warnings</title> +<para> +The +<xref linkend='XtDisplayStringConversionWarning' xrefstyle='select: title'/> +procedure is a convenience routine for resource type converters +that convert from string values. +</para> + +<funcsynopsis id='XtDisplayStringConversionWarning'> +<funcprototype> +<funcdef>void <function>XtDisplayStringConversionWarning</function></funcdef> + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>String <parameter>from_value</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the display connection with which the conversion is associated. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>from_value</emphasis> + </term> + <listitem> + <para> +Specifies the string that could not be converted. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>to_type</emphasis> + </term> + <listitem> + <para> +Specifies the target representation type requested. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The +<xref linkend='XtDisplayStringConversionWarning' xrefstyle='select: title'/> +procedure issues a warning message using +<xref linkend='XtAppWarningMsg' xrefstyle='select: title'/> +with <emphasis remap='I'>name</emphasis> ``conversionError'', +<emphasis remap='I'>type</emphasis> ``string'', <emphasis remap='I'>class</emphasis> ``XtToolkitError'', and the default message +``Cannot convert "<emphasis remap='I'>from_value</emphasis>" to type <emphasis remap='I'>to_type</emphasis>''. +</para> + +<para> +To issue other types of warning or error messages, the type converter +should use +<xref linkend='XtAppWarningMsg' xrefstyle='select: title'/> +or +<xref linkend='XtAppErrorMsg' xrefstyle='select: title'/>. +</para> + +<para> +To retrieve the application context associated with a given +display connection, use +<xref linkend='XtDisplayToApplicationContext' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtDisplayToApplicationContext'> +<funcprototype> +<funcdef>XtAppContext <function>XtDisplayToApplicationContext</function></funcdef> + <paramdef>Display *<parameter>display</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies an open and initialized display connection. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The +<xref linkend='XtDisplayToApplicationContext' xrefstyle='select: title'/> +function returns the application +context in which the specified <emphasis remap='I'>display</emphasis> was initialized. If the +display is not known to the Intrinsics, an error message is issued. +</para> +</sect2> + +<sect2 id="Registering_a_New_Resource_Converter"> +<title>Registering a New Resource Converter</title> +<para> +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 <function>XtCacheType</function> +argument. </para> + +<literallayout > +typedef int XtCacheType; +</literallayout> + +<para> +An <function>XtCacheType</function> +field may contain one of the following values: +</para> + +<para> +<function>XtCacheNone</function> +</para> +<itemizedlist spacing='compact'> + <listitem> + <para> +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. + </para> + </listitem> +</itemizedlist> +<para> +<function>XtCacheAll</function> +</para> +<itemizedlist spacing='compact'> + <listitem> + <para> +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. + </para> + </listitem> +</itemizedlist> +<para> +<function>XtCacheByDisplay</function> +</para> +<itemizedlist spacing='compact'> + <listitem> + <para> +Specifies that the results of a previous conversion +should be used as for +<function>XtCacheAll</function> +but the destructor will be called, if specified, if +<xref linkend='XtCloseDisplay' xrefstyle='select: title'/> +is called +for the display connection associated with the converted value, and +the value will be removed from the conversion cache. + </para> + </listitem> +</itemizedlist> +<para> +The qualifier +<function>XtCacheRefCount</function> +may be ORed with any of the above values. If +<function>XtCacheRefCount</function> +is specified, calls to +<xref linkend='XtCreateWidget' xrefstyle='select: title'/>, +<xref linkend='XtCreateManagedWidget' xrefstyle='select: title'/>, +<xref linkend='XtGetApplicationResources' xrefstyle='select: title'/>, +and +<xref linkend='XtGetSubresources' xrefstyle='select: title'/> +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. +</para> + +<para> +To register a type converter for all application contexts in a +process, use +<xref linkend='XtSetTypeConverter' xrefstyle='select: title'/>, +and to register a type converter in a single application context, use +<xref linkend='XtAppSetTypeConverter' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtSetTypeConverter'> +<funcprototype> +<funcdef>void <function>XtSetTypeConverter</function></funcdef> + <paramdef>String <parameter>from_type</parameter></paramdef> + <paramdef>String <parameter>to_type</parameter></paramdef> + <paramdef>XtTypeConverter <parameter>converter</parameter></paramdef> + <paramdef>XtConvertArgList <parameter>convert_args</parameter></paramdef> + <paramdef>Cardinal <parameter>num_args</parameter></paramdef> + <paramdef>XtCacheType <parameter>cache_type</parameter></paramdef> + <paramdef>XtDestructor <parameter>destructor</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>from_type</emphasis> + </term> + <listitem> + <para> +Specifies the source type. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>to_type</emphasis> + </term> + <listitem> + <para> +Specifies the destination type. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>converter</emphasis> + </term> + <listitem> + <para> +Specifies the resource type converter procedure. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>convert_args</emphasis> + </term> + <listitem> + <para> +Specifies additional conversion arguments, or NULL. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_args</emphasis> + </term> + <listitem> + <para> +Specifies the number of entries in <emphasis remap='I'>convert_args</emphasis>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>cache_type</emphasis> + </term> + <listitem> + <para> +Specifies whether or not resources produced by this +converter are sharable or display-specific and when +they should be freed. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>destructor</emphasis> + </term> + <listitem> + <para> +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. + </para> + </listitem> + </varlistentry> +</variablelist> + + +<funcsynopsis id='XtAppSetTypeConverter'> +<funcprototype> +<funcdef> <function>XtAppSetTypeConverter</function></funcdef> + <paramdef>XtAppContext <parameter>app_context</parameter></paramdef> + <paramdef>String <parameter>from_type</parameter></paramdef> + <paramdef>String <parameter>to_type</parameter></paramdef> + <paramdef>XtTypeConverter <parameter>converter</parameter></paramdef> + <paramdef>XtConvertArgList <parameter>convert_args</parameter></paramdef> + <paramdef>Cardinal <parameter>num_args</parameter></paramdef> + <paramdef>XtCacheType <parameter>cache_type</parameter></paramdef> + <paramdef>XtDestructor <parameter>destructor</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>app_context</emphasis> + </term> + <listitem> + <para> +Specifies the application context. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>from_type</emphasis> + </term> + <listitem> + <para> +Specifies the source type. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>to_type</emphasis> + </term> + <listitem> + <para> +Specifies the destination type. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>converter</emphasis> + </term> + <listitem> + <para> +Specifies the resource type converter procedure. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>convert_args</emphasis> + </term> + <listitem> + <para> +Specifies additional conversion arguments, or NULL. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_args</emphasis> + </term> + <listitem> + <para> +Specifies the number of entries in <emphasis remap='I'>convert_args</emphasis>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>cache_type</emphasis> + </term> + <listitem> + <para> +Specifies whether or not resources produced by this +converter are sharable or display-specific and when +they should be freed. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>destructor</emphasis> + </term> + <listitem> + <para> +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. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<xref linkend='XtSetTypeConverter' xrefstyle='select: title'/> +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. +<xref linkend='XtAppSetTypeConverter' xrefstyle='select: title'/> +registers the specified type converter in the +single application context specified. If the same <emphasis remap='I'>from_type</emphasis> and +<emphasis remap='I'>to_type</emphasis> are specified in multiple calls to either function, the most +recent overrides the previous ones. +</para> + +<para> +For the few type converters that need additional arguments, +the Intrinsics conversion mechanism provides a method of specifying +how these arguments should be computed. +The enumerated type +<function>XtAddressMode</function> +and the structure +<function>XtConvertArgRec</function> +specify how each argument is derived. +These are defined in +<function><X11/Intrinsic.h></function>. +</para> +<literallayout > +typedef enum { + /* address mode parameter representation */ + XtAddress, /* address */ + XtBaseOffset, /* offset */ + XtImmediate, /* constant */ + XtResourceString, /* resource name string */ + XtResourceQuark, /* resource name quark */ + XtWidgetBaseOffset, /* offset */ + XtProcedureArg /* procedure to call */ +} XtAddressMode; + +typedef struct { + XtAddressMode address_mode; + XtPointer address_id; + Cardinal size; +} XtConvertArgRec, *XtConvertArgList; +</literallayout> +<para> +The <emphasis remap='I'>size</emphasis> field specifies the length of the data in bytes. +The <emphasis remap='I'>address_mode</emphasis> field specifies how the <emphasis remap='I'>address_id</emphasis> field should be +interpreted. +<function>XtAddress</function> +causes <emphasis remap='I'>address_id</emphasis> to be interpreted as the address of the data. +<function>XtBaseOffset</function> +causes <emphasis remap='I'>address_id</emphasis> to be interpreted as the offset from the widget base. +<function>XtImmediate</function> +causes <emphasis remap='I'>address_id</emphasis> to be interpreted as a constant. +<function>XtResourceString</function> +causes <emphasis remap='I'>address_id</emphasis> to be interpreted as the name of a resource +that is to be converted into an offset from the widget base. +<function>XtResourceQuark</function> +causes <emphasis remap='I'>address_id</emphasis> to be interpreted as the result of an +<function>XrmStringToQuark</function> +conversion on the name of a resource, +which is to be converted into an offset from the widget base. +<function>XtWidgetBaseOffset</function> +is similar to +<function>XtBaseOffset</function> +except that it +searches for the closest windowed ancestor if the object is not +of a subclass of +Core +(see <xref linkend='Nonwidget_Objects' />). +<function>XtProcedureArg</function> +specifies that <emphasis remap='I'>address_id</emphasis> is a pointer to a procedure to +be invoked to return the conversion argument. If +<function>XtProcedureArg</function> +is specified, <emphasis remap='I'>address_id</emphasis> must contain +the address of a function of type +<xref linkend='XtConvertArgProc' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtConvertArgProc'> +<funcprototype> +<funcdef>typedef void <function>(*XtConvertArgProc)</function></funcdef> + <paramdef>XtAppContext <parameter>app</parameter></paramdef> + <paramdef>XrmValue *<parameter>to</parameter></paramdef> + <paramdef>XtPointer <parameter>converter_data</parameter></paramdef> + <paramdef>XrmValue *<parameter>args</parameter></paramdef> + <paramdef>Cardinal *<parameter>num_args</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>app</emphasis> + </term> + <listitem> + <para> +Specifies an application context in which the resource is being freed. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>to</emphasis> + </term> + <listitem> + <para> +Specifies a descriptor for the resource produced by the type converter. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>converter_data</emphasis> + </term> + <listitem> + <para> +Specifies the converter-specific data returned by the type converter. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>args</emphasis> + </term> + <listitem> + <para> +Specifies the additional converter arguments as passed +to the type converter when the conversion was performed. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_args</emphasis> + </term> + <listitem> + <para> +Specifies the number of entries in <emphasis remap='I'>args</emphasis>. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The destructor procedure is responsible for freeing the resource +specified by the <emphasis remap='I'>to</emphasis> argument, including any auxiliary storage +associated with that resource, but not the memory directly addressed +by the size and location in the <emphasis remap='I'>to</emphasis> argument or the memory specified +by <emphasis remap='I'>args</emphasis>. +</para> +</sect2> + +<sect2 id="Resource_Converter_Invocation"> +<title>Resource Converter Invocation</title> +<para> +All resource-fetching routines (for example, +<xref linkend='XtGetSubresources' xrefstyle='select: title'/>, +<xref linkend='XtGetApplicationResources' xrefstyle='select: title'/>, +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. +</para> + +<para> +To invoke explicit resource conversions, use +<xref linkend='XtConvertAndStore' xrefstyle='select: title'/> +or +<xref linkend='XtCallConverter' xrefstyle='select: title'/>. +</para> +<literallayout > +typedef XtPointer XtCacheRef; +</literallayout> + +<funcsynopsis id='XtCallConverter'> +<funcprototype> +<funcdef>Boolean <function>XtCallConverter</function></funcdef> + <paramdef>Display* <parameter>display</parameter></paramdef> + <paramdef>XtTypeConverter <parameter>converter</parameter></paramdef> + <paramdef>XrmValuePtr <parameter>conversion_args</parameter></paramdef> + <paramdef>Cardinal <parameter>num_args</parameter></paramdef> + <paramdef>XrmValuePtr <parameter>from</parameter></paramdef> + <paramdef>XrmValuePtr <parameter>to_in_out</parameter></paramdef> + <paramdef>XtCacheRef *<parameter>cache_ref_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the display with which the conversion is to be associated. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>converter</emphasis> + </term> + <listitem> + <para> +Specifies the conversion procedure to be called. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>conversion_args</emphasis> + </term> + <listitem> + <para> +Specifies the additional conversion arguments needed +to perform the conversion, or NULL. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_args</emphasis> + </term> + <listitem> + <para> +Specifies the number of entries in <emphasis remap='I'>conversion_args</emphasis>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>from</emphasis> + </term> + <listitem> + <para> +Specifies a descriptor for the source value. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>to_in_out</emphasis> + </term> + <listitem> + <para> +Returns the converted value. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>cache_ref_return</emphasis> + </term> + <listitem> + <para> +Returns a conversion cache id. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The +<xref linkend='XtCallConverter' xrefstyle='select: title'/> +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 +<function>XtCacheAll</function> +or +<function>XtCacheByDisplay</function>, +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, +<xref linkend='XtCallConverter' xrefstyle='select: title'/> +returns +<function>False</function> +immediately; +otherwise it checks the size specified in the <emphasis remap='I'>to</emphasis> 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 +<emphasis remap='I'>to->addr</emphasis>, stores the cache size into <emphasis remap='I'>to->size</emphasis>, and returns +<function>True</function>. +If the size specified in the <emphasis remap='I'>to</emphasis> argument is smaller than the size stored +in the cache, +<xref linkend='XtCallConverter' xrefstyle='select: title'/> +copies the cache size into <emphasis remap='I'>to->size</emphasis> and returns +<function>False</function>. +If the converter was registered with cache type +<function>XtCacheNone</function> +or no value was found in the conversion cache, +<xref linkend='XtCallConverter' xrefstyle='select: title'/> +calls the converter, and if it was not registered with cache type +<function>XtCacheNone</function>, +enters the result in the cache. +<xref linkend='XtCallConverter' xrefstyle='select: title'/> +then returns what the converter returned. +</para> + +<para> +The <emphasis remap='I'>cache_ref_return</emphasis> field specifies storage allocated by the caller in which +an opaque value will be stored. If the type converter has been +registered with the +<function>XtCacheRefCount</function> +modifier and if the value returned +in <emphasis remap='I'>cache_ref_return</emphasis> is non-NULL, then the caller should store the +<emphasis remap='I'>cache_ref_return</emphasis> value in order to decrement the reference count when +the converted value is no longer required. The <emphasis remap='I'>cache_ref_return</emphasis> +argument should be +NULL if the caller is unwilling or unable to store the +value. +</para> + +<para> +To explicitly decrement the reference counts for resources obtained +from +<xref linkend='XtCallConverter' xrefstyle='select: title'/>, +use +<xref linkend='XtAppReleaseCacheRefs' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtAppReleaseCacheRefs'> +<funcprototype> +<funcdef>void <function>XtAppReleaseCacheRefs</function></funcdef> + <paramdef>XtAppContext <parameter>app_context</parameter></paramdef> + <paramdef>XtCacheRef *<parameter>refs</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>app_context</emphasis> + </term> + <listitem> + <para> +Specifies the application context. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>refs</emphasis> + </term> + <listitem> + <para> +Specifies the list of cache references to be released. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<xref linkend='XtAppReleaseCacheRefs' xrefstyle='select: title'/> +decrements the reference count for the +conversion entries identified by the <emphasis remap='I'>refs</emphasis> argument. +This argument is a +pointer to a NULL-terminated list of +<function>XtCacheRef</function> +values. If any reference +count reaches zero, the destructor, if any, will be called and +the resource removed from the conversion cache. +</para> + +<para> +As a convenience to clients needing to explicitly decrement reference +counts via a callback function, the Intrinsics define two callback +procedures, +<xref linkend='XtCallbackReleaseCacheRef' xrefstyle='select: title'/> +and +<xref linkend='XtCallbackReleaseCacheRefList' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtCallbackReleaseCacheRef'> +<funcprototype> +<funcdef>void <function>XtCallbackReleaseCacheRef</function></funcdef> + <paramdef>Widget <parameter>object</parameter></paramdef> + <paramdef>XtPointer <parameter>client_data</parameter></paramdef> + <paramdef>XtPointer <parameter>call_data</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>object</emphasis> + </term> + <listitem> + <para> +Specifies the object with which the resource is associated. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>client_data</emphasis> + </term> + <listitem> + <para> +Specifies the conversion cache entry to be released. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>call_data</emphasis> + </term> + <listitem> + <para> +Is ignored. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +This callback procedure may be added to a callback list to release a +previously returned +<function>XtCacheRef</function> +value. When adding the callback, the +callback <emphasis remap='I'>client_data</emphasis> argument must be specified as the value of the +<function>XtCacheRef</function> +data cast to type +<function>XtPointer</function>. +</para> + +<funcsynopsis id='XtCallbackReleaseCacheRefList'> +<funcprototype> +<funcdef>void <function>XtCallbackReleaseCacheRefList</function></funcdef> + <paramdef>Widget <parameter>object</parameter></paramdef> + <paramdef>XtPointer <parameter>client_data</parameter></paramdef> + <paramdef>XtPointer <parameter>call_data</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>object</emphasis> + </term> + <listitem> + <para> +Specifies the object with which the resources are associated. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>client_data</emphasis> + </term> + <listitem> + <para> +Specifies the conversion cache entries to be released. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>call_data</emphasis> + </term> + <listitem> + <para> +Is ignored. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +This callback procedure may be added to a callback list to release a +list of previously returned +<function>XtCacheRef</function> +values. When adding the +callback, the callback <emphasis remap='I'>client_data</emphasis> argument must be specified as a +pointer to a NULL-terminated list of +<function>XtCacheRef</function> +values. +</para> + +<para> +To lookup and call a resource converter, copy the resulting value, +and free a cached resource when a widget is destroyed, use +<xref linkend='XtConvertAndStore' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtConvertAndStore'> +<funcprototype> +<funcdef>Boolean <function>XtConvertAndStore</function></funcdef> + <paramdef>Widget <parameter>object</parameter></paramdef> + <paramdef>String <parameter>from_type</parameter></paramdef> + <paramdef>XrmValuePtr <parameter>from</parameter></paramdef> + <paramdef>String <parameter>to_type</parameter></paramdef> + <paramdef>XrmValuePtr <parameter>to_in_out</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>object</emphasis> + </term> + <listitem> + <para> +Specifies the object to use for additional arguments, if any are needed, +and the destroy callback list. Must be of class Object or any subclass thereof. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>from_type</emphasis> + </term> + <listitem> + <para> +Specifies the source type. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>from</emphasis> + </term> + <listitem> + <para> +Specifies the value to be converted. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>to_type</emphasis> + </term> + <listitem> + <para> +Specifies the destination type. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>to_in_out</emphasis> + </term> + <listitem> + <para> +Specifies a descriptor for storage into which the converted value +will be returned. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The +<xref linkend='XtConvertAndStore' xrefstyle='select: title'/> +function looks up the type converter registered +to convert <emphasis remap='I'>from_type</emphasis> to <emphasis remap='I'>to_type</emphasis>, computes any additional arguments +needed, and then calls +<xref linkend='XtCallConverter' xrefstyle='select: title'/> +(or +<xref linkend='XtDirectConvert' xrefstyle='select: title'/> +if an old-style converter was registered with +<xref linkend='XtAddConverter' xrefstyle='select: title'/> +or +<xref linkend='XtAppAddConverter' xrefstyle='select: title'/>; +see Appendix C) with the <emphasis remap='I'>from</emphasis> and <emphasis remap='I'>to_in_out</emphasis> arguments. The +<emphasis remap='I'>to_in_out</emphasis> 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 <emphasis remap='I'>size</emphasis> field will be modified on return to indicate the actual +size of the converted data. +If the conversion succeeds, +<xref linkend='XtConvertAndStore' xrefstyle='select: title'/> +returns +<function>True</function>; +otherwise, it returns +<function>False</function>. +</para> + +<para> +<xref linkend='XtConvertAndStore' xrefstyle='select: title'/> +adds +<xref linkend='XtCallbackReleaseCacheRef' xrefstyle='select: title'/> +to the destroyCallback list of the specified object if the conversion +returns an +<function>XtCacheRef</function> +value. The resulting resource should not be referenced +after the object has been destroyed. +</para> + +<para> +<xref linkend='XtCreateWidget' xrefstyle='select: title'/> +performs processing equivalent to +<xref linkend='XtConvertAndStore' xrefstyle='select: title'/> +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. +</para> + +<para> +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 +<function>Boolean</function> +resource +XtNinitialResourcesPersistent, +class +XtCInitialResourcesPersistent. +</para> + +<para> +When +<xref linkend='XtCreateWidget' xrefstyle='select: title'/> +is called, if this resource is not specified as +<function>False</function> +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 +<function>True</function>; +thus clients that expect to destroy one or +more objects and want resources deallocated must explicitly specify +<function>False</function> +for +XtNinitialResourcesPersistent. +</para> + +<para> +The resources are still freed and destructors called when +<xref linkend='XtCloseDisplay' xrefstyle='select: title'/> +is called if the conversion was registered as +<function>XtCacheByDisplay</function>. +</para> +</sect2> +</sect1> + +<sect1 id="Reading_and_Writing_Widget_State"> +<title>Reading and Writing Widget State</title> +<para> +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. +</para> +<sect2 id="Obtaining_Widget_State"> +<title>Obtaining Widget State</title> +<para> +To retrieve the current values of resources associated with a +widget instance, use +<xref linkend='XtGetValues' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtGetValues'> +<funcprototype> +<funcdef>void <function>XtGetValues</function></funcdef> + <paramdef>Widget <parameter>object</parameter></paramdef> + <paramdef>ArgList <parameter>args</parameter></paramdef> + <paramdef>Cardinal <parameter>num_args</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>object</emphasis> + </term> + <listitem> + <para> +Specifies the object whose resource values are to be returned. Must be of class Object or any subclass thereof. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>args</emphasis> + </term> + <listitem> + <para> +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. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_args</emphasis> + </term> + <listitem> + <para> +Specifies the number of entries in the argument list. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The +<xref linkend='XtGetValues' xrefstyle='select: title'/> +function starts with the resources specified for the Object class +and proceeds down the subclass chain to the class of the object. +The <emphasis remap='I'>value</emphasis> 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 +Intrinsics-defined resources, the following lifetimes apply: +</para> +<itemizedlist spacing='compact'> + <listitem> + <para> +Not valid following any operation that modifies the resource: + </para> + </listitem> + <listitem> + <itemizedlist spacing='compact'> + <listitem> + <para> +XtNchildren resource of composite widgets. + </para> + </listitem> + <listitem> + <para> +All resources of representation type XtRCallback. + </para> + </listitem> + </itemizedlist> + </listitem> + <listitem> + <para> +Remain valid at least until the widget is destroyed: + </para> + </listitem> + <listitem> + <itemizedlist spacing='compact'> + <listitem> + <para> +XtNaccelerators, XtNtranslations. + </para> + </listitem> + </itemizedlist> + </listitem> + <listitem> + <para> +Remain valid until the Display is closed: + </para> + </listitem> + <listitem> + <itemizedlist spacing='compact'> + <listitem> + <para> +XtNscreen. + </para> + </listitem> + </itemizedlist> + </listitem> +</itemizedlist> +<para> +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. +</para> + +<para> +If the class of the object's parent is a subclass of +<function>constraintWidgetClass</function>, +<xref linkend='XtGetValues' xrefstyle='select: title'/> +then fetches the values for any constraint resources requested. +It starts with the constraint resources specified for +<function>constraintWidgetClass</function> +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. +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 +<xref linkend='XtGetValues' xrefstyle='select: title'/>. +Finally, if the object's parent is a +subclass of +<function>constraintWidgetClass</function>, +and if any of the parent's class or +superclass records have declared +<function>ConstraintClassExtension</function> +records in +the Constraint class part <emphasis remap='I'>extension</emphasis> field with a record type of +<emphasis role='strong'>NULLQUARK</emphasis>, +and if the <emphasis remap='I'>get_values_hook</emphasis> field in the extension record is non-NULL, +<xref linkend='XtGetValues' xrefstyle='select: title'/> +calls the get_values_hook procedures in superclass-to-subclass order. +This permits a Constraint parent to provide +nonresource data via +<xref linkend='XtGetValues' xrefstyle='select: title'/>. +</para> + +<para> +Get_values_hook procedures may modify the data stored at the +location addressed by the <emphasis remap='I'>value</emphasis> field, including (but not +limited to) making a copy of data whose resource representation is a +pointer. None of the Intrinsics-defined object classes copy +data in this manner. Any operation that modifies the queried +object resource may invalidate the pointed-to data. +</para> + +<para> +To retrieve the current values of resources associated with a widget +instance using varargs lists, use +<xref linkend='XtVaGetValues' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtVaGetValues'> +<funcprototype> +<funcdef>void <function>XtVaGetValues</function></funcdef> + <paramdef>Widget <parameter>object</parameter></paramdef> + <paramdef><parameter>...</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>object</emphasis> + </term> + <listitem> + <para> +Specifies the object whose resource values are to be returned. Must be of class Object or any subclass thereof. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + ... + </term> + <listitem> + <para> +Specifies the variable argument list for the resources to +be returned. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<xref linkend='XtVaGetValues' xrefstyle='select: title'/> +is identical in function to +<xref linkend='XtGetValues' xrefstyle='select: title'/> +with the <emphasis remap='I'>args</emphasis> +and <emphasis remap='I'>num_args</emphasis> 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 +<function>XtVaTypedArg</function> +is specified, the <emphasis remap='I'>type</emphasis> argument +specifies the representation desired by the caller and <emphasis remap='I'>the</emphasis> 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. +</para> +<sect3 id="Widget_Subpart_Resource_Data_The_get_values_hook_Procedure"> +<title>Widget Subpart Resource Data: The get_values_hook Procedure</title> +<para> +Widgets that have subparts can return resource values from them through +<xref linkend='XtGetValues' xrefstyle='select: title'/> +by supplying a get_values_hook procedure. +The get_values_hook procedure pointer is of type +<xref linkend='XtArgsProc' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='_XtArgsProc'> +<funcprototype> +<funcdef>typedef void <function>(*XtArgsProc)</function></funcdef> + + <paramdef>Widget <parameter>w</parameter></paramdef> + <paramdef>ArgList <parameter>args</parameter></paramdef> + <paramdef>Cardinal *<parameter>num_args</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the widget whose subpart resource values are to be retrieved. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>args</emphasis> + </term> + <listitem> + <para> +Specifies the argument list that was passed to +<xref linkend='XtGetValues' xrefstyle='select: title'/> +or the transformed varargs list passed to +<xref linkend='XtVaGetValues' xrefstyle='select: title'/>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_args</emphasis> + </term> + <listitem> + <para> +Specifies the number of entries in the argument list. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The widget with subpart resources should call +<xref linkend='XtGetSubvalues' xrefstyle='select: title'/> +in the get_values_hook procedure +and pass in its subresource list and the <emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis> parameters. +</para> +</sect3> +<sect3 id="Widget_Subpart_State"> +<title>Widget Subpart State</title> +<para> +To retrieve the current values of subpart resource data associated with a +widget instance, use +<xref linkend='XtGetSubvalues' xrefstyle='select: title'/>. +For a discussion of subpart resources, +see <xref linkend='Subresources' />. +</para> + +<funcsynopsis id='XtGetSubvalues'> +<funcprototype> +<funcdef>void <function>XtGetSubvalues</function></funcdef> + <paramdef>XtPointer <parameter>base</parameter></paramdef> + <paramdef>XtResourceList <parameter>resources</parameter></paramdef> + <paramdef>Cardinal <parameter>num_resources</parameter></paramdef> + <paramdef>ArgList <parameter>args</parameter></paramdef> + <paramdef>Cardinal <parameter>num_args</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>base</emphasis> + </term> + <listitem> + <para> +Specifies the base address of the subpart data structure for which the +resources should be retrieved. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>resources</emphasis> + </term> + <listitem> + <para> +Specifies the subpart resource list. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_resources</emphasis> + </term> + <listitem> + <para> +Specifies the number of entries in the resource list. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>args</emphasis> + </term> + <listitem> + <para> +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. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_args</emphasis> + </term> + <listitem> + <para> +Specifies the number of entries in the argument list. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The +<xref linkend='XtGetSubvalues' xrefstyle='select: title'/> +function obtains resource values from the structure identified by <emphasis remap='I'>base</emphasis>. +The <emphasis remap='I'>value</emphasis> 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. +</para> + +<para> +To retrieve the current values of subpart resources associated with +a widget instance using varargs lists, use +<xref linkend='XtVaGetSubvalues' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtVaGetSubvalues'> +<funcprototype> +<funcdef>void <function>XtVaGetSubvalues</function></funcdef> + <paramdef>XtPointer <parameter>base</parameter></paramdef> + <paramdef>XtResourceList <parameter>resources</parameter></paramdef> + <paramdef>Cardinal <parameter>num_resources</parameter></paramdef> + <paramdef> <parameter>...</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>base</emphasis> + </term> + <listitem> + <para> +Specifies the base address of the subpart data structure for which the +resources should be retrieved. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>resources</emphasis> + </term> + <listitem> + <para> +Specifies the subpart resource list. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_resources</emphasis> + </term> + <listitem> + <para> +Specifies the number of entries in the resource list. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + ... + </term> + <listitem> + <para> +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. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<xref linkend='XtVaGetSubvalues' xrefstyle='select: title'/> +is identical in function to +<xref linkend='XtGetSubvalues' xrefstyle='select: title'/> +with the +<emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis> parameters replaced by a varargs list, as described +in Section 2.5.1. +<function>XtVaTypedArg</function> +is not supported for +<xref linkend='XtVaGetSubvalues' xrefstyle='select: title'/>. +If +<function>XtVaTypedArg</function> +is specified in the list, a warning message is issued +and the entry is then ignored. +</para> +</sect3> +</sect2> + +<sect2 id="Setting_Widget_State"> +<title>Setting Widget State</title> +<para> +To modify the current values of resources associated with a widget +instance, use +<xref linkend='XtSetValues' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtSetValues'> +<funcprototype> +<funcdef>void <function>XtSetValues</function></funcdef> + <paramdef>Widget <parameter>object</parameter></paramdef> + <paramdef>ArgList <parameter>args</parameter></paramdef> + <paramdef>Cardinal <parameter>num_args</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>object</emphasis> + </term> + <listitem> + <para> +Specifies the object whose resources are to be modified. Must be of class Object or any subclass thereof. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>args</emphasis> + </term> + <listitem> + <para> +Specifies the argument list of name/value pairs that contain the +resources to be modified and their new values. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_args</emphasis> + </term> + <listitem> + <para> +Specifies the number of entries in the argument list. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The +<xref linkend='XtSetValues' xrefstyle='select: title'/> +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 <emphasis remap='I'>object</emphasis> resource fields with any values +specified in the argument list. +<xref linkend='XtSetValues' xrefstyle='select: title'/> +then calls the set_values procedures for the object in superclass-to-subclass +order. +If the object has any non-NULL <emphasis remap='I'>set_values_hook</emphasis> fields, +these are called immediately after the +corresponding set_values procedure. +This procedure permits subclasses to set subpart data via +<xref linkend='XtSetValues' xrefstyle='select: title'/>. +</para> + +<para> +If the class of the object's parent is a subclass of +<function>constraintWidgetClass</function>, +<xref linkend='XtSetValues' xrefstyle='select: title'/> +also updates the object's constraints. +It starts with the constraint resources specified for +<function>constraintWidgetClass</function> +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 +<function>constraintWidgetClass</function> +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. +</para> + +<para> +If the object is of a subclass of +RectObj, +<xref linkend='XtSetValues' xrefstyle='select: title'/> +determines if a geometry request is needed by comparing the old object to +the new object. +If any geometry changes are required, +<xref linkend='XtSetValues' xrefstyle='select: title'/> +restores the original geometry and makes the request on behalf of the widget. +If the geometry manager returns +<function>XtGeometryYes</function>, +<xref linkend='XtSetValues' xrefstyle='select: title'/> +calls the object's resize procedure. +If the geometry manager returns +<function>XtGeometryDone</function>, +<xref linkend='XtSetValues' xrefstyle='select: title'/> +continues, as the object's resize procedure should have been called +by the geometry manager. +If the geometry manager returns +<function>XtGeometryNo</function>, +<xref linkend='XtSetValues' xrefstyle='select: title'/> +ignores the geometry request and continues. +If the geometry manager returns +<function>XtGeometryAlmost</function>, +<xref linkend='XtSetValues' xrefstyle='select: title'/> +calls the set_values_almost procedure, +which determines what should be done. +<xref linkend='XtSetValues' xrefstyle='select: title'/> +then repeats this process, +deciding once more whether the geometry manager should be called. +</para> + +<para> +Finally, if any of the set_values procedures returned +<function>True</function>, +and the widget is realized, +<xref linkend='XtSetValues' xrefstyle='select: title'/> +causes the widget's expose procedure to be invoked by calling +<function>XClearArea</function> +on the widget's window. +</para> + +<para> +To modify the current values of resources associated with a widget +instance using varargs lists, use +<xref linkend='XtVaSetValues' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtVaSetValues'> +<funcprototype> +<funcdef>void <function>XtVaSetValues</function></funcdef> + <paramdef>Widget <parameter>object</parameter></paramdef> + <paramdef> <parameter>...</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>object</emphasis> + </term> + <listitem> + <para> +Specifies the object whose resources are to be modified. Must be of class Object or any subclass thereof. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + ... + </term> + <listitem> + <para> +Specifies the variable argument list of name/value pairs that +contain the resources to be modified and their new values. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<xref linkend='XtVaSetValues' xrefstyle='select: title'/> +is identical in function to +<xref linkend='XtSetValues' xrefstyle='select: title'/> +with the <emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis> parameters replaced by a varargs list, as +described in Section 2.5.1. +</para> +<sect3 id="Widget_State_The_set_values_Procedure"> +<title>Widget State: The set_values Procedure</title> +<para> +The set_values procedure pointer in a widget class is of type +<xref linkend='XtSetValuesFunc' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtSetValuesFunc'> +<funcprototype> +<funcdef>typedef Boolean <function>(*XtSetValuesFunc)</function></funcdef> + + <paramdef>Widget <parameter>current</parameter></paramdef> + <paramdef>Widget <parameter>request</parameter></paramdef> + <paramdef>Widget <parameter>new</parameter></paramdef> + <paramdef>ArgList <parameter>args</parameter></paramdef> + <paramdef>Cardinal *<parameter>num_args</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>current</emphasis> + </term> + <listitem> + <para> +Specifies a copy of the widget as it was before the +<xref linkend='XtSetValues' xrefstyle='select: title'/> +call. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>request</emphasis> + </term> + <listitem> + <para> +Specifies a copy of the widget with all values changed as asked for by the +<xref linkend='XtSetValues' xrefstyle='select: title'/> +call before any class set_values procedures have been called. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>new</emphasis> + </term> + <listitem> + <para> +Specifies the widget with the new values that are actually allowed. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>args</emphasis> + </term> + <listitem> + <para> +Specifies the argument list passed to +<xref linkend='XtSetValues' xrefstyle='select: title'/> +or the transformed argument list passed to +<xref linkend='XtVaSetValues' xrefstyle='select: title'/>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_args</emphasis> + </term> + <listitem> + <para> +Specifies the number of entries in the argument list. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +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 <emphasis remap='I'>set_values</emphasis> field in the class record. +</para> + +<para> +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. +</para> + +<para> +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. +</para> + +<para> +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? +</para> + +<para> +The <emphasis remap='I'>request</emphasis> and <emphasis remap='I'>new</emphasis> parameters provide the necessary information. +The <emphasis remap='I'>request</emphasis> widget is a copy of the widget, updated as originally requested. +The <emphasis remap='I'>new</emphasis> 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 <emphasis remap='I'>request</emphasis> widget +unless it must resolve conflicts between the <emphasis remap='I'>current</emphasis> and <emphasis remap='I'>new</emphasis> widgets. +Any changes the widget needs to make, including geometry changes, +should be made in the <emphasis remap='I'>new</emphasis> widget. +</para> + +<para> +In the above example, +the subclass with the visual surround can see +if the <emphasis remap='I'>width</emphasis> and <emphasis remap='I'>height</emphasis> in the <emphasis remap='I'>request</emphasis> widget are zero. +If so, +it adds its surround size to the <emphasis remap='I'>width</emphasis> and +<emphasis remap='I'>height</emphasis> fields in the <emphasis remap='I'>new</emphasis> 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. +</para> + +<para> +The <emphasis remap='I'>new</emphasis> widget is the actual widget instance record. +Therefore, +the set_values procedure should do all its work on the <emphasis remap='I'>new</emphasis> widget; +the <emphasis remap='I'>request</emphasis> widget should never be modified. +If the set_values procedure needs to call any routines that operate on +a widget, it should specify <emphasis remap='I'>new</emphasis> as the widget instance. +</para> + +<para> +Before calling the set_values procedures, the Intrinsics modify the +resources of the <emphasis remap='I'>request</emphasis> 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 <emphasis remap='I'>args</emphasis>. +</para> + +<para> +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 +<function>True</function>; +the X server will eventually generate an +<function>Expose</function> +event, if necessary. +After calling all the set_values procedures, +<xref linkend='XtSetValues' xrefstyle='select: title'/> +forces a redisplay by calling +<function>XClearArea</function> +if any of the set_values procedures returned +<function>True</function>. +Therefore, a set_values procedure should not try to do its own redisplaying. +</para> + +<para> +Set_values procedures should not do any work in response to changes in +geometry because +<xref linkend='XtSetValues' xrefstyle='select: title'/> +eventually will perform a geometry request, and that request might be denied. +If the widget actually changes size in response to a +call to +<xref linkend='XtSetValues' xrefstyle='select: title'/>, +its resize procedure is called. +Widgets should do any geometry-related work in their resize procedure. +</para> + +<para> +Note that it is permissible to call +<xref linkend='XtSetValues' xrefstyle='select: title'/> +before a widget is realized. +Therefore, the set_values procedure must not assume that the widget is realized. +</para> +</sect3> +<sect3 id="Widget_State_The_set_values_almost_Procedure"> +<title>Widget State: The set_values_almost Procedure</title> +<para> +The set_values_almost procedure pointer in the widget class record is of type +<xref linkend='XtAlmostProc' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtAlmostProc'> +<funcprototype> +<funcdef>typedef void <function>(*XtAlmostProc)</function></funcdef> + + <paramdef>Widget <parameter>old</parameter></paramdef> + <paramdef>Widget <parameter>new</parameter></paramdef> + <paramdef>XtWidgetGeometry *<parameter>request</parameter></paramdef> + <paramdef>XtWidgetGeometry *<parameter>reply</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>old</emphasis> + </term> + <listitem> + <para> +Specifies a copy of the object as it was before the +<xref linkend='XtSetValues' xrefstyle='select: title'/> +call. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>new</emphasis> + </term> + <listitem> + <para> +Specifies the object instance record. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>request</emphasis> + </term> + <listitem> + <para> +Specifies the original geometry request that was sent to the geometry +manager that caused +<function>XtGeometryAlmost</function> +to be returned. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>reply</emphasis> + </term> + <listitem> + <para> +Specifies the compromise geometry that was returned by the geometry +manager with +<function>XtGeometryAlmost</function>. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +Most classes inherit the set_values_almost procedure from their superclass by +specifying +<function>XtInheritSetValuesAlmost</function> +in the class initialization. +The +set_values_almost procedure in +<function>rectObjClass</function> +accepts the compromise suggested. +</para> + +<para> +The set_values_almost procedure is called when a client tries to set a widget's +geometry by means of a call to +<xref linkend='XtSetValues' xrefstyle='select: title'/> +and the geometry manager cannot +satisfy the request but instead returns +<function>XtGeometryNo</function> +or +<function>XtGeometryAlmost</function> +and a compromise geometry. +The <emphasis remap='I'>new</emphasis> object is the actual instance record. The <emphasis remap='I'>x</emphasis>, <emphasis remap='I'>y</emphasis>, +<emphasis remap='I'>width</emphasis>, <emphasis remap='I'>height</emphasis>, +and <emphasis remap='I'>border_width</emphasis> fields contain the original values as they were +before the +<xref linkend='XtSetValues' xrefstyle='select: title'/> +call, and all other fields contain the new +values. The <emphasis remap='I'>request</emphasis> parameter contains the new geometry request that +was made to the parent. The <emphasis remap='I'>reply</emphasis> parameter contains +<emphasis remap='I'>reply->request_mode</emphasis> equal to zero if the parent returned +<function>XtGeometryNo</function> +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 <emphasis remap='I'>request</emphasis> 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 <emphasis remap='I'>reply</emphasis> geometry into the <emphasis remap='I'>request</emphasis> geometry; to attempt an +alternative geometry, the procedure may modify any part of the <emphasis remap='I'>request</emphasis> +argument; to terminate the geometry negotiation and retain the +original geometry, the procedure must set <emphasis remap='I'>request->request_mode</emphasis> to +zero. The geometry fields of the <emphasis remap='I'>old</emphasis> and <emphasis remap='I'>new</emphasis> instances must not be modified +directly. +</para> +</sect3> +<sect3 id="Widget_State_The_ConstraintClassPart_set_values_Procedure"> +<title>Widget State: The ConstraintClassPart set_values Procedure</title> +<para> +The constraint set_values procedure pointer is of type +<xref linkend='XtSetValuesFunc' xrefstyle='select: title'/>. +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 <emphasis remap='I'>set_values</emphasis> field of the +<function>ConstraintPart</function> +if it need not compute anything. +</para> + +<para> +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 <emphasis remap='I'>height</emphasis> field in the +widget. +</para> +</sect3> +<sect3 id='Widget_Subpart_State_2'> +<title>Widget Subpart State</title> +<para> +To set the current values of subpart resources associated with a +widget instance, use +<xref linkend='XtSetSubvalues' xrefstyle='select: title'/>. +For a discussion of subpart resources, +see <xref linkend='Subresources' />. +</para> + +<funcsynopsis id='XtSetSubvalues'> +<funcprototype> +<funcdef>void <function>XtSetSubvalues</function></funcdef> + <paramdef>XtPointer <parameter>base</parameter></paramdef> + <paramdef>XtResourceList <parameter>resources</parameter></paramdef> + <paramdef>Cardinal <parameter>num_resources</parameter></paramdef> + <paramdef>ArgList <parameter>args</parameter></paramdef> + <paramdef>Cardinal <parameter>num_args</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>base</emphasis> + </term> + <listitem> + <para> +Specifies the base address of the subpart data structure into which the +resources should be written. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>resources</emphasis> + </term> + <listitem> + <para> +Specifies the subpart resource list. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_resources</emphasis> + </term> + <listitem> + <para> +Specifies the number of entries in the resource list. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>args</emphasis> + </term> + <listitem> + <para> +Specifies the argument list of name/value pairs that contain the +resources to be modified and their new values. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_args</emphasis> + </term> + <listitem> + <para> +Specifies the number of entries in the argument list. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The +<xref linkend='XtSetSubvalues' xrefstyle='select: title'/> +function updates the resource fields of the structure identified by +<emphasis remap='I'>base</emphasis>. Any specified arguments that do not match an entry in the +resource list are silently ignored. +</para> + +<para> +To set the current values of subpart resources associated with +a widget instance using varargs lists, use +<xref linkend='XtVaSetSubvalues' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtVaSetSubvalues'> +<funcprototype> +<funcdef>void <function>XtVaSetSubvalues</function></funcdef> + <paramdef>XtPointer <parameter>base</parameter></paramdef> + <paramdef>XtResourceList <parameter>resources</parameter></paramdef> + <paramdef>Cardinal <parameter>num_resources</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>base</emphasis> + </term> + <listitem> + <para> +Specifies the base address of the subpart data structure into which the +resources should be written. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>resources</emphasis> + </term> + <listitem> + <para> +Specifies the subpart resource list. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_resources</emphasis> + </term> + <listitem> + <para> +Specifies the number of entries in the resource list. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + ... + </term> + <listitem> + <para> +Specifies the variable argument list of name/value pairs that +contain the resources to be modified and their new values. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<xref linkend='XtVaSetSubvalues' xrefstyle='select: title'/> +is identical in function to +<xref linkend='XtSetSubvalues' xrefstyle='select: title'/> +with the <emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis> parameters replaced by a varargs list, as +described in Section 2.5.1. +<function>XtVaTypedArg</function> +is not supported for +<xref linkend='XtVaSetSubvalues' xrefstyle='select: title'/>. +If an entry containing +<function>XtVaTypedArg</function> +is specified in the list, a warning message is issued +and the entry is ignored. +</para> +</sect3> + +<sect3 id='Widget_Subpart_Resource_Data_The_set_values_hook_Procedure'> +<title>Widget Subpart Resource Data: The set_values_hook Procedure</title> +<note><para> +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. +</para> +</note> +<para> +Widgets that have a subpart can set the subpart resource values through +<xref linkend='XtSetValues' xrefstyle='select: title'/> +by supplying a set_values_hook procedure. +The set_values_hook procedure pointer in a widget class is of type +<xref linkend='XtArgsFunc' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtArgsFunc'> +<funcprototype> +<funcdef>typedef Boolean <function>(*XtArgsFunc)</function></funcdef> + <paramdef>Widget <parameter>w</parameter></paramdef> + <paramdef>Arglist <parameter>args</parameter></paramdef> + <paramdef>Cardinal *<parameter>num_args</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the widget whose subpart resource values are to be changed. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>args</emphasis> + </term> + <listitem> + <para> +Specifies the argument list that was passed to +<xref linkend='XtSetValues' xrefstyle='select: title'/> +or the transformed varargs list passed to +<xref linkend='XtVaSetValues' xrefstyle='select: title'/>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_args</emphasis> + </term> + <listitem> + <para> +Specifies the number of entries in the argument list. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The widget with subpart resources may call +<xref linkend='XtSetValues' xrefstyle='select: title'/> +from the set_values_hook procedure +and pass in its subresource list and the +<emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis> parameters. +</para> +</sect3> +</sect2> +</sect1> +</chapter> |