XtConvertAn(3x) — HP-UX 9.05

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

objectSpecifies 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_typeSpecifies the source type.

fromSpecifies the value to be converted.

to_typeSpecifies the destination type.

to_in_outSpecifies 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_outReturns 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. 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 (no need to call XtParseAcceleratorTable()).
	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 Dimension.
	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 (if it is not already loaded) and returns the font ID. See Appendix C, Specifying Fonts and Colors, for more information on legal values. The value XtDefaultFont will return the default font for the screen.
	XtRFontStruct	Given a font name, loads the font (if it is not already loaded) and returns a pointer to the FontStruct containing font metrics. The value XtDefaultFont returns the default font for the screen.
	XtRInt	Converts a numeric string to an integer.
	XtRPixel	Converts a color name string (e.g., red or #FF0000) into the pixel value that will produce the closest color possible on the hardware. See Appendix C, Specifying Fonts and Colors, for more information on legal values. The two values XtDefaultBackground and XtDefaultForeground are always guaranteed to exist, and to contrast, on any server.
	XtRPosition	Converts an x or y value to a Position.
	XtRShort	Converts a numeric string to a short integer.
	XtRTranslationTable	Compiles string translation table into internal translation table format (no need to call XtParseTranslationTable()).
	XtRUnsignedChar	Converts a string to an unsigned char.
XtRColor	XtRPixel	Converts an XColor structure to a pixel value.
XtRPixel	XtRColor	Converts a pixel value to an XColor structure.
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;

Museum

Related Articles