Name
XtTypeConverter — prototype procedure for a new-style resource converter.
Synopsis
typedef Boolean (∗XtTypeConverter)(Display ∗, XrmValue ∗, Cardinal ∗, XrmValue ∗, XrmValue ∗, XtPointer ∗);
Display ∗display;
XrmValue ∗args;
Cardinal ∗num_args;
XrmValue ∗from;
XrmValue ∗to;
XtPointer ∗converter_data;
Arguments
displaySpecifies the Display connection with which this conversion is associated.
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.
toSpecifies a descriptor for a location into which to store the converted value.
converter_data
Specifies a location into which the converter may store converter-specific data that is associated with this conversion.
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.
The display argument is normally used only when generating error messages, to identify the application context (with the function XtDisplayToApplicationContext).
The to argument specifies the size and location into which the converter should store the converted value. If the location is NULL, the converter should allocate appropriate storage and store the size and location into the to descriptor. If the type converter allocates the storage, it remains under the ownership of the converter and must not be modified by the caller. The type converter is permitted to use static storage for this purpose and therefore the caller must immediately copy the data upon return from the converter. If the location is not NULL, the converter must check the size field to insure that sufficient space has been allocated before storing the converted value.
•If insufficient space is specified, the converter should update the size field with the number of bytes required and should return False without modifying the data at the specified location.
•If sufficient space was allocated by the caller, the converter should update the size field with the number of bytes actually occupied by the converted value.
For converted values of type XtRString, the size should include the NULL-terminating byte, if any. The converter may store any value it wishes in the location specified in converter_data; this data will be passed to the destructor, if any, when the resource is freed by the Intrinsics.
The converter must return True if the conversion was successful and must return False otherwise. If the conversion cannot be performed due to an improper source value, a warning message should be issued with XtAppWarningMsg.
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
XtRAtom
XtRBoolean
XtRBool
XtRCursor
XtRDimension
XtRDisplay
XtRFile
XtRFloat
XtRFont
XtRFontStruct
XtRInt
XtRInitialState
XtRPixel
XtRPosition
XtRShort
XtRTranslationTable
XtRUnsignedChar
XtRVisual
From XtRColor to XtRPixel.
From XRInt to:
XtRBoolean
XtRBool
XtRColor
XtRDimension
XtRFloat
XtRFont
XtRPixel
XtRPixmap
XtRPosition
XtRShort
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 in the following manner:
•Query the resource database for the resource whose full name is xtDefaultFont, class XtDefaultFont (that is, no widget name/class prefixes) and use a type XtRString value returned as the font name, or a type XtRFont or XtRFontStruct value directly as the resource value.
•If the resource database does not contain a value for xtDefaultFont, class XtDefaultFont, or if the returned font name cannot be successfully opened, an implementation-defined font in ISO8859-1 character set encoding is opened. One possible algorithm is to perform an XListFonts using a wildcard font name and use the first font in the list. This wildcard font name should be as broad as possible to maximize the probability of locating a useable font; for example:
-∗-∗-∗-R-∗-∗-∗-120-∗-∗-∗-∗-ISO8859-1
•If no suitable ISO8859-1 font can be found, issue an error message.
The String-to-InitialState conversion accepts the values NormalState or IconicState as defined by the ICCCM.
The String-to-Visual conversion calls XMatchVisualInfo using the screen and depth resources from core_part and returns the first matching Visual on the list. The widget resource list must specify any resource of type XtRVisual after the depth resource. The allowed string values are the X Protocol visual class names: StaticGray, StaticColor, TrueColor, GrayScale, PseudoColor, and DirectColor.
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;
The addr field specifies the address of the data and the size field gives the total number of significant bytes in the data. For values of type String, addr is the address of the first character and size includes the NULL-terminating byte.
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 location specified in the 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 if an address is written into to->addr, it cannot be that of a local variable of the converter because the data will not be valid after the converter returns. Static variables may be used, as in the following example.
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 a converter that takes a string and converts it to a pixel value. Note that the display parameter is only used to generate error messages; the Screen conversion argument is still required to inform the Intrinsics that the converted value is a function of the particular display (and colormap).
#define done(type, value) \
{ \
if (toVal->addr != NULL) { \
if (toVal->size < sizeof(type)) { \
toVal->size = sizeof(type); \
return False; \
} \
∗(type∗)(toVal->addr) = (value); \
} \
else { \
static type static_val; \
static_val = (value); \
toVal->addr = (XtPointer)&static_val; \
} \
toVal->size = sizeof(type); \
return True; \
}
static Boolean CvtStringToPixel(display, args, num_args, fromVal,
toVal, converter_data)
Display ∗dpy;
XrmValue ∗args;
Cardinal ∗num_args;
XrmValue ∗fromVal;
XrmValue ∗toVal;
XtPointer ∗converter_data;
{
static XColor screenColor;
XColor exactColor;
Screen ∗screen;
Colormap colormap;
Status status;
char message[1000];
XrmQuark q;
String params[1];
Cardinal num_params = 1;
if (∗num_args != 2)
XtAppErrorMsg(XtDisplayToApplicationContext(dpy),
"cvtStringToPixel", "wrongParameters", "XtToolkitError",
"String to pixel conversion needs screen \
and colormap arguments",
(String ∗)NULL, (Cardinal ∗)NULL);
screen = ∗((Screen ∗∗) args[0].addr); /∗ could also use dpy now ∗/
colormap = ∗((Colormap ∗) args[1].addr);
LowerCase((char ∗) fromVal->addr, message);
if ( strcmp(message, "xtdefaultbackground") == 0) {
done(&screen->white_ pixel, Pixel);
}
if ( strcmp(message, "xtdefaultforeground") == 0) {
done(&screen->black_ pixel, Pixel);
}
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;
XtAppWarningMsg(XtDisplayToApplicationContext(dpy),
"cvtStringToPixel", "noColormap", "XtToolkitError",
"Cannot allocate colormap entry for \"%s\"", \
params, &num_params);
} else {
done( &screenColor.pixel, Pixel );
}
/∗ converter_data not used here ∗/
};
See Also
XtAppSetTypeConverter(1), XtCallConverter(1), XtConvertAndStore(1), XtDisplayStringConversionWarning(1), XtSetTypeConverter(1).