XtAppAddConverter() XtAppAddConverter()
Name
XtAppAddConverter - register an "old-style" resource converter.
Synopsis
void 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;
Inputs
app_context Specifies the application context.
from_type Specifies the source type of the resource to be converted.
to_type Specifies the destination type to which the resource is to be converted.
converter Specifies 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_args Specifies the number of additional arguments to the converter or zero.
Description
XtAppAddConverter() registers converter in application context app_context as a procedure to convert data of resource type from_type to
resource type to_type.
Each element of convert_args is an XtConvertArgRec. It is not the argument actually passed to the converter procedure, but specifies how
to obtain an XrmValue argument which will be passed to the converter. The "Background" section below explains the XtConvertArgRec struc-
ture in detail.
See XtConverter(2) for an explanation of how to write an "old-style" converter.
Usage
XtAppAddConverter() registers an "old-style" converter. This kind of converter is still in common use, but are not as flexible as the
(incompatible) "new-style" converter added in Release 4. If you must register an existing old-style converter, use XtAppAddConverter(),
but if you are writing a converter of your own, consider using a new-style converter. See XtAppSetTypeConverter().
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.
Some converters need additional arguments, such as a screen or colormap in order to correctly perform the conversion. These converters are
registered with an XtConvertArgList. Generally the author of the converter will also define a static array of XtConvertArgRec to be regis-
tered with the converter. There are also two XtConvertArgLists predefined by the Intrinsics: screenConvertArg passes the widget's screen
field to the converter in args[0], and colorConvertArgs passes the widget's screen field to the converter in args[0] and the widget's col-
ormap field in args[1].
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
You can register the String-to-Widget converter from the Xmu library with the following:
static XtConvertArgRec parentCvtArg[] = {
{XtBaseOffset, (XtPointer)XtOffset(Widget, core.parent), sizeof(Widget)}
};
XtAppAddConverter(app, XtRString, XtRWidget, XmuCvtStringToWidget,
parentCvtArg, XtNumber(parentCvtArg));
Background
For the few type converters that need additional arguments, the Intrinsics conversion mechanism provides a method of specifying how these
arguments should be computed. Before a converter is called, each element of the XtConvertArgList is interpreted to determine the sizes and
values of the arguments. These computed arguments are passed to the converter as an array of XrmValue. The enumerated type XtAddressMode
and the structure XtConvertArgRec specify how each argument is derived.
typedef enum {
/* address mode parameter representation */
XtAddress, /* address */
XtBaseOffset, /* offset */
XtImmediate, /* constant */
XtResourceString,/* resource name string */
XtResourceQuark, /* resource name quark */
XtWidgetBaseOffset,/* offset */
XtProcedureArg /* procedure to call */
} XtAddressMode;
typedef struct {
XtAddressMode address_mode;
XtPointer address_id;
Cardinal size;
} XtConvertArgRec, *XtConvertArgList;
The size field of an XtConvertArgRec specifies the length of the data in bytes. The address_mode field specifies how the address_id field
should be interpreted. The possible values of XtAddressMode have the following meanings:
XtAddress
causes address_id to be interpreted as the address of the data.
XtBaseOffset
causes address_id to be interpreted as the offset from the widget base.
XtImmediate
causes address_id to be interpreted as a constant.
XtResourceString
causes address_id to be interpreted as the name of a resource that is to be converted into an offset from the widget base.
XtResourceQuark
causes address_id to be interpreted as the result of an XrmStringToQuark() conversion on the name of a resource, which is to be con-
verted into an offset from the widget base.
XtWidgetBaseOffset
is similar to XtBaseOffset except that it searches for the closest windowed ancestor if the object is not of a subclass of Core.
XtProcedureArg
specifies that address_id is a pointer to a procedure of type XtConvertArgProc to be invoked to return the conversion argument. See
XtConvertArgProc(2) for an explanation of how to write a procedure of this type.
Structures
The XtConvertArgRec structure and the related XtAddressMode type are shown in the "Background" section above.
See Also
XtAppSetTypeConverter(1), XtCallConverter(1), XtConvertandStore, XtDirectConvert(1), XtSetTypeConverter(1),
XtConverter(2), XtTypeConverter(2), XtConvertArgProc(2),
XmuCvtStringToMisc(6).
Xt - Resource Management XtAppAddConverter()