home *** CD-ROM | disk | FTP | other *** search
Text File | 1991-08-27 | 86.4 KB | 3,004 lines |
- .\" $XConsortium: CH09,v 1.8 91/08/26 13:36:17 swick Exp $
- .\"
- .\" Copyright 1985, 1986, 1987, 1988, 1991
- .\" Massachusetts Institute of Technology, Cambridge, Massachusetts,
- .\" and 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
- .\" M.I.T. or Digital not be used in in advertising or publicity pertaining
- .\" to distribution of the software without specific, written prior permission.
- .\" M.I.T and 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 \- 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
- .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"
-
- .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_Iclass\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 lower-case letter
- and is spelled exactly like the field name,
- except all underscores (_) are deleted and the next letter is replaced by its
- upper-case 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 offwhite
- 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 offwhite or darkblue:
- .LP
- .Ds 5
- .TA .5i 1.5i
- .ta .5i 1.5i
- *Background: offwhite
- *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 upper-case 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.75i) lw(2.75i).
- _
- .sp 6p
- .TB
- 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 XtRCursor
- T} Cursor
- T{
- .PN XtRDimension
- T} Dimension
- T{
- .PN XtRDisplay
- T} Display*
- T{
- .PN XtREnum
- T} XtEnum
- 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 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 XtRScreen
- T} Screen*
- T{
- .PN XtRShort
- T} short
- 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 .
- .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
- 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 .
- .IN "XtGetResourceList" "" "@DEF@"
- .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
- 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 .
- .IN "XtGetConstraintResourceList" "" "@DEF@"
- .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
- 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.5 3i
- .ta .5i 1.5 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 .
- .IN "XtOffsetOf" "" "@DEF@"
- .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
- 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 .
- .IN "XtOffset" "" "@DEF@"
- .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
- 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.
- .IN "XtGetSubresources" "" "@DEF@"
- .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
- 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 .
- .IN "XtVaGetSubresources" "" "@DEF@"
- .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
- .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 .
- .IN "XtGetApplicationResources" "" "@DEF@"
- .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
- 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 .
- .IN "XtVaGetApplicationResources" "" "@DEF@"
- .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
- .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.5i) lw(2.25i) 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 XtRCursor
- T} T{
- .PN XtCvtStringToCursor
- T} Display*
- T{
- .PN XtRDimension
- T} T{
- .PN XtCvtStringToDimension
- 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 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 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-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
- .Ds 0
- .TA .5i 3i
- .ta .5i 3i
- typedef struct {
- unsigned int size;
- XPointer addr;
- } XrmValue, *XrmValuePtr;
- .De
- .LP
- 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 NUL terminating byte.
- .LP
- A resource converter procedure pointer is of type
- .PN XtTypeConverter .
- .IN "XtTypeConverter" "" "@DEF@"
- .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 \fIscreen\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
- 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 data 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 only
- used 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;
- char message[1000];
-
- if (*num_args != 2)
- XtAppErrorMsg(XtDisplayToApplicationContext(dpy),
- "cvtStringToPixel", "wrongParameters", "XtToolkitError",
- "String to pixel conversion needs screen and colormap arguments",
- (String *)NULL, (Cardinal *)NULL);
-
- screen = *((Screen**) args[0].addr);
- colormap = *((Colormap *) args[1].addr);
-
- LowerCase((char *) fromVal->addr, message);
-
- if (strcmp(message, "xtdefaultbackground") == 0) done(&WhitePixelOfScreen(screen), Pixel);
- if (strcmp(message, "xtdefaultforeground") == 0) done(&BlackPixelOfScreen(screen), Pixel);
-
- 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),
- "cvtStringToPixel", "noColormap", "XtToolkitError",
- "Cannot allocate colormap entry for \\"%s\\"", params, &num_params);
- } else {
- done( &screenColor.pixel, Pixel );
- }
-
- /* converter_data not used here */
- };
- .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 .
- .IN "XtDestructor" "" "@DEF@"
- .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
- 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 nor 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.
- .IN "XtDisplayStringConversionWarning" "" "@DEF@"
- .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
- 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 .
- .IN "XtDisplayToApplicationContext" "" "@DEF@"
- .FD 0
- XtAppContext XtDisplayToApplicationContext( \fIdisplay\fP )
- .br
- Display *\fIdisplay\fP;
- .FN
- .IP \fIdisplay\fP 1i
- Specifies an open and initialized display connection.
- .LP
- 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
- .IN "XtCacheType" "" "@DEF@"
- argument.
- .sp
- .Ds 0
- typedef int XtCacheType;
- .De
- .LP
- 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 .
- .IN "XtSetTypeConverter" "" "@DEF@"
- .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.
-
- .sp
- .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
- .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
- .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;
-
- typedef struct {
- XtAddressMode address_mode;
- XtPointer address_id;
- Cardinal size;
- } XtConvertArgRec, *XtConvertArgList;
- .De
- .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 .
- .IN "XtConvertArgProc" "" "@DEF@"
- .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
- 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 on.
- 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 is 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 .
- .sp
- .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 1i
- Specifies the display with which the conversion is to be associated.
- .IP \fIconverter\fP 1i
- Specifies the conversion procedure to be called.
- .IP \fIconversion_args\fP 1i
- Specifies the additional conversion arguments needed
- to perform the conversion, or NULL.
- .IP \fInum_args\fP 1i
- Specifies the number of entries in \fIconversion_args\fP.
- .IP \fIfrom\fP 1i
- Specifies a descriptor for the source value.
- .IP \fIto_in_out\fP 1i
- Returns the converted value.
- .IP \fIcache_ref_return\fP 1i
- Returns a conversion cache id.
- .LP
- 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 .
- .IN "XtAppReleaseCacheRefs" "" "@DEF@"
- .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
- .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 .
- .IN "XtCallbackReleaseCacheRef" "" "@DEF@"
- .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
- 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 .
- .sp
- .IN "XtCallbackReleaseCacheRefList" "" "@DEF@"
- .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
- 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 .
- .IN "XtConvertAndStore" "" "@DEF@"
- .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
- 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 .
- .IN "XtGetValues" "" "@DEF@"
- .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
- 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 .
- .IN "XtVaGetValues" "" "@DEF@"
- .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
- .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 .
- .IN "get_values_hook procedure" "" "@DEF@"
- .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
- 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.
- .IN "XtGetSubvalues" "" "@DEF@"
- .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
- 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 .
- .IN "XtVaGetSubvalues" "" "@DEF@"
- .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
- .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 .
- .IN "XtSetValues" "" "@DEF@"
- .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
- 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.a
- 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 .
- .IN "XtVaSetValues" "" "@DEF@"
- .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
- .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 .
- .IN "XtSetValuesFunc" "" "@DEF@"
- .IN "set_values procedure" "" "@DEF@"
- .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
- 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 .
- .IN "set_values_almost procedure" "" "@DEF@"
- .IN "XtAlmostProc" "" "@DEF@"
- .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
- 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.
- Further, 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.
- .IN "XtSetSubvalues" "" "@DEF@"
- .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
- 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 .
- .IN "XtVaSetSubvalues" "" "@DEF@"
- .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
- .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 .
- .IN "set_values_hook procedure" "" "@DEF@"
- .IN "XtArgsFunc" "" "@DEF@"
- .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
- 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
-