XtConvertAn(3) — OSF1 1.0

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;

Arguments

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 a descriptor for storage into which the converted value will be returned.

Description

XtConvertAndStore looks up the type converter registered to convert from_type to to_type, computes any additional arguments needed, and then calls XtCallConverter (or XtDirectConvert if an old-style converter was registered with XtAddConverter or XtAppAddConverter) with the from and to_in_out arguments. The to_in_out 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. If the conversion succeeds, XtConvertAndStore returns True; otherwise it returns False.

Xt recognizes and converts between the from_types and the to_types shown in the table below. In addition, it is possible to register custom converters using XtAddConverter.

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 will return 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.

XtConvertAndStore adds XtCallbackReleaseCacheRef to the destroyCallback list of the specified widget if the conversion returns an XtCacheRef value. The resulting resource should not be referenced after the widget has been destroyed.

XtCreateWidget performs processing equivalent to XtConvertAndStore when initializing the widget instance. Because there is extra memory overhead required to implement reference counting, clients may distinguish those widgets which are never destroyed before the application exits from those which may be destroyed and whose resources should be deallocated.

To specify whether or not reference counting is to be enabled for the resources of a particular widget when the widget is created, the client can specify a value for the Boolean resource XtNinitialResourcesPersistent, class XtCInitialResourcesPersistent.

When XtCreateWidget is called, if this resource is not specified as False in either the arg list or the resource database, then the resources referenced by this widget are not reference counted, regardless of how the type converter may have been registered. The effective default value is True; thus clients which expect to destroy one or more widgets and want resources deallocated must explicitly specify False for XtNinitialResourcesPersistent.

The resources are still freed and destructors called when XtCloseDisplay is called if the conversion was registered as XtCacheByDisplay.

Converters not only are a good labor-saving device, but also make it possible to hide the details of data structures in the resource converter. For example, a program can access fonts, files, and application-dependent data structures using resource conversions.

Structures

typedef struct {
unsigned int size;
caddr_t addr;
} XrmValue, ∗XrmValuePtr;

Museum

Related Articles

Name

Synopsis

Arguments

Description

Structures

See Also