diff options
Diffstat (limited to 'libXt/specs/CH09')
| -rw-r--r-- | libXt/specs/CH09 | 3211 |
1 files changed, 3211 insertions, 0 deletions
diff --git a/libXt/specs/CH09 b/libXt/specs/CH09 new file mode 100644 index 000000000..9538651bc --- /dev/null +++ b/libXt/specs/CH09 @@ -0,0 +1,3211 @@ +.\" $Xorg: CH09,v 1.3 2000/08/17 19:42:46 cpqbld Exp $ +.\" Copyright \(co 1985, 1986, 1987, 1988, 1991, 1994 +.\" X Consortium +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be included +.\" in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR +.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +.\" OTHER DEALINGS IN THE SOFTWARE. +.\" +.\" Except as contained in this notice, the name of the X Consortium shall +.\" not be used in advertising or otherwise to promote the sale, use or +.\" other dealings in this Software without prior written authorization +.\" from the X Consortium. +.\" +.\" Copyright \(co 1985, 1986, 1987, 1988, 1991, 1994 +.\" Digital Equipment Corporation, Maynard, Massachusetts. +.\" +.\" Permission to use, copy, modify and distribute this documentation for any +.\" purpose and without fee is hereby granted, provided that the above copyright +.\" notice appears in all copies and that both that copyright notice and this +.\" permission notice appear in supporting documentation, and that the name of +.\" Digital not be used in in advertising or publicity pertaining +.\" to distribution of the software without specific, written prior permission. +.\" Digital makes no representations about the suitability of the +.\" software described herein for any purpose. +.\" It is provided ``as is'' without express or implied warranty. +.\" +\& +.sp 1 +.ce 3 +\s+1\fBChapter 9\fP\s-1 + +\s+1\fBResource Management\fP\s-1 +.sp 2 +.nr H1 9 +.nr H2 0 +.nr H3 0 +.nr H4 0 +.nr H5 0 +.LP +.XS +Chapter 9 \(em Resource Management +.XE +A resource is a field in the widget record with a corresponding +resource entry in the \fIresources\fP list of the widget or any of its +superclasses. +This means that the field is +settable by +.PN XtCreateWidget +(by naming the field in the argument list), by an +entry in a resource file (by using either the name or class), and by +.PN XtSetValues . +In addition, it is readable by +.PN XtGetValues . +Not all fields in a widget record are resources. +Some are for bookkeeping use by the +generic routines (like \fImanaged\fP and \fIbeing_destroyed\fP). +Others can be for local bookkeeping, +and still others are derived from resources +(many graphics contexts and pixmaps). +.LP +Widgets typically need to obtain a large set of resources at widget +creation time. +Some of the resources come from the argument list supplied in the call to +.PN XtCreateWidget , +some from the resource database, +and some from the internal defaults specified by the widget. +Resources are obtained first from the argument list, +then from the resource database for all resources not specified +in the argument list, +and last, from the internal default, if needed. + +.NH 2 +Resource Lists +.XS +\*(SN Resource Lists +.XE +.LP +.IN "Resource Management" +A resource entry specifies a field in the widget, +the textual name and class of the field that argument lists +and external resource files use to refer to the field, +and a default value that the field should get if no value is specified. +The declaration for the +.PN XtResource +structure is +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + String resource_name; + String resource_class; + String resource_type; + Cardinal resource_size; + Cardinal resource_offset; + String default_type; + XtPointer default_addr; +} XtResource, *XtResourceList; +.De +.IN "XtResourceList" +.eM + +.LP +When the resource list is specified as the +.PN CoreClassPart , +.PN ObjectClassPart , +.PN RectObjClassPart , +or +.PN ConstraintClassPart +\fIresources\fP field, the strings pointed to by \fIresource_name\fP, +\fIresource_class\fP, \fIresource_type\fP, and \fIdefault_type\fP must +be permanently allocated prior to or during the execution of the class +initialization procedure and must not be subsequently deallocated. + +.LP +The \fIresource_name\fP field contains the name used by clients to access the field +in the widget. +By convention, it starts with a lowercase letter +and is spelled exactly like the field name, +except all underscores (_) are deleted and the next letter is replaced by its +uppercase counterpart. +For example, the resource name for background_pixel becomes backgroundPixel. +Resource names beginning with the two-character +sequence ``xt'', and resource classes beginning with the two-character +sequence ``Xt'' are reserved to the \*(xI for future standard and +implementation-dependent uses. +Widget header files typically contain a symbolic name for each resource name. +All resource names, classes, and types used by the \*(xI are named in +.Pn < X11/StringDefs.h >. +The \*(xI's symbolic resource names begin with +``XtN'' +and are followed by the string name (for example, XtNbackgroundPixel +for backgroundPixel). + +.LP +The \fIresource_class\fP field contains the class string used in resource +specification files to identify the field. +A resource class provides two functions: +.IP \(bu 5 +It isolates an application from different representations that widgets +can use for a similar resource. +.IP \(bu 5 +It lets you specify values for several actual resources with a single name. +A resource class should be chosen to span a group of closely related fields. +.LP +For example, +a widget can have several pixel resources: background, foreground, +border, block cursor, pointer cursor, and so on. +Typically, the background defaults to white +and everything else to black. +The resource class for each of these resources in the resource list +should be chosen so that it takes the minimal number of entries +in the resource database to make the background ivory +and everything else darkblue. +.LP +In this case, the background pixel should have a resource class of +``Background'' +and all the other pixel entries a resource class of +``Foreground''. +Then, the resource file needs only two lines to +change all pixels to ivory or darkblue: +.LP +.Ds 5 +.TA .5i 1.5i +.ta .5i 1.5i +*Background: ivory +*Foreground: darkblue +.De +.LP +Similarly, a widget may have several font resources (such as normal and bold), +but all fonts should have the class Font. +Thus, changing all fonts simply requires only a single line in the +default resource file: +.LP +.Ds 5 +.TA .5i 3i +.ta .5i 3i +*Font: 6x13 +.De +.LP +By convention, +resource classes are always spelled starting with a capital letter +to distinguish them from resource names. +Their symbolic names are preceded with +``XtC'' +(for example, XtCBackground). +.LP +The \fIresource_type\fP field gives the physical representation type of the resource +and also encodes information about the specific usage of the field. +By convention, it starts with an uppercase letter and is +spelled identically to the type name of the field. +The resource type is used when resources are fetched to +convert from the resource database format (usually +.PN String ) +or the format of the resource default value +(almost anything, but often +.PN String ) +to the desired +physical representation (see Section 9.6). +The \*(xI define the following resource types: +.TS H +lw(2.5i) lw(2.5i). +_ +.sp 6p +Resource Type Structure or Field Type +.sp 6p +_ +.sp 6p +.TH +.R +T{ +.PN XtRAcceleratorTable +T} XtAccelerators +T{ +.PN XtRAtom +T} Atom +T{ +.PN XtRBitmap +T} Pixmap, depth=1 +T{ +.PN XtRBoolean +T} Boolean +T{ +.PN XtRBool +T} Bool +T{ +.PN XtRCallback +T} XtCallbackList +T{ +.PN XtRCardinal +T} Cardinal +T{ +.PN XtRColor +T} XColor +T{ +.PN XtRColormap +T} Colormap +T{ +.PN XtRCommandArgArray +T} String* +T{ +.PN XtRCursor +T} Cursor +T{ +.PN XtRDimension +T} Dimension +T{ +.PN XtRDirectoryString +T} String +T{ +.PN XtRDisplay +T} Display* +T{ +.PN XtREnum +T} XtEnum +T{ +.PN XtREnvironmentArray +T} String* +T{ +.PN XtRFile +T} FILE* +T{ +.PN XtRFloat +T} float +T{ +.PN XtRFont +T} Font +T{ +.PN XtRFontSet +T} XFontSet +T{ +.PN XtRFontStruct +T} XFontStruct* +T{ +.PN XtRFunction +T} (*)() +T{ +.PN XtRGeometry +T} T{ +char*, format as defined by +.PN XParseGeometry +T} +T{ +.PN XtRGravity +T} int +T{ +.PN XtRInitialState +T} int +T{ +.PN XtRInt +T} int +T{ +.PN XtRLongBoolean +T} long +T{ +.PN XtRObject +T} Object +T{ +.PN XtRPixel +T} Pixel +T{ +.PN XtRPixmap +T} Pixmap +T{ +.PN XtRPointer +T} XtPointer +T{ +.PN XtRPosition +T} Position +T{ +.PN XtRRestartStyle +T} unsigned char +T{ +.PN XtRScreen +T} Screen* +T{ +.PN XtRShort +T} short +T{ +.PN XtRSmcConn +T} XtPointer +T{ +.PN XtRString +T} String +T{ +.PN XtRStringArray +T} String* +T{ +.PN XtRStringTable +T} String* +T{ +.PN XtRTranslationTable +T} XtTranslations +T{ +.PN XtRUnsignedChar +T} unsigned char +T{ +.PN XtRVisual +T} Visual* +T{ +.PN XtRWidget +T} Widget +T{ +.PN XtRWidgetClass +T} WidgetClass +T{ +.PN XtRWidgetList +T} WidgetList +T{ +.PN XtRWindow +T} Window +.sp 6p +_ +.TE +.sp +.LP +.Pn < X11/StringDefs.h > +also defines the following resource types as a +convenience for widgets, although they do not have any corresponding +data type assigned: +.PN XtREditMode , +.PN XtRJustify , +and +.PN XtROrientation . +.LP +The \fIresource_size\fP field is the size of the physical representation in bytes; +you should specify it as +.PN sizeof (\fItype\fP) +so that the +compiler fills in the value. +The \fIresource_offset\fP field is the offset in bytes of the field +within the widget. +You should use the +.PN XtOffsetOf +macro to retrieve this value. +The \fIdefault_type\fP field is the representation type of the default +resource value. +If \fIdefault_type\fP is different from \fIresource_type\fP and the default value +is needed, +the resource manager invokes a conversion procedure from \fIdefault_type\fP +to \fIresource_type\fP. +Whenever possible, +the default type should be identical to the resource type in order +to minimize widget creation time. +However, there are sometimes no values of the type that the program +can easily specify. +In this case, +it should be a value for which the converter is guaranteed to work (for example, +.PN XtDefaultForeground +for a pixel resource). +The \fIdefault_addr\fP field specifies the address of the default resource value. +As a special case, if \fIdefault_type\fP is +.PN XtRString , +then the value in the \fIdefault_addr\fP field is the pointer to +the string rather than a pointer to the pointer. +The default is used if a resource is not specified in the argument list +or in the resource database or if the conversion from the representation +type stored in the resource database fails, +which can happen for various reasons (for example, a misspelled entry in a +resource file). +.LP +Two special representation types +(XtRImmediate +and +XtRCallProc) +are usable only as default resource types. +XtRImmediate +indicates that the value in the \fIdefault_addr\fP field is the actual value of +the resource rather than the address of the value. +The value must be in the correct representation type for the resource, +coerced to an +.PN XtPointer . +No conversion is possible, since there is no source representation type. +XtRCallProc +indicates that the value in the \fIdefault_addr\fP field is a procedure +pointer. +This procedure is automatically invoked with the widget, +\fIresource_offset\fP, and a pointer to an +.PN XrmValue +in which to store the result. +XtRCallProc +procedure pointers are of type +.PN XtResourceDefaultProc . +.LP +.sM +.FD 0 +typedef void (*XtResourceDefaultProc)(Widget, int, XrmValue*); +.br + Widget \fIw\fP; +.br + int \fIoffset\fP; +.br + XrmValue *\fIvalue\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget whose resource value is to be obtained. +.IP \fIoffset\fP 1i +Specifies the offset of the field in the widget record. +.IP \fIvalue\fP 1i +Specifies the resource value descriptor to return. +.LP +.eM +The +.PN XtResourceDefaultProc +procedure should fill in the \fIvalue->addr\fP field with a pointer +to the resource value in its correct representation type. +.sp +.LP +To get the resource list structure for a particular class, use +.PN XtGetResourceList . +.LP +.IN "XtGetResourceList" "" "@DEF@" +.sM +.FD 0 +void XtGetResourceList(\fIclass\fP, \fIresources_return\fP, \fInum_resources_return\fP); +.br + WidgetClass \fIclass\fP; +.br + XtResourceList *\fIresources_return\fP; +.br + Cardinal *\fInum_resources_return\fP; +.FN +.IP \fIclass\fP 1.5i +Specifies the object class to be queried. It must be +.PN objectClass +or any subclass thereof. +.IP \fIresources_return\fP 1.5i +Returns the resource list. +.IP \fInum_resources_return\fP 1.5i +Returns the number of entries in the resource list. +.LP +.eM +If +.PN XtGetResourceList +is called before the class is initialized, +it returns the resource list as specified in the class record. +If it is called after the class has been initialized, +.PN XtGetResourceList +returns a merged resource list that includes the resources +for all superclasses. +The list returned by +.PN XtGetResourceList +should be freed using +.PN XtFree +when it is no longer needed. +.sp +.LP +To get the constraint resource list structure for a particular widget +class, use +.PN XtGetConstraintResourceList . +.LP +.IN "XtGetConstraintResourceList" "" "@DEF@" +.sM +.FD 0 +void XtGetConstraintResourceList(\fIclass\fP, \fIresources_return\fP, \ +\fInum_resources_return\fP) +.br + WidgetClass \fIclass\fP; +.br + XtResourceList *\fIresources_return\fP; +.br + Cardinal *\fInum_resources_return\fP; +.FN +.IP \fIclass\fP 1.5i +Specifies the object class to be queried. It must be +.PN objectClass +or any subclass thereof. +.IP \fIresources_return\fP 1.5i +Returns the constraint resource list. +.IP \fInum_resources_return\fP 1.5i +Returns the number of entries in the constraint resource list. +.LP +.eM +If +.PN XtGetConstraintResourceList +is called before the widget class is +initialized, the resource list as specified in the widget +class Constraint part is returned. If +.PN XtGetConstraintResourceList +is called after the widget class has been initialized, the merged +resource list for the class and all Constraint superclasses is +returned. If the +specified class is not a subclass of +.PN constraintWidgetClass , +*\fIresources_return\fP is set to NULL +and *\fInum_resources_return\fP is set to zero. +The list returned by +.PN XtGetConstraintResourceList +should be freed using +.PN XtFree +when it is no longer needed. +.sp +.LP +The routines +.PN XtSetValues +and +.PN XtGetValues +also use the resource list to set and get widget state; +see Sections 9.7.1 and 9.7.2. +.LP +Here is an abbreviated version of a possible resource list for a Label widget: +.LP +.Ds +.TA .5i 1.5i 3i +.ta .5i 1.5i 3i +/* Resources specific to Label */ +static XtResource resources[] = { +{XtNforeground, XtCForeground, XtRPixel, sizeof(Pixel), + XtOffsetOf(LabelRec, label.foreground), XtRString, XtDefaultForeground}, +{XtNfont, XtCFont, XtRFontStruct, sizeof(XFontStruct*), + XtOffsetOf(LabelRec, label.font), XtRString, XtDefaultFont}, +{XtNlabel, XtCLabel, XtRString, sizeof(String), + XtOffsetOf(LabelRec, label.label), XtRString, NULL}, + . + . + . +} +.De +.LP +The complete resource name for a field of a widget instance is the +concatenation of the application shell name (from +.PN XtAppCreateShell ), +the instance names of all the widget's parents up to the +top of the widget tree, +the instance name of the widget itself, +and the resource name of the specified field of the widget. +Similarly, +the full resource class of a field of a widget instance is the +concatenation of the application class (from +.PN XtAppCreateShell ), +the widget class names of all the widget's parents up to the +top of the widget tree, +the widget class name of the widget itself, +and the resource class of the specified field of the widget. + +.NH 2 +Byte Offset Calculations +.XS +\*(SN Byte Offset Calculations +.XE +.LP +To determine the byte offset of a field within a structure type, use +.PN XtOffsetOf . +.LP +.IN "XtOffsetOf" "" "@DEF@" +.sM +.FD 0 +Cardinal XtOffsetOf(\fIstructure_type\fP, \fIfield_name\fP) +.br + \fIType structure_type\fP; +.br + \fIField field_name\fP; +.FN +.IP \fIstructure_type\fP 1i +Specifies a type that is declared as a structure. +.IP \fIfield_name\fP 1i +Specifies the name of a member within the structure. +.LP +.eM +The +.PN XtOffsetOf +macro expands to a constant expression that gives the +offset in bytes to the specified structure member from the beginning +of the structure. It is normally used to statically initialize +resource lists and is more portable than +.PN XtOffset , +which serves the same function. + +.LP +To determine the byte offset of a field within a structure pointer type, use +.PN XtOffset . +.LP +.IN "XtOffset" "" "@DEF@" +.sM +.FD 0 +Cardinal XtOffset(\fIpointer_type\fP, \fIfield_name\fP) +.br + \fIType pointer_type\fP; +.br + \fIField field_name\fP; +.FN +.IP \fIpointer_type\fP 1i +Specifies a type that is declared as a pointer to a structure. +.IP \fIfield_name\fP 1i +Specifies the name of a member within the structure. +.LP +.eM +The +.PN XtOffset +macro expands to a constant expression that gives the +offset in bytes to the specified structure member from the beginning +of the structure. It may be used to statically initialize +resource lists. +.PN XtOffset +is less portable than +.PN XtOffsetOf . + +.NH 2 +Superclass-to-Subclass Chaining of Resource Lists +.XS +\*(SN Superclass-to-Subclass Chaining of Resource Lists +.XE +.LP +.IN "Inheritance" +.IN "Superclass Chaining" +.IN "Chaining" +The +.PN XtCreateWidget +function gets resources as a superclass-to-subclass chained operation. +That is, the resources specified in the +.PN objectClass +resource list are fetched, +then those in +.PN rectObjClass , +and so on down to the resources specified +for this widget's class. Within a class, resources are fetched in the order +they are declared. +.LP +In general, if a widget resource field is declared in a superclass, +that field is included in the superclass's resource list and need not be +included in the subclass's resource list. +For example, the +Core +class contains a resource entry for \fIbackground_pixel\fP. +Consequently, +the implementation of Label need not also have a resource entry +for \fIbackground_pixel\fP. +However, a subclass, +by specifying a resource entry for that field in its own resource list, +can override the resource entry for any field declared in a superclass. +This is most often done to override the defaults provided in the +superclass with new ones. +At class initialization time, +resource lists for that class are scanned from the superclass down +to the class to look for resources with the same offset. +A matching resource in a subclass will be reordered to override +the superclass entry. +If reordering is necessary, a copy of the superclass resource list is made to +avoid affecting other subclasses of the superclass. +.LP +.IN "class_initialize procedure" +.IN "Widget" "class initialization" +Also at class initialization time, the \*(xI produce an +internal representation of the resource list to optimize access time +when creating widgets. In order to save memory, the \*(xI may +overwrite the storage allocated for the resource list in the class +record; therefore, widgets must allocate resource lists in writable +storage and must not access the list contents directly after the +class_initialize procedure has returned. + +.NH 2 +Subresources +.XS +\*(SN Subresources +.XE +.LP +A widget does not do anything to retrieve its own resources; +instead, +.PN XtCreateWidget +does this automatically before calling the class initialize procedure. +.LP +Some widgets have subparts that are not widgets but for which the widget +would like to fetch resources. +Such widgets call +.PN XtGetSubresources +to accomplish this. +.LP +.IN "XtGetSubresources" "" "@DEF@" +.sM +.FD 0 +void XtGetSubresources(\fIw\fP, \fIbase\fP, \fIname\fP, \fIclass\fP, \ +\fIresources\fP, \fInum_resources\fP, \fIargs\fP, \fInum_args\fP) +.br + Widget \fIw\fP; +.br + XtPointer \fIbase\fP; +.br + String \fIname\fP; +.br + String \fIclass\fP; +.br + XtResourceList \fIresources\fP; +.br + Cardinal \fInum_resources\fP; +.br + ArgList \fIargs\fP; +.br + Cardinal \fInum_args\fP; +.FN +.IP \fIw\fP 1i +Specifies the object used to qualify the subpart resource name and +class. \*(oI +.IP \fIbase\fP 1i +Specifies the base address of the subpart data structure into which the +resources will be written. +.IP \fIname\fP 1i +Specifies the name of the subpart. +.IP \fIclass\fP 1i +Specifies the class of the subpart. +.IP \fIresources\fP 1i +Specifies the resource list for the subpart. +.IP \fInum_resources\fP 1i +Specifies the number of entries in the resource list. +.IP \fIargs\fP 1i +Specifies the argument list to override any other resource specifications. +.IP \fInum_args\fP 1i +Specifies the number of entries in the argument list. +.LP +.eM +The +.PN XtGetSubresources +function constructs a name and class list from the application name and class, +the names and classes of all the object's ancestors, and the object itself. +Then it appends to this list the \fIname\fP and \fIclass\fP pair passed in. +The resources are fetched from the argument list, the resource database, +or the default values in the resource list. +Then they are copied into the subpart record. +If \fIargs\fP is NULL, +\fInum_args\fP must be zero. +However, if \fInum_args\fP is zero, +the argument list is not referenced. +.LP +.PN XtGetSubresources +may overwrite the specified resource list with an +equivalent representation in an internal format, which optimizes access +time if the list is used repeatedly. The resource list must be +allocated in writable storage, and the caller must not modify the list +contents after the call if the same list is to be used again. +Resources fetched by +.PN XtGetSubresources +are reference-counted as +if they were referenced by the specified object. Subresources might +therefore be freed from the conversion cache and destroyed +when the object is destroyed, but not before then. +.sp +.LP +To fetch resources for widget subparts using varargs lists, use +.PN XtVaGetSubresources . +.LP +.IN "XtVaGetSubresources" "" "@DEF@" +.sM +.FD 0 +void XtVaGetSubresources(\fIw\fP, \fIbase\fP, \fIname\fP, \fIclass\fP, \ +\fIresources\fP, \fInum_resources\fP, ...) +.br + Widget \fIw\fP; +.br + XtPointer \fIbase\fP; +.br + String \fIname\fP; +.br + String \fIclass\fP; +.br + XtResourceList \fIresources\fP; +.br + Cardinal \fInum_resources\fP; +.FN +.IP \fIw\fP 1i +Specifies the object used to qualify the subpart resource name and +class. \*(oI +.IP \fIbase\fP 1i +Specifies the base address of the subpart data structure into which the +resources will be written. +.IP \fIname\fP 1i +Specifies the name of the subpart. +.IP \fIclass\fP 1i +Specifies the class of the subpart. +.IP \fIresources\fP 1i +Specifies the resource list for the subpart. +.IP \fInum_resources\fP 1i +Specifies the number of entries in the resource list. +.IP ... 1i +Specifies the variable argument list to override any other +resource specifications. +.LP +.eM +.PN XtVaGetSubresources +is identical in function to +.PN XtGetSubresources +with the \fIargs\fP and \fInum_args\fP parameters replaced by a varargs list, as +described in Section 2.5.1. + +.NH 2 +Obtaining Application Resources +.XS +\fB\*(SN Obtaining Application Resources\fP +.XE +.LP +To retrieve resources that are not specific to a widget +but apply to the overall application, use +.PN XtGetApplicationResources . +.LP +.IN "XtGetApplicationResources" "" "@DEF@" +.sM +.FD 0 +void XtGetApplicationResources(\fIw\fP, \fIbase\fP, \fIresources\fP, \ +\fInum_resources\fP, \fIargs\fP, \fInum_args\fP) +.br + Widget \fIw\fP; +.br + XtPointer \fIbase\fP; +.br + XtResourceList \fIresources\fP; +.br + Cardinal \fInum_resources\fP; +.br + ArgList \fIargs\fP; +.br + Cardinal \fInum_args\fP; +.FN +.IP \fIw\fP 1i +Specifies the object that identifies the resource database to search +(the database is that associated with the display for this object). \*(oI +.IP \fIbase\fP 1i +Specifies the base address into which +the resource values will be written. +.IP \fIresources\fP 1i +Specifies the resource list. +.IP \fInum_resources\fP 1i +Specifies the number of entries in the resource list. +.IP \fIargs\fP 1i +Specifies the argument list to override any other resource specifications. +.IP \fInum_args\fP 1i +Specifies the number of entries in the argument list. +.LP +.eM +The +.PN XtGetApplicationResources +function first uses the passed object, +which is usually an application shell widget, +to construct a resource name and class list. +The full name and class of the specified object (that is, including its +ancestors, if any) is logically added to the +front of each resource name and class. +Then it retrieves the resources from the argument list, +the resource database, or the resource list default values. +After adding base to each address, +.PN XtGetApplicationResources +copies the resources into the addresses +obtained by adding \fIbase\fP to each \fIoffset\fP in the resource list. +If \fIargs\fP is NULL, +\fInum_args\fP must be zero. +However, if \fInum_args\fP is zero, +the argument list is not referenced. +The portable way to specify application resources is to declare them +as members of a structure and pass the address of the structure +as the \fIbase\fP argument. +.LP +.PN XtGetApplicationResources +may overwrite the specified resource list +with an equivalent representation in an internal format, which +optimizes access time if the list is used repeatedly. The resource +list must be allocated in writable storage, and the caller must not +modify the list contents after the call if the same list is to be +used again. Any per-display resources fetched by +.PN XtGetApplicationResources +will not be freed from the resource cache until the display is closed. +.sp +.LP +To retrieve resources for the overall application using varargs lists, use +.PN XtVaGetApplicationResources . +.LP +.IN "XtVaGetApplicationResources" "" "@DEF@" +.sM +.FD 0 +void XtVaGetApplicationResources(\fIw\fP, \fIbase\fP, \fIresources\fP, \ +\fInum_resources\fP, ...) +.br + Widget \fIw\fP; +.br + XtPointer \fIbase\fP; +.br + XtResourceList \fIresources\fP; +.br + Cardinal \fInum_resources\fP; +.FN +.IP \fIw\fP 1i +Specifies the object that identifies the resource database to search +(the database is that associated with the display for this object). \*(oI +.IP \fIbase\fP 1i +Specifies the base address into which +the resource values will be written. +.IP \fIresources\fP 1i +Specifies the resource list for the subpart. +.IP \fInum_resources\fP 1i +Specifies the number of entries in the resource list. +.IP ... 1i +Specifies the variable argument list to override any other +resource specifications. +.LP +.eM +.PN XtVaGetApplicationResources +is identical in function to +.PN XtGetApplicationResources +with the \fIargs\fP and \fInum_args\fP parameters +replaced by a varargs list, as described in Section 2.5.1. + +.NH 2 +Resource Conversions +.XS +\*(SN Resource Conversions +.XE +.LP +The \*(xI provide a mechanism for registering representation converters that +are automatically invoked by the resource-fetching routines. +The \*(xI additionally provide and register several commonly used converters. +This resource conversion mechanism serves several purposes: +.IP \(bu 5 +It permits user and application resource files to contain textual +representations of nontextual values. +.IP \(bu 5 +It allows textual or other representations of default resource values that +are dependent on the display, screen, or colormap, and thus must be +computed at runtime. +.IP \(bu 5 +It caches conversion source and result data. +Conversions that require much computation or space +(for example, string-to-translation-table) +or that require round-trips to the server +(for example, string-to-font or string-to-color) are performed only once. + +.NH 3 +Predefined Resource Converters +.XS +\*(SN Predefined Resource Converters +.XE +.LP +The \*(xI define all the representations used in the +Object, +RectObj, +Core, +Composite, +Constraint, +and +Shell +widget classes. +The \*(xI register the following resource converters that accept +input values of representation type +.PN XtRString . +.LP +.TS +lw(1.7i) lw(2.4i) lw(1.5i) . +_ +.sp 6p +Target Representation Converter Name Additional Args +.sp 6p +_ +.sp 6p +T{ +.PN XtRAcceleratorTable +T} T{ +.PN XtCvtStringToAcceleratorTable +T} +T{ +.PN XtRAtom +T} T{ +.PN XtCvtStringToAtom +T} Display* +T{ +.PN XtRBoolean +T} T{ +.PN XtCvtStringToBoolean +T} +T{ +.PN XtRBool +T} T{ +.PN XtCvtStringToBool +T} +T{ +.PN XtRCommandArgArray +T} T{ +.PN XtCvtStringToCommandArgArray +T} +T{ +.PN XtRCursor +T} T{ +.PN XtCvtStringToCursor +T} Display* +T{ +.PN XtRDimension +T} T{ +.PN XtCvtStringToDimension +T} +T{ +.PN XtRDirectoryString +T} T{ +.PN XtCvtStringToDirectoryString +T} +T{ +.PN XtRDisplay +T} T{ +.PN XtCvtStringToDisplay +T} +T{ +.PN XtRFile +T} T{ +.PN XtCvtStringToFile +T} +T{ +.PN XtRFloat +T} T{ +.PN XtCvtStringToFloat +T} +T{ +.PN XtRFont +T} T{ +.PN XtCvtStringToFont +T} Display* +T{ +.PN XtRFontSet +T} T{ +.PN XtCvtStringToFontSet +T} Display*, String \fIlocale\fP +T{ +.PN XtRFontStruct +T} T{ +.PN XtCvtStringToFontStruct +T} Display* +T{ +.PN XtRGravity +T} T{ +.PN XtCvtStringToGravity +T} +T{ +.PN XtRInitialState +T} T{ +.PN XtCvtStringToInitialState +T} +T{ +.PN XtRInt +T} T{ +.PN XtCvtStringToInt +T} +T{ +.PN XtRPixel +T} T{ +.PN XtCvtStringToPixel +T} T{ +.PN colorConvertArgs +T} +T{ +.PN XtRPosition +T} T{ +.PN XtCvtStringToPosition +T} +T{ +.PN XtRRestartStyle +T} T{ +.PN XtCvtStringToRestartStyle +T} +T{ +.PN XtRShort +T} T{ +.PN XtCvtStringToShort +T} +T{ +.PN XtRTranslationTable +T} T{ +.PN XtCvtStringToTranslationTable +T} +T{ +.PN XtRUnsignedChar +T} T{ +.PN XtCvtStringToUnsignedChar +T} +T{ +.PN XtRVisual +T} T{ +.PN XtCvtStringToVisual +T} Screen*, Cardinal \fIdepth\fP +.sp 6p +_ +.TE + +.LP +The String-to-Pixel conversion has two predefined constants that are +guaranteed to work and contrast with each other: +.PN XtDefaultForeground +and +.PN XtDefaultBackground . +.IN "XtDefaultBackground" "" "@DEF@" +.IN "XtDefaultForeground" "" "@DEF@" +They evaluate to the black and white pixel values of the widget's screen, +respectively. +.IN "Resources" "reverseVideo" +If the application resource reverseVideo is +.PN True , +they evaluate to the white and black pixel values of the widget's screen, +respectively. +Similarly, the String-to-Font and String-to-FontStruct converters recognize +the constant +.PN XtDefaultFont +.IN "XtDefaultFont" "" "@DEF@" +.IN "Resources" "xtDefaultFont" +and evaluate this in the following manner: +.IP \(bu 5 +Query the resource database for the resource whose full name +is ``xtDefaultFont'', class ``XtDefaultFont'' (that is, no widget +name/class prefixes), and use a type +.PN XtRString +value returned as the font name or a type +.PN XtRFont +or +.PN XtRFontStruct +value directly as the resource value. +.IP \(bu 5 +If the resource database does not contain a value for xtDefaultFont, +class XtDefaultFont, or if the returned font name cannot be +successfully opened, an implementation-defined font in ISO8859-1 +character set encoding is opened. (One possible algorithm is to +perform an +.PN XListFonts +using a wildcard font name and use the first +font in the list. This wildcard font name should be as broad as +possible to maximize the probability of locating a useable font; +for example, "-*-*-*-R-*-*-*-120-*-*-*-*-ISO8859-1".) +.IP \(bu 5 +If no suitable ISO8859-1 font can be found, issue a warning message +and return +.PN False . +.LP +The String-to-FontSet converter recognizes the constant +.PN XtDefaultFontSet +.IN "XtDefaultFontSet" "" "@DEF@" +.IN "Resources" "xtDefaultFontSet" +and evaluate this in the following manner: +.IP \(bu 5 +Query the resource database for the resource whose full name +is ``xtDefaultFontSet'', class ``XtDefaultFontSet'' (that is, no widget +name/class prefixes), and use a type +.PN XtRString +value returned as the base font name list or a type +.PN XtRFontSet +value directly as the resource value. +.IP \(bu 5 +If the resource database does not contain a value for xtDefaultFontSet, +class XtDefaultFontSet, or if a font set cannot be +successfully created from this resource, +an implementation-defined font set is created. +(One possible algorithm is to +perform an +.PN XCreateFontSet +using a wildcard base font name. +This wildcard base font name should be as broad as +possible to maximize the probability of locating a useable font; +for example, "-*-*-*-R-*-*-*-120-*-*-*-*".) +.IP \(bu 5 +If no suitable font set can be created, issue a warning message +and return +.PN False . +.LP +If a font set is created but \fImissing_charset_list\fP is not +empty, a warning is issued and the partial font set is returned. +The \*(xI register the String-to-FontSet converter with +a conversion argument list that extracts the current process +locale at the time the converter is invoked. This ensures +that the converter is invoked again if the same conversion +is required in a different locale. +.LP +The String-to-Gravity conversion accepts string values that are the +names of window and bit gravities and their numerical equivalents, +as defined in \fI\*(xL\fP: +.PN ForgetGravity , +.PN UnmapGravity , +.PN NorthWestGravity , +.PN NorthGravity , +.PN NorthEastGravity , +.PN WestGravity , +.PN CenterGravity , +.PN EastGravity , +.PN SouthWestGravity , +.PN SouthGravity , +.PN SouthEastGravity , +and +.PN StaticGravity . +Alphabetic case is not significant in the conversion. +.LP +The String-to-CommandArgArray conversion parses a String into an +array of strings. +White space characters separate elements of the command line. +The converter recognizes the backslash character ``\\'' as an escape +character to allow the following white space character to be part of the +array element. +.LP +.IN "XtCurrentDirectory" "" "@DEF@" +The String-to-DirectoryString conversion recognizes the +string ``XtCurrentDirectory'' and returns the result of a call +to the operating system to get the current directory. +.LP +The String-to-RestartStyle conversion accepts the values +.PN RestartIfRunning , +.PN RestartAnyway , +.PN RestartImmediately , +and +.PN RestartNever +as defined by the \fIX Session Management Protocol\fP. +.LP +The String-to-InitialState conversion accepts the values +.PN NormalState +or +.PN IconicState +as defined by the \fI\*(xC\fP. +.LP +The String-to-Visual conversion calls +.PN XMatchVisualInfo +using the +\fIscreen\fP and \fIdepth\fP fields from the core part and returns the first +matching Visual on the list. The widget resource list must be certain +to specify any resource of type +.PN XtRVisual +after the depth resource. +The allowed string values are the visual class names defined in \fI\*(xP\fP, +Section 8; +.PN StaticGray , +.PN StaticColor , +.PN TrueColor , +.PN GrayScale , +.PN PseudoColor , +and +.PN DirectColor . + +.LP +The \*(xI register the following resource converter that accepts +an input value of representation type +.PN XtRColor . +.LP +.TS +lw(1.5i) lw(2.25i) lw(1.5i) . +_ +.sp 6p +Target Representation Converter Name Additional Args +.sp 6p +_ +.sp 6p +T{ +.PN XtRPixel +T} T{ +.PN XtCvtColorToPixel +T} +.sp 6p +_ +.TE + +.LP +The \*(xI register the following resource converters that accept +input values of representation type +.PN XtRInt . +.LP +.TS +lw(1.5i) lw(2.25i) lw(1.5i) . +_ +.sp 6p +Target Representation Converter Name Additional Args +.sp 6p +_ +.sp 6p +T{ +.PN XtRBoolean +T} T{ +.PN XtCvtIntToBoolean +T} +T{ +.PN XtRBool +T} T{ +.PN XtCvtIntToBool +T} +T{ +.PN XtRColor +T} T{ +.PN XtCvtIntToColor +T} T{ +.PN colorConvertArgs +T} +T{ +.PN XtRDimension +T} T{ +.PN XtCvtIntToDimension +T} +T{ +.PN XtRFloat +T} T{ +.PN XtCvtIntToFloat +T} +T{ +.PN XtRFont +T} T{ +.PN XtCvtIntToFont +T} +T{ +.PN XtRPixel +T} T{ +.PN XtCvtIntToPixel +T} +T{ +.PN XtRPixmap +T} T{ +.PN XtCvtIntToPixmap +T} +T{ +.PN XtRPosition +T} T{ +.PN XtCvtIntToPosition +T} +T{ +.PN XtRShort +T} T{ +.PN XtCvtIntToShort +T} +T{ +.PN XtRUnsignedChar +T} T{ +.PN XtCvtIntToUnsignedChar +T} +.sp 6p +_ +.TE + +.LP +The \*(xI register the following resource converter that accepts +an input value of representation type +.PN XtRPixel . +.LP +.TS +lw(1.5i) lw(2.25i) lw(1.5i) . +_ +.sp 6p +Target Representation Converter Name Additional Args +.sp 6p +_ +.sp 6p +T{ +.PN XtRColor +T} T{ +.PN XtCvtPixelToColor +T} +.sp 6p +_ +.TE + +.NH 3 +New Resource Converters +.XS +\*(SN New Resource Converters +.XE +.LP +Type converters use pointers to +.PN XrmValue +structures (defined in +.Pn < X11/Xresource.h >; +see Section 15.4 in \fI\*(xL\fP) +for input and output values. +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + unsigned int size; + XPointer addr; +} XrmValue, *XrmValuePtr; +.De +.LP +.eM +The \fIaddr\fP field specifies the address of the data, and the \fIsize\fP +field gives the total number of significant bytes in the data. +For values of type +.PN String , +\fIaddr\fP is the address of the first character and \fIsize\fP +includes the NULL-terminating byte. +.LP +A resource converter procedure pointer is of type +.PN XtTypeConverter . +.LP +.IN "XtTypeConverter" "" "@DEF@" +.sM +.FD 0 +typedef Boolean (*XtTypeConverter)(Display*, XrmValue*, Cardinal*, + XrmValue*, XrmValue*, XtPointer*); +.br + Display *\fIdisplay\fP; +.br + XrmValue *\fIargs\fP; +.br + Cardinal *\fInum_args\fP; +.br + XrmValue *\fIfrom\fP; +.br + XrmValue *\fIto\fP; +.br + XtPointer *\fIconverter_data\fP; +.FN +.IP \fIdisplay\fP 1i +Specifies the display connection with which this conversion is associated. +.IP \fIargs\fP 1i +Specifies a list of additional +.PN XrmValue +arguments to the converter if additional context is needed +to perform the conversion, or NULL. +For example, the String-to-Font converter needs the widget's \fIdisplay\fP, +and the String-to-Pixel converter needs the widget's \fIscreen\fP and \fIcolormap\fP. +.IP \fInum_args\fP 1i +Specifies the number of entries in \fIargs\fP. +.IP \fIfrom\fP 1i +Specifies the value to convert. +.IP \fIto\fP 1i +Specifies a descriptor for a location into which to store the converted value. +.IP \fIconverter_data\fP 1i +Specifies a location into which the converter may +store converter-specific data associated +with this conversion. +.LP +.eM +The \fIdisplay\fP argument is normally used only when generating error +messages, to identify the application context (with the function +.PN XtDisplayToApplicationContext ). +.LP +The \fIto\fP argument specifies the size and location into which the +converter should store the converted value. If the \fIaddr\fP field is NULL, +the converter should allocate appropriate storage and store the size +and location into the \fIto\fP descriptor. If the type converter allocates +the storage, it remains under the ownership of the converter and must +not be modified by the caller. The type converter is permitted to use +static storage for this purpose, and therefore the caller must +immediately copy the data upon return from the converter. If the +\fIaddr\fP field is not NULL, the converter must check the \fIsize\fP field to +ensure that sufficient space has been allocated before storing the +converted value. If insufficient space is specified, the converter +should update the \fIsize\fP field with the number of bytes required and +return +.PN False +without modifying the data at the specified location. +If sufficient space was allocated by the caller, the converter should +update the \fIsize\fP field with the number of bytes actually occupied by the +converted value. For converted values of type +.PN XtRString , +the size should +include the NULL-terminating byte, if any. +The converter may store any value in the location specified +in \fIconverter_data\fP; this value will be passed to the destructor, if any, +when the resource is freed by the \*(xI. +.LP +The converter must return +.PN True +if the conversion was successful and +.PN False +otherwise. If the conversion cannot be performed because of an +improper source value, a warning message should also be issued with +.PN XtAppWarningMsg . + +.LP +Most type converters just take the data described by the specified \fIfrom\fP +argument and return data by writing into the location specified in +the \fIto\fP argument. +A few need other information, which is available in \fIargs\fP. +A type converter can invoke another type converter, +which allows differing sources that may convert into a common intermediate +result to make maximum use of the type converter cache. +.LP +Note that if an address is written into \fIto->addr\fP, it cannot be that +of a local variable of the converter because the data will not be +valid after the converter returns. Static variables may be used, +as in the following example. +If the converter modifies the resource database, +the changes affect any in-progress widget creation, +.PN XtGetApplicationResources , +or +.PN XtGetSubresources +in an implementation-defined manner; however, insertion of new entries +or changes to existing entries is allowed and will not directly cause +an error. + +.LP +The following is an example of a converter that takes a +.PN string +and converts it to a +.PN Pixel . +Note that the \fIdisplay\fP parameter is +used only to generate error messages; the +.PN Screen +conversion argument is +still required to inform the \*(xI that the converted value is +a function of the particular display (and colormap). +.LP +.Ds 0 +.TA .3i .7i 1i 1.3i 1.7i 2i 4i +.ta .3i .7i 1i 1.3i 1.7i 2i 4i + +#define done(type, value) \\ + { \\ + if (toVal->addr != NULL) { \\ + if (toVal->size < sizeof(type)) { \\ + toVal->size = sizeof(type); \\ + return False; \\ + } \\ + *(type*)(toVal->addr) = (value); \\ + } \\ + else { \\ + static type static_val; \\ + static_val = (value); \\ + toVal->addr = (XPointer)&static_val; \\ + } \\ + toVal->size = sizeof(type); \\ + return True; \\ + } + +static Boolean CvtStringToPixel(dpy, args, num_args, fromVal, toVal, converter_data) + Display *dpy; + XrmValue *args; + Cardinal *num_args; + XrmValue *fromVal; + XrmValue *toVal; + XtPointer *converter_data; +{ + static XColor screenColor; + XColor exactColor; + Screen *screen; + Colormap colormap; + Status status; + + if (*num_args != 2) + XtAppWarningMsg(XtDisplayToApplicationContext(dpy), + "wrongParameters", "cvtStringToPixel", "XtToolkitError", + "String to pixel conversion needs screen and colormap arguments", + (String *)NULL, (Cardinal *)NULL); + + screen = *((Screen**) args[0].addr); + colormap = *((Colormap *) args[1].addr); + + if (CompareISOLatin1(str, XtDefaultBackground) == 0) { + *closure_ret = False; + done(Pixel, WhitePixelOfScreen(screen)); + } + if (CompareISOLatin1(str, XtDefaultForeground) == 0) { + *closure_ret = False; + done(Pixel, BlackPixelOfScreen(screen)); + } + + + status = XAllocNamedColor(DisplayOfScreen(screen), colormap, (char*)fromVal->addr, + &screenColor, &exactColor); + + if (status == 0) { + String params[1]; + Cardinal num_params = 1; + params[0] = (String)fromVal->addr; + XtAppWarningMsg(XtDisplayToApplicationContext(dpy), + "noColormap", "cvtStringToPixel", "XtToolkitError", + "Cannot allocate colormap entry for \\"%s\\"", params,\ + &num_params); + *converter_data = (char *) False; + return False; + } else { + *converter_data = (char *) True; + done(Pixel, &screenColor.pixel); + } +} +.De +.LP +All type converters should define some set of conversion values for which they +are guaranteed to succeed so these can be used in the resource defaults. +This issue arises only with conversions, such as fonts and colors, +where there is no string representation that all server implementations +will necessarily recognize. +For resources like these, +the converter should define a symbolic constant +in the same manner as +.PN XtDefaultForeground , +.PN XtDefaultBackground , +and +.PN XtDefaultFont . +.sp +.LP +To allow the \*(xI to deallocate resources produced by type +converters, a resource destructor procedure may also be provided. +.LP +A resource destructor procedure pointer is of type +.PN XtDestructor . +.LP +.IN "XtDestructor" "" "@DEF@" +.sM +.FD 0 +typedef void (*XtDestructor) (XtAppContext, XrmValue*, XtPointer, XrmValue*, \ +Cardinal*); +.br + XtAppContext \fIapp\fP; +.br + XrmValue *\fIto\fP; +.br + XtPointer \fIconverter_data\fP; +.br + XrmValue *\fIargs\fP; +.br + Cardinal *\fInum_args\fP; +.FN +.IP \fIapp\fP 1i +Specifies an application context in which the resource is being freed. +.IP \fIto\fP 1i +Specifies a descriptor for the resource produced by the type converter. +.IP \fIconverter_data\fP 1i +Specifies the converter-specific data returned by the type converter. +.IP \fIargs\fP 1i +Specifies the additional converter arguments as passed +to the type converter when the conversion was performed. +.IP \fInum_args\fP 1i +Specifies the number of entries in \fIargs\fP. +.LP +.eM +The destructor procedure is responsible for freeing the resource +specified by the \fIto\fP argument, including any auxiliary storage +associated with that resource, but not the memory directly addressed +by the size and location in the \fIto\fP argument or the memory specified +by \fIargs\fP. + +.NH 3 +Issuing Conversion Warnings +.XS +\*(SN Issuing Conversion Warnings +.XE +.LP +The +.PN XtDisplayStringConversionWarning +procedure is a convenience routine for resource type converters +that convert from string values. +.LP +.IN "XtDisplayStringConversionWarning" "" "@DEF@" +.sM +.FD 0 +void XtDisplayStringConversionWarning(\fIdisplay\fP, \fIfrom_value\fP, \ +\fIto_type\fP) +.br + Display *\fIdisplay\fP; +.br + String \fIfrom_value\fP, \fIto_type\fP; +.FN +.IP \fIdisplay\fP 1i +Specifies the display connection with which the conversion is associated. +.IP \fIfrom_value\fP 1i +Specifies the string that could not be converted. +.IP \fIto_type\fP 1i +Specifies the target representation type requested. +.LP +.eM +The +.PN XtDisplayStringConversionWarning +procedure issues a warning message using +.PN XtAppWarningMsg +with \fIname\fP ``conversionError'', +\fItype\fP ``string'', \fIclass\fP ``XtToolkitError'', and the default message +``Cannot convert "\fIfrom_value\fP" to type \fIto_type\fP''. +.LP +To issue other types of warning or error messages, the type converter +should use +.PN XtAppWarningMsg +or +.PN XtAppErrorMsg . +.sp +.LP +To retrieve the application context associated with a given +display connection, use +.PN XtDisplayToApplicationContext . +.LP +.IN "XtDisplayToApplicationContext" "" "@DEF@" +.sM +.FD 0 +XtAppContext XtDisplayToApplicationContext( \fIdisplay\fP ) +.br + Display *\fIdisplay\fP; +.FN +.IP \fIdisplay\fP 1i +Specifies an open and initialized display connection. +.LP +.eM +The +.PN XtDisplayToApplicationContext +function returns the application +context in which the specified \fIdisplay\fP was initialized. If the +display is not known to the \*(xI, an error message is issued. + +.NH 3 +Registering a New Resource Converter +.XS +\fB\*(SN Registering a New Resource Converter\fP +.XE +.LP +When registering a resource converter, the client must specify the +manner in which the conversion cache is to be used when there are multiple +calls to the converter. Conversion cache control is specified +via an +.PN XtCacheType +.LP +.IN "XtCacheType" "" "@DEF@" +argument. +.sM +.Ds 0 +typedef int XtCacheType; +.De +.LP +.eM +An +.PN XtCacheType +field may contain one of the following values: +.br +.sp +.LP +.PN XtCacheNone +.IN "XtCacheNone" "" "@DEF@" +.IP +Specifies that the results of a previous conversion +may not be reused to satisfy any other resource +requests; the specified converter will be called +each time the converted value is required. +.br +.sp +.LP +.PN XtCacheAll +.IN "XtCacheAll" "" "@DEF@" +.IP +Specifies that the results of a previous conversion +should be reused for any resource request that depends +upon the same source value and conversion arguments. +.br +.sp +.LP +.PN XtCacheByDisplay +.IN "XtCacheByDisplay" "" "@DEF@" +.IP +Specifies that the results of a previous conversion +should be used as for +.PN XtCacheAll +but the destructor will be called, if specified, if +.PN XtCloseDisplay +is called +for the display connection associated with the converted value, and +the value will be removed from the conversion cache. +.LP +The qualifier +.PN XtCacheRefCount +.IN "XtCacheRefCount" "" "@DEF@" +may be ORed with any of the above values. If +.PN XtCacheRefCount +is specified, calls to +.PN XtCreateWidget , +.PN XtCreateManagedWidget , +.PN XtGetApplicationResources , +and +.PN XtGetSubresources +that use the converted value will be counted. When a widget using the +converted value is destroyed, the count is decremented, and, if the +count reaches zero, the destructor procedure will be called and the +converted value will be removed from the conversion cache. + +.LP +To register a type converter for all application contexts in a +process, use +.PN XtSetTypeConverter , +and to register a type converter in a single application context, use +.PN XtAppSetTypeConverter . +.LP +.IN "XtSetTypeConverter" "" "@DEF@" +.sM +.FD 0 +void XtSetTypeConverter(\fIfrom_type\fP, \fIto_type\fP, \fIconverter\fP, \ +\fIconvert_args\fP, \fInum_args\fP, + \fIcache_type\fP, \fIdestructor\fP) +.br + String \fIfrom_type\fP; +.br + String \fIto_type\fP; +.br + XtTypeConverter \fIconverter\fP; +.br + XtConvertArgList \fIconvert_args\fP; +.br + Cardinal \fInum_args\fP; +.br + XtCacheType \fIcache_type\fP; +.br + XtDestructor \fIdestructor\fP; +.FN +.IP \fIfrom_type\fP 1i +Specifies the source type. +.IP \fIto_type\fP 1i +Specifies the destination type. +.IP \fIconverter\fP 1i +Specifies the resource type converter procedure. +.IP \fIconvert_args\fP 1i +Specifies additional conversion arguments, or NULL. +.IP \fInum_args\fP 1i +Specifies the number of entries in \fIconvert_args\fP. +.IP \fIcache_type\fP 1i +Specifies whether or not resources produced by this +converter are sharable or display-specific and when +they should be freed. +.IP \fIdestructor\fP 1i +Specifies a destroy procedure for resources produced by +this conversion, or NULL if no additional action is +required to deallocate resources produced by the converter. +.LP +.IN "XtAppSetTypeConverter" "" "@DEF@" +.FD 0 +void XtAppSetTypeConverter(\fIapp_context\fP, \fIfrom_type\fP, \fIto_type\fP, \ +\fIconverter\fP, \fIconvert_args\fP, + \fInum_args\fP, \fIcache_type\fP, \fIdestructor\fP) +.br + XtAppContext \fIapp_context\fP; +.br + String \fIfrom_type\fP; +.br + String \fIto_type\fP; +.br + XtTypeConverter \fIconverter\fP; +.br + XtConvertArgList \fIconvert_args\fP; +.br + Cardinal \fInum_args\fP; +.br + XtCacheType \fIcache_type\fP; +.br + XtDestructor \fIdestructor\fP; +.FN +.IP \fIapp_context\fP 1i +Specifies the application context. +.IP \fIfrom_type\fP 1i +Specifies the source type. +.IP \fIto_type\fP 1i +Specifies the destination type. +.IP \fIconverter\fP 1i +Specifies the resource type converter procedure. +.IP \fIconvert_args\fP 1i +Specifies additional conversion arguments, or NULL. +.IP \fInum_args\fP 1i +Specifies the number of entries in \fIconvert_args\fP. +.IP \fIcache_type\fP 1i +Specifies whether or not resources produced by this +converter are sharable or display-specific and when +they should be freed. +.IP \fIdestructor\fP 1i +Specifies a destroy procedure for resources produced by +this conversion, or NULL if no additional action is +required to deallocate resources produced by the converter. +.LP +.eM +.PN XtSetTypeConverter +registers the specified type converter and +destructor in all application contexts created by the calling process, +including any future application contexts that may be created. +.PN XtAppSetTypeConverter +registers the specified type converter in the +single application context specified. If the same \fIfrom_type\fP and +\fIto_type\fP are specified in multiple calls to either function, the most +recent overrides the previous ones. +.sp +.LP +For the few type converters that need additional arguments, +the \*(xI conversion mechanism provides a method of specifying +how these arguments should be computed. +The enumerated type +.PN XtAddressMode +and the structure +.PN XtConvertArgRec +specify how each argument is derived. +These are defined in +.Pn < X11/Intrinsic.h >. +.LP +.sM +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef enum { + /* address mode parameter representation */ + XtAddress, /* address */ + XtBaseOffset, /* offset */ + XtImmediate, /* constant */ + XtResourceString, /* resource name string */ + XtResourceQuark, /* resource name quark */ + XtWidgetBaseOffset, /* offset */ + XtProcedureArg /* procedure to call */ +} XtAddressMode; +.sp +typedef struct { + XtAddressMode address_mode; + XtPointer address_id; + Cardinal size; +} XtConvertArgRec, *XtConvertArgList; +.De +.eM +.LP +The \fIsize\fP field specifies the length of the data in bytes. +The \fIaddress_mode\fP field specifies how the \fIaddress_id\fP field should be +interpreted. +.PN XtAddress +.IN "XtAddress" "" "@DEF@" +causes \fIaddress_id\fP to be interpreted as the address of the data. +.PN XtBaseOffset +.IN "XtBaseOffset" "" "@DEF@" +causes \fIaddress_id\fP to be interpreted as the offset from the widget base. +.PN XtImmediate +.IN "XtImmediate" "" "@DEF@" +causes \fIaddress_id\fP to be interpreted as a constant. +.PN XtResourceString +.IN "XtResourceString" "" "@DEF@" +causes \fIaddress_id\fP to be interpreted as the name of a resource +that is to be converted into an offset from the widget base. +.PN XtResourceQuark +.IN "XtResourceQuark" "" "@DEF@" +causes \fIaddress_id\fP to be interpreted as the result of an +.PN XrmStringToQuark +conversion on the name of a resource, +which is to be converted into an offset from the widget base. +.PN XtWidgetBaseOffset +.IN "XtWidgetBaseOffset" "" "@DEF@" +is similar to +.PN XtBaseOffset +except that it +searches for the closest windowed ancestor if the object is not +of a subclass of +Core +(see Chapter 12). +.PN XtProcedureArg +.IN "XtProcedureArg" "" "@DEF@" +specifies that \fIaddress_id\fP is a pointer to a procedure to +be invoked to return the conversion argument. If +.PN XtProcedureArg +is specified, \fIaddress_id\fP must contain +the address of a function of type +.PN XtConvertArgProc . +.LP +.IN "XtConvertArgProc" "" "@DEF@" +.sM +.FD 0 +typedef void (*XtConvertArgProc)(Widget, Cardinal*, XrmValue*); +.br + Widget \fIobject\fP; +.br + Cardinal *\fIsize\fP; +.br + XrmValue *\fIvalue\fP; +.FN +.IP \fIobject\fP 1i +Passes the object for which the resource is being +converted, or NULL if the converter was invoked by +.PN XtCallConverter +or +.PN XtDirectConvert . +.IP \fIsize\fP 1i +Passes a pointer to the \fIsize\fP field from the +.PN XtConvertArgRec . +.IP \fIvalue\fP 1i +Passes a pointer to a descriptor into which the procedure +must store the conversion argument. +.LP +.eM +When invoked, the +.PN XtConvertArgProc +procedure must derive a conversion +argument and store the address and size of the argument in the location +pointed to by \fIvalue\fP. +.LP +In order to permit reentrancy, the +.PN XtConvertArgProc +should return the address of storage whose lifetime is no shorter than the +lifetime of \fIobject\fP. If \fIobject\fP is NULL, the lifetime of the conversion +argument must be no shorter than the lifetime of the resource with +which the conversion argument is associated. The \*(xI do not +guarantee to copy this storage but do guarantee not to reference it if +the resource is removed from the conversion cache. +.LP +The following example illustrates how to register the CvtStringToPixel +routine given earlier: +.LP +.Ds +.TA .2i 3i +.ta .2i 3i +static XtConvertArgRec colorConvertArgs[] = { + {XtWidgetBaseOffset, (XtPointer)XtOffset(Widget, core.screen), sizeof(Screen*)}, + {XtWidgetBaseOffset, (XtPointer)XtOffset(Widget, core.colormap),sizeof(Colormap)} +}; + +XtSetTypeConverter(XtRString, XtRPixel, CvtStringToPixel, + colorConvertArgs, XtNumber(colorConvertArgs), XtCacheByDisplay, NULL); +.De +.LP +The conversion argument descriptors +.PN colorConvertArgs +and +.PN screenConvertArg +are predefined by the \*(xI. Both take the +values from the closest windowed ancestor if the object is not of a +subclass of +Core. +The +.PN screenConvertArg +descriptor puts the widget's \fIscreen\fP field into \fIargs\fP[0]. The +.PN colorConvertArgs +descriptor puts the widget's \fIscreen\fP field into \fIargs\fP[0], +and the widget's \fIcolormap\fP field into \fIargs\fP[1]. +.LP +Conversion routines should not just put a descriptor for the address of the +base of the widget into \fIargs\fP[0], and use that in the routine. +They should pass in the actual values on which the conversion depends. +By keeping the dependencies of the conversion procedure specific, +it is more likely that subsequent conversions will find what they need +in the conversion cache. +This way the cache is smaller and has fewer and more widely applicable entries. +.LP +If any conversion arguments of type +.PN XtBaseOffset , +.PN XtResourceString , +.PN XtResourceQuark , +and +.PN XtWidgetBaseOffset +are specified for conversions performed by +.PN XtGetApplicationResources , +.PN XtGetSubresources , +.PN XtVaGetApplicationResources , +or +.PN XtVaGetSubresources , +the arguments are +computed with respect to the specified widget, not the base address or +resource list specified in the call. +.LP +If the +.PN XtConvertArgProc +modifies the resource database, +the changes affect any in-progress widget creation, +.PN XtGetApplicationResources , +or +.PN XtGetSubresources +in an implementation-defined manner; however, insertion of new entries +or changes to existing entries are allowed and will not directly cause +an error. + +.NH 3 +Resource Converter Invocation +.XS +\fB\*(SN Resource Converter Invocation\fP +.XE +.LP +All resource-fetching routines (for example, +.PN XtGetSubresources , +.PN XtGetApplicationResources , +and so on) call resource converters if the resource database or +varargs list specifies a value +that has a different representation from the desired representation or if the +widget's default resource value representation is different from the desired +representation. +.sp +.LP +To invoke explicit resource conversions, use +.PN XtConvertAndStore +or +.PN XtCallConverter . +.LP +.sM +.Ds 0 +typedef XtPointer XtCacheRef; +.De +.IN "XtCallConverter" "" "@DEF@" +.FD 0 +Boolean XtCallConverter(\fIdisplay\fP, \fIconverter\fP, \ +\fIconversion_args\fP, \fInum_args\fP, \fIfrom\fP, \fIto_in_out\fP, + \fIcache_ref_return\fP) +.br + Display* \fIdisplay\fP; +.br + XtTypeConverter \fIconverter\fP; +.br + XrmValuePtr \fIconversion_args\fP; +.br + Cardinal \fInum_args\fP; +.br + XrmValuePtr \fIfrom\fP; +.br + XrmValuePtr \fIto_in_out\fP; +.br + XtCacheRef *\fIcache_ref_return\fP; +.FN +.IP \fIdisplay\fP 1.5i +Specifies the display with which the conversion is to be associated. +.IP \fIconverter\fP 1.5i +Specifies the conversion procedure to be called. +.IP \fIconversion_args\fP 1.5i +Specifies the additional conversion arguments needed +to perform the conversion, or NULL. +.IP \fInum_args\fP 1.5i +Specifies the number of entries in \fIconversion_args\fP. +.IP \fIfrom\fP 1.5i +Specifies a descriptor for the source value. +.IP \fIto_in_out\fP 1.5i +Returns the converted value. +.IP \fIcache_ref_return\fP 1.5i +Returns a conversion cache id. +.LP +.eM +The +.PN XtCallConverter +function looks up the +specified type converter in the application context associated with +the display and, if the converter was not registered or was registered +with cache type +.PN XtCacheAll +or +.PN XtCacheByDisplay , +looks in the conversion cache to see if this conversion procedure +has been called with the specified conversion arguments. If so, it +checks the success status of the prior call, and if +the conversion failed, +.PN XtCallConverter +returns +.PN False +immediately; +otherwise it checks the size specified in the \fIto\fP argument, and, if it is +greater than or equal to the size stored in the cache, copies the +information stored in the cache into the location specified by +\fIto->addr\fP, stores the cache size into \fIto->size\fP, and returns +.PN True . +If the size specified in the \fIto\fP argument is smaller than the size stored +in the cache, +.PN XtCallConverter +copies the cache size into \fIto->size\fP and returns +.PN False . +If the converter was registered with cache type +.PN XtCacheNone +or no value was found in the conversion cache, +.PN XtCallConverter +calls the converter, and if it was not registered with cache type +.PN XtCacheNone , +enters the result in the cache. +.PN XtCallConverter +then returns what the converter returned. +.LP +The \fIcache_ref_return\fP field specifies storage allocated by the caller in which +an opaque value will be stored. If the type converter has been +registered with the +.PN XtCacheRefCount +modifier and if the value returned +in \fIcache_ref_return\fP is non-NULL, then the caller should store the +\fIcache_ref_return\fP value in order to decrement the reference count when +the converted value is no longer required. The \fIcache_ref_return\fP +argument should be +NULL if the caller is unwilling or unable to store the +value. +.sp +.LP +To explicitly decrement the reference counts for resources obtained +from +.PN XtCallConverter , +use +.PN XtAppReleaseCacheRefs . +.LP +.IN "XtAppReleaseCacheRefs" "" "@DEF@" +.sM +.FD 0 +void XtAppReleaseCacheRefs(\fIapp_context\fP, \fIrefs\fP) +.br + XtAppContext \fIapp_context\fP; +.br + XtCacheRef *\fIrefs\fP; +.FN +.IP \fIapp_context\fP 1i +Specifies the application context. +.IP \fIrefs\fP 1i +Specifies the list of cache references to be released. +.LP +.eM +.PN XtAppReleaseCacheRefs +decrements the reference count for the +conversion entries identified by the \fIrefs\fP argument. +This argument is a +pointer to a NULL-terminated list of +.PN XtCacheRef +values. If any reference +count reaches zero, the destructor, if any, will be called and +the resource removed from the conversion cache. +.sp +.LP +As a convenience to clients needing to explicitly decrement reference +counts via a callback function, the \*(xI define two callback +procedures, +.PN XtCallbackReleaseCacheRef +and +.PN XtCallbackReleaseCacheRefList . +.LP +.IN "XtCallbackReleaseCacheRef" "" "@DEF@" +.sM +.FD 0 +void XtCallbackReleaseCacheRef(\fIobject\fP, \fIclient_data\fP, \fIcall_data\fP) +.br + Widget \fIobject\fP; +.br + XtPointer \fIclient_data\fP; +.br + XtPointer \fIcall_data\fP; +.FN +.IP \fIobject\fP 1i +Specifies the object with which the resource is associated. +.IP \fIclient_data\fP 1i +Specifies the conversion cache entry to be released. +.IP \fIcall_data\fP 1i +Is ignored. +.LP +.eM +This callback procedure may be added to a callback list to release a +previously returned +.PN XtCacheRef +value. When adding the callback, the +callback \fIclient_data\fP argument must be specified as the value of the +.PN XtCacheRef +data cast to type +.PN XtPointer . +.LP +.IN "XtCallbackReleaseCacheRefList" "" "@DEF@" +.sM +.FD 0 +void XtCallbackReleaseCacheRefList(\fIobject\fP, \fIclient_data\fP, \fIcall_data\fP) +.br + Widget \fIobject\fP; +.br + XtPointer \fIclient_data\fP; +.br + XtPointer \fIcall_data\fP; +.FN +.IP \fIobject\fP 1i +Specifies the object with which the resources are associated. +.IP \fIclient_data\fP 1i +Specifies the conversion cache entries to be released. +.IP \fIcall_data\fP 1i +Is ignored. +.LP +.eM +This callback procedure may be added to a callback list to release a +list of previously returned +.PN XtCacheRef +values. When adding the +callback, the callback \fIclient_data\fP argument must be specified as a +pointer to a NULL-terminated list of +.PN XtCacheRef +values. +.sp +.LP +To lookup and call a resource converter, copy the resulting value, +and free a cached resource when a widget is destroyed, use +.PN XtConvertAndStore . +.LP +.IN "XtConvertAndStore" "" "@DEF@" +.sM +.FD 0 +Boolean XtConvertAndStore(\fIobject\fP, \fIfrom_type\fP, \fIfrom\fP, \ +\fIto_type\fP, \fIto_in_out\fP) +.br + Widget \fIobject\fP; +.br + String \fIfrom_type\fP; +.br + XrmValuePtr \fIfrom\fP; +.br + String \fIto_type\fP; +.br + XrmValuePtr \fIto_in_out\fP; +.FN +.IP \fIobject\fP 1i +Specifies the object to use for additional arguments, if any are needed, +and the destroy callback list. \*(oI +.IP \fIfrom_type\fP 1i +Specifies the source type. +.IP \fIfrom\fP 1i +Specifies the value to be converted. +.IP \fIto_type\fP 1i +Specifies the destination type. +.IP \fIto_in_out\fP 1i +Specifies a descriptor for storage into which the converted value +will be returned. +.LP +.eM +The +.PN XtConvertAndStore +function looks up the type converter registered +to convert \fIfrom_type\fP to \fIto_type\fP, computes any additional arguments +needed, and then calls +.PN XtCallConverter +(or +.PN XtDirectConvert +if an old-style converter was registered with +.PN XtAddConverter +or +.PN XtAppAddConverter ; +see Appendix C) with the \fIfrom\fP and \fIto_in_out\fP arguments. The +\fIto_in_out\fP argument specifies the size and location into which the +converted value will be stored and is passed directly to the +converter. If the location is specified as NULL, it will be replaced +with a pointer to private storage and the size will be returned in the +descriptor. The caller is expected to copy this private storage +immediately and must not modify it in any way. If a non-NULL location +is specified, the caller must allocate sufficient storage to hold the +converted value and must also specify the size of that storage in the +descriptor. +The \fIsize\fP field will be modified on return to indicate the actual +size of the converted data. +If the conversion succeeds, +.PN XtConvertAndStore +returns +.PN True ; +otherwise, it returns +.PN False . +.LP +.PN XtConvertAndStore +adds +.PN XtCallbackReleaseCacheRef +.IN "destroyCallback" +to the destroyCallback list of the specified object if the conversion +returns an +.PN XtCacheRef +value. The resulting resource should not be referenced +after the object has been destroyed. +.LP +.PN XtCreateWidget +performs processing equivalent to +.PN XtConvertAndStore +when initializing the object instance. Because there is extra memory +overhead required to implement reference counting, clients may +distinguish those objects that are never destroyed before the +application exits from those that may be destroyed and whose +resources should be deallocated. +.LP +To specify whether reference counting is to be enabled for the +resources of a particular object when the object is created, the +client can specify a value for the +.PN Boolean +resource +XtNinitialResourcesPersistent, +.IN "XtNinitialResourcesPersistent" "" "@DEF@" +class +XtCInitialResourcesPersistent. +.LP +When +.PN XtCreateWidget +is called, if this resource is not specified as +.PN False +in either the arglist or the resource database, then the +resources referenced by this object are not reference-counted, regardless of +how the type converter may have been registered. The effective +default value is +.PN True ; +thus clients that expect to destroy one or +more objects and want resources deallocated must explicitly specify +.PN False +for +.IN XtNinitialResourcesPersistent +XtNinitialResourcesPersistent. +.LP +The resources are still freed and destructors called when +.PN XtCloseDisplay +is called if the conversion was registered as +.PN XtCacheByDisplay . + +.NH 2 +Reading and Writing Widget State +.XS +\fB\*(SN Reading and Writing Widget State\fP +.XE +.LP +Any resource field in a widget can be read or written by a client. +On a write operation, +the widget decides what changes it will actually allow and updates all +derived fields appropriately. + +.NH 3 +Obtaining Widget State +.XS +\fB\*(SN Obtaining Widget State\fP +.XE +.LP +To retrieve the current values of resources associated with a +widget instance, use +.PN XtGetValues . +.LP +.IN "XtGetValues" "" "@DEF@" +.sM +.FD 0 +void XtGetValues(\fIobject\fP, \fIargs\fP, \fInum_args\fP) +.br + Widget \fIobject\fP; +.br + ArgList \fIargs\fP; +.br + Cardinal \fInum_args\fP; +.FN +.IP \fIobject\fP 1i +Specifies the object whose resource values are to be returned. \*(oI +.IP \fIargs\fP 1i +Specifies the argument list of name/address pairs that contain the +resource names and the addresses into which the resource values are to +be stored. +The resource names are widget-dependent. +.IP \fInum_args\fP 1i +Specifies the number of entries in the argument list. +.LP +.eM +The +.PN XtGetValues +function starts with the resources specified for the Object class +and proceeds down the subclass chain to the class of the object. +The \fIvalue\fP field of a passed argument list must contain the +address into which to copy the contents of the corresponding +object instance field. If the field is a pointer type, the lifetime +of the pointed-to data is defined by the object class. For the +\*(xI-defined resources, the following lifetimes apply: +.IP \(bu 3 +Not valid following any operation that modifies the resource: +.RS +.IP \- 3 +XtNchildren resource of composite widgets. +.IP \- 3 +All resources of representation type XtRCallback. +.RE +.IP \(bu 3 +Remain valid at least until the widget is destroyed: +.RS +.IP \- 3 +XtNaccelerators, XtNtranslations. +.RE +.IP \(bu 3 +Remain valid until the Display is closed: +.RS +.IP \- 3 +XtNscreen. +.RE +.LP +It is the caller's responsibility +to allocate and deallocate storage for the copied data +according to the size of the +resource representation type used within the object. +.LP +If the class of the object's parent is a subclass of +.PN constraintWidgetClass , +.PN XtGetValues +then fetches the values for any constraint resources requested. +It starts with the constraint resources specified for +.PN constraintWidgetClass +and proceeds down the subclass chain to the parent's constraint resources. +If the argument list contains a resource name that is not found in any of the +resource lists searched, +the value at the corresponding address is not modified. +.IN "get_values_hook procedure" +If any get_values_hook procedures in the +object's class or superclass records are non-NULL, +they are called in superclass-to-subclass order after +all the resource values have been fetched by +.PN XtGetValues . +Finally, if the object's parent is a +subclass of +.PN constraintWidgetClass , +and if any of the parent's class or +superclass records have declared +.PN ConstraintClassExtension +records in +the Constraint class part \fIextension\fP field with a record type of +.PN \s-1NULLQUARK\s+1 , +and if the \fIget_values_hook\fP field in the extension record is non-NULL, +.PN XtGetValues +calls the get_values_hook procedures in superclass-to-subclass order. +This permits a Constraint parent to provide +nonresource data via +.PN XtGetValues . +.LP +Get_values_hook procedures may modify the data stored at the +location addressed by the \fIvalue\fP field, including (but not +limited to) making a copy of data whose resource representation is a +pointer. None of the \*(xI-defined object classes copy +data in this manner. Any operation that modifies the queried +object resource may invalidate the pointed-to data. + +.sp +.LP +To retrieve the current values of resources associated with a widget +instance using varargs lists, use +.PN XtVaGetValues . +.LP +.IN "XtVaGetValues" "" "@DEF@" +.sM +.FD 0 +void XtVaGetValues(\fIobject\fP, ...) +.br + Widget \fIobject\fP; +.FN +.IP \fIobject\fP 1i +Specifies the object whose resource values are to be returned. \*(oI +.IP ... 1i +Specifies the variable argument list for the resources to +be returned. +.LP +.eM +.PN XtVaGetValues +is identical in function to +.PN XtGetValues +with the \fIargs\fP +and \fInum_args\fP parameters replaced by a varargs list, as described in +Section 2.5.1. All value entries in the list must specify pointers to +storage allocated by the caller to which the resource value will be +copied. It is the caller's responsibility to ensure that sufficient +storage is allocated. If +.PN XtVaTypedArg +is specified, the \fItype\fP argument +specifies the representation desired by the caller and \fIthe\fP size argument +specifies the number of bytes allocated to store the result of the +conversion. If the size is insufficient, a warning message is issued +and the list entry is skipped. + +.NH 4 +Widget Subpart Resource Data: The get_values_hook Procedure +.XS +\*(SN Widget Subpart Resource Data: The get_values_hook Procedure +.XE +.LP +Widgets that have subparts can return resource values from them through +.PN XtGetValues +by supplying a get_values_hook procedure. +The get_values_hook procedure pointer is of type +.PN XtArgsProc . +.LP +.IN "get_values_hook procedure" "" "@DEF@" +.sM +.FD 0 +typedef void (*XtArgsProc)(Widget, ArgList, Cardinal*); +.br + Widget \fIw\fP; +.br + ArgList \fIargs\fP; +.br + Cardinal *\fInum_args\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget whose subpart resource values are to be retrieved. +.IP \fIargs\fP 1i +Specifies the argument list that was passed to +.PN XtGetValues +or the transformed varargs list passed to +.PN XtVaGetValues . +.IP \fInum_args\fP 1i +Specifies the number of entries in the argument list. +.LP +.eM +The widget with subpart resources should call +.PN XtGetSubvalues +in the get_values_hook procedure +and pass in its subresource list and the \fIargs\fP and \fInum_args\fP parameters. + +.NH 4 +Widget Subpart State +.XS +\*(SN Widget Subpart State +.XE +.LP +To retrieve the current values of subpart resource data associated with a +widget instance, use +.PN XtGetSubvalues . +For a discussion of subpart resources, +see Section 9.4. +.LP +.IN "XtGetSubvalues" "" "@DEF@" +.sM +.FD 0 +void XtGetSubvalues(\fIbase\fP, \fIresources\fP, \fInum_resources\fP, \ +\fIargs\fP, \fInum_args\fP) +.br + XtPointer \fIbase\fP; +.br + XtResourceList \fIresources\fP; +.br + Cardinal \fInum_resources\fP; +.br + ArgList \fIargs\fP; +.br + Cardinal \fInum_args\fP; +.FN +.IP \fIbase\fP 1i +Specifies the base address of the subpart data structure for which the +resources should be retrieved. +.IP \fIresources\fP 1i +Specifies the subpart resource list. +.IP \fInum_resources\fP 1i +Specifies the number of entries in the resource list. +.IP \fIargs\fP 1i +Specifies the argument list of name/address pairs that contain the +resource names and the addresses into which the resource values are to +be stored. +.IP \fInum_args\fP 1i +Specifies the number of entries in the argument list. +.LP +.eM +The +.PN XtGetSubvalues +function obtains resource values from the structure identified by \fIbase\fP. +The \fIvalue\fP field in each argument entry must contain the address into +which to store the corresponding resource value. It is the caller's +responsibility to allocate and deallocate this storage according to +the size of the resource representation type used within the subpart. +If the argument list contains a resource name that is not found in the +resource list, the value at the corresponding address is not modified. + +.sp +.LP +To retrieve the current values of subpart resources associated with +a widget instance using varargs lists, use +.PN XtVaGetSubvalues . +.LP +.IN "XtVaGetSubvalues" "" "@DEF@" +.sM +.FD 0 +void XtVaGetSubvalues(\fIbase\fP, \fIresources\fP, \fInum_resources\fP, ...) +.br + XtPointer \fIbase\fP; +.br + XtResourceList \fIresources\fP; +.br + Cardinal \fInum_resources\fP; +.FN +.IP \fIbase\fP 1i +Specifies the base address of the subpart data structure for which the +resources should be retrieved. +.IP \fIresources\fP 1i +Specifies the subpart resource list. +.IP \fInum_resources\fP 1i +Specifies the number of entries in the resource list. +.IP ... 1i +Specifies a variable argument list of name/address pairs that +contain the resource names and the addresses into which the resource +values are to be stored. +.LP +.eM +.PN XtVaGetSubvalues +is identical in function to +.PN XtGetSubvalues +with the +\fIargs\fP and \fInum_args\fP parameters replaced by a varargs list, as described +in Section 2.5.1. +.PN XtVaTypedArg +is not supported for +.PN XtVaGetSubvalues . +If +.PN XtVaTypedArg +is specified in the list, a warning message is issued +and the entry is then ignored. + +.NH 3 +Setting Widget State +.XS +\fB\*(SN Setting Widget State\fP +.XE +.LP +To modify the current values of resources associated with a widget +instance, use +.PN XtSetValues . +.LP +.IN "XtSetValues" "" "@DEF@" +.sM +.FD 0 +void XtSetValues(\fIobject\fP, \fIargs\fP, \fInum_args\fP) +.br + Widget \fIobject\fP; +.br + ArgList \fIargs\fP; +.br + Cardinal \fInum_args\fP; +.FN +.IP \fIobject\fP 1i +Specifies the object whose resources are to be modified. \*(oI +.IP \fIargs\fP 1i +Specifies the argument list of name/value pairs that contain the +resources to be modified and their new values. +.IP \fInum_args\fP 1i +Specifies the number of entries in the argument list. +.LP +.eM +The +.PN XtSetValues +function starts with the resources specified for the +Object +class fields and proceeds down the subclass chain to the object. +At each stage, it replaces the \fIobject\fP resource fields with any values +specified in the argument list. +.PN XtSetValues +then calls the set_values procedures for the object in superclass-to-subclass +order. +.IN "set_values_hook procedure" +If the object has any non-NULL \fIset_values_hook\fP fields, +these are called immediately after the +corresponding set_values procedure. +This procedure permits subclasses to set subpart data via +.PN XtSetValues . +.LP +If the class of the object's parent is a subclass of +.PN constraintWidgetClass , +.PN XtSetValues +also updates the object's constraints. +It starts with the constraint resources specified for +.PN constraintWidgetClass +and proceeds down the subclass chain to the parent's class. +At each stage, it replaces the constraint resource fields with any +values specified in the argument list. +It then calls the constraint set_values procedures from +.PN constraintWidgetClass +down to the parent's class. +The constraint set_values procedures are called with widget arguments, +as for all set_values procedures, not just the constraint records, +so that they can make adjustments to the desired values based +on full information about the widget. Any arguments specified that +do not match a resource list entry are silently ignored. +.LP +If the object is of a subclass of +RectObj, +.PN XtSetValues +determines if a geometry request is needed by comparing the old object to +the new object. +If any geometry changes are required, +.PN XtSetValues +restores the original geometry and makes the request on behalf of the widget. +If the geometry manager returns +.PN XtGeometryYes , +.PN XtSetValues +calls the object's resize procedure. +If the geometry manager returns +.PN XtGeometryDone , +.PN XtSetValues +continues, as the object's resize procedure should have been called +by the geometry manager. +If the geometry manager returns +.PN XtGeometryNo , +.PN XtSetValues +ignores the geometry request and continues. +If the geometry manager returns +.PN XtGeometryAlmost , +.PN XtSetValues +calls the set_values_almost procedure, +which determines what should be done. +.PN XtSetValues +then repeats this process, +deciding once more whether the geometry manager should be called. +.LP +Finally, if any of the set_values procedures returned +.PN True , +and the widget is realized, +.PN XtSetValues +causes the widget's expose procedure to be invoked by calling +.PN XClearArea +on the widget's window. +.sp +.LP +To modify the current values of resources associated with a widget +instance using varargs lists, use +.PN XtVaSetValues . +.LP +.IN "XtVaSetValues" "" "@DEF@" +.sM +.FD 0 +void XtVaSetValues(\fIobject\fP, ...) +.br + Widget \fIobject\fP; +.FN +.IP \fIobject\fP 1i +Specifies the object whose resources are to be modified. \*(oI +.IP ... 1i +Specifies the variable argument list of name/value pairs that +contain the resources to be modified and their new values. +.LP +.eM +.PN XtVaSetValues +is identical in function to +.PN XtSetValues +with the \fIargs\fP and \fInum_args\fP parameters replaced by a varargs list, as +described in Section 2.5.1. + +.NH 4 +Widget State: The set_values Procedure +.XS +\*(SN Widget State: The set_values Procedure +.XE +.LP +The set_values procedure pointer in a widget class is of type +.PN XtSetValuesFunc . +.LP +.IN "XtSetValuesFunc" "" "@DEF@" +.IN "set_values procedure" "" "@DEF@" +.sM +.FD 0 +typedef Boolean (*XtSetValuesFunc)(Widget, Widget, Widget, ArgList, Cardinal*); +.br + Widget \fIcurrent\fP; +.br + Widget \fIrequest\fP; +.br + Widget \fInew\fP; +.br + ArgList \fIargs\fP; +.br + Cardinal *\fInum_args\fP; +.FN +.IP \fIcurrent\fP 1i +Specifies a copy of the widget as it was before the +.PN XtSetValues +call. +.IP \fIrequest\fP 1i +Specifies a copy of the widget with all values changed as asked for by the +.PN XtSetValues +call before any class set_values procedures have been called. +.IP \fInew\fP 1i +Specifies the widget with the new values that are actually allowed. +.IP \fIargs\fP 1i +Specifies the argument list passed to +.PN XtSetValues +or the transformed argument list passed to +.PN XtVaSetValues . +.IP \fInum_args\fP 1i +Specifies the number of entries in the argument list. +.LP +.eM +The set_values procedure should recompute any field +derived from resources that are changed +(for example, many GCs depend on foreground and background pixels). +If no recomputation is necessary, and if none of the resources specific to a +subclass require the window to be redisplayed when their values are changed, +you can specify NULL for the \fIset_values\fP field in the class record. +.LP +Like the initialize procedure, +set_values mostly deals only with the fields defined in the subclass, +but it has to resolve conflicts with its superclass, +especially conflicts over width and height. +.LP +Sometimes a subclass may want to overwrite values filled in by its +superclass. +In particular, size calculations of a superclass are often +incorrect for a subclass, and, in this case, +the subclass must modify or recalculate fields declared +and computed by its superclass. +.LP +As an example, +a subclass can visually surround its superclass display. +In this case, the width and height calculated by the superclass set_values +procedure are too small and need to be incremented by the size of the surround. +The subclass needs to know if its superclass's size was calculated by the +superclass or was specified explicitly. +All widgets must place themselves into whatever size is explicitly given, +but they should compute a reasonable size if no size is requested. +How does a subclass know the difference between a specified size +and a size computed by a superclass? +.LP +The \fIrequest\fP and \fInew\fP parameters provide the necessary information. +The \fIrequest\fP widget is a copy of the widget, updated as originally requested. +The \fInew\fP widget starts with the values in the request, +but it has additionally been updated by all superclass set_values +procedures called so far. +A subclass set_values procedure can compare these two to resolve +any potential conflicts. +The set_values procedure need not refer to the \fIrequest\fP widget +unless it must resolve conflicts between the \fIcurrent\fP and \fInew\fP widgets. +Any changes the widget needs to make, including geometry changes, +should be made in the \fInew\fP widget. +.LP +In the above example, +the subclass with the visual surround can see +if the \fIwidth\fP and \fIheight\fP in the \fIrequest\fP widget are zero. +If so, +it adds its surround size to the \fIwidth\fP and +\fIheight\fP fields in the \fInew\fP widget. +If not, it must make do with the size originally specified. +In this case, zero is a special value defined by the class to permit +the application to invoke this behavior. +.LP +The \fInew\fP widget is the actual widget instance record. +Therefore, +the set_values procedure should do all its work on the \fInew\fP widget; +the \fIrequest\fP widget should never be modified. +If the set_values procedure needs to call any routines that operate on +a widget, it should specify \fInew\fP as the widget instance. +.LP +Before calling the set_values procedures, the \*(xI modify the +resources of the \fIrequest\fP widget according to the contents of the arglist; +if the widget names all its resources in the class resource list, it is +never necessary to examine the contents of \fIargs\fP. +.LP +Finally, the set_values procedure must return a Boolean that indicates whether +the widget needs to be redisplayed. +Note that a change in the geometry fields alone does not require +the set_values procedure to return +.PN True ; +the X server will eventually generate an +.PN Expose +event, if necessary. +After calling all the set_values procedures, +.PN XtSetValues +forces a redisplay by calling +.PN XClearArea +if any of the set_values procedures returned +.PN True . +Therefore, a set_values procedure should not try to do its own redisplaying. +.LP +Set_values procedures should not do any work in response to changes in +geometry because +.PN XtSetValues +eventually will perform a geometry request, and that request might be denied. +If the widget actually changes size in response to a +call to +.PN XtSetValues , +its resize procedure is called. +Widgets should do any geometry-related work in their resize procedure. +.LP +Note that it is permissible to call +.PN XtSetValues +before a widget is realized. +Therefore, the set_values procedure must not assume that the widget is realized. + +.NH 4 +Widget State: The set_values_almost Procedure +.XS +\*(SN Widget State: The set_values_almost Procedure +.XE +.LP +The set_values_almost procedure pointer in the widget class record is of type +.PN XtAlmostProc . +.LP +.IN "set_values_almost procedure" "" "@DEF@" +.IN "XtAlmostProc" "" "@DEF@" +.sM +.FD 0 +typedef void (*XtAlmostProc)(Widget, Widget, XtWidgetGeometry*, \ +XtWidgetGeometry*); +.br + Widget \fIold\fP; +.br + Widget \fInew\fP; +.br + XtWidgetGeometry *\fIrequest\fP; +.br + XtWidgetGeometry *\fIreply\fP; +.FN +.IP \fIold\fP 1i +Specifies a copy of the object as it was before the +.PN XtSetValues +call. +.IP \fInew\fP 1i +Specifies the object instance record. +.IP \fIrequest\fP 1i +Specifies the original geometry request that was sent to the geometry +manager that caused +.PN XtGeometryAlmost +to be returned. +.IP \fIreply\fP 1i +Specifies the compromise geometry that was returned by the geometry +manager with +.PN XtGeometryAlmost . +.LP +.eM +Most classes inherit the set_values_almost procedure from their superclass by +specifying +.PN XtInheritSetValuesAlmost +in the class initialization. +The +set_values_almost procedure in +.PN rectObjClass +accepts the compromise suggested. +.LP +The set_values_almost procedure is called when a client tries to set a widget's +geometry by means of a call to +.PN XtSetValues +and the geometry manager cannot +satisfy the request but instead returns +.PN XtGeometryNo +or +.PN XtGeometryAlmost +and a compromise geometry. +The \fInew\fP object is the actual instance record. The \fIx\fP, \fIy\fP, +\fIwidth\fP, \fIheight\fP, +and \fIborder_width\fP fields contain the original values as they were +before the +.PN XtSetValues +call, and all other fields contain the new +values. The \fIrequest\fP parameter contains the new geometry request that +was made to the parent. The \fIreply\fP parameter contains +\fIreply->request_mode\fP equal to zero if the parent returned +.PN XtGeometryNo +and contains the parent's compromise geometry otherwise. The +set_values_almost procedure takes the original geometry and the +compromise geometry and determines if the compromise is +acceptable or whether +to try a different compromise. +It returns its results in the \fIrequest\fP parameter, +which is then sent back to the geometry manager for another try. +To accept the compromise, the procedure must copy the contents +of the \fIreply\fP geometry into the \fIrequest\fP geometry; to attempt an +alternative geometry, the procedure may modify any part of the \fIrequest\fP +argument; to terminate the geometry negotiation and retain the +original geometry, the procedure must set \fIrequest->request_mode\fP to +zero. The geometry fields of the \fIold\fP and \fInew\fP instances must not be modified +directly. + +.NH 4 +Widget State: The ConstraintClassPart set_values Procedure +.XS +\*(SN Widget State: The ConstraintClassPart set_values Procedure +.XE +.IN "set_values procedure" +.LP +The constraint set_values procedure pointer is of type +.PN XtSetValuesFunc . +The values passed to the parent's constraint set_values procedure +are the same as those passed to the child's class +set_values procedure. +A class can specify NULL for the \fIset_values\fP field of the +.PN ConstraintPart +if it need not compute anything. +.LP +The constraint set_values procedure should recompute any constraint fields +derived from constraint resources that are changed. +Furthermore, it may modify other widget fields as appropriate. +For example, if a constraint for the maximum height of a widget is changed +to a value smaller than the widget's current height, +the constraint set_values procedure may reset the \fIheight\fP field in the +widget. + +.NH 4 +Widget Subpart State +.XS +\*(SN Widget Subpart State +.XE +.LP +To set the current values of subpart resources associated with a +widget instance, use +.PN XtSetSubvalues . +For a discussion of subpart resources, +see Section 9.4. +.LP +.IN "XtSetSubvalues" "" "@DEF@" +.sM +.FD 0 +void XtSetSubvalues(\fIbase\fP, \fIresources\fP, \fInum_resources\fP, \ +\fIargs\fP, \fInum_args\fP) +.br + XtPointer \fIbase\fP; +.br + XtResourceList \fIresources\fP; +.br + Cardinal \fInum_resources\fP; +.br + ArgList \fIargs\fP; +.br + Cardinal \fInum_args\fP; +.FN +.IP \fIbase\fP 1i +Specifies the base address of the subpart data structure into which the +resources should be written. +.IP \fIresources\fP 1i +Specifies the subpart resource list. +.IP \fInum_resources\fP 1i +Specifies the number of entries in the resource list. +.IP \fIargs\fP 1i +Specifies the argument list of name/value pairs that contain the +resources to be modified and their new values. +.IP \fInum_args\fP 1i +Specifies the number of entries in the argument list. +.LP +.eM +The +.PN XtSetSubvalues +function updates the resource fields of the structure identified by +\fIbase\fP. Any specified arguments that do not match an entry in the +resource list are silently ignored. +.sp +.LP +To set the current values of subpart resources associated with +a widget instance using varargs lists, use +.PN XtVaSetSubvalues . +.LP +.IN "XtVaSetSubvalues" "" "@DEF@" +.sM +.FD 0 +void XtVaSetSubvalues(\fIbase\fP, \fIresources\fP, \fInum_resources\fP, ...) +.br + XtPointer \fIbase\fP; +.br + XtResourceList \fIresources\fP; +.br + Cardinal \fInum_resources\fP; +.FN +.IP \fIbase\fP 1i +Specifies the base address of the subpart data structure into which the +resources should be written. +.IP \fIresources\fP 1i +Specifies the subpart resource list. +.IP \fInum_resources\fP 1i +Specifies the number of entries in the resource list. +.IP ... 1i +Specifies the variable argument list of name/value pairs that +contain the resources to be modified and their new values. +.LP +.eM +.PN XtVaSetSubvalues +is identical in function to +.PN XtSetSubvalues +with the \fIargs\fP and \fInum_args\fP parameters replaced by a varargs list, as +described in Section 2.5.1. +.PN XtVaTypedArg +is not supported for +.PN XtVaSetSubvalues . +If an entry containing +.PN XtVaTypedArg +is specified in the list, a warning message is issued +and the entry is ignored. + +.NH 4 +Widget Subpart Resource Data: The set_values_hook Procedure +.XS +\*(SN Widget Subpart Resource Data: The set_values_hook Procedure +.XE +.IN "set_values_hook procedure" +.NT +The set_values_hook procedure is obsolete, as the same information +is now available to the set_values procedure. The procedure has been +retained for those widgets that used it in versions prior to Release 4. +.NE +.LP +Widgets that have a subpart can set the subpart resource values through +.PN XtSetValues +by supplying a set_values_hook procedure. +The set_values_hook procedure pointer in a widget class is of type +.PN XtArgsFunc . +.LP +.IN "set_values_hook procedure" "" "@DEF@" +.IN "XtArgsFunc" "" "@DEF@" +.sM +.FD 0 +typedef Boolean (*XtArgsFunc)(Widget, Arglist, Cardinal*); +.br + Widget \fIw\fP; +.br + Arglist \fIargs\fP; +.br + Cardinal *\fInum_args\fP; +.FN +.IP \fIw\fP 1i +Specifies the widget whose subpart resource values are to be changed. +.IP \fIargs\fP 1i +Specifies the argument list that was passed to +.PN XtSetValues +or the transformed varargs list passed to +.PN XtVaSetValues . +.IP \fInum_args\fP 1i +Specifies the number of entries in the argument list. +.LP +.eM +The widget with subpart resources may call +.PN XtSetValues +from the set_values_hook procedure +and pass in its subresource list and the +\fIargs\fP and \fInum_args\fP parameters. +.bp |