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