XtVaSetValues() XtVaSetValues()
Name
XtVaSetValues - set resource values for a widget, using varargs argument style.
Synopsis
void XtVaSetValues(object, ..., NULL)
Widget object;
Inputs
object Specifies the object whose resources are to be modified; may be of class Object or any subclass thereof.
..., NULL A NULL-terminated variable-length list of resource name/value pairs to override any other resource specifications.
Availability
Release 4 and later.
Description
XtVaSetValues() sets the resources of object named in the variable-length argument list to the values specified in the same list. It is
identical to XtSetValues() except that the args array of resource names and values and the num_args argument of that function are replaced
with a NULL-terminated variable-length argument list.
The "Background" section below explains how to specify resource names and values in a variable-length argument list. See XtSetValues() for
more information on setting widget resources.
Usage
Using variable-length argument lists is usually much more convenient than passing an ArgList which must be declared and initialized. Note
that the varargs interface is less efficient than the ArgList interface, because each varargs function converts its argument list into an
ArgList and calls the corresponding ArgList function. Unless you are setting or querying resources repeatedly, however, this overhead is
not generally significant.
Variable-length argument lists cannot be type-checked by the compiler, and so using XtVaSetValues() and other varargs functions can be a
source of bugs. Be sure to end all of your argument lists with NULL, and be sure that the type of each argument is as expected. If you
specify only a single name/value pair per line, it will be easy to delete or comment out resources, and to insert new resources at an
acceptable place.
Example
You can use XtVaSetValues() as in the following example:
XtVaSetValues(w,
XtNlabel, "Enter a value:",
XtNjustify, XtJustifyRight,
XtVaTypedArg, XtNforeground, XtRString, "red", 4,
NULL);
Background
This function and the other XtVa functions have resource names and values specified in a NULL-terminated variable-length argument list,
rather than an ArgList array. Generally, the argument list to these functions will consist of resource names (of type String) followed by
resource values (these are of type XtArgVal, but because varargs lists cannot be type-checked, you do not have to cast your values). There
are two special symbols which can be used in place of a resource name, however. Each symbol modifies the interpretation of the following
arguments.
XtVaNestedList
If you specify a resource name of XtVaNestedList, the following argument will be interpreted as an XtVarArgsList value, as returned by
XtVaCreateArgsList(). The resource names and values on this nested list will be treated exactly as if they were specified at the current
point in the original list. Nested lists may contain other nested lists, to any depth of nesting.
XtVaTypedArg
If you specify a resource name of XtVaTypedArg, then the following four arguments will be interpreted specially as instructions to invoke
a resource converter and set a resource to the result of the conversion. The first following argument is the name of the resource to be
set, and must be of type String. The second following argument is also a String, the resource type of the following value. This type,
plus the type of the named resource identify the resource converter to be invoked. This argument is usually XtRString, or one of the
other XtR types predefined by the Intrinsics. The third following argument is the value to be converted. It is of the type specified by
the previous argument, usually a String. If the type is not XtRString, then if the value fits in an XtArgVal, it is passed directly in
the argument list, otherwise a pointer to the value is passed. Finally, the forth following argument is the size in bytes of the type.
If the type is XtRString, however, then type should be the length of the string plus one, not sizeof(String).
The example above show a use of the XtVaTypedArg value. See XtVaCreateArgsList() for an example of XtVaNestedList.
See Also
XtSetValues(1), XtVaCreateArgsList(1).
Xt - Resource Management XtVaSetValues()