XtAppSetTypeConverter() XtAppSetTypeConverter()
Name
XtAppSetTypeConverter - register a "new-style" type converter in a single 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 deallo-
cate resources produced by converter.
Availability
Release 4 and later.
Description
XtAppSetTypeConverter() registers converter in 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.
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 qualifier XtCacheRefCount can be ORed with any of these values and specifies that references to cached values produced by this con-
verter 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.
Usage
XtAppSetTypeConverter() 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 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 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);
Background
Specifying Arguments to a Converter
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.
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 con-
verter 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(), XtCre-
ateManagedWidget(), 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 Also
XtAppReleaseCacheRefs(1), XtCallbackReleaseCacheRef(1), XtCallbackReleaseCacheRefList(1), XtCallConverter(1), XtConvertAndStore(1), XtSet-
TypeConverter(1),
XtConvertArgProc(2), XtDestructor(2), XtTypeConverter(2).
Xt - Resource Management XtAppSetTypeConverter()