XtGetValues() XtGetValues()
Name
XtGetValues - query widget resource values.
Synopsis
void XtGetValues(object, args, num_args)
Widget object;
ArgList args;
Cardinal num_args;
Inputs
object Specifies the object whose resource values are to be returned; may be of class Object or any subclass thereof.
args Specifies the argument list of name/address pairs that contain the resource names and the addresses into which the resource val-
ues are to be stored.
num_args Specifies the number of arguments in the argument list.
Description
XtGetValues() retrieves the current values of one or more resources associated with a widget instance. Each element in args is an Arg
structure which contains the resource name in the name field, and a pointer to the location at which the resource is to be stored in the
value field. It is the caller's responsibility to ensure that the value field points to a value of the correct type. If the value field
points to allocated memory, the caller is also responsible for freeing that memory.
If args contains a resource name that is not found in any of the resource lists searched, the value at the corresponding address is not
modified.
Many widget resource values are simply copied from the widget to the specified address. When the resource is a pointer type (such as a
string or pointer to a structure) some widgets will make a copy of the pointed to value and store the address of this copy at the specified
address. If a copy is made, the caller is responsible for freeing the value when done with it. If no copy is made, then the returned
value points to memory owned by the widget, and the caller must not modify or free this value in any way. None of the Intrinsics defined
classes copy values in this way, nor do widgets in the Athena Widget set. See the documentation for the particular resource of the partic-
ular widget you are using to determine if a copy is made.
If a resource value which is a pointer type is returned without being copied, then the returned value may not remain valid indefinitely.
The Intrinsics specify lifetimes for the following resources: The XtNchildren resource of Composite widgets and any callback list resource
are only valid until some operation (such as XtCreateWidget() or XtAddCallback()) modifies the resource. The XtNtranslations and XtNaccel-
erators Core resources remain valid at least until the widget is destroyed. The XtNscreen Core resource remains valid until the Display is
closed. See the documentation for the particular resource of the particular widget you are using to determine its lifetime.
The "Background" section below explains in detail how XtGetValues() finds the requested resource values.
Usage
Generally you will use the XtSetArg() macro to initialize the ArgList passed to this function. You can also use XtVaGetValues() pass it a
variable-length argument list instead of an ArgList array. The "Example" section below shows an example use of this function.
Note that some widgets provide public functions to query the value of commonly used resources. These functions are generally faster, and
it is usually better specified whether or not the caller must free the returned value.
You can set a widget's resources with XtSetValues() or XtVaSetValues().
Example
You can use XtGetValues() as follows to get widget resources:
Arg args[10];
int i;
String label;
Dimension margin;
Pixel color;
/* set up an argument list */
i = 0;
XtSetArg(args[i], XtNlabel, &label); i++;
XtSetArg(args[i], XtNmargin, &margin); i++;
XtSetArg(args[i], XtNforeground, &color); i++;
/* query the values */
XtGetValues(s, args, i);
/* label, margin, and color now contain the requested values */
printf("Widget's label is %s; margin is %d.0, label, margin);
printf("Widget's label is %s; margin is %d.0, label, margin);
/* In some widget sets we'd have to free label now. */
/* XtFree(label); */
Background
XtGetValues() looks for resources named in args using the following procedure:
o It searches the normal resource lists for the object, starting with the resources of the Object class and proceeding down the subclass
chain to the class of the object.
o If the object's parent is a subclass of constraintWidgetClass, it searches the constraint resource lists of the parent, starting at con-
straintWidgetClass and proceeding down the subclass chain to the constraint resources of the parent's class.
Once all the resources have been fetched from the widget's normal and constraint resources list, XtGetValues() calls the widget's get_val-
ues_hook() methods. get_values_hook() procedures can be used to return subpart resource values or constraint subpart resource values
through the XtGetValues() interface (see XtGetSubvalues()) and may modify the data stored at the location addressed by the value field of
the argument. This means that a get_values_hook() may be used to make copies of data (such as strings) whose resource representation is a
pointer. The get_values_hook() methods are called as follows:
o If any get_values_hook() methods in the object's class or superclass records are non-NULL, they are called in superclass-to-subclass
order.
o If the object's parent is a subclass of constraintWidgetClass, and if any of the parent's class or superclass records have declared Con-
straintClassExtension records in the Constraint class part extension field with a record type of NULLQUARK and if the get_values_hook()
field in the extension record is non-NULL, then XtGetValues() calls these get_values_hook() procedures in superclass-to-subclass order.
Structures
An Arg is defined as follows:
typedef struct {
String name;
XtArgVal value;
} Arg, *ArgList;
See Also
XtSetArg(1), XtSetValues(1), XtVaGetValues(1), XtVaSetValues(1),
get_values_hook(4).
Xt - Resource Management XtGetValues()