Query: xttypeconverter
OS: hpux
Section: 3
Format: Original Unix Latex Style Formatted with HTML and a Horizontal Scroll Bar
XtTypeConverter() XtTypeConverter()
Name
XtTypeConverter - interface definition 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_in_out;
XtPointer *converter_data;
Inputs
display Specifies the Display connection with which this conversion is associated.
args Specifies a list of additional XrmValue arguments to the converter, or NULL.
num_args Specifies the number of arguments in args.
from Specifies the address and size of the value to convert.
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.
converter_data
Returns arbitrary data which will be passed to the destructor procedure, if any, associated with this converter when the con-
verted resource is freed from the resource cache.
Returns
True if the conversion was successful; False otherwise.
Availability
Release 4 and later.
Description
An XtTypeConverter is a "new-style" resource converter registered with XtAppSetTypeConverter() or XtSetTypeConverter(). It is invoked by
the Intrinsics to convert resource values between the types for which it is registered, or can be invoked explicitly with XtConvertAnd-
Store() or XtCallConverter().
An XtTypeConverter should convert the value pointed to by from->addr (which is from->size bytes long) into the appropriate type and store
the converted value at to_in_out->addr. If this pointer is NULL, the converter should store the converted value in its own storage and
place the size and address of this storage into to_in_out. This memory remains under the ownership of the converter and must not be modi-
fied 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 to_in_out->addr is not NULL, the converter must check the size field to insure that sufficient space has been allocated before storing
the converted value.
o If insufficient space is specified, the converter should update the size field to indicate number of bytes required and should return
False without modifying the data pointed to by the addr field.
o If sufficient space was allocated by the caller, the converter should store the converted value at the location pointed to by the addr
field and set the size field to 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 return any value it wishes in converter_data; this data is similar to the client_data argument to a callback and will be
passed to the destructor, if any, associated with this converter when the resource value is freed by the Intrinsics. See XtDestructor(2)
for more information.
The args argument is an array of values (such as a Screen pointer or Colormap ID) that the converter may need to perform the conversion.
The contents and interpretation of this array are determined by the XtConvertArgList array supplied when the converter is registered. The
Intrinsics use the XtConvertArgList to compute an array of XrmValue to pass to the converter each time it is invoked. An XtTypeConverter
that expects values in its args argument must be registered with a suitable XtConvertArgList or it will not work correctly. See XtAppSet-
TypeConverter() for information on declaring XtConvertArgList arrays.
The display argument to an XtTypeConverter may be used by some converters in the conversion process, and is also needed to obtain the
application context (with the function XtDisplayToApplicationContext()) in order to report warning messages. Note that one of the primary
differences between "new-style" and "old-style" converters is that new-style converters have this display argument.
An XtTypeConverter should return True if the conversion was successful and return False otherwise. If the conversion cannot be performed
due to an improper source value, a warning message should be issued with XtAppWarningMsg() or XtDisplayStringConversionWarning().
Usage
Note that the num_args argument is a pointer to the number of elements in args, and not the number of arguments itself. Be sure to deref-
erence this argument correctly before using it.
An XtTypeConverter must check both the addr and size fields of its to_in_out argument, and be prepared to return the converted value in
different ways depending on the values in these fields. To encapsulate all the requirements for returning a converted value, the standard
converters defined by the Intrinsics all call a macro named done() which is passed the converted value and returns it in the correct way
depending on the to_in_out argument. This done() macro is shown in the example below.
All type converters should define some set of values for which they are guaranteed to succeed, so that these values can be used as widget
and application resource defaults. For some string converters, this may mean defining a string value which will be handled specially by
the converter. It is useful if you give this string a symbolic name. The special constants XtDefaultFont, XtDefaultForeground, and XtDe-
faultBackground are strings of this type which are specially recognized by their converters.
If you write a widget that has a resource which is of some enumerated type, you should write a converter routine which will convert between
the symbolic names of each value and the values themselves. This converter should then be registered in your widget's class_initialize()
method.
If you are writing a programming library or an application that defines non-standard types, it may be useful to provide string converters
for those types. This allows resources of that type to be specified from a resource file. An application that supported user-configurable
popup menus, for example, might include a String-to-Menu converter.
If your converter needs additional arguments to perform the conversion, you should declare and export the XtConvertArgList array to be reg-
istered with the converter, or at least document the array that must be registered. Since the wrong arguments will likely cause your con-
verter to dump core, you should consider defining the argument list part of the process of writing the converter. Note that there are also
two XtConvertArgLists predefined by the Intrinsics: screenConvertArg passes the widget's screen field to the converter in args[0], and col-
orConvertArgs passes the widget's screen field to the converter in args[0] and the widget's colormap field in args[1].
A type converter may invoke other converters to aid with its conversion. When converting complex types, this is a good idea because it
allows differing source types that convert into a common intermediate type to make maximum use of the type converter cache.
The Intrinsics define a number of standard converters which do not need to be registered. See XtConvertAndStore() for a list of these pre-
defined converters. There are also a number of other useful converters defined in the Xmu library which do need to be registered explic-
itly. See XmuCvtStringToMisc(6).
Example
The done() macro below is from the X11R5 Intrinsics. It is used to return a converted resource value correctly depending on the to_in_out
argument (which is here given the name toVal). Note that the type argument is used to declare a static variable to store the value in when
to_in_out (or toVal) does not provide a location to store it.
#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 = (XPointer)&static_val; } toVal->size = sizeof(type); return True; }
An XtTypeConverter from the X11R5 Intrinsics to convert between a string and a Pixel is shown below, along with the XtConvertArgList that
it must be registered with. Note how it checks num_args and then determines the screen and colormap from its args argument. Also note
that it tests for two special values: the strings with symbolic names XtDefaultForeground and XtDefaultBackground. It is guaranteed to
successfully convert these values. The pd variable is an Intrinsics internal structure, and pd->rv indicates whether or not the reverseV-
ideo application resource is specified in the resource database.
This converter returns a Boolean in its converter_data argument (called closure_ret here) which indicates to the resource destructor
whether or not it should deallocate the color. The pixels associated with XtDefaultForeground and XtDefaultBackground are never deallo-
cated. See XtDestructor(2) for the destructor procedure that accompanies this converter.
Finally, note that this converter uses the done macro five times, which is inefficient because it expands to a large macro. With some sim-
ple reorganization, it need only be called once.
XtConvertArgRec Const colorConvertArgs[] = {
{XtWidgetBaseOffset, (XtPointer)XtOffsetOf(WidgetRec, core.screen),
sizeof(Screen *)},
{XtWidgetBaseOffset, (XtPointer)XtOffsetOf(WidgetRec, core.colormap),
sizeof(Colormap)}
};
Boolean XtCvtStringToPixel(dpy, args, num_args, fromVal, toVal, closure_ret)
Display* dpy;
XrmValuePtr args;
Cardinal *num_args;
XrmValuePtr fromVal;
XrmValuePtr toVal;
XtPointer *closure_ret;
{
String str = (String)fromVal->addr;
XColor screenColor;
XColor exactColor;
Screen *screen;
XtPerDisplay pd = _XtGetPerDisplay(dpy);
Colormap colormap;
Status status;
String params[1];
Cardinal num_params=1;
if (*num_args != 2) {
XtAppWarningMsg(pd->appContext, XtNwrongParameters, "cvtStringToPixel",
XtCXtToolkitError,
"String to pixel conversion needs screen and colormap arguments",
(String *)NULL, (Cardinal *)NULL);
return False;
}
screen = *((Screen **) args[0].addr);
colormap = *((Colormap *) args[1].addr);
if (CompareISOLatin1(str, XtDefaultBackground) == 0) {
*closure_ret = False;
if (pd->rv) done(Pixel, BlackPixelOfScreen(screen))
else done(Pixel, WhitePixelOfScreen(screen));
}
if (CompareISOLatin1(str, XtDefaultForeground) == 0) {
*closure_ret = False;
if (pd->rv) done(Pixel, WhitePixelOfScreen(screen))
else done(Pixel, BlackPixelOfScreen(screen));
}
status = XAllocNamedColor(DisplayOfScreen(screen), colormap,
(char*)str, &screenColor, &exactColor);
if (status == 0) {
String msg, type;
params[0] = str;
/* Server returns a specific error code but Xlib discards it. Ugh */
if (XLookupColor(DisplayOfScreen(screen), colormap, (char*)str,
&exactColor, &screenColor)) {
type = "noColormap";
msg = "Cannot allocate colormap entry for "%s"";
}
else {
type = "badValue";
msg = "Color name "%s" is not defined";
}
XtAppWarningMsg(pd->appContext, type, "cvtStringToPixel",
XtCXtToolkitError, msg, params, &num_params);
*closure_ret = False;
return False;
} else {
*closure_ret = (char*)True;
done(Pixel, screenColor.pixel);
}
}
Structures
The XrmValue structure is defined as follows:
typedef struct {
unsigned int size;
XPointer addr;
} XrmValue, *XrmValuePtr;
See Also
XtAppSetTypeConverter(1), XtCallConverter(1), XtConvertAndStore(1), XtDisplayStringConversionWarning(1), XtSetTypeConverter(1),
XmuCvtStringToMisc(6).
Xt - Resource Management XtTypeConverter()