XtAppAddConverter()XtAppAddConverter()NameXtAppAddConverter - register an "old-style" resource converter.
Synopsis
void XtAppAddConverter(app_context, from_type, to_type, converter, con‐
vert_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.
DescriptionXtAppAddConverter() registers converter in application context app_con‐
text 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 structure
in detail.
See XtConverter(2) for an explanation of how to write an "old-style"
converter.
UsageXtAppAddConverter() 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 reg‐
istered with the converter. There are also two XtConvertArgLists pre‐
defined by the Intrinsics: screenConvertArg passes the widget's screen
field to the converter in args[0], and colorConvertArgs passes the wid‐
get'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 prede‐
fined converters. There are also a number of other useful converters
defined in the Xmu library which do need to be registered explicitly.
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 Intrin‐
sics conversion mechanism provides a method of specifying how these
arguments should be computed. Before a converter is called, each ele‐
ment 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 wid‐
get 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 Xrm‐
StringToQuark() conversion on the name of a resource, which is
to be converted into an offset from the widget base.
XtWidgetBaseOffset
is similar to XtBaseOffset except that it searches for the clos‐
est 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 argu‐
ment. 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 AlsoXtAppSetTypeConverter(1), XtCallConverter(1), XtConvertandStore, XtDi‐
rectConvert(1), XtSetTypeConverter(1),
XtConverter(2), XtTypeConverter(2), XtConvertArgProc(2),
XmuCvtStringToMisc(6).
Xt - Resource Management XtAppAddConverter()
