XtConvertArgProc() XtConvertArgProc()
Name
XtConvertArgProc - 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 converted, or NULL if the converter was invoked by XtCallConverter() or
XtDirectConvert(). May be of class Object or any subclass thereof.
size Specifies a pointer to the size field from the XtConvertArgRec 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 calling a resource converter. It is registered in the address_id field
of an XtConvertArgRec structure with the address_mode field XtProcedureArg. This XtConvertArgRec structure must be part of an XtConvertAr-
gList 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 procedure, if desired.
To permit re-entry, XtConvertArgProc should return the address of storage 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 Display pointer that the converter should use.
XtSetTypeConverter(XtQString, XtQCursor, CvtStringToCursor,
displayConvertArg, XtNumber(displayConvertArg),
XtCacheByDisplay, FreeCursor);
See Also
XtAppSetTypeConverter(1), XtAppAddConverter(1), XtSetTypeConverter(1),
XtTypeConverter(2).
Xt - Resource Management XtConvertArgProc()