XtConvertAndStore() XtConvertAndStore()
Name
XtConvertAndStore - look up and call a resource converter, copying the resulting value.
Synopsis
Boolean XtConvertAndStore(object, from_type, from, to_type, to_in_out)
Widget object;
String from_type;
XrmValuePtr from;
String to_type;
XrmValuePtr to_in_out;
Inputs
object Specifies the object to use for additional arguments, if any are needed, and the destroy callback list; may be of class Object or
any subclass thereof.
from_type Specifies the source type.
from Specifies the value to be converted.
to_type Specifies the destination type.
to_in_out Specifies the address at which the converted value is to be stored, or NULL, and the number of bytes allocated for the value at
that address.
Outputs
to_in_out Returns the address at which the converted value was stored, and the actual number of bytes occupied by that value.
Returns
True if the conversion was successful; False otherwise.
Availability
Release 4 and later.
Description
XtConvertAndStore() looks up the type converter registered to convert from_type to to_type, computes any additional arguments needed (see
XtSetTypeConverter() for an explanation of how these arguments are computed), and then calls XtCallConverter() (or XtDirectConvert() for
old-style converters) with the from and to_in_out arguments.
When converting from a string, from_type should be XtRString, from->addr should be the address of the first character of the string (a char
*, not a char **), and from->size should be the length of the string plus one.
Generally, the caller will initialize the to_in_out argument to specify the location at which the converted value will be stored and the
number of bytes of memory allocated at that location. The to_in_out argument is passed directly to the converter which stores the data at
the requested location and modifies the size field to the actual size of the converted data.
If instead to_in_out->addr is NULL on entry to XtConvertAndStore(), it will be replaced with a pointer to private storage which contains
the converted value. As in the previous case, the size of the converted value will be returned in to_in_out->size. A value returned in
this way is stored in memory that is static to the converter, and the caller is expected to copy it immediately and must not modify it in
any way.
XtCallConverter() returns True if the conversion succeeds, and returns False otherwise.
XtConvertAndStore() adds XtCallbackReleaseCacheRef() to the destroyCallback list of the specified widget or object if the conversion
returns an XtCacheRef value. This will automatically decrement the reference count on the cached value of the resource when the object no
longer needs it. The resulting resource should not be referenced after the object has been destroyed.
Usage
You do not often need, in applications or widgets, to convert between resource types directly. Generally you can rely on the Intrinsics
resource management code to perform all necessary conversions for you. When writing a resource converter, however, you may find that you
need to invoke another converter.
The Intrinsics define a number of pre-registered converters, most of them between String and other common Xt types. The table below
describes these predefined converters. The Xmu library also contains a number of useful converters, which are not pre-registered. See
XmuCvtStringToMisc(6).
from_type to_type Description
XtRString XtRAcceleratorTable Compiles a string accelerator table into
internal accelerator table format.
XtRAtom Converts a string to an Atom with XInter-
nAtom().
XtRBoolean Converts strings true, false, yes, no, on,
off to corresponding Boolean value (case
insensitive).
XtRBool Same as for XtRBoolean.
XtRCursor Given a standard X cursor name, returns a
cursor ID.
XtRDimension Converts a width or height value to a Dimen-
sion.
XtRDisplay Given a display name, opens the display and
returns a Display structure.
XtRFile Given a filename, opens the file and returns
the file descriptor.
XtRFloat Converts a numeric string to floating point.
XtRFont Given a font name, loads the font and returns
the font ID. The value XtDefaultFont will
return the default font for the screen.
XtRFontSet Converts a list of base font names to an
XFontSet. See XCreateFontSet() for informa-
tion on the syntax of the font name list.
The value XtDefaultFontSet will be converted
to the default XFontSet for the screen.
XtRFontStruct Given a font name, loads the font and returns
a pointer to the XFontStruct containing font
metrics. XtDefaultFont returns the default
font for the screen.
XtRInt Converts a numeric string to an integer.
XtRInitialState Converts the strings "NormalState" and "Icon-
icState" to the corresponding enum values
NormalState and IconicState.
XtRPixel Converts a color name string (e.g., red or
#FF0000) into the pixel value that will pro-
duce the closest color possible on the hard-
ware. See Appendix C, Specifying Fonts and
Colors, for information on legal values. The
values XtDefaultBackground and XtDefaultFore-
ground are always guaranteed to exist, and to
contrast, on any server.
XtRPosition Same as for XtRShort.
XtRShort Converts a numeric string to a short integer.
XtRTranslationTable Compiles string translation table into inter-
nal translation table format.
XtRUnsignedChar Converts a string to an unsigned char.
XtRVisual Converts the strings "StaticGray", "Static-
Color", "TrueColor", "GrayScale", "Pseudo-
Color", and "DirectColor" to the correspond-
ing visual type.
XtRColor XtRPixel Converts an XColor structure to a pixel
value.
XtRPixel XtRColor Converts a pixel value to an XColor struc-
ture.
XtRInt XtRBoolean Converts an int to a Boolean.
XtRBool Converts an int to a Bool.
XtRColor Converts an int to an XColor.
XtRDimension Converts an int to a Dimension.
XtRFloat Converts an int to a float.
XtRFont Converts an int to a Font.
XtRPixel Converts an int to a pixel value.
XtRPixmap Converts an int to a Pixmap.
XtRPosition Converts an int to a Position.
XtRShort Converts an int to a short.
XtRUnsignedChar Converts an int to an unsigned char.
Structures
typedef struct {
unsigned int size;
XPointer addr;
} XrmValue, *XrmValuePtr;
See Also
XtAppSetTypeConverter(1), XtCallbackReleaseCacheRef(1), XtCallConverter(1), XtDirectConvert(1), XtSetTypeConverter(1).
Xt - Resource Management XtConvertAndStore()