From 5f8448ef6b85a9ff72c5af4cec99183c8bb60dc6 Mon Sep 17 00:00:00 2001 From: marha Date: Tue, 10 Apr 2012 14:58:33 +0200 Subject: Updated following packages: bigreqsproto-1.1.2 fontsproto-2.1.2 recordproto-1.14.2 scrnsaverproto-1.2.2 xcmiscproto-1.2.2 libXt-1.1.3 xhost-1.0.5 kbproto-1.0.6 libXrender-0.9.7 libxkbfile-1.0.8 freetype-2.4.9 libXaw-1.0.10 libXpm-3.5.10 xproto-7.0.23 --- libXt/specs/CH09.xml | 4326 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 4326 insertions(+) create mode 100644 libXt/specs/CH09.xml (limited to 'libXt/specs/CH09.xml') diff --git a/libXt/specs/CH09.xml b/libXt/specs/CH09.xml new file mode 100644 index 000000000..1f64de593 --- /dev/null +++ b/libXt/specs/CH09.xml @@ -0,0 +1,4326 @@ + +Resource Management + +A resource is a field in the widget record with a corresponding +resource entry in the resources list of the widget or any of its +superclasses. +This means that the field is +settable by + +(by naming the field in the argument list), by an +entry in a resource file (by using either the name or class), and by +. +In addition, it is readable by +. +Not all fields in a widget record are resources. +Some are for bookkeeping use by the +generic routines (like managed and being_destroyed). +Others can be for local bookkeeping, +and still others are derived from resources +(many graphics contexts and pixmaps). + + + +Widgets typically need to obtain a large set of resources at widget +creation time. +Some of the resources come from the argument list supplied in the call to +, +some from the resource database, +and some from the internal defaults specified by the widget. +Resources are obtained first from the argument list, +then from the resource database for all resources not specified +in the argument list, +and last, from the internal default, if needed. + + +Resource Lists + +A resource entry specifies a field in the widget, +the textual name and class of the field that argument lists +and external resource files use to refer to the field, +and a default value that the field should get if no value is specified. +The declaration for the +XtResource +structure is + + +typedef struct { + String resource_name; + String resource_class; + String resource_type; + Cardinal resource_size; + Cardinal resource_offset; + String default_type; + XtPointer default_addr; +} XtResource, *XtResourceList; + + +When the resource list is specified as the +CoreClassPart, +ObjectClassPart, +RectObjClassPart, +or +ConstraintClassPart +resources field, the strings pointed to by resource_name, +resource_class, resource_type, and default_type must +be permanently allocated prior to or during the execution of the class +initialization procedure and must not be subsequently deallocated. + + + +The resource_name field contains the name used by clients to access the field +in the widget. +By convention, it starts with a lowercase letter +and is spelled exactly like the field name, +except all underscores (_) are deleted and the next letter is replaced by its +uppercase counterpart. +For example, the resource name for background_pixel becomes backgroundPixel. +Resource names beginning with the two-character +sequence ``xt'', and resource classes beginning with the two-character +sequence ``Xt'' are reserved to the Intrinsics for future standard and +implementation-dependent uses. +Widget header files typically contain a symbolic name for each resource name. +All resource names, classes, and types used by the Intrinsics are named in +<X11/StringDefs.h>. +The Intrinsics's symbolic resource names begin with +``XtN'' +and are followed by the string name (for example, XtNbackgroundPixel +for backgroundPixel). + + + +The resource_class field contains the class string used in resource +specification files to identify the field. +A resource class provides two functions: + + + + +It isolates an application from different representations that widgets +can use for a similar resource. + + + + +It lets you specify values for several actual resources with a single name. +A resource class should be chosen to span a group of closely related fields. + + + + +For example, +a widget can have several pixel resources: background, foreground, +border, block cursor, pointer cursor, and so on. +Typically, the background defaults to white +and everything else to black. +The resource class for each of these resources in the resource list +should be chosen so that it takes the minimal number of entries +in the resource database to make the background ivory +and everything else darkblue. + + + +In this case, the background pixel should have a resource class of +``Background'' +and all the other pixel entries a resource class of +``Foreground''. +Then, the resource file needs only two lines to +change all pixels to ivory or darkblue: + + +*Background: ivory +*Foreground: darkblue + + +Similarly, a widget may have several font resources (such as normal and bold), +but all fonts should have the class Font. +Thus, changing all fonts simply requires only a single line in the +default resource file: + + +*Font: 6x13 + + +By convention, +resource classes are always spelled starting with a capital letter +to distinguish them from resource names. +Their symbolic names are preceded with +``XtC'' +(for example, XtCBackground). + + + +The resource_type field gives the physical representation type of the resource +and also encodes information about the specific usage of the field. +By convention, it starts with an uppercase letter and is +spelled identically to the type name of the field. +The resource type is used when resources are fetched to +convert from the resource database format (usually +String) +or the format of the resource default value +(almost anything, but often +String) +to the desired +physical representation (see ). +The Intrinsics define the following resource types: + + + + + + + + + + Resource Type + Structure or Field Type + + + + + XtRAcceleratorTable + XtAccelerators + + + XtRAtom + Atom + + + XtRBitmap + Pixmap, depth=1 + + + XtRBoolean + Boolean + + + XtRBool + Bool + + + XtRCallback + XtCallbackList + + + XtRCardinal + Cardinal + + + XtRColor + XColor + + + XtRColormap + Colormap + + + XtRCommandArgArray + String* + + + XtRCursor + Cursor + + + XtRDimension + Dimension + + + XtRDirectoryString + String + + + XtRDisplay + Display* + + + XtREnum + XtEnum + + + XtREnvironmentArray + String* + + + XtRFile + FILE* + + + XtRFloat + float + + + XtRFont + Font + + + XtRFontSet + XFontSet + + + XtRFontStruct + XFontStruct* + + + XtRFunction + (*)() + + + XtRGeometry + char*, format as defined by + XParseGeometry + + + XtRGravity + int + + + XtRInitialState + int + + + XtRInt + int + + + XtRLongBoolean + long + + + XtRObject + Object + + + XtRPixel + Pixel + + + XtRPixmap + Pixmap + + + XtRPointer + XtPointer + + + XtRPosition + Position + + + XtRRestartStyle + unsigned char + + + XtRScreen + Screen* + + + XtRShort + short + + + XtRSmcConn + XtPointer + + + XtRString + String + + + XtRStringArray + String* + + + XtRStringTable + String* + + + XtRTranslationTable + XtTranslations + + + XtRUnsignedChar + unsigned char + + + XtRVisual + Visual* + + + XtRWidget + Widget + + + XtRWidgetClass + WidgetClass + + + XtRWidgetList + WidgetList + + + XtRWindow + Window + + + + + + +<X11/StringDefs.h> +also defines the following resource types as a +convenience for widgets, although they do not have any corresponding +data type assigned: +XtREditMode, +XtRJustify, +and +XtROrientation. + + + +The resource_size field is the size of the physical representation in bytes; +you should specify it as +sizeof(type) so that the +compiler fills in the value. +The resource_offset field is the offset in bytes of the field +within the widget. +You should use the + +macro to retrieve this value. +The default_type field is the representation type of the default +resource value. +If default_type is different from resource_type and the default value +is needed, +the resource manager invokes a conversion procedure from default_type +to resource_type. +Whenever possible, +the default type should be identical to the resource type in order +to minimize widget creation time. +However, there are sometimes no values of the type that the program +can easily specify. +In this case, +it should be a value for which the converter is guaranteed to work (for example, +XtDefaultForeground +for a pixel resource). +The default_addr field specifies the address of the default resource value. +As a special case, if default_type is +XtRString, +then the value in the default_addr field is the pointer to +the string rather than a pointer to the pointer. +The default is used if a resource is not specified in the argument list +or in the resource database or if the conversion from the representation +type stored in the resource database fails, +which can happen for various reasons (for example, a misspelled entry in a +resource file). + + + +Two special representation types +(XtRImmediate +and +XtRCallProc) +are usable only as default resource types. +XtRImmediate +indicates that the value in the default_addr field is the actual value of +the resource rather than the address of the value. +The value must be in the correct representation type for the resource, +coerced to an +XtPointer. +No conversion is possible, since there is no source representation type. +XtRCallProc +indicates that the value in the default_addr field is a procedure +pointer. +This procedure is automatically invoked with the widget, +resource_offset, and a pointer to an +XrmValue +in which to store the result. +XtRCallProc +procedure pointers are of type +. + + + + +typedef void (*XtResourceDefaultProc) + Widget w + int offset + XrmValue *value + + + + + + + w + + + +Specifies the widget whose resource value is to be obtained. + + + + + + offset + + + +Specifies the offset of the field in the widget record. + + + + + + value + + + +Specifies the resource value descriptor to return. + + + + + + +The + +procedure should fill in the value->addr field with a pointer +to the resource value in its correct representation type. + + + +To get the resource list structure for a particular class, use +. + + + + +void XtGetResourceList + + WidgetClass class + XtResourceList *resources_return + Cardinal *num_resources_return + + + + + + + class + + + +Specifies the object class to be queried. It must be +objectClass +or any subclass thereof. + + + + + + resources_return + + + +Returns the resource list. + + + + + + num_resources_return + + + +Returns the number of entries in the resource list. + + + + + + +If + +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, + +returns a merged resource list that includes the resources +for all superclasses. +The list returned by + +should be freed using + +when it is no longer needed. + + + +To get the constraint resource list structure for a particular widget +class, use +. + + + + +void XtGetConstraintResourceList + WidgetClass class + XtResourceList *resources_return + Cardinal *num_resources_return + + + + + + + class + + + +Specifies the object class to be queried. It must be +objectClass +or any subclass thereof. + + + + + + resources_return + + + +Returns the constraint resource list. + + + + + + num_resources_return + + + +Returns the number of entries in the constraint resource list. + + + + + + +If + +is called before the widget class is +initialized, the resource list as specified in the widget +class Constraint part is returned. If + +is called after the widget class has been initialized, the merged +resource list for the class and all Constraint superclasses is +returned. If the +specified class is not a subclass of +constraintWidgetClass, +*resources_return is set to NULL +and *num_resources_return is set to zero. +The list returned by + +should be freed using + +when it is no longer needed. + + + +The routines + +and + +also use the resource list to set and get widget state; +see and +. + + + +Here is an abbreviated version of a possible resource list for a Label widget: + + +/* Resources specific to Label */ +static XtResource resources[] = { +{XtNforeground, XtCForeground, XtRPixel, sizeof(Pixel), + XtOffsetOf(LabelRec, label.foreground), XtRString, XtDefaultForeground}, +{XtNfont, XtCFont, XtRFontStruct, sizeof(XFontStruct*), + XtOffsetOf(LabelRec, label.font), XtRString, XtDefaultFont}, +{XtNlabel, XtCLabel, XtRString, sizeof(String), + XtOffsetOf(LabelRec, label.label), XtRString, NULL}, + . + . + . +} + + +The complete resource name for a field of a widget instance is the +concatenation of the application shell name (from +XtAppCreateShell ), +the instance names of all the widget's parents up to the +top of the widget tree, +the instance name of the widget itself, +and the resource name of the specified field of the widget. +Similarly, +the full resource class of a field of a widget instance is the +concatenation of the application class (from +XtAppCreateShell ), +the widget class names of all the widget's parents up to the +top of the widget tree, +the widget class name of the widget itself, +and the resource class of the specified field of the widget. + + + + +Byte Offset Calculations + +To determine the byte offset of a field within a structure type, use +. + + + + +Cardinal XtOffsetOf + Type structure_type + Field field_name + + + + + + + + + structure_type + + + +Specifies a type that is declared as a structure. + + + + + + field_name + + + +Specifies the name of a member within the structure. + + + + + + +The + +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 +, +which serves the same function. + + + +To determine the byte offset of a field within a structure pointer type, use +. + + + + +Cardinal XtOffset + Type pointer_type + Field field_name + + + + + + + pointer_type + + + +Specifies a type that is declared as a pointer to a structure. + + + + + + field_name + + + +Specifies the name of a member within the structure. + + + + + + +The + +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. + +is less portable than +. + + + + +Superclass-to-Subclass Chaining of Resource Lists + +The + +function gets resources as a superclass-to-subclass chained operation. +That is, the resources specified in the +objectClass +resource list are fetched, +then those in +rectObjClass, +and so on down to the resources specified +for this widget's class. Within a class, resources are fetched in the order +they are declared. + + + +In general, if a widget resource field is declared in a superclass, +that field is included in the superclass's resource list and need not be +included in the subclass's resource list. +For example, the +Core +class contains a resource entry for background_pixel. +Consequently, +the implementation of Label need not also have a resource entry +for background_pixel. +However, a subclass, +by specifying a resource entry for that field in its own resource list, +can override the resource entry for any field declared in a superclass. +This is most often done to override the defaults provided in the +superclass with new ones. +At class initialization time, +resource lists for that class are scanned from the superclass down +to the class to look for resources with the same offset. +A matching resource in a subclass will be reordered to override +the superclass entry. +If reordering is necessary, a copy of the superclass resource list is made to +avoid affecting other subclasses of the superclass. + + + +Also at class initialization time, the Intrinsics produce an +internal representation of the resource list to optimize access time +when creating widgets. In order to save memory, the Intrinsics may +overwrite the storage allocated for the resource list in the class +record; therefore, widgets must allocate resource lists in writable +storage and must not access the list contents directly after the +class_initialize procedure has returned. + + + + +Subresources + +A widget does not do anything to retrieve its own resources; +instead, + +does this automatically before calling the class initialize procedure. + + + +Some widgets have subparts that are not widgets but for which the widget +would like to fetch resources. +Such widgets call + +to accomplish this. + + + + +void XtGetSubresources + Widget w + XtPointer base + String name + String class + XtResourceList resources + Cardinal num_resources + ArgList args + Cardinal num_args + + + + + + + w + + + +Specifies the object used to qualify the subpart resource name and +class. Must be of class Object or any subclass thereof. + + + + + + base + + + +Specifies the base address of the subpart data structure into which the +resources will be written. + + + + + + name + + + +Specifies the name of the subpart. + + + + + + class + + + +Specifies the class of the subpart. + + + + + + resources + + + +Specifies the resource list for the subpart. + + + + + + num_resources + + + +Specifies the number of entries in the resource list. + + + + + + args + + + +Specifies the argument list to override any other resource specifications. + + + + + + num_args + + + +Specifies the number of entries in the argument list. + + + + + + +The + +function constructs a name and class list from the application name and class, +the names and classes of all the object's ancestors, and the object itself. +Then it appends to this list the name and class pair passed in. +The resources are fetched from the argument list, the resource database, +or the default values in the resource list. +Then they are copied into the subpart record. +If args is NULL, +num_args must be zero. +However, if num_args is zero, +the argument list is not referenced. + + + + +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 + +are reference-counted as +if they were referenced by the specified object. Subresources might +therefore be freed from the conversion cache and destroyed +when the object is destroyed, but not before then. + + + +To fetch resources for widget subparts using varargs lists, use +. + + + + +void XtVaGetSubresources + Widget w + XtPointer base + String name + String class + XtResourceList resources + Cardinal num_resources + + + + + + + w + + + +Specifies the object used to qualify the subpart resource name and +class. Must be of class Object or any subclass thereof. + + + + + + base + + + +Specifies the base address of the subpart data structure into which the +resources will be written. + + + + + + name + + + +Specifies the name of the subpart. + + + + + + class + + + +Specifies the class of the subpart. + + + + + + resources + + + +Specifies the resource list for the subpart. + + + + + + num_resources + + + +Specifies the number of entries in the resource list. + + + + + + ... + + + +Specifies the variable argument list to override any other +resource specifications. + + + + + + + +is identical in function to + +with the args and num_args parameters replaced by a varargs list, as +described in Section 2.5.1. + + + + +Obtaining Application Resources + +To retrieve resources that are not specific to a widget +but apply to the overall application, use +. + + + + +void XtGetApplicationResources + Widget w + XtPointer base + XtResourceList resources + Cardinal num_resources + ArgList args + Cardinal num_args + + + + + + + w + + + +Specifies the object that identifies the resource database to search +(the database is that associated with the display for this object). Must be of class Object or any subclass thereof. + + + + + + base + + + +Specifies the base address into which +the resource values will be written. + + + + + + resources + + + +Specifies the resource list. + + + + + + num_resources + + + +Specifies the number of entries in the resource list. + + + + + + args + + + +Specifies the argument list to override any other resource specifications. + + + + + + num_args + + + +Specifies the number of entries in the argument list. + + + + + + +The + +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, + +copies the resources into the addresses +obtained by adding base to each offset in the resource list. +If args is NULL, +num_args must be zero. +However, if num_args is zero, +the argument list is not referenced. +The portable way to specify application resources is to declare them +as members of a structure and pass the address of the structure +as the base argument. + + + + +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 + +will not be freed from the resource cache until the display is closed. + + + +To retrieve resources for the overall application using varargs lists, use +. + + + + +void XtVaGetApplicationResources + Widget w + XtPointer base + XtResourceList resources + Cardinal num_resources + + + + + + + w + + + +Specifies the object that identifies the resource database to search +(the database is that associated with the display for this object). Must be of class Object or any subclass thereof. + + + + + + base + + + +Specifies the base address into which +the resource values will be written. + + + + + + resources + + + +Specifies the resource list for the subpart. + + + + + + num_resources + + + +Specifies the number of entries in the resource list. + + + + + + ... + + + +Specifies the variable argument list to override any other +resource specifications. + + + + + + + +is identical in function to + +with the args and num_args parameters +replaced by a varargs list, as described in Section 2.5.1. + + + + +Resource Conversions + +The Intrinsics provide a mechanism for registering representation converters that +are automatically invoked by the resource-fetching routines. +The Intrinsics additionally provide and register several commonly used converters. +This resource conversion mechanism serves several purposes: + + + + +It permits user and application resource files to contain textual +representations of nontextual values. + + + + +It allows textual or other representations of default resource values that +are dependent on the display, screen, or colormap, and thus must be +computed at runtime. + + + + +It caches conversion source and result data. +Conversions that require much computation or space +(for example, string-to-translation-table) +or that require round-trips to the server +(for example, string-to-font or string-to-color) are performed only once. + + + + +Predefined Resource Converters + +The Intrinsics define all the representations used in the +Object, +RectObj, +Core, +Composite, +Constraint, +and +Shell +widget classes. +The Intrinsics register the following resource converters that accept +input values of representation type +XtRString. + + + + + + + + + + + Target Representation + Converter Name + Additional Args + + + + + XtRAcceleratorTable + XtCvtStringToAcceleratorTable + + + XtRAtom + XtCvtStringToAtom + Display* + + + XtRBoolean + XtCvtStringToBoolean + + + XtRBool + XtCvtStringToBool + + + XtRCommandArgArray + XtCvtStringToCommandArgArray + + + XtRCursor + XtCvtStringToCursor + Display* + + + XtRDimension + XtCvtStringToDimension + + + XtRDirectoryString + XtCvtStringToDirectoryString + + + XtRDisplay + XtCvtStringToDisplay + + + XtRFile + XtCvtStringToFile + + + XtRFloat + XtCvtStringToFloat + + + XtRFont + XtCvtStringToFont + Display* + + + XtRFontSet + XtCvtStringToFontSet + Display*, String locale + + + XtRFontStruct + XtCvtStringToFontStruct + Display* + + + XtRGravity + XtCvtStringToGravity + + + XtRInitialState + XtCvtStringToInitialState + + + XtRInt + XtCvtStringToInt + + + XtRPixel + XtCvtStringToPixel + colorConvertArgs + + + XtRPosition + XtCvtStringToPosition + + + XtRRestartStyle + XtCvtStringToRestartStyle + + + XtRShort + XtCvtStringToShort + + + XtRTranslationTable + XtCvtStringToTranslationTable + + + XtRUnsignedChar + XtCvtStringToUnsignedChar + + + XtRVisual + XtCvtStringToVisual + Screen*, Cardinal depth + + + + + + +The String-to-Pixel conversion has two predefined constants that are +guaranteed to work and contrast with each other: +XtDefaultForeground +and +XtDefaultBackground. +They evaluate to the black and white pixel values of the widget's screen, +respectively. +If the application resource reverseVideo is +True, +they evaluate to the white and black pixel values of the widget's screen, +respectively. +Similarly, the String-to-Font and String-to-FontStruct converters recognize +the constant +XtDefaultFont +and evaluate this in the following manner: + + + + +Query the resource database for the resource whose full name +is ``xtDefaultFont'', class ``XtDefaultFont'' (that is, no widget +name/class prefixes), and use a type +XtRString +value returned as the font name or a type +XtRFont +or +XtRFontStruct +value directly as the resource value. + + + + +If the resource database does not contain a value for xtDefaultFont, +class XtDefaultFont, or if the returned font name cannot be +successfully opened, an implementation-defined font in ISO8859-1 +character set encoding is opened. (One possible algorithm is to +perform an +XListFonts +using a wildcard font name and use the first +font in the list. This wildcard font name should be as broad as +possible to maximize the probability of locating a useable font; +for example, "-*-*-*-R-*-*-*-120-*-*-*-*-ISO8859-1".) + + + + +If no suitable ISO8859-1 font can be found, issue a warning message +and return +False. + + + + +The String-to-FontSet converter recognizes the constant +XtDefaultFontSet +and evaluate this in the following manner: + + + + +Query the resource database for the resource whose full name +is ``xtDefaultFontSet'', class ``XtDefaultFontSet'' (that is, no widget +name/class prefixes), and use a type +XtRString +value returned as the base font name list or a type +XtRFontSet +value directly as the resource value. + + + + +If the resource database does not contain a value for xtDefaultFontSet, +class XtDefaultFontSet, or if a font set cannot be +successfully created from this resource, +an implementation-defined font set is created. +(One possible algorithm is to +perform an +XCreateFontSet +using a wildcard base font name. +This wildcard base font name should be as broad as +possible to maximize the probability of locating a useable font; +for example, "-*-*-*-R-*-*-*-120-*-*-*-*".) + + + + +If no suitable font set can be created, issue a warning message +and return +False. + + + + +If a font set is created but missing_charset_list is not +empty, a warning is issued and the partial font set is returned. +The Intrinsics register the String-to-FontSet converter with +a conversion argument list that extracts the current process +locale at the time the converter is invoked. This ensures +that the converter is invoked again if the same conversion +is required in a different locale. + + + +The String-to-Gravity conversion accepts string values that are the +names of window and bit gravities and their numerical equivalents, +as defined in Xlib — C Language X Interface.: +ForgetGravity, +UnmapGravity, +NorthWestGravity, +NorthGravity, +NorthEastGravity, +WestGravity, +CenterGravity, +EastGravity, +SouthWestGravity, +SouthGravity, +SouthEastGravity, +and +StaticGravity. +Alphabetic case is not significant in the conversion. + + + +The String-to-CommandArgArray conversion parses a String into an +array of strings. +White space characters separate elements of the command line. +The converter recognizes the backslash character ``\\'' as an escape +character to allow the following white space character to be part of the +array element. + + + +The String-to-DirectoryString conversion recognizes the +string ``XtCurrentDirectory'' and returns the result of a call +to the operating system to get the current directory. + + + +The String-to-RestartStyle conversion accepts the values +RestartIfRunning, +RestartAnyway, +RestartImmediately, +and +RestartNever +as defined by the X Session Management Protocol. + + + +The String-to-InitialState conversion accepts the values +NormalState +or +IconicState +as defined by the Inter-Client Communication Conventions Manual.. + + + +The String-to-Visual conversion calls +XMatchVisualInfo +using the +screen and depth fields from the core part and returns the first +matching Visual on the list. The widget resource list must be certain +to specify any resource of type +XtRVisual +after the depth resource. +The allowed string values are the visual class names defined in X Window System Protocol, +Section 8; +StaticGray, +StaticColor, +TrueColor, +GrayScale, +PseudoColor, +and +DirectColor. + + + +The Intrinsics register the following resource converter that accepts +an input value of representation type +XtRColor. + + + + + + + + + + + Target Representation + Converter Name + Additional Args + + + + + XtRPixel + XtCvtColorToPixel + + + + + + +The Intrinsics register the following resource converters that accept +input values of representation type +XtRInt. + + + + + + + + + + + Target Representation + Converter Name + Additional Args + + + + + XtRBoolean + XtCvtIntToBoolean + + + XtRBool + XtCvtIntToBool + + + XtRColor + XtCvtIntToColor + colorConvertArgs + + + XtRDimension + XtCvtIntToDimension + + + XtRFloat + XtCvtIntToFloat + + + XtRFont + XtCvtIntToFont + + + XtRPixel + XtCvtIntToPixel + + + XtRPixmap + XtCvtIntToPixmap + + + XtRPosition + XtCvtIntToPosition + + + XtRShort + XtCvtIntToShort + + + XtRUnsignedChar + XtCvtIntToUnsignedChar + + + + + + +The Intrinsics register the following resource converter that accepts +an input value of representation type +XtRPixel. + + + + + + + + + + + Target Representation + Converter Name + Additional Args + + + + + XtRColor + XtCvtPixelToColor + + + + + + + +New Resource Converters + +Type converters use pointers to +XrmValue +structures (defined in +<X11/Xresource.h>; +see Section 15.4 in +Xlib — C Language X Interface.) +for input and output values. + + +typedef struct { + unsigned int size; + XPointer addr; +} XrmValue, *XrmValuePtr; + + +The addr field specifies the address of the data, and the size +field gives the total number of significant bytes in the data. +For values of type +String, +addr is the address of the first character and size +includes the NULL-terminating byte. + + + +A resource converter procedure pointer is of type +. + + + + +typedef Boolean (*XtTypeConverter) + Display *display + XrmValue *args + Cardinal *num_args + XrmValue *from + XrmValue *to + XtPointer *converter_data + + + + + + + display + + + +Specifies the display connection with which this conversion is associated. + + + + + + args + + + +Specifies a list of additional +XrmValue +arguments to the converter if additional context is needed +to perform the conversion, or NULL. +For example, the String-to-Font converter needs the widget's display, +and the String-to-Pixel converter needs the widget's screen and colormap. + + + + + + num_args + + + +Specifies the number of entries in args. + + + + + + from + + + +Specifies the value to convert. + + + + + + to + + + +Specifies a descriptor for a location into which to store the converted value. + + + + + + converter_data + + + +Specifies a location into which the converter may +store converter-specific data associated +with this conversion. + + + + + + +The display argument is normally used only when generating error +messages, to identify the application context (with the function +XtDisplayToApplicationContext ). + + + +The to argument specifies the size and location into which the +converter should store the converted value. If the addr field is NULL, +the converter should allocate appropriate storage and store the size +and location into the to descriptor. If the type converter allocates +the storage, it remains under the ownership of the converter and must +not be modified by the caller. The type converter is permitted to use +static storage for this purpose, and therefore the caller must +immediately copy the data upon return from the converter. If the +addr field is not NULL, the converter must check the size field to +ensure that sufficient space has been allocated before storing the +converted value. If insufficient space is specified, the converter +should update the size field with the number of bytes required and +return +False +without modifying the data at the specified location. +If sufficient space was allocated by the caller, the converter should +update the size field with the number of bytes actually occupied by the +converted value. For converted values of type +XtRString, +the size should +include the NULL-terminating byte, if any. +The converter may store any value in the location specified +in converter_data; this value will be passed to the destructor, if any, +when the resource is freed by the Intrinsics. + + + +The converter must return +True +if the conversion was successful and +False +otherwise. If the conversion cannot be performed because of an +improper source value, a warning message should also be issued with +. + + + +Most type converters just take the data described by the specified from +argument and return data by writing into the location specified in +the to argument. +A few need other information, which is available in args. +A type converter can invoke another type converter, +which allows differing sources that may convert into a common intermediate +result to make maximum use of the type converter cache. + + + +Note that if an address is written into to->addr, it cannot be that +of a local variable of the converter because the data will not be +valid after the converter returns. Static variables may be used, +as in the following example. +If the converter modifies the resource database, +the changes affect any in-progress widget creation, +, +or + +in an implementation-defined manner; however, insertion of new entries +or changes to existing entries is allowed and will not directly cause +an error. + + + +The following is an example of a converter that takes a +string +and converts it to a +Pixel. +Note that the display parameter is +used only to generate error messages; the +Screen +conversion argument is +still required to inform the Intrinsics that the converted value is +a function of the particular display (and colormap). + + + +#define done(type, value) \\ + { \\ + if (toVal->addr != NULL) { \\ + if (toVal->size < sizeof(type)) { \\ + toVal->size = sizeof(type); \\ + return False; \\ + } \\ + *(type*)(toVal->addr) = (value); \\ + } \\ + else { \\ + static type static_val; \\ + static_val = (value); \\ + toVal->addr = (XPointer)&static_val; \\ + } \\ + toVal->size = sizeof(type); \\ + return True; \\ + } +static Boolean CvtStringToPixel(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); + } +} + + + +All type converters should define some set of conversion values for which they +are guaranteed to succeed so these can be used in the resource defaults. +This issue arises only with conversions, such as fonts and colors, +where there is no string representation that all server implementations +will necessarily recognize. +For resources like these, +the converter should define a symbolic constant +in the same manner as +XtDefaultForeground, +XtDefaultBackground, +and +XtDefaultFont. + + + +To allow the Intrinsics to deallocate resources produced by type +converters, a resource destructor procedure may also be provided. + + + +A resource destructor procedure pointer is of type +. + + + + + typedef void (*XtDestructor) + XtAppContext app + XrmValue *to + XtPointer converter_data + XrmValue *args + Cardinal *num_args + + + + + + + app + + + +Specifies an application context in which the resource is being freed. + + + + + + to + + + +Specifies a descriptor for the resource produced by the type converter. + + + + + + converter_data + + + +Specifies the converter-specific data returned by the type converter. + + + + + + args + + + +Specifies the additional converter arguments as passed +to the type converter when the conversion was performed. + + + + + + num_args + + + +Specifies the number of entries in args. + + + + + + +The destructor procedure is responsible for freeing the resource +specified by the to argument, including any auxiliary storage +associated with that resource, but not the memory directly addressed +by the size and location in the to argument or the memory specified +by args. + + + + +Issuing Conversion Warnings + +The + +procedure is a convenience routine for resource type converters +that convert from string values. + + + + +void XtDisplayStringConversionWarning + Display *display + String from_value + + + + + + + display + + + +Specifies the display connection with which the conversion is associated. + + + + + + from_value + + + +Specifies the string that could not be converted. + + + + + + to_type + + + +Specifies the target representation type requested. + + + + + + +The + +procedure issues a warning message using + +with name ``conversionError'', +type ``string'', class ``XtToolkitError'', and the default message +``Cannot convert "from_value" to type to_type''. + + + +To issue other types of warning or error messages, the type converter +should use + +or +. + + + +To retrieve the application context associated with a given +display connection, use +. + + + + +XtAppContext XtDisplayToApplicationContext + Display *display + + + + + + + display + + + +Specifies an open and initialized display connection. + + + + + + +The + +function returns the application +context in which the specified display was initialized. If the +display is not known to the Intrinsics, an error message is issued. + + + + +Registering a New Resource Converter + +When registering a resource converter, the client must specify the +manner in which the conversion cache is to be used when there are multiple +calls to the converter. Conversion cache control is specified +via an XtCacheType +argument. + + +typedef int XtCacheType; + + + +An XtCacheType +field may contain one of the following values: + + + +XtCacheNone + + + + +Specifies that the results of a previous conversion +may not be reused to satisfy any other resource +requests; the specified converter will be called +each time the converted value is required. + + + + +XtCacheAll + + + + +Specifies that the results of a previous conversion +should be reused for any resource request that depends +upon the same source value and conversion arguments. + + + + +XtCacheByDisplay + + + + +Specifies that the results of a previous conversion +should be used as for +XtCacheAll +but the destructor will be called, if specified, if + +is called +for the display connection associated with the converted value, and +the value will be removed from the conversion cache. + + + + +The qualifier +XtCacheRefCount +may be ORed with any of the above values. If +XtCacheRefCount +is specified, calls to +, +, +, +and + +that use the converted value will be counted. When a widget using the +converted value is destroyed, the count is decremented, and, if the +count reaches zero, the destructor procedure will be called and the +converted value will be removed from the conversion cache. + + + +To register a type converter for all application contexts in a +process, use +, +and to register a type converter in a single application context, use +. + + + + +void XtSetTypeConverter + String from_type + String to_type + XtTypeConverter converter + XtConvertArgList convert_args + Cardinal num_args + XtCacheType cache_type + XtDestructor destructor + + + + + + + from_type + + + +Specifies the source type. + + + + + + to_type + + + +Specifies the destination type. + + + + + + converter + + + +Specifies the resource type converter procedure. + + + + + + convert_args + + + +Specifies additional conversion arguments, or NULL. + + + + + + num_args + + + +Specifies the number of entries in convert_args. + + + + + + cache_type + + + +Specifies whether or not resources produced by this +converter are sharable or display-specific and when +they should be freed. + + + + + + destructor + + + +Specifies a destroy procedure for resources produced by +this conversion, or NULL if no additional action is +required to deallocate resources produced by the converter. + + + + + + + + + XtAppSetTypeConverter + XtAppContext app_context + String from_type + String to_type + XtTypeConverter converter + XtConvertArgList convert_args + Cardinal num_args + XtCacheType cache_type + XtDestructor destructor + + + + + + + app_context + + + +Specifies the application context. + + + + + + from_type + + + +Specifies the source type. + + + + + + to_type + + + +Specifies the destination type. + + + + + + converter + + + +Specifies the resource type converter procedure. + + + + + + convert_args + + + +Specifies additional conversion arguments, or NULL. + + + + + + num_args + + + +Specifies the number of entries in convert_args. + + + + + + cache_type + + + +Specifies whether or not resources produced by this +converter are sharable or display-specific and when +they should be freed. + + + + + + destructor + + + +Specifies a destroy procedure for resources produced by +this conversion, or NULL if no additional action is +required to deallocate resources produced by the converter. + + + + + + + +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. + +registers the specified type converter in the +single application context specified. If the same from_type and +to_type are specified in multiple calls to either function, the most +recent overrides the previous ones. + + + +For the few type converters that need additional arguments, +the Intrinsics conversion mechanism provides a method of specifying +how these arguments should be computed. +The enumerated type +XtAddressMode +and the structure +XtConvertArgRec +specify how each argument is derived. +These are defined in +<X11/Intrinsic.h>. + + +typedef enum { + /* address mode parameter representation */ + XtAddress, /* address */ + XtBaseOffset, /* offset */ + XtImmediate, /* constant */ + XtResourceString, /* resource name string */ + XtResourceQuark, /* resource name quark */ + XtWidgetBaseOffset, /* offset */ + XtProcedureArg /* procedure to call */ +} XtAddressMode; + +typedef struct { + XtAddressMode address_mode; + XtPointer address_id; + Cardinal size; +} XtConvertArgRec, *XtConvertArgList; + + +The size field specifies the length of the data in bytes. +The address_mode field specifies how the address_id field should be +interpreted. +XtAddress +causes address_id to be interpreted as the address of the data. +XtBaseOffset +causes address_id to be interpreted as the offset from the widget base. +XtImmediate +causes address_id to be interpreted as a constant. +XtResourceString +causes address_id to be interpreted as the name of a resource +that is to be converted into an offset from the widget base. +XtResourceQuark +causes address_id to be interpreted as the result of an +XrmStringToQuark +conversion on the name of a resource, +which is to be converted into an offset from the widget base. +XtWidgetBaseOffset +is similar to +XtBaseOffset +except that it +searches for the closest windowed ancestor if the object is not +of a subclass of +Core +(see ). +XtProcedureArg +specifies that address_id is a pointer to a procedure to +be invoked to return the conversion argument. If +XtProcedureArg +is specified, address_id must contain +the address of a function of type +. + + + + +typedef void (*XtConvertArgProc) + XtAppContext app + XrmValue *to + XtPointer converter_data + XrmValue *args + Cardinal *num_args + + + + + + + app + + + +Specifies an application context in which the resource is being freed. + + + + + + to + + + +Specifies a descriptor for the resource produced by the type converter. + + + + + + converter_data + + + +Specifies the converter-specific data returned by the type converter. + + + + + + args + + + +Specifies the additional converter arguments as passed +to the type converter when the conversion was performed. + + + + + + num_args + + + +Specifies the number of entries in args. + + + + + + +The destructor procedure is responsible for freeing the resource +specified by the to argument, including any auxiliary storage +associated with that resource, but not the memory directly addressed +by the size and location in the to argument or the memory specified +by args. + + + + +Resource Converter Invocation + +All resource-fetching routines (for example, +, +, +and so on) call resource converters if the resource database or +varargs list specifies a value +that has a different representation from the desired representation or if the +widget's default resource value representation is different from the desired +representation. + + + +To invoke explicit resource conversions, use + +or +. + + +typedef XtPointer XtCacheRef; + + + + +Boolean XtCallConverter + Display* display + XtTypeConverter converter + XrmValuePtr conversion_args + Cardinal num_args + XrmValuePtr from + XrmValuePtr to_in_out + XtCacheRef *cache_ref_return + + + + + + + display + + + +Specifies the display with which the conversion is to be associated. + + + + + + converter + + + +Specifies the conversion procedure to be called. + + + + + + conversion_args + + + +Specifies the additional conversion arguments needed +to perform the conversion, or NULL. + + + + + + num_args + + + +Specifies the number of entries in conversion_args. + + + + + + from + + + +Specifies a descriptor for the source value. + + + + + + to_in_out + + + +Returns the converted value. + + + + + + cache_ref_return + + + +Returns a conversion cache id. + + + + + + +The + +function looks up the +specified type converter in the application context associated with +the display and, if the converter was not registered or was registered +with cache type +XtCacheAll +or +XtCacheByDisplay, +looks in the conversion cache to see if this conversion procedure +has been called with the specified conversion arguments. If so, it +checks the success status of the prior call, and if +the conversion failed, + +returns +False +immediately; +otherwise it checks the size specified in the to argument, and, if it is +greater than or equal to the size stored in the cache, copies the +information stored in the cache into the location specified by +to->addr, stores the cache size into to->size, and returns +True. +If the size specified in the to argument is smaller than the size stored +in the cache, + +copies the cache size into to->size and returns +False. +If the converter was registered with cache type +XtCacheNone +or no value was found in the conversion cache, + +calls the converter, and if it was not registered with cache type +XtCacheNone, +enters the result in the cache. + +then returns what the converter returned. + + + +The cache_ref_return field specifies storage allocated by the caller in which +an opaque value will be stored. If the type converter has been +registered with the +XtCacheRefCount +modifier and if the value returned +in cache_ref_return is non-NULL, then the caller should store the +cache_ref_return value in order to decrement the reference count when +the converted value is no longer required. The cache_ref_return +argument should be +NULL if the caller is unwilling or unable to store the +value. + + + +To explicitly decrement the reference counts for resources obtained +from +, +use +. + + + + +void XtAppReleaseCacheRefs + XtAppContext app_context + XtCacheRef *refs + + + + + + + app_context + + + +Specifies the application context. + + + + + + refs + + + +Specifies the list of cache references to be released. + + + + + + + +decrements the reference count for the +conversion entries identified by the refs argument. +This argument is a +pointer to a NULL-terminated list of +XtCacheRef +values. If any reference +count reaches zero, the destructor, if any, will be called and +the resource removed from the conversion cache. + + + +As a convenience to clients needing to explicitly decrement reference +counts via a callback function, the Intrinsics define two callback +procedures, + +and +. + + + + +void XtCallbackReleaseCacheRef + Widget object + XtPointer client_data + XtPointer call_data + + + + + + + object + + + +Specifies the object with which the resource is associated. + + + + + + client_data + + + +Specifies the conversion cache entry to be released. + + + + + + call_data + + + +Is ignored. + + + + + + +This callback procedure may be added to a callback list to release a +previously returned +XtCacheRef +value. When adding the callback, the +callback client_data argument must be specified as the value of the +XtCacheRef +data cast to type +XtPointer. + + + + +void XtCallbackReleaseCacheRefList + Widget object + XtPointer client_data + XtPointer call_data + + + + + + + object + + + +Specifies the object with which the resources are associated. + + + + + + client_data + + + +Specifies the conversion cache entries to be released. + + + + + + call_data + + + +Is ignored. + + + + + + +This callback procedure may be added to a callback list to release a +list of previously returned +XtCacheRef +values. When adding the +callback, the callback client_data argument must be specified as a +pointer to a NULL-terminated list of +XtCacheRef +values. + + + +To lookup and call a resource converter, copy the resulting value, +and free a cached resource when a widget is destroyed, use +. + + + + +Boolean XtConvertAndStore + Widget object + String from_type + XrmValuePtr from + String to_type + XrmValuePtr to_in_out + + + + + + + object + + + +Specifies the object to use for additional arguments, if any are needed, +and the destroy callback list. Must be of class Object or any subclass thereof. + + + + + + from_type + + + +Specifies the source type. + + + + + + from + + + +Specifies the value to be converted. + + + + + + to_type + + + +Specifies the destination type. + + + + + + to_in_out + + + +Specifies a descriptor for storage into which the converted value +will be returned. + + + + + + +The + +function looks up the type converter registered +to convert from_type to to_type, computes any additional arguments +needed, and then calls + +(or + +if an old-style converter was registered with + +or +; +see Appendix C) with the from and to_in_out arguments. The +to_in_out argument specifies the size and location into which the +converted value will be stored and is passed directly to the +converter. If the location is specified as NULL, it will be replaced +with a pointer to private storage and the size will be returned in the +descriptor. The caller is expected to copy this private storage +immediately and must not modify it in any way. If a non-NULL location +is specified, the caller must allocate sufficient storage to hold the +converted value and must also specify the size of that storage in the +descriptor. +The size field will be modified on return to indicate the actual +size of the converted data. +If the conversion succeeds, + +returns +True; +otherwise, it returns +False. + + + + +adds + +to the destroyCallback list of the specified object if the conversion +returns an +XtCacheRef +value. The resulting resource should not be referenced +after the object has been destroyed. + + + + +performs processing equivalent to + +when initializing the object instance. Because there is extra memory +overhead required to implement reference counting, clients may +distinguish those objects that are never destroyed before the +application exits from those that may be destroyed and whose +resources should be deallocated. + + + +To specify whether reference counting is to be enabled for the +resources of a particular object when the object is created, the +client can specify a value for the +Boolean +resource +XtNinitialResourcesPersistent, +class +XtCInitialResourcesPersistent. + + + +When + +is called, if this resource is not specified as +False +in either the arglist or the resource database, then the +resources referenced by this object are not reference-counted, regardless of +how the type converter may have been registered. The effective +default value is +True; +thus clients that expect to destroy one or +more objects and want resources deallocated must explicitly specify +False +for +XtNinitialResourcesPersistent. + + + +The resources are still freed and destructors called when + +is called if the conversion was registered as +XtCacheByDisplay. + + + + + +Reading and Writing Widget State + +Any resource field in a widget can be read or written by a client. +On a write operation, +the widget decides what changes it will actually allow and updates all +derived fields appropriately. + + +Obtaining Widget State + +To retrieve the current values of resources associated with a +widget instance, use +. + + + + +void XtGetValues + Widget object + ArgList args + Cardinal num_args + + + + + + + object + + + +Specifies the object whose resource values are to be returned. Must be of class Object or any subclass thereof. + + + + + + args + + + +Specifies the argument list of name/address pairs that contain the +resource names and the addresses into which the resource values are to +be stored. +The resource names are widget-dependent. + + + + + + num_args + + + +Specifies the number of entries in the argument list. + + + + + + +The + +function starts with the resources specified for the Object class +and proceeds down the subclass chain to the class of the object. +The value field of a passed argument list must contain the +address into which to copy the contents of the corresponding +object instance field. If the field is a pointer type, the lifetime +of the pointed-to data is defined by the object class. For the +Intrinsics-defined resources, the following lifetimes apply: + + + + +Not valid following any operation that modifies the resource: + + + + + + +XtNchildren resource of composite widgets. + + + + +All resources of representation type XtRCallback. + + + + + + +Remain valid at least until the widget is destroyed: + + + + + + +XtNaccelerators, XtNtranslations. + + + + + + +Remain valid until the Display is closed: + + + + + + +XtNscreen. + + + + + + +It is the caller's responsibility +to allocate and deallocate storage for the copied data +according to the size of the +resource representation type used within the object. + + + +If the class of the object's parent is a subclass of +constraintWidgetClass, + +then fetches the values for any constraint resources requested. +It starts with the constraint resources specified for +constraintWidgetClass +and proceeds down the subclass chain to the parent's constraint resources. +If the argument list contains a resource name that is not found in any of the +resource lists searched, +the value at the corresponding address is not modified. +If any get_values_hook procedures in the +object's class or superclass records are non-NULL, +they are called in superclass-to-subclass order after +all the resource values have been fetched by +. +Finally, if the object's parent is a +subclass of +constraintWidgetClass, +and if any of the parent's class or +superclass records have declared +ConstraintClassExtension +records in +the Constraint class part extension field with a record type of +NULLQUARK, +and if the get_values_hook field in the extension record is non-NULL, + +calls the get_values_hook procedures in superclass-to-subclass order. +This permits a Constraint parent to provide +nonresource data via +. + + + +Get_values_hook procedures may modify the data stored at the +location addressed by the value field, including (but not +limited to) making a copy of data whose resource representation is a +pointer. None of the Intrinsics-defined object classes copy +data in this manner. Any operation that modifies the queried +object resource may invalidate the pointed-to data. + + + +To retrieve the current values of resources associated with a widget +instance using varargs lists, use +. + + + + +void XtVaGetValues + Widget object + ... + + + + + + + object + + + +Specifies the object whose resource values are to be returned. Must be of class Object or any subclass thereof. + + + + + + ... + + + +Specifies the variable argument list for the resources to +be returned. + + + + + + + +is identical in function to + +with the args +and num_args parameters replaced by a varargs list, as described in +Section 2.5.1. All value entries in the list must specify pointers to +storage allocated by the caller to which the resource value will be +copied. It is the caller's responsibility to ensure that sufficient +storage is allocated. If +XtVaTypedArg +is specified, the type argument +specifies the representation desired by the caller and the size argument +specifies the number of bytes allocated to store the result of the +conversion. If the size is insufficient, a warning message is issued +and the list entry is skipped. + + +Widget Subpart Resource Data: The get_values_hook Procedure + +Widgets that have subparts can return resource values from them through + +by supplying a get_values_hook procedure. +The get_values_hook procedure pointer is of type +. + + + + +typedef void (*XtArgsProc) + + Widget w + ArgList args + Cardinal *num_args + + + + + + + w + + + +Specifies the widget whose subpart resource values are to be retrieved. + + + + + + args + + + +Specifies the argument list that was passed to + +or the transformed varargs list passed to +. + + + + + + num_args + + + +Specifies the number of entries in the argument list. + + + + + + +The widget with subpart resources should call + +in the get_values_hook procedure +and pass in its subresource list and the args and num_args parameters. + + + +Widget Subpart State + +To retrieve the current values of subpart resource data associated with a +widget instance, use +. +For a discussion of subpart resources, +see . + + + + +void XtGetSubvalues + XtPointer base + XtResourceList resources + Cardinal num_resources + ArgList args + Cardinal num_args + + + + + + + base + + + +Specifies the base address of the subpart data structure for which the +resources should be retrieved. + + + + + + resources + + + +Specifies the subpart resource list. + + + + + + num_resources + + + +Specifies the number of entries in the resource list. + + + + + + args + + + +Specifies the argument list of name/address pairs that contain the +resource names and the addresses into which the resource values are to +be stored. + + + + + + num_args + + + +Specifies the number of entries in the argument list. + + + + + + +The + +function obtains resource values from the structure identified by base. +The value field in each argument entry must contain the address into +which to store the corresponding resource value. It is the caller's +responsibility to allocate and deallocate this storage according to +the size of the resource representation type used within the subpart. +If the argument list contains a resource name that is not found in the +resource list, the value at the corresponding address is not modified. + + + +To retrieve the current values of subpart resources associated with +a widget instance using varargs lists, use +. + + + + +void XtVaGetSubvalues + XtPointer base + XtResourceList resources + Cardinal num_resources + ... + + + + + + + base + + + +Specifies the base address of the subpart data structure for which the +resources should be retrieved. + + + + + + resources + + + +Specifies the subpart resource list. + + + + + + num_resources + + + +Specifies the number of entries in the resource list. + + + + + + ... + + + +Specifies a variable argument list of name/address pairs that +contain the resource names and the addresses into which the resource +values are to be stored. + + + + + + + +is identical in function to + +with the +args and num_args parameters replaced by a varargs list, as described +in Section 2.5.1. +XtVaTypedArg +is not supported for +. +If +XtVaTypedArg +is specified in the list, a warning message is issued +and the entry is then ignored. + + + + + +Setting Widget State + +To modify the current values of resources associated with a widget +instance, use +. + + + + +void XtSetValues + Widget object + ArgList args + Cardinal num_args + + + + + + + object + + + +Specifies the object whose resources are to be modified. Must be of class Object or any subclass thereof. + + + + + + args + + + +Specifies the argument list of name/value pairs that contain the +resources to be modified and their new values. + + + + + + num_args + + + +Specifies the number of entries in the argument list. + + + + + + +The + +function starts with the resources specified for the +Object +class fields and proceeds down the subclass chain to the object. +At each stage, it replaces the object resource fields with any values +specified in the argument list. + +then calls the set_values procedures for the object in superclass-to-subclass +order. +If the object has any non-NULL set_values_hook fields, +these are called immediately after the +corresponding set_values procedure. +This procedure permits subclasses to set subpart data via +. + + + +If the class of the object's parent is a subclass of +constraintWidgetClass, + +also updates the object's constraints. +It starts with the constraint resources specified for +constraintWidgetClass +and proceeds down the subclass chain to the parent's class. +At each stage, it replaces the constraint resource fields with any +values specified in the argument list. +It then calls the constraint set_values procedures from +constraintWidgetClass +down to the parent's class. +The constraint set_values procedures are called with widget arguments, +as for all set_values procedures, not just the constraint records, +so that they can make adjustments to the desired values based +on full information about the widget. Any arguments specified that +do not match a resource list entry are silently ignored. + + + +If the object is of a subclass of +RectObj, + +determines if a geometry request is needed by comparing the old object to +the new object. +If any geometry changes are required, + +restores the original geometry and makes the request on behalf of the widget. +If the geometry manager returns +XtGeometryYes, + +calls the object's resize procedure. +If the geometry manager returns +XtGeometryDone, + +continues, as the object's resize procedure should have been called +by the geometry manager. +If the geometry manager returns +XtGeometryNo, + +ignores the geometry request and continues. +If the geometry manager returns +XtGeometryAlmost, + +calls the set_values_almost procedure, +which determines what should be done. + +then repeats this process, +deciding once more whether the geometry manager should be called. + + + +Finally, if any of the set_values procedures returned +True, +and the widget is realized, + +causes the widget's expose procedure to be invoked by calling +XClearArea +on the widget's window. + + + +To modify the current values of resources associated with a widget +instance using varargs lists, use +. + + + + +void XtVaSetValues + Widget object + ... + + + + + + + object + + + +Specifies the object whose resources are to be modified. Must be of class Object or any subclass thereof. + + + + + + ... + + + +Specifies the variable argument list of name/value pairs that +contain the resources to be modified and their new values. + + + + + + + +is identical in function to + +with the args and num_args parameters replaced by a varargs list, as +described in Section 2.5.1. + + +Widget State: The set_values Procedure + +The set_values procedure pointer in a widget class is of type +. + + + + +typedef Boolean (*XtSetValuesFunc) + + Widget current + Widget request + Widget new + ArgList args + Cardinal *num_args + + + + + + + current + + + +Specifies a copy of the widget as it was before the + +call. + + + + + + request + + + +Specifies a copy of the widget with all values changed as asked for by the + +call before any class set_values procedures have been called. + + + + + + new + + + +Specifies the widget with the new values that are actually allowed. + + + + + + args + + + +Specifies the argument list passed to + +or the transformed argument list passed to +. + + + + + + num_args + + + +Specifies the number of entries in the argument list. + + + + + + +The set_values procedure should recompute any field +derived from resources that are changed +(for example, many GCs depend on foreground and background pixels). +If no recomputation is necessary, and if none of the resources specific to a +subclass require the window to be redisplayed when their values are changed, +you can specify NULL for the set_values field in the class record. + + + +Like the initialize procedure, +set_values mostly deals only with the fields defined in the subclass, +but it has to resolve conflicts with its superclass, +especially conflicts over width and height. + + + +Sometimes a subclass may want to overwrite values filled in by its +superclass. +In particular, size calculations of a superclass are often +incorrect for a subclass, and, in this case, +the subclass must modify or recalculate fields declared +and computed by its superclass. + + + +As an example, +a subclass can visually surround its superclass display. +In this case, the width and height calculated by the superclass set_values +procedure are too small and need to be incremented by the size of the surround. +The subclass needs to know if its superclass's size was calculated by the +superclass or was specified explicitly. +All widgets must place themselves into whatever size is explicitly given, +but they should compute a reasonable size if no size is requested. +How does a subclass know the difference between a specified size +and a size computed by a superclass? + + + +The request and new parameters provide the necessary information. +The request widget is a copy of the widget, updated as originally requested. +The new widget starts with the values in the request, +but it has additionally been updated by all superclass set_values +procedures called so far. +A subclass set_values procedure can compare these two to resolve +any potential conflicts. +The set_values procedure need not refer to the request widget +unless it must resolve conflicts between the current and new widgets. +Any changes the widget needs to make, including geometry changes, +should be made in the new widget. + + + +In the above example, +the subclass with the visual surround can see +if the width and height in the request widget are zero. +If so, +it adds its surround size to the width and +height fields in the new widget. +If not, it must make do with the size originally specified. +In this case, zero is a special value defined by the class to permit +the application to invoke this behavior. + + + +The new widget is the actual widget instance record. +Therefore, +the set_values procedure should do all its work on the new widget; +the request widget should never be modified. +If the set_values procedure needs to call any routines that operate on +a widget, it should specify new as the widget instance. + + + +Before calling the set_values procedures, the Intrinsics modify the +resources of the request widget according to the contents of the arglist; +if the widget names all its resources in the class resource list, it is +never necessary to examine the contents of args. + + + +Finally, the set_values procedure must return a Boolean that indicates whether +the widget needs to be redisplayed. +Note that a change in the geometry fields alone does not require +the set_values procedure to return +True; +the X server will eventually generate an +Expose +event, if necessary. +After calling all the set_values procedures, + +forces a redisplay by calling +XClearArea +if any of the set_values procedures returned +True. +Therefore, a set_values procedure should not try to do its own redisplaying. + + + +Set_values procedures should not do any work in response to changes in +geometry because + +eventually will perform a geometry request, and that request might be denied. +If the widget actually changes size in response to a +call to +, +its resize procedure is called. +Widgets should do any geometry-related work in their resize procedure. + + + +Note that it is permissible to call + +before a widget is realized. +Therefore, the set_values procedure must not assume that the widget is realized. + + + +Widget State: The set_values_almost Procedure + +The set_values_almost procedure pointer in the widget class record is of type +. + + + + +typedef void (*XtAlmostProc) + + Widget old + Widget new + XtWidgetGeometry *request + XtWidgetGeometry *reply + + + + + + + old + + + +Specifies a copy of the object as it was before the + +call. + + + + + + new + + + +Specifies the object instance record. + + + + + + request + + + +Specifies the original geometry request that was sent to the geometry +manager that caused +XtGeometryAlmost +to be returned. + + + + + + reply + + + +Specifies the compromise geometry that was returned by the geometry +manager with +XtGeometryAlmost. + + + + + + +Most classes inherit the set_values_almost procedure from their superclass by +specifying +XtInheritSetValuesAlmost +in the class initialization. +The +set_values_almost procedure in +rectObjClass +accepts the compromise suggested. + + + +The set_values_almost procedure is called when a client tries to set a widget's +geometry by means of a call to + +and the geometry manager cannot +satisfy the request but instead returns +XtGeometryNo +or +XtGeometryAlmost +and a compromise geometry. +The new object is the actual instance record. The x, y, +width, height, +and border_width fields contain the original values as they were +before the + +call, and all other fields contain the new +values. The request parameter contains the new geometry request that +was made to the parent. The reply parameter contains +reply->request_mode equal to zero if the parent returned +XtGeometryNo +and contains the parent's compromise geometry otherwise. The +set_values_almost procedure takes the original geometry and the +compromise geometry and determines if the compromise is +acceptable or whether +to try a different compromise. +It returns its results in the request parameter, +which is then sent back to the geometry manager for another try. +To accept the compromise, the procedure must copy the contents +of the reply geometry into the request geometry; to attempt an +alternative geometry, the procedure may modify any part of the request +argument; to terminate the geometry negotiation and retain the +original geometry, the procedure must set request->request_mode to +zero. The geometry fields of the old and new instances must not be modified +directly. + + + +Widget State: The ConstraintClassPart set_values Procedure + +The constraint set_values procedure pointer is of type +. +The values passed to the parent's constraint set_values procedure +are the same as those passed to the child's class +set_values procedure. +A class can specify NULL for the set_values field of the +ConstraintPart +if it need not compute anything. + + + +The constraint set_values procedure should recompute any constraint fields +derived from constraint resources that are changed. +Furthermore, it may modify other widget fields as appropriate. +For example, if a constraint for the maximum height of a widget is changed +to a value smaller than the widget's current height, +the constraint set_values procedure may reset the height field in the +widget. + + + +Widget Subpart State + +To set the current values of subpart resources associated with a +widget instance, use +. +For a discussion of subpart resources, +see . + + + + +void XtSetSubvalues + XtPointer base + XtResourceList resources + Cardinal num_resources + ArgList args + Cardinal num_args + + + + + + + base + + + +Specifies the base address of the subpart data structure into which the +resources should be written. + + + + + + resources + + + +Specifies the subpart resource list. + + + + + + num_resources + + + +Specifies the number of entries in the resource list. + + + + + + args + + + +Specifies the argument list of name/value pairs that contain the +resources to be modified and their new values. + + + + + + num_args + + + +Specifies the number of entries in the argument list. + + + + + + +The + +function updates the resource fields of the structure identified by +base. Any specified arguments that do not match an entry in the +resource list are silently ignored. + + + +To set the current values of subpart resources associated with +a widget instance using varargs lists, use +. + + + + +void XtVaSetSubvalues + XtPointer base + XtResourceList resources + Cardinal num_resources + + + + + + + base + + + +Specifies the base address of the subpart data structure into which the +resources should be written. + + + + + + resources + + + +Specifies the subpart resource list. + + + + + + num_resources + + + +Specifies the number of entries in the resource list. + + + + + + ... + + + +Specifies the variable argument list of name/value pairs that +contain the resources to be modified and their new values. + + + + + + + +is identical in function to + +with the args and num_args parameters replaced by a varargs list, as +described in Section 2.5.1. +XtVaTypedArg +is not supported for +. +If an entry containing +XtVaTypedArg +is specified in the list, a warning message is issued +and the entry is ignored. + + + + +Widget Subpart Resource Data: The set_values_hook Procedure + +The set_values_hook procedure is obsolete, as the same information +is now available to the set_values procedure. The procedure has been +retained for those widgets that used it in versions prior to Release 4. + + + +Widgets that have a subpart can set the subpart resource values through + +by supplying a set_values_hook procedure. +The set_values_hook procedure pointer in a widget class is of type +. + + + + +typedef Boolean (*XtArgsFunc) + Widget w + Arglist args + Cardinal *num_args + + + + + + + w + + + +Specifies the widget whose subpart resource values are to be changed. + + + + + + args + + + +Specifies the argument list that was passed to + +or the transformed varargs list passed to +. + + + + + + num_args + + + +Specifies the number of entries in the argument list. + + + + + + +The widget with subpart resources may call + +from the set_values_hook procedure +and pass in its subresource list and the +args and num_args parameters. + + + + + -- cgit v1.2.3