XtConvertArgProc()XtConvertArgProc()NameXtConvertArgProc - interface definition for procedure to obtain an
argument for a resource converter.
Synopsis
typedef void (*XtConvertArgProc)(Widget, Cardinal *, XrmValue *);
Widget object;
Cardinal *size;
XrmValue *value_return;
Inputs
object Specifies the object for which the resource is being con‐
verted, or NULL if the converter was invoked by XtCallCon‐
verter() or XtDirectConvert(). May be of class Object or
any subclass thereof.
size Specifies a pointer to the size field from the XtConvertAr‐
gRec structure.
Outputs
value_return
Returns the address and size of the argument.
Availability
Release 4 and later.
Description
A procedure of type XtConvertArgProc gets an argument needed when call‐
ing a resource converter. It is registered in the address_id field of
an XtConvertArgRec structure with the address_mode field XtProce‐
dureArg. This XtConvertArgRec structure must be part of an XtConver‐
tArgList array which is registered with a converter procedure with
XtAppSetTypeConverter(), XtSetTypeConverter(), or XtAppAddConverter().
When invoked, the XtConvertArgProc procedure must derive its argument
value (generally from the specified object) and store the address and
size of the value in the XrmValue structure pointed to by its
value_return argument. The size argument is not assigned any meaning
by the Intrinsics, and can be used like client_data to a callback pro‐
cedure, if desired.
To permit re-entry, XtConvertArgProc should return the address of stor‐
age whose lifetime is no shorter than the lifetime of object. If
object is NULL, the lifetime of the conversion argument must be no
shorter than the lifetime of the resource with which the conversion
argument is associated. The Intrinsics do not guarantee to copy this
storage, but they do guarantee not to reference it if the resource is
removed from the conversion cache.
If the XtConvertArgProc modifies the resource database, the changes
affect any in-progress widget creation or XtGetApplicationResources()
or XtGetSubresources() calls in an implementation-defined manner.
Insertion of new entries into the database and modification of existing
entries is allowed, however, and will not directly cause an error.
See XtAppSetTypeConverter() for an explanation of how to declare an
XtConvertArgList which will invoke an XtConvertArgProc.
Example
The XtConvertArgProc used by the Intrinsics String-to-Cursor converter
is shown below, along with the XtConvertArgList that registers it. It
looks up the Display * of the specified widget, and places its address
(a Display **) in value->addr. (Note that DisplayOfScreen() is a
macro, so the ampersand before it is legal.)
/*ARGSUSED*/
static void FetchDisplayArg(widget, size, value)
Widget widget;
Cardinal *size;
XrmValue* value;
{
if (widget == NULL)
XtErrorMsg("missingWidget", "fetchDisplayArg", XtCXtToolkitError,
"FetchDisplayArg called without a widget to reference",
(String*)NULL, (Cardinal*)NULL);
/* can't return any useful Display and caller will de-ref NULL,
so aborting is the only useful option */
value->size = sizeof(Display*);
value->addr = (XPointer)&DisplayOfScreen(XtScreenOfObject(widget));
}
static XtConvertArgRec Const displayConvertArg[] = {
{XtProcedureArg, (XtPointer)FetchDisplayArg, 0},
};
The String-to-Cursor converter could now be registered with a call like
the following. Given the displayConvertArg array defined above, that
converter would be invoked with args[0].addr, the address of the Dis‐
play pointer that the converter should use.
XtSetTypeConverter(XtQString, XtQCursor, CvtStringToCursor,
displayConvertArg, XtNumber(displayConvertArg),
XtCacheByDisplay, FreeCursor);
See AlsoXtAppSetTypeConverter(1), XtAppAddConverter(1), XtSetTypeConverter(1),
XtTypeConverter(2).
Xt - Resource Management XtConvertArgProc()
