XtAppSetTypeConverter()XtAppSetTypeConverter()NameXtAppSetTypeConverter - register a "new-style" type converter in a sin‐
gle application context.
Synopsis
void XtAppSetTypeConverter(app_context, from_type, to_type, converter,
convert_args, num_args, cache_type, destructor)
XtAppContext app_context;
String from_type;
String to_type;
XtTypeConverter converter;
XtConvertArgList convert_args;
Cardinal num_args;
XtCacheType cache_type;
XtDestructor destructor;
Inputs
app_context
Specifies the application context.
from_type Specifies the source type.
to_type Specifies the destination type.
converter Specifies the resource type converter procedure.
convert_args
Specifies additional conversion arguments, or NULL.
num_args Specifies the count of additional conversion arguments, or
zero.
cache_type
Specifies whether or not resources produced by this converter
are sharable or display-specific and when they should be
freed.
destructor
Specifies a destroy procedure for resources produced by this
conversion, or NULL if no additional action is required, to
deallocate resources produced by converter.
Availability
Release 4 and later.
DescriptionXtAppSetTypeConverter() registers converter in app_context as a proce‐
dure 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.
Converted resource values returned by converter will automatically be
cached according to the argument cache_type, which can be XtCacheNone,
XtCacheAll, or XtCacheByDisplay. The meanings of these types are
described in the "Background" section below. In addition, the quali‐
fier XtCacheRefCount can be ORed with any of these values and specifies
that references to cached values produced by this converter should be
counted, and if the count ever drops to zero, the value should be
removed from the cache, and the procedure destructor should be called
to free any memory or resources associated with that value.
If the same from_type and to_type are specified in multiple calls to
XtAppSetTypeConverter(), the most recent overrides the previous ones.
See XtTypeConverter(2) for an explanation of how to write a "new-style"
converter. See XtDestuctor(2) for an explanation of how to write a
destructor procedure. See XtCallConverter() for an explanation of how
reference counting of cached values is performed.
UsageXtAppSetTypeConverter() registers a resource converter of a type added
to the Intrinsics in Release 4. If you need to register an "old-style"
converter which was written before Release 4, use XtAppAddConverter().
XtSetTypeConverter() is identical to XtAppSetTypeConverter() except
that it registers the converter in all application contexts, including
application contexts that are created in the future.
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 con‐
verter 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 con‐
verter will also define a static array of XtConvertArgRec to be regis‐
tered with the converter. There are also two XtConvertArgLists prede‐
fined 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 XmuCvtStringToColorCursor from the Xmu library
with the following:
static XtConvertArgRec colorCursorConvertArgs[] = {
{XtWidgetBaseOffset, (XtPointer) XtOffsetOf(WidgetRec, core.screen),
sizeof(Screen *)},
{XtResourceString, (XtPointer) XtNpointerColor,sizeof(Pixel)},
{XtResourceString, (XtPointer) XtNpointerColorBackground, sizeof(Pixel)},
{XtWidgetBaseOffset, (XtPointer) XtOffsetOf(WidgetRec,core.colormap),
sizeof(Colormap)}
};
XtSetTypeConverter(XtRString, XtRColorCursor, XmuCvtStringToColorCursor,
colorCursorConvertArgs, XtNumber(colorCursorConvertArgs),
XtCacheByDisplay, NULL);
BackgroundSpecifying Arguments to a Converter
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.
Caching Converted Values
The possible values for the cache_type argument are as follows:
XtCacheNone
Specifies that the results of a previous conversion may not be
reused to satisfy any other resource requests; the specified
converter will be called each time the converted value is
required.
XtCacheAll
Specifies that the results of a previous conversion should be
reused for any resource request that depends upon the same
source value and conversion arguments.
XtCacheByDisplay
Specifies that the results of a previous conversion should be
used as for XtCacheAll but that the value should be removed from
the cache and the destructor, if any, should be called, when
XtCloseDisplay() is called for the display connection associated
with the converted value.
The qualifier XtCacheRefCount may be ORed with any of the above values.
If XtCacheRefCount is specified, calls to XtCreateWidget(), XtCreateM‐
anagedWidget(), XtGetApplicationResources() and XtGetSubresources()
that use the converted value will be counted. When a widget using the
converted value is destroyed, the count is decremented, and if the
count reaches zero, the destructor procedure destructor will be called
and the converted value will be removed from the conversion cache.
Structures
The XtConvertArgRec structure and the related XtAddressMode type are
shown in the "Background" section above. The XtCacheType type and its
legal values are defined as follows:
typedef int XtCacheType;
#define XtCacheNone 0x001
#define XtCacheAll 0x002
#define XtCacheByDisplay 0x003
#define XtCacheRefCount 0x100
See AlsoXtAppReleaseCacheRefs(1), XtCallbackReleaseCacheRef(1), XtCallbackRe‐
leaseCacheRefList(1), XtCallConverter(1), XtConvertAndStore(1), XtSet‐
TypeConverter(1),
XtConvertArgProc(2), XtDestructor(2), XtTypeConverter(2).
Xt - Resource Management XtAppSetTypeConverter()
