Query: xtconvertandstore
OS: hpux
Section: 1
Format: Original Unix Latex Style Formatted with HTML and a Horizontal Scroll Bar
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()