Name

XtAppAddConverter — register a new resource converter for an application. 

Synopsis

XtAppAddConverter(app_context, from_type, to_type, converter, convert_args, num_args)

    XtAppContext app_context;
    String from_type;
    String to_type;
    XtConverter converter;
    XtConvertArgList convert_args;
    Cardinal num_args;

Arguments

app_contextSpecifies the application context. 

from_typeSpecifies the source type of the resource to be converted. 

to_typeSpecifies the destination type to which the resource is to be converted. 

converterSpecifies the converter procedure.  See XtConverter(2). 

convert_args
Specifies how to obtain additional arguments needed for the conversion; if no arguments are provided, this should be NULL.  See the Structures section below for a detailed description of the format of convert_args. 

num_argsSpecifies the number of additional arguments to the converter or zero. 

Description

XtAppAddConverter has been superseded by XtSetTypeConverter.  Resource converters provide a general way to pass specific data structures, and to hide the details of the data structures themselves.  Using XtAppAddConverter or XtAddConverter, an application can register a converter to transform data of a given type to another specified type.  The types themselves are arbitrary, and are specified by a string.  For example, the converter mechanism can convert data of type String to an application data type of Menu if the application has registered the appropriate converter; to the application, the data type Menu is opaque. 

Some converters need additional arguments, which can be obtained from fields within the widget or as constants.  The enumerated type XtAddressMode and the structure XtConvertArgRec specify how each argument is derived.  These are defined in <X11/Convert.h>, as follows:

typedef enum {
/∗ address mode parameter representation ∗/
XtAddress,/∗ address ∗/
XtBaseOffset,/∗ offset ∗/
XtImmediate/∗ constant ∗/
XtResourceString/∗ resource name string ∗/
XtResourceQuark/∗ resource name quark ∗/
} XtAddressMode;
typedef struct {
XtAddressMode address_mode;
caddr_t address_id;
Cardinal size;
} XtConvertArgRec, ∗XtConvertArgList;

The address_mode member specifies how to interpret the address_id member:

XtAddresscauses address_id to be interpreted as the address of the data. 

XtBaseOffsetcauses address_id to be interpreted as the offset from the widget base. 

XtImmediatecauses address_id to be interpreted as a constant. 

XtResourceStringcauses address_id to be interpreted as the name of a resource to be converted into an offset from the widget base. 

XtResourceQuarkmeans address_id is an internal compiled form of an XtResourceString.  The size field specifies the length of the data in bytes. 

Assuming a routine called CvtStringToPixel (see XtConverter for an example of this converter), the following code registers the routine as an official resource converter:

static XtConvertArgRec colorConvertArgs[] = {
{XtBaseOffset, (caddr_t) XtOffset(Widget, core.screen),
sizeof(Screen ∗)},
{XtBaseOffset, (caddr_t) XtOffset(Widget, core.colormap),
sizeof(Colormap)}
};
XtAddConverter(XtRString, XtRPixel, CvtStringToPixel,
    colorConvertArgs, XtNumber(colorConvertArgs));

The conversion argument descriptors colorConvertArgs and screenConvertArg are predefined.  The screenConvertArg descriptor puts the widget’s screen field into args[0].  The colorConvertArgs descriptor puts the widget’s screen field into args[0] and the widget’s colormap field into args[1]. 

Conversion routines should not just put a descriptor for the address of the base of the widget into args[0] and then use that in the routine.  They should pass in the actual values that the conversion depends on.  By keeping the dependencies of the conversion procedure-specific, it is more likely that subsequent conversions will find what they need in the conversion cache.  This way the cache is smaller and has fewer and more widely applicable entries. 

XtAddConverter provides a simplified interface for programs using the default application context. 

XtConverter(2) explains the responsibilities and conventions of the converter function itself; it also shows an example converter, CvtStringToPixel. 

See Also

XtCallConverter(1), XtConvertandStore, XtDirectConvert(1), XtSetTypeConverter(1),
XtConverter(2).