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