XtConverter(3x) — HP-UX 9.10

NAME

XtConverter − interface definition for old-style resource converter.

Synopsis

typedef void (*XtConverter)(XrmValue *, Cardinal *, XrmValue *,
XrmValue *);

    XrmValue *args;
    Cardinal *num_args;
    XrmValue *from;
    XrmValue *to_return;

Inputs

argsSpecifies an array of additional XrmValue arguments to the converter if additional context is needed to perform the conversion, or NULL.

num_argsSpecifies the number of arguments in args.

fromSpecifies the address and size of the value to convert.

Outputs

to_returnReturns the address and size of the converted value.

Description

An XtConverter is an old-style resource converter, registered with XtAppAddConverter(), and invoked automatically by the Intrinsics to convert resources of the appropriate type, or invoked directly with XtConvertAndStore() or XtDirectConvert(). An XtConverter should perform the following actions:

•Check to see that the number of arguments passed is correct.

•Attempt the type conversion.

•If successful, return the address and size of the converted value in the to_return argument, otherwise, call XtWarningMsg() or XtStringConversionWarning() and return without modifying to_return. Most type converters just take the data described by the specified from argument and return data by writing into the to_return argument. A few need other information, such as a display or screen pointer. These converters can be registered with an XtConvertArgList which will cause the Intrinsics to compute an argument list for the converter before invoking it. See XtAppSetTypeConverter() for information on declaring XtConvertArgList arrays. Note that the address written in to_return->addr cannot be that of a local variable of the converter because this is not valid after the converter returns. It should be the address of a static variable.

Usage

An XtConverter is an "old-style" resource converter. In Release 4, the "new-style" resource converter XtTypeConverter was defined. There are still existing old-style converters in use, but if you are going to write a new converter, you should write an XtTypeConverter instead of an XtConverter. See XtTypeConverter(2) for more information. Note that the num_args argument is a pointer to the number of elements in args, and not the number of arguments itself. Be sure to dereference this argument correctly before using it.

Example

The following procedure is a modified version of the String-to-Justification converter from the Xmu library:

/* ARGSUSED */
void
XmuCvtStringToJustify(args, num_args, fromVal, toVal)
    XrmValuePtr args;           /* unused */
    Cardinal    *num_args;      /* unused */
    XrmValuePtr fromVal;
    XrmValuePtr toVal;
{
    static XtJustify    e;
    static XrmQuark     XrmQEleft;
    static XrmQuark     XrmQEcenter;
    static XrmQuark     XrmQEright;
    static int          haveQuarks = 0;
    XrmQuark    q;
    char        *s = (char *) fromVal->addr;
     if (s == NULL) return;
    if (!haveQuarks) {
        XrmQEleft   = XrmPermStringToQuark(XtEleft);
        XrmQEcenter = XrmPermStringToQuark(XtEcenter);
        XrmQEright = XrmPermStringToQuark(XtEright);
        haveQuarks = 1;
    }
     if (q == XrmQEleft)        e = XtJustifyLeft;
    else if (q == XrmQEcenter) e = XtJustifyCenter;
    else if (q == XrmQEright) e = XtJustifyRight;
    else {
        XtStringConversionWarning(s, XtRJustify);
        return;
    }
     toVal->size = sizeof(XtJustify);
    toVal->addr = (caddr_t) &e;
}

Structures

The XrmValue structure is defined as follows:

typedef struct {
unsigned int size;
XPointer addr;
} XrmValue, *XrmValuePtr;

Museum

Related Articles