Name
XtConverter — prototype procedure for an old-style resource converter.
Synopsis
typedef void (∗XtConverter)(XrmValue ∗, Cardinal ∗,
XrmValue ∗, XrmValue ∗);
XrmValue ∗args;
Cardinal ∗num_args;
XrmValue ∗from;
XrmValue ∗to;
Arguments
argsSpecifies a list of additional XrmValue arguments to the converter if additional context is needed to perform the conversion, or specifies NULL. For example, a string-to-font converter needs the widget’s screen, or a string-to-pixel converter needs the widget’s screen and colormap.
num_argsSpecifies the number of additional XrmValue arguments, or specifies zero.
fromSpecifies the value to convert.
toSpecifies the descriptor to use to return the converted value.
Description
The Intrinsics provide a mechanism for registering converters that are automatically invoked by the resource-fetching routines. The Intrinsics additionally provide and register several commonly used converters. This resource conversion mechanism serves several purposes:
•It permits user and application resource files to contain ASCII representations of nontextual values.
•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 run time.
•It caches all 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 color) are performed only once.
XtConverter is the old-style converter used until R4. The new-style converter is XtTypeConverter. The two converter interfaces are not compatible.
The Intrinsics define all the representations used in the Core, Composite, Constraint, and Shell widgets. The following resource converters are registered with the Intrinsics:
From XtRString to:
XtRAcceleratorTable, XtRBoolean, XtRBool, XtRCursor, XtRDimension, XtRDisplay, XtRFile, XtRFloat, XtRFont, XtRFontStruct, XtRInt, XtRPixel, XtRPosition, XtRShort, XtRTranslationTable, and XtRUnsignedChar.
From XtRColor to:
XtRPixel.
From XRInt to:
XtRBoolean, XtRBool, XtRColor, XtRDimension, XtRFloat, XtRFont, XtRPixel, XtRPixmap, XtRPosition, XtRShort, and XtRUnsignedChar.
From XtRPixel to:
XtRColor.
The string-to-pixel conversion has two predefined constants that are guaranteed to work and contrast with each other and with XtDefaultBackground. They evaluate the black and white pixel values of the widget’s screen, respectively. For applications that run with reverse video, however, they evaluate the white and black pixel values of the widget’s screen, respectively.
Similarly, the string to font and font structure converters recognize the constant XtDefaultFont and evaluate this to the font in the screen’s default graphics context.
Type converters use pointers to XrmValue structures (defined in <X11/Xresource.h>) for input and output values.
typedef struct {
unsigned int size;
caddr_t addr;
} XrmValue, ∗XrmValuePtr;
A resource converter procedure pointer is of type XtConverter.
Type converters should perform the following actions:
•Check to see that the number of arguments passed is correct.
•Attempt the type conversion.
•If successful, return a pointer to the data in the to parameter; otherwise, call XtWarningMsg and return without modifying to.
Most type converters just take the data described by the specified from argument and return data by writing into the specified to argument. A few need other information, which is available in the specified argument list.
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.
Note that the address written in to->addr cannot be that of a local variable of the converter because this is not valid after the converter returns. It should be a pointer to a static variable, as in the example below in which screenColor is returned.
All type converters should define some set of conversion values that they are guaranteed to succeed on so these can be used in the resource defaults. This might be problematic with particular 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 (for example, XtDefaultForeground, XtDefaultBackground, or XtDefaultFont).
Examples
The following example shows an old-style converter that takes a string and converts it to a pixel value:
static void CvtStringToPixel(args, num_args, fromVal, toVal)
XrmValuePtrargs;
Cardinal∗num_args;
XrmValuePtrfromVal;
XrmValuePtrtoVal;
{
static XColorscreenColor;
XColorexactColor;
Screen∗screen;
Colormapcolormap;
Statusstatus;
charmessage[1000];
XrmQuarkq;
Stringparams[1];
Cardinalnum_params = 1;
if (∗num_args != 2)
XtErrorMsg("cvtStringToPixel","wrongParameters",
"XtToolkitError",
"String to pixel conversion needs screen and
colormap arguments",
(String ∗)NULL, (Cardinal ∗)NULL);
screen = ∗((Screen ∗∗) args[0].addr);
colormap = ∗((Colormap ∗) args[1].addr);
LowerCase((char ∗) fromVal->addr, message);
q = XrmStringToQuark(message);
if (q == XtQExtdefaultbackground) { done(&screen->white_pixel, Pixel);
return; }
if (q == XtQExtdefaultforeground) { done(&screen->black_pixel, Pixel);
return; }
if ((char) fromVal->addr[0] == ’#’) { /∗ some color rgb definition ∗/
status = XParseColor(DisplayOfScreen(screen), colormap,
(String) fromVal->addr, &screenColor);
if (status != 0) status = XAllocColor(DisplayOfScreen
(screen), colormap, &screenColor);
} else /∗ some color name ∗/
status = XAllocNamedColor(DisplayOfScreen(screen), colormap,
(String) fromVal->addr, &screenColor, &exactColor);
if (status == 0) {
params[0]=(String)fromVal->addr;
XtWarningMsg("cvtStringToPixel","noColormap",
"XtToolkitError",
"Cannot allocate colormap entry for \
\"%s\"", params, &num_params);
} else {
done(&(screenColor.pixel), Pixel)
}
};
See Also
XtAppAddConverter(1), XtAppSetTypeConverter(1), XtConvert(1), XtDirectConvert(1), XtSetTypeConverter(1), XtStringConversionWarning(1), XtTypeConverter(1).