# Resource Management

A resource is a field in the widget record with a corresponding resource entry in the resources list of the widget or any of its superclasses. This means that the field is settable by XtCreateWidget (by naming the field in the argument list), by an entry in a resource file (by using either the name or class), and by XtSetValues. In addition, it is readable by XtGetValues. Not all fields in a widget record are resources. Some are for bookkeeping use by the generic routines (like managed and being_destroyed). Others can be for local bookkeeping, and still others are derived from resources (many graphics contexts and pixmaps).

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 XtCreateWidget, some from the resource database, and some from the internal defaults specified by the widget. Resources are obtained first from the argument list, then from the resource database for all resources not specified in the argument list, and last, from the internal default, if needed.

## Resource Lists

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 `XtResource` structure is

    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;

When the resource list is specified as the `CoreClassPart`, `ObjectClassPart`, `RectObjClassPart`, or `ConstraintClassPart` resources field, the strings pointed to by resource_name, resource_class, resource_type, and default_type must be permanently allocated prior to or during the execution of the class initialization procedure and must not be subsequently deallocated.

The resource_name field contains the name used by clients to access the field in the widget. By convention, it starts with a lowercase letter and is spelled 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 `<X11/StringDefs.h>`. The Intrinsics's symbolic resource names begin with “XtN” and are followed by the string name (for example, XtNbackgroundPixel for backgroundPixel).

The resource_class field contains the class string used in resource specification files to identify the field. A resource class provides two functions:

- It isolates an application from different representations that widgets can use for a similar resource.

- 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.

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.

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:

    *Background:    ivory
    *Foreground:    darkblue

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:

    *Font:  6x13

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).

The resource_type 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 `String`) or the format of the resource default value (almost anything, but often `String`) to the desired physical representation (see Resource_Conversions). The Intrinsics define the following resource types:

Resource Type | Structure or Field Type
`XtRAcceleratorTable` | XtAccelerators
`XtRAtom` | Atom
`XtRBitmap` | Pixmap, depth=1
`XtRBoolean` | Boolean
`XtRBool` | Bool
`XtRCallback` | XtCallbackList
`XtRCardinal` | Cardinal
`XtRColor` | XColor
`XtRColormap` | Colormap
`XtRCommandArgArray` | String*
`XtRCursor` | Cursor
`XtRDimension` | Dimension
`XtRDirectoryString` | String
`XtRDisplay` | Display*
`XtREnum` | XtEnum
`XtREnvironmentArray` | String*
`XtRFile` | FILE*
`XtRFloat` | float
`XtRFont` | Font
`XtRFontSet` | XFontSet
`XtRFontStruct` | XFontStruct*
`XtRFunction` | (*)(Widget)
`XtRGeometry` | char*, format as defined by `XParseGeometry`
`XtRGravity` | int
`XtRInitialState` | int
`XtRInt` | int
`XtRLongBoolean` | long
`XtRObject` | Object
`XtRPixel` | Pixel
`XtRPixmap` | Pixmap
`XtRPointer` | XtPointer
`XtRPosition` | Position
`XtRRestartStyle` | unsigned char
`XtRScreen` | Screen*
`XtRShort` | short
`XtRSmcConn` | XtPointer
`XtRString` | String
`XtRStringArray` | String*
`XtRStringTable` | String*
`XtRTranslationTable` | XtTranslations
`XtRUnsignedChar` | unsigned char
`XtRVisual` | Visual*
`XtRWidget` | Widget
`XtRWidgetClass` | WidgetClass
`XtRWidgetList` | WidgetList
`XtRWindow` | Window

`<X11/StringDefs.h>` also defines the following resource types as a convenience for widgets, although they do not have any corresponding data type assigned: `XtREditMode`, `XtRJustify`, and `XtROrientation`.

The resource_size field is the size of the physical representation in bytes; you should specify it as `sizeof`(type) so that the compiler fills in the value. The resource_offset field is the offset in bytes of the field within the widget. You should use the XtOffsetOf macro to retrieve this value. The default_type field is the representation type of the default resource value. If default_type is different from resource_type and the default value is needed, the resource manager invokes a conversion procedure from default_type to resource_type. Whenever possible, the default type should be identical to the resource type in order to minimize widget creation time. However, there are sometimes no values of the type that the program can easily specify. In this case, it should be a value for which the converter is guaranteed to work (for example, `XtDefaultForeground` for a pixel resource). The default_addr field specifies the address of the default resource value. As a special case, if default_type is `XtRString`, then the value in the default_addr field is the pointer to the string rather than a pointer to the pointer. The default is used if a resource is not specified in the argument list or in the resource database or if the conversion from the representation type stored in the resource database fails, which can happen for various reasons (for example, a misspelled entry in a resource file).

Two special representation types (XtRImmediate and XtRCallProc) are usable only as default resource types. XtRImmediate indicates that the value in the default_addr field is the actual value of the resource rather than the address of the value. The value must be in the correct representation type for the resource, coerced to an `XtPointer`. No conversion is possible, since there is no source representation type. XtRCallProc indicates that the value in the default_addr field is a procedure pointer. This procedure is automatically invoked with the widget, resource_offset, and a pointer to an `XrmValue` in which to store the result. XtRCallProc procedure pointers are of type XtResourceDefaultProc.

    typedef void (*XtResourceDefaultProc)
       Widget w
       int offset
       XrmValue *value

w

- Specifies the widget whose resource value is to be obtained.

offset

- Specifies the offset of the field in the widget record.

value

- Specifies the resource value descriptor to return.

The XtResourceDefaultProc procedure should fill in the value->addr field with a pointer to the resource value in its correct representation type.

To get the resource list structure for a particular class, use XtGetResourceList.

    void XtGetResourceList

       WidgetClass class
       XtResourceList *resources_return
       Cardinal *num_resources_return

class

- Specifies the object class to be queried. It must be `objectClass` or any subclass thereof.

resources_return

- Returns the resource list.

num_resources_return

- Returns the number of entries in the resource list.

If XtGetResourceList is called before the class is initialized, it returns the resource list as specified in the class record. If it is called after the class has been initialized, XtGetResourceList returns a merged resource list that includes the resources for all superclasses. The list returned by XtGetResourceList should be freed using XtFree when it is no longer needed.

To get the constraint resource list structure for a particular widget class, use XtGetConstraintResourceList.

    void XtGetConstraintResourceList
       WidgetClass class
       XtResourceList *resources_return
       Cardinal *num_resources_return

class

- Specifies the object class to be queried. It must be `objectClass` or any subclass thereof.

resources_return

- Returns the constraint resource list.

num_resources_return

- Returns the number of entries in the constraint resource list.

If XtGetConstraintResourceList is called before the widget class is initialized, the resource list as specified in the widget class Constraint part is returned. If XtGetConstraintResourceList is called after the widget class has been initialized, the merged resource list for the class and all Constraint superclasses is returned. If the specified class is not a subclass of `constraintWidgetClass`, *resources_return is set to NULL and *num_resources_return is set to zero. The list returned by XtGetConstraintResourceList should be freed using XtFree when it is no longer needed.

The routines XtSetValues and XtGetValues also use the resource list to set and get widget state; see Obtaining_Widget_State and Setting_Widget_State.

Here is an abbreviated version of a possible resource list for a Label widget:

    /* 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},
            .
            .
            .
    }

The complete resource name for a field of a widget instance is the concatenation of the application shell name (from `XtAppCreateShell`), the instance names of all the widget's parents up to the top of the widget tree, the instance name of the widget itself, and the resource name of the specified field of the widget. Similarly, the full resource class of a field of a widget instance is the concatenation of the application class (from `XtAppCreateShell`), the widget class names of all the widget's parents up to the top of the widget tree, the widget class name of the widget itself, and the resource class of the specified field of the widget.

## Byte Offset Calculations

To determine the byte offset of a field within a structure type, use XtOffsetOf.

    Cardinal XtOffsetOf
          Type structure_type
          Field field_name

structure_type

- Specifies a type that is declared as a structure.

field_name

- Specifies the name of a member within the structure.

The XtOffsetOf macro expands to a constant expression that gives the offset in bytes to the specified structure member from the beginning of the structure. It is normally used to statically initialize resource lists and is more portable than XtOffset, which serves the same function.

To determine the byte offset of a field within a structure pointer type, use XtOffset.

    Cardinal XtOffset
          Type  pointer_type
          Field  field_name

pointer_type

- Specifies a type that is declared as a pointer to a structure.

field_name

- Specifies the name of a member within the structure.

The XtOffset macro expands to a constant expression that gives the offset in bytes to the specified structure member from the beginning of the structure. It may be used to statically initialize resource lists. XtOffset is less portable than XtOffsetOf.

## Superclass-to-Subclass Chaining of Resource Lists

The XtCreateWidget function gets resources as a superclass-to-subclass chained operation. That is, the resources specified in the `objectClass` resource list are fetched, then those in `rectObjClass`, and so on down to the resources specified for this widget's class. Within a class, resources are fetched in the order they are declared.

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 background_pixel. Consequently, the implementation of Label need not also have a resource entry for background_pixel. However, a subclass, by specifying a resource entry for that field in its own resource list, can override the resource entry for any field declared in a superclass. This is most often done to override the defaults provided in the superclass with new ones. At class initialization time, resource lists for that class are scanned from the superclass down to the class to look for resources with the same offset. A matching resource in a subclass will be reordered to override the superclass entry. If reordering is necessary, a copy of the superclass resource list is made to avoid affecting other subclasses of the superclass.

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.

## Subresources

A widget does not do anything to retrieve its own resources; instead, XtCreateWidget does this automatically before calling the class initialize procedure.

Some widgets have subparts that are not widgets but for which the widget would like to fetch resources. Such widgets call XtGetSubresources to accomplish this.

    void XtGetSubresources
       Widget w
       XtPointer base
       const char * name
       const char * class
       XtResourceList resources
       Cardinal num_resources
       ArgList args
       Cardinal num_args

w

- Specifies the object used to qualify the subpart resource name and class. Must be of class Object or any subclass thereof.

base

- Specifies the base address of the subpart data structure into which the resources will be written.

name

- Specifies the name of the subpart.

class

- Specifies the class of the subpart.

resources

- Specifies the resource list for the subpart.

num_resources

- Specifies the number of entries in the resource list.

args

- Specifies the argument list to override any other resource specifications.

num_args

- Specifies the number of entries in the argument list.

The XtGetSubresources function constructs a name and class list from the application name and class, the names and classes of all the object's ancestors, and the object itself. Then it appends to this list the name and class pair passed in. The resources are fetched from the argument list, the resource database, or the default values in the resource list. Then they are copied into the subpart record. If args is NULL, num_args must be zero. However, if num_args is zero, the argument list is not referenced.

XtGetSubresources may overwrite the specified resource list with an equivalent representation in an internal format, which optimizes access time if the list is used repeatedly. The resource list must be allocated in writable storage, and the caller must not modify the list contents after the call if the same list is to be used again. Resources fetched by XtGetSubresources are reference-counted as if they were referenced by the specified object. Subresources might therefore be freed from the conversion cache and destroyed when the object is destroyed, but not before then.

To fetch resources for widget subparts using varargs lists, use XtVaGetSubresources.

    void XtVaGetSubresources
       Widget w
       XtPointer base
       const char * name
       const char * class
       XtResourceList resources
       Cardinal num_resources
       ...

w

- Specifies the object used to qualify the subpart resource name and class. Must be of class Object or any subclass thereof.

base

- Specifies the base address of the subpart data structure into which the resources will be written.

name

- Specifies the name of the subpart.

class

- Specifies the class of the subpart.

resources

- Specifies the resource list for the subpart.

num_resources

- Specifies the number of entries in the resource list.

...

- Specifies the variable argument list to override any other resource specifications.

XtVaGetSubresources is identical in function to XtGetSubresources with the args and num_args parameters replaced by a varargs list, as described in Section 2.5.1.

## Obtaining Application Resources

To retrieve resources that are not specific to a widget but apply to the overall application, use XtGetApplicationResources.

    void XtGetApplicationResources
       Widget w
       XtPointer base
       XtResourceList resources
       Cardinal num_resources
       ArgList args
       Cardinal num_args

w

- 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.

base

- Specifies the base address into which the resource values will be written.

resources

- Specifies the resource list.

num_resources

- Specifies the number of entries in the resource list.

args

- Specifies the argument list to override any other resource specifications.

num_args

- Specifies the number of entries in the argument list.

The XtGetApplicationResources function first uses the passed object, which is usually an application shell widget, to construct a resource name and class list. The full name and class of the specified object (that is, including its ancestors, if any) is logically added to the front of each resource name and class. Then it retrieves the resources from the argument list, the resource database, or the resource list default values. After adding base to each address, XtGetApplicationResources copies the resources into the addresses obtained by adding base to each offset in the resource list. If args is NULL, num_args must be zero. However, if num_args is zero, the argument list is not referenced. The portable way to specify application resources is to declare them as members of a structure and pass the address of the structure as the base argument.

XtGetApplicationResources may overwrite the specified resource list with an equivalent representation in an internal format, which optimizes access time if the list is used repeatedly. The resource list must be allocated in writable storage, and the caller must not modify the list contents after the call if the same list is to be used again. Any per-display resources fetched by XtGetApplicationResources will not be freed from the resource cache until the display is closed.

To retrieve resources for the overall application using varargs lists, use XtVaGetApplicationResources.

    void XtVaGetApplicationResources
       Widget w
       XtPointer base
       XtResourceList resources
       Cardinal num_resources
       ...

w

- 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.

base

- Specifies the base address into which the resource values will be written.

resources

- Specifies the resource list for the subpart.

num_resources

- Specifies the number of entries in the resource list.

...

- Specifies the variable argument list to override any other resource specifications.

XtVaGetApplicationResources is identical in function to XtGetApplicationResources with the args and num_args parameters replaced by a varargs list, as described in Section 2.5.1.

## Resource Conversions

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:

- It permits user and application resource files to contain textual representations of nontextual values.

- 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.

- 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.

### Predefined Resource Converters

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 `XtRString`.

Target Representation | Converter Name | Additional Args
`XtRAcceleratorTable` | `XtCvtStringToAcceleratorTable`
`XtRAtom` | `XtCvtStringToAtom` | Display*
`XtRBoolean` | `XtCvtStringToBoolean`
`XtRBool` | `XtCvtStringToBool`
`XtRCommandArgArray` | `XtCvtStringToCommandArgArray`
`XtRCursor` | `XtCvtStringToCursor` | Display*
`XtRDimension` | `XtCvtStringToDimension`
`XtRDirectoryString` | `XtCvtStringToDirectoryString`
`XtRDisplay` | `XtCvtStringToDisplay`
`XtRFile` | `XtCvtStringToFile`
`XtRFloat` | `XtCvtStringToFloat`
`XtRFont` | `XtCvtStringToFont` | Display*
`XtRFontSet` | `XtCvtStringToFontSet` | Display*, String locale
`XtRFontStruct` | `XtCvtStringToFontStruct` | Display*
`XtRGravity` | `XtCvtStringToGravity`
`XtRInitialState` | `XtCvtStringToInitialState`
`XtRInt` | `XtCvtStringToInt`
`XtRPixel` | `XtCvtStringToPixel` | `colorConvertArgs`
`XtRPosition` | `XtCvtStringToPosition`
`XtRRestartStyle` | `XtCvtStringToRestartStyle`
`XtRShort` | `XtCvtStringToShort`
`XtRTranslationTable` | `XtCvtStringToTranslationTable`
`XtRUnsignedChar` | `XtCvtStringToUnsignedChar`
`XtRVisual` | `XtCvtStringToVisual` | Screen*, Cardinal depth

The String-to-Pixel conversion has two predefined constants that are guaranteed to work and contrast with each other: `XtDefaultForeground` and `XtDefaultBackground`. They evaluate to the black and white pixel values of the widget's screen, respectively. If the application resource reverseVideo is `True`, they evaluate to the white and black pixel values of the widget's screen, respectively. Similarly, the String-to-Font and String-to-FontStruct converters recognize the constant `XtDefaultFont` and evaluate this in the following manner:

- 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 `XtRString` value returned as the font name or a type `XtRFont` or `XtRFontStruct` value directly as the resource value.

- 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 `XListFonts` using a wildcard font name and use the first font in the list. This wildcard font name should be as broad as possible to maximize the probability of locating a usable font; for example, “`-*-*-*-R-*-*-*-120-*-*-*-*-ISO8859-1`”.)

- If no suitable ISO8859-1 font can be found, issue a warning message and return `False`.

The String-to-FontSet converter recognizes the constant `XtDefaultFontSet` and evaluate this in the following manner:

- 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 `XtRString` value returned as the base font name list or a type `XtRFontSet` value directly as the resource value.

- 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 `XCreateFontSet` using a wildcard base font name. This wildcard base font name should be as broad as possible to maximize the probability of locating a usable font; for example, “`-*-*-*-R-*-*-*-120-*-*-*-*`”.)

- If no suitable font set can be created, issue a warning message and return `False`.

If a font set is created but missing_charset_list 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.

The String-to-Gravity conversion accepts string values that are the names of window and bit gravities and their numerical equivalents, as defined in Xlib — C Language X Interface: `ForgetGravity`, `UnmapGravity`, `NorthWestGravity`, `NorthGravity`, `NorthEastGravity`, `WestGravity`, `CenterGravity`, `EastGravity`, `SouthWestGravity`, `SouthGravity`, `SouthEastGravity`, and `StaticGravity`. Alphabetic case is not significant in the conversion.

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.

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.

The String-to-RestartStyle conversion accepts the values `RestartIfRunning`, `RestartAnyway`, `RestartImmediately`, and `RestartNever` as defined by the X Session Management Protocol.

The String-to-InitialState conversion accepts the values `NormalState` or `IconicState` as defined by the Inter-Client Communication Conventions Manual.

The String-to-Visual conversion calls `XMatchVisualInfo` using the screen and depth 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 `XtRVisual` after the depth resource. The allowed string values are the visual class names defined in X Window System Protocol, Section 8; `StaticGray`, `StaticColor`, `TrueColor`, `GrayScale`, `PseudoColor`, and `DirectColor`.

The Intrinsics register the following resource converter that accepts an input value of representation type `XtRColor`.

Target Representation | Converter Name | Additional Args
`XtRPixel` | `XtCvtColorToPixel`

The Intrinsics register the following resource converters that accept input values of representation type `XtRInt`.

Target Representation | Converter Name | Additional Args
`XtRBoolean` | `XtCvtIntToBoolean`
`XtRBool` | `XtCvtIntToBool`
`XtRColor` | `XtCvtIntToColor` | `colorConvertArgs`
`XtRDimension` | `XtCvtIntToDimension`
`XtRFloat` | `XtCvtIntToFloat`
`XtRFont` | `XtCvtIntToFont`
`XtRPixel` | `XtCvtIntToPixel`
`XtRPixmap` | `XtCvtIntToPixmap`
`XtRPosition` | `XtCvtIntToPosition`
`XtRShort` | `XtCvtIntToShort`
`XtRUnsignedChar` | `XtCvtIntToUnsignedChar`

The Intrinsics register the following resource converter that accepts an input value of representation type `XtRPixel`.

Target Representation | Converter Name | Additional Args
`XtRColor` | `XtCvtPixelToColor`

### New Resource Converters

Type converters use pointers to `XrmValue` structures (defined in `<X11/Xresource.h>;` see Section 15.4 in Xlib — C Language X Interface) for input and output values.

    typedef struct {
           unsigned int size;
           XPointer addr;
    } XrmValue, *XrmValuePtr;

The addr field specifies the address of the data, and the size field gives the total number of significant bytes in the data. For values of type `String`, addr is the address of the first character and size includes the NULL-terminating byte.

A resource converter procedure pointer is of type XtTypeConverter.

    typedef Boolean (*XtTypeConverter)
       Display *display
       XrmValue *args
       Cardinal *num_args
       XrmValue *from
       XrmValue *to
       XtPointer *converter_data

display

- Specifies the display connection with which this conversion is associated.

args

- Specifies a list of additional `XrmValue` arguments to the converter if additional context is needed to perform the conversion, or NULL. For example, the String-to-Font converter needs the widget's display, and the String-to-Pixel converter needs the widget's screen and colormap.

num_args

- Specifies the number of entries in args.

from

- Specifies the value to convert.

to

- Specifies a descriptor for a location into which to store the converted value.

converter_data

- Specifies a location into which the converter may store converter-specific data associated with this conversion.

The display argument is normally used only when generating error messages, to identify the application context (with the function `XtDisplayToApplicationContext ).`

The to argument specifies the size and location into which the converter should store the converted value. If the addr field is NULL, the converter should allocate appropriate storage and store the size and location into the to descriptor. If the type converter allocates the storage, it remains under the ownership of the converter and must not be modified by the caller. The type converter is permitted to use static storage for this purpose, and therefore the caller must immediately copy the data upon return from the converter. If the addr field is not NULL, the converter must check the size field to ensure that sufficient space has been allocated before storing the converted value. If insufficient space is specified, the converter should update the size field with the number of bytes required and return `False` without modifying the data at the specified location. If sufficient space was allocated by the caller, the converter should update the size field with the number of bytes actually occupied by the converted value. For converted values of type `XtRString`, the size should include the NULL-terminating byte, if any. The converter may store any value in the location specified in converter_data; this value will be passed to the destructor, if any, when the resource is freed by the Intrinsics.

The converter must return `True` if the conversion was successful and `False` otherwise. If the conversion cannot be performed because of an improper source value, a warning message should also be issued with XtAppWarningMsg.

Most type converters just take the data described by the specified from argument and return data by writing into the location specified in the to argument. A few need other information, which is available in args. 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.

Note that if an address is written into to->addr, it cannot be that of a local variable of the converter because the data will not be valid after the converter returns. Static variables may be used, as in the following example. If the converter modifies the resource database, the changes affect any in-progress widget creation, XtGetApplicationResources, or XtGetSubresources in an implementation-defined manner; however, insertion of new entries or changes to existing entries is allowed and will not directly cause an error.

The following is an example of a converter that takes a `string` and converts it to a `Pixel`. Note that the display parameter is used only to generate error messages; the `Screen` conversion argument is still required to inform the Intrinsics that the converted value is a function of the particular display (and colormap).

    #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(
         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);
         }
    }

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 `XtDefaultForeground`, `XtDefaultBackground`, and `XtDefaultFont`.

To allow the Intrinsics to deallocate resources produced by type converters, a resource destructor procedure may also be provided.

A resource destructor procedure pointer is of type XtDestructor.

      typedef void (*XtDestructor)
       XtAppContext app
       XrmValue *to
       XtPointer converter_data
       XrmValue *args
       Cardinal *num_args

app

- Specifies an application context in which the resource is being freed.

to

- Specifies a descriptor for the resource produced by the type converter.

converter_data

- Specifies the converter-specific data returned by the type converter.

args

- Specifies the additional converter arguments as passed to the type converter when the conversion was performed.

num_args

- Specifies the number of entries in args.

The destructor procedure is responsible for freeing the resource specified by the to argument, including any auxiliary storage associated with that resource, but not the memory directly addressed by the size and location in the to argument or the memory specified by args.

### Issuing Conversion Warnings

The XtDisplayStringConversionWarning procedure is a convenience routine for resource type converters that convert from string values.

    void XtDisplayStringConversionWarning
       Display *display
       const char * from_value
       const char * to_type

display

- Specifies the display connection with which the conversion is associated.

from_value

- Specifies the string that could not be converted.

to_type

- Specifies the target representation type requested.

The XtDisplayStringConversionWarning procedure issues a warning message using XtAppWarningMsg with name “conversionError”, type “string”, class “XtToolkitError”, and the default message “Cannot convert "from_value" to type to_type”.

To issue other types of warning or error messages, the type converter should use XtAppWarningMsg or XtAppErrorMsg.

To retrieve the application context associated with a given display connection, use XtDisplayToApplicationContext.

    XtAppContext XtDisplayToApplicationContext
       Display *display

display

- Specifies an open and initialized display connection.

The XtDisplayToApplicationContext function returns the application context in which the specified display was initialized. If the display is not known to the Intrinsics, an error message is issued.

### Registering a New Resource Converter

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 `XtCacheType` argument.

    typedef int XtCacheType;

An `XtCacheType` field may contain one of the following values:

`XtCacheNone`

- 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.

`XtCacheAll`

- 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.

`XtCacheByDisplay`

- Specifies that the results of a previous conversion should be used as for `XtCacheAll` but the destructor will be called, if specified, if XtCloseDisplay is called for the display connection associated with the converted value, and the value will be removed from the conversion cache.

The qualifier `XtCacheRefCount` may be ORed with any of the above values. If `XtCacheRefCount` is specified, calls to XtCreateWidget, XtCreateManagedWidget, XtGetApplicationResources, and XtGetSubresources that use the converted value will be counted. When a widget using the converted value is destroyed, the count is decremented, and, if the count reaches zero, the destructor procedure will be called and the converted value will be removed from the conversion cache.

To register a type converter for all application contexts in a process, use XtSetTypeConverter, and to register a type converter in a single application context, use XtAppSetTypeConverter.

    void XtSetTypeConverter
       const char * from_type
       const char * to_type
       XtTypeConverter converter
       XtConvertArgList convert_args
       Cardinal num_args
       XtCacheType cache_type
       XtDestructor destructor

from_type

- Specifies the source type.

to_type

- Specifies the destination type.

converter

- Specifies the resource type converter procedure.

convert_args

- Specifies additional conversion arguments, or NULL.

num_args

- Specifies the number of entries in convert_args.

cache_type

- Specifies whether or not resources produced by this converter are shareable or display-specific and when they should be freed.

destructor

- 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.

    void XtAppSetTypeConverter
       XtAppContext app_context
       const char * from_type
       const char * to_type
       XtTypeConverter converter
       XtConvertArgList convert_args
       Cardinal num_args
       XtCacheType cache_type
       XtDestructor destructor

app_context

- Specifies the application context.

from_type

- Specifies the source type.

to_type

- Specifies the destination type.

converter

- Specifies the resource type converter procedure.

convert_args

- Specifies additional conversion arguments, or NULL.

num_args

- Specifies the number of entries in convert_args.

cache_type

- Specifies whether or not resources produced by this converter are shareable or display-specific and when they should be freed.

destructor

- 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.

XtSetTypeConverter registers the specified type converter and destructor in all application contexts created by the calling process, including any future application contexts that may be created. XtAppSetTypeConverter registers the specified type converter in the single application context specified. If the same from_type and to_type are specified in multiple calls to either function, the most recent overrides the previous ones.

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 `XtAddressMode` and the structure `XtConvertArgRec` specify how each argument is derived. These are defined in `<X11/Intrinsic.h>`.

    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;

The size field specifies the length of the data in bytes. The address_mode field specifies how the address_id field should be interpreted. `XtAddress` causes address_id to be interpreted as the address of the data. `XtBaseOffset` causes address_id to be interpreted as the offset from the widget base. `XtImmediate` causes address_id to be interpreted as a constant. `XtResourceString` causes address_id to be interpreted as the name of a resource that is to be converted into an offset from the widget base. `XtResourceQuark` causes address_id to be interpreted as the result of an `XrmStringToQuark` conversion on the name of a resource, which is to be converted into an offset from the widget base. `XtWidgetBaseOffset` is similar to `XtBaseOffset` except that it searches for the closest windowed ancestor if the object is not of a subclass of Core (see Nonwidget_Objects). `XtProcedureArg` specifies that address_id is a pointer to a procedure to be invoked to return the conversion argument. If `XtProcedureArg` is specified, address_id must contain the address of a function of type XtConvertArgProc.

    typedef void (*XtConvertArgProc)
       Widget object
       Cardinal *size
       XrmValue *value

object

- Passes the object for which the resource is being converted, or NULL if the converter was invoked by XtCallConverter or XtDirectConvert.

size

- Passes a pointer to the size field from the XtConvertArgRec.

value

- Passes a pointer to a descriptor into which the procedure must store the conversion argument.

When invoked, the `XtConvertArgProc` procedure must derive a conversion argument and store the address and size of the argument in the location pointed to by value.

In order to permit reentrancy, the `XtConvertArgProc` should return the address of storage whose lifetime is no shorter than the lifetime of object. If object is NULL, the lifetime of the conversion argument must be no shorter than the lifetime of the resource with which the conversion argument is associated. The Intrinsics do not guarantee to copy this storage but do guarantee not to reference it if the resource is removed from the conversion cache.

The following example illustrates how to register the `CvtStringToPixel` routine given earlier:

    static XtConvertArgRec colorConvertArgs[] = {
      {XtWidgetBaseOffset,
       (XtPointer)XtOffset(Widget, core.screen),
       sizeof(Screen*)},
      {XtWidgetBaseOffset,
       (XtPointer)XtOffset(Widget, core.colormap),
       sizeof(Colormap)}
    };

    XtSetTypeConverter(XtRString,
                       XtRPixel,
                       CvtStringToPixel,
                       colorConvertArgs,
                       XtNumber(colorConvertArgs),
                       XtCacheByDisplay, NULL);

The conversion argument descriptors colorConvertArgs and screenConvertArg are predefined by the Intrinsics. Both take the values from the closest windowed ancestor if the object is not of a subclass of Core. The screenConvertArg descriptor puts the widget’s screen field into args[0]. The colorConvertArgs descriptor puts the widget’s screen field into args[0], and the widget’s colormap field into args[1].

Conversion routines should not just put a descriptor for the address of the base of the widget into args[0], and use that in the routine. They should pass in the actual values on which the conversion depends. By keeping the dependencies of the conversion procedure specific, it is more likely that subsequent conversions will find what they need in the conversion cache. This way the cache is smaller and has fewer and more widely applicable entries.

If any conversion arguments of type `XtBaseOffset`, `XtResourceString`, `XtResourceQuark`, and `XtWidgetBaseOffset` are specified for conversions performed by `XtGetApplicationResources`, `XtGetSubresources`, `XtVaGetApplicationResources`, or `XtVaGetSubresources`, the arguments are computed with respect to the specified widget, not the base address or resource list specified in the call.

If the `XtConvertArgProc` modifies the resource database, the changes affect any in-progress widget creation, XtGetApplicationResources, or XtGetSubresources in an implementation-defined manner; however, insertion of new entries or changes to existing entries are allowed and will not directly cause an error.

### Resource Converter Invocation

All resource-fetching routines (for example, XtGetSubresources, XtGetApplicationResources, and so on) call resource converters if the resource database or varargs list specifies a value that has a different representation from the desired representation or if the widget's default resource value representation is different from the desired representation.

To invoke explicit resource conversions, use XtConvertAndStore or XtCallConverter.

    typedef XtPointer XtCacheRef;

    Boolean  XtCallConverter
       Display* display
       XtTypeConverter converter
       XrmValuePtr conversion_args
       Cardinal num_args
       XrmValuePtr from
       XrmValuePtr to_in_out
       XtCacheRef *cache_ref_return

display

- Specifies the display with which the conversion is to be associated.

converter

- Specifies the conversion procedure to be called.

conversion_args

- Specifies the additional conversion arguments needed to perform the conversion, or NULL.

num_args

- Specifies the number of entries in conversion_args.

from

- Specifies a descriptor for the source value.

to_in_out

- Returns the converted value.

cache_ref_return

- Returns a conversion cache id.

The XtCallConverter function looks up the specified type converter in the application context associated with the display and, if the converter was not registered or was registered with cache type `XtCacheAll` or `XtCacheByDisplay`, looks in the conversion cache to see if this conversion procedure has been called with the specified conversion arguments. If so, it checks the success status of the prior call, and if the conversion failed, XtCallConverter returns `False` immediately; otherwise it checks the size specified in the to argument, and, if it is greater than or equal to the size stored in the cache, copies the information stored in the cache into the location specified by to->addr, stores the cache size into to->size, and returns `True`. If the size specified in the to argument is smaller than the size stored in the cache, XtCallConverter copies the cache size into to->size and returns `False`. If the converter was registered with cache type `XtCacheNone` or no value was found in the conversion cache, XtCallConverter calls the converter, and if it was not registered with cache type `XtCacheNone`, enters the result in the cache. XtCallConverter then returns what the converter returned.

The cache_ref_return field specifies storage allocated by the caller in which an opaque value will be stored. If the type converter has been registered with the `XtCacheRefCount` modifier and if the value returned in cache_ref_return is non-NULL, then the caller should store the cache_ref_return value in order to decrement the reference count when the converted value is no longer required. The cache_ref_return argument should be NULL if the caller is unwilling or unable to store the value.

To explicitly decrement the reference counts for resources obtained from XtCallConverter, use XtAppReleaseCacheRefs.

    void XtAppReleaseCacheRefs
       XtAppContext app_context
       XtCacheRef *refs

app_context

- Specifies the application context.

refs

- Specifies the list of cache references to be released.

XtAppReleaseCacheRefs decrements the reference count for the conversion entries identified by the refs argument. This argument is a pointer to a NULL-terminated list of `XtCacheRef` values. If any reference count reaches zero, the destructor, if any, will be called and the resource removed from the conversion cache.

As a convenience to clients needing to explicitly decrement reference counts via a callback function, the Intrinsics define two callback procedures, XtCallbackReleaseCacheRef and XtCallbackReleaseCacheRefList.

    void XtCallbackReleaseCacheRef
       Widget object
       XtPointer client_data
       XtPointer call_data

object

- Specifies the object with which the resource is associated.

client_data

- Specifies the conversion cache entry to be released.

call_data

- Is ignored.

This callback procedure may be added to a callback list to release a previously returned `XtCacheRef` value. When adding the callback, the callback client_data argument must be specified as the value of the `XtCacheRef` data cast to type `XtPointer`.

    void XtCallbackReleaseCacheRefList
       Widget object
       XtPointer client_data
       XtPointer call_data

object

- Specifies the object with which the resources are associated.

client_data

- Specifies the conversion cache entries to be released.

call_data

- Is ignored.

This callback procedure may be added to a callback list to release a list of previously returned `XtCacheRef` values. When adding the callback, the callback client_data argument must be specified as a pointer to a NULL-terminated list of `XtCacheRef` values.

To lookup and call a resource converter, copy the resulting value, and free a cached resource when a widget is destroyed, use XtConvertAndStore.

    Boolean XtConvertAndStore
       Widget object
       const char * from_type
       XrmValuePtr from
       const char * to_type
       XrmValuePtr to_in_out

object

- 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.

from_type

- Specifies the source type.

from

- Specifies the value to be converted.

to_type

- Specifies the destination type.

to_in_out

- Specifies a descriptor for storage into which the converted value will be returned.

The XtConvertAndStore function looks up the type converter registered to convert from_type to to_type, computes any additional arguments needed, and then calls XtCallConverter (or XtDirectConvert if an old-style converter was registered with XtAddConverter or XtAppAddConverter; see Appendix C) with the from and to_in_out arguments. The to_in_out argument specifies the size and location into which the converted value will be stored and is passed directly to the converter. If the location is specified as NULL, it will be replaced with a pointer to private storage and the size will be returned in the descriptor. The caller is expected to copy this private storage immediately and must not modify it in any way. If a non-NULL location is specified, the caller must allocate sufficient storage to hold the converted value and must also specify the size of that storage in the descriptor. The size field will be modified on return to indicate the actual size of the converted data. If the conversion succeeds, XtConvertAndStore returns `True`; otherwise, it returns `False`.

XtConvertAndStore adds XtCallbackReleaseCacheRef to the destroyCallback list of the specified object if the conversion returns an `XtCacheRef` value. The resulting resource should not be referenced after the object has been destroyed.

XtCreateWidget performs processing equivalent to XtConvertAndStore when initializing the object instance. Because there is extra memory overhead required to implement reference counting, clients may distinguish those objects that are never destroyed before the application exits from those that may be destroyed and whose resources should be deallocated.

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 `Boolean` resource XtNinitialResourcesPersistent, class XtCInitialResourcesPersistent.

When XtCreateWidget is called, if this resource is not specified as `False` in either the arglist or the resource database, then the resources referenced by this object are not reference-counted, regardless of how the type converter may have been registered. The effective default value is `True`; thus clients that expect to destroy one or more objects and want resources deallocated must explicitly specify `False` for XtNinitialResourcesPersistent.

The resources are still freed and destructors called when XtCloseDisplay is called if the conversion was registered as `XtCacheByDisplay`.

## Reading and Writing Widget State

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.

### Obtaining Widget State

To retrieve the current values of resources associated with a widget instance, use XtGetValues.

    void XtGetValues
       Widget object
       ArgList args
       Cardinal num_args

object

- Specifies the object whose resource values are to be returned. Must be of class Object or any subclass thereof.

args

- 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.

num_args

- Specifies the number of entries in the argument list.

The XtGetValues function starts with the resources specified for the Object class and proceeds down the subclass chain to the class of the object. The value 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:

- Not valid following any operation that modifies the resource:

  - XtNchildren resource of composite widgets.

  - All resources of representation type XtRCallback.

- Remain valid at least until the widget is destroyed:

  - XtNaccelerators, XtNtranslations.

- Remain valid until the Display is closed:

  - XtNscreen.

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.

If the class of the object's parent is a subclass of `constraintWidgetClass`, XtGetValues then fetches the values for any constraint resources requested. It starts with the constraint resources specified for `constraintWidgetClass` and proceeds down the subclass chain to the parent's constraint resources. If the argument list contains a resource name that is not found in any of the resource lists searched, the value at the corresponding address is not modified. 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 XtGetValues. Finally, if the object's parent is a subclass of `constraintWidgetClass`, and if any of the parent's class or superclass records have declared `ConstraintClassExtension` records in the Constraint class part extension field with a record type of NULLQUARK, and if the get_values_hook field in the extension record is non-NULL, XtGetValues calls the get_values_hook procedures in superclass-to-subclass order. This permits a Constraint parent to provide nonresource data via XtGetValues.

Get_values_hook procedures may modify the data stored at the location addressed by the value 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.

To retrieve the current values of resources associated with a widget instance using varargs lists, use XtVaGetValues.

    void XtVaGetValues
       Widget object
       ...

object

- Specifies the object whose resource values are to be returned. Must be of class Object or any subclass thereof.

...

- Specifies the variable argument list for the resources to be returned.

XtVaGetValues is identical in function to XtGetValues with the args and num_args 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 `XtVaTypedArg` is specified, the type argument specifies the representation desired by the caller and the 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.

#### Widget Subpart Resource Data: The get_values_hook Procedure

Widgets that have subparts can return resource values from them through XtGetValues by supplying a get_values_hook procedure. The get_values_hook procedure pointer is of type XtArgsProc.

    typedef void (*XtArgsProc)

       Widget w
       ArgList args
       Cardinal *num_args

w

- Specifies the widget whose subpart resource values are to be retrieved.

args

- Specifies the argument list that was passed to XtGetValues or the transformed varargs list passed to XtVaGetValues.

num_args

- Specifies the number of entries in the argument list.

The widget with subpart resources should call XtGetSubvalues in the get_values_hook procedure and pass in its subresource list and the args and num_args parameters.

#### Widget Subpart State

To retrieve the current values of subpart resource data associated with a widget instance, use XtGetSubvalues. For a discussion of subpart resources, see Subresources.

    void XtGetSubvalues
       XtPointer base
       XtResourceList resources
       Cardinal num_resources
       ArgList args
       Cardinal num_args

base

- Specifies the base address of the subpart data structure for which the resources should be retrieved.

resources

- Specifies the subpart resource list.

num_resources

- Specifies the number of entries in the resource list.

args

- 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.

num_args

- Specifies the number of entries in the argument list.

The XtGetSubvalues function obtains resource values from the structure identified by base. The value 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.

To retrieve the current values of subpart resources associated with a widget instance using varargs lists, use XtVaGetSubvalues.

    void XtVaGetSubvalues
       XtPointer base
       XtResourceList resources
       Cardinal num_resources
        ...

base

- Specifies the base address of the subpart data structure for which the resources should be retrieved.

resources

- Specifies the subpart resource list.

num_resources

- Specifies the number of entries in the resource list.

...

- 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.

XtVaGetSubvalues is identical in function to XtGetSubvalues with the args and num_args parameters replaced by a varargs list, as described in Section 2.5.1. `XtVaTypedArg` is not supported for XtVaGetSubvalues. If `XtVaTypedArg` is specified in the list, a warning message is issued and the entry is then ignored.

### Setting Widget State

To modify the current values of resources associated with a widget instance, use XtSetValues.

    void XtSetValues
       Widget object
       ArgList args
       Cardinal num_args

object

- Specifies the object whose resources are to be modified. Must be of class Object or any subclass thereof.

args

- Specifies the argument list of name/value pairs that contain the resources to be modified and their new values.

num_args

- Specifies the number of entries in the argument list.

The XtSetValues function starts with the resources specified for the Object class fields and proceeds down the subclass chain to the object. At each stage, it replaces the object resource fields with any values specified in the argument list. XtSetValues then calls the set_values procedures for the object in superclass-to-subclass order. If the object has any non-NULL set_values_hook fields, these are called immediately after the corresponding set_values procedure. This procedure permits subclasses to set subpart data via XtSetValues.

If the class of the object's parent is a subclass of `constraintWidgetClass`, XtSetValues also updates the object's constraints. It starts with the constraint resources specified for `constraintWidgetClass` and proceeds down the subclass chain to the parent's class. At each stage, it replaces the constraint resource fields with any values specified in the argument list. It then calls the constraint set_values procedures from `constraintWidgetClass` down to the parent's class. The constraint set_values procedures are called with widget arguments, as for all set_values procedures, not just the constraint records, so that they can make adjustments to the desired values based on full information about the widget. Any arguments specified that do not match a resource list entry are silently ignored.

If the object is of a subclass of RectObj, XtSetValues determines if a geometry request is needed by comparing the old object to the new object. If any geometry changes are required, XtSetValues restores the original geometry and makes the request on behalf of the widget. If the geometry manager returns `XtGeometryYes`, XtSetValues calls the object's resize procedure. If the geometry manager returns `XtGeometryDone`, XtSetValues continues, as the object's resize procedure should have been called by the geometry manager. If the geometry manager returns `XtGeometryNo`, XtSetValues ignores the geometry request and continues. If the geometry manager returns `XtGeometryAlmost`, XtSetValues calls the set_values_almost procedure, which determines what should be done. XtSetValues then repeats this process, deciding once more whether the geometry manager should be called.

Finally, if any of the set_values procedures returned `True`, and the widget is realized, XtSetValues causes the widget's expose procedure to be invoked by calling `XClearArea` on the widget's window.

To modify the current values of resources associated with a widget instance using varargs lists, use XtVaSetValues.

    void XtVaSetValues
       Widget object
        ...

object

- Specifies the object whose resources are to be modified. Must be of class Object or any subclass thereof.

...

- Specifies the variable argument list of name/value pairs that contain the resources to be modified and their new values.

XtVaSetValues is identical in function to XtSetValues with the args and num_args parameters replaced by a varargs list, as described in Section 2.5.1.

#### Widget State: The set_values Procedure

The set_values procedure pointer in a widget class is of type XtSetValuesFunc.

    typedef Boolean (*XtSetValuesFunc)

       Widget current
       Widget request
       Widget new
       ArgList args
       Cardinal *num_args

current

- Specifies a copy of the widget as it was before the XtSetValues call.

request

- Specifies a copy of the widget with all values changed as asked for by the XtSetValues call before any class set_values procedures have been called.

new

- Specifies the widget with the new values that are actually allowed.

args

- Specifies the argument list passed to XtSetValues or the transformed argument list passed to XtVaSetValues.

num_args

- Specifies the number of entries in the argument list.

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 set_values field in the class record.

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.

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.

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?

The request and new parameters provide the necessary information. The request widget is a copy of the widget, updated as originally requested. The new 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 request widget unless it must resolve conflicts between the current and new widgets. Any changes the widget needs to make, including geometry changes, should be made in the new widget.

In the above example, the subclass with the visual surround can see if the width and height in the request widget are zero. If so, it adds its surround size to the width and height fields in the new widget. If not, it must make do with the size originally specified. In this case, zero is a special value defined by the class to permit the application to invoke this behavior.

The new widget is the actual widget instance record. Therefore, the set_values procedure should do all its work on the new widget; the request widget should never be modified. If the set_values procedure needs to call any routines that operate on a widget, it should specify new as the widget instance.

Before calling the set_values procedures, the Intrinsics modify the resources of the request widget according to the contents of the arglist; if the widget names all its resources in the class resource list, it is never necessary to examine the contents of args.

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 `True`; the X server will eventually generate an `Expose` event, if necessary. After calling all the set_values procedures, XtSetValues forces a redisplay by calling `XClearArea` if any of the set_values procedures returned `True`. Therefore, a set_values procedure should not try to do its own redisplaying.

Set_values procedures should not do any work in response to changes in geometry because XtSetValues eventually will perform a geometry request, and that request might be denied. If the widget actually changes size in response to a call to XtSetValues, its resize procedure is called. Widgets should do any geometry-related work in their resize procedure.

Note that it is permissible to call XtSetValues before a widget is realized. Therefore, the set_values procedure must not assume that the widget is realized.

#### Widget State: The set_values_almost Procedure

The set_values_almost procedure pointer in the widget class record is of type XtAlmostProc.

    typedef void (*XtAlmostProc)

       Widget old
       Widget new
       XtWidgetGeometry *request
       XtWidgetGeometry *reply

old

- Specifies a copy of the object as it was before the XtSetValues call.

new

- Specifies the object instance record.

request

- Specifies the original geometry request that was sent to the geometry manager that caused `XtGeometryAlmost` to be returned.

reply

- Specifies the compromise geometry that was returned by the geometry manager with `XtGeometryAlmost`.

Most classes inherit the set_values_almost procedure from their superclass by specifying `XtInheritSetValuesAlmost` in the class initialization. The set_values_almost procedure in `rectObjClass` accepts the compromise suggested.

The set_values_almost procedure is called when a client tries to set a widget's geometry by means of a call to XtSetValues and the geometry manager cannot satisfy the request but instead returns `XtGeometryNo` or `XtGeometryAlmost` and a compromise geometry. The new object is the actual instance record. The x, y, width, height, and border_width fields contain the original values as they were before the XtSetValues call, and all other fields contain the new values. The request parameter contains the new geometry request that was made to the parent. The reply parameter contains reply->request_mode equal to zero if the parent returned `XtGeometryNo` and contains the parent's compromise geometry otherwise. The set_values_almost procedure takes the original geometry and the compromise geometry and determines if the compromise is acceptable or whether to try a different compromise. It returns its results in the request parameter, which is then sent back to the geometry manager for another try. To accept the compromise, the procedure must copy the contents of the reply geometry into the request geometry; to attempt an alternative geometry, the procedure may modify any part of the request argument; to terminate the geometry negotiation and retain the original geometry, the procedure must set request->request_mode to zero. The geometry fields of the old and new instances must not be modified directly.

#### Widget State: The ConstraintClassPart set_values Procedure

The constraint set_values procedure pointer is of type XtSetValuesFunc. The values passed to the parent's constraint set_values procedure are the same as those passed to the child's class set_values procedure. A class can specify NULL for the set_values field of the `ConstraintPart` if it need not compute anything.

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 height field in the widget.

#### Widget Subpart State

To set the current values of subpart resources associated with a widget instance, use XtSetSubvalues. For a discussion of subpart resources, see Subresources.

    void XtSetSubvalues
       XtPointer base
       XtResourceList resources
       Cardinal num_resources
       ArgList args
       Cardinal num_args

base

- Specifies the base address of the subpart data structure into which the resources should be written.

resources

- Specifies the subpart resource list.

num_resources

- Specifies the number of entries in the resource list.

args

- Specifies the argument list of name/value pairs that contain the resources to be modified and their new values.

num_args

- Specifies the number of entries in the argument list.

The XtSetSubvalues function updates the resource fields of the structure identified by base. Any specified arguments that do not match an entry in the resource list are silently ignored.

To set the current values of subpart resources associated with a widget instance using varargs lists, use XtVaSetSubvalues.

    void XtVaSetSubvalues
       XtPointer base
       XtResourceList resources
       Cardinal num_resources
       ...

base

- Specifies the base address of the subpart data structure into which the resources should be written.

resources

- Specifies the subpart resource list.

num_resources

- Specifies the number of entries in the resource list.

...

- Specifies the variable argument list of name/value pairs that contain the resources to be modified and their new values.

XtVaSetSubvalues is identical in function to XtSetSubvalues with the args and num_args parameters replaced by a varargs list, as described in Section 2.5.1. `XtVaTypedArg` is not supported for XtVaSetSubvalues. If an entry containing `XtVaTypedArg` is specified in the list, a warning message is issued and the entry is ignored.

#### Widget Subpart Resource Data: The set_values_hook Procedure

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.

Widgets that have a subpart can set the subpart resource values through XtSetValues by supplying a set_values_hook procedure. The set_values_hook procedure pointer in a widget class is of type XtArgsFunc.

    typedef Boolean (*XtArgsFunc)
       Widget w
       Arglist args
       Cardinal *num_args

w

- Specifies the widget whose subpart resource values are to be changed.

args

- Specifies the argument list that was passed to XtSetValues or the transformed varargs list passed to XtVaSetValues.

num_args

- Specifies the number of entries in the argument list.

The widget with subpart resources may call XtSetValues from the set_values_hook procedure and pass in its subresource list and the args and num_args parameters.