XtGetValues()XtGetValues()NameXtGetValues - 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 con‐
tain the resource names and the addresses into which the
resource values are to be stored.
num_args Specifies the number of arguments in the argument list.
DescriptionXtGetValues() 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 particular 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 XtNchil‐
dren resource of Composite widgets and any callback list resource are
only valid until some operation (such as XtCreateWidget() or XtAddCall‐
back()) modifies the resource. The XtNtranslations and XtNaccelerators
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 "Exam‐
ple" 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); */
BackgroundXtGetValues() looks for resources named in args using the following
procedure:
· 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.
· If the object's parent is a subclass of constraintWidgetClass, it
searches the constraint resource lists of the parent, starting at
constraintWidgetClass 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 argu‐
ment. 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:
· 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.
· If the object's parent is a subclass of constraintWidgetClass, and
if any of the parent's class or superclass records have declared
ConstraintClassExtension records in the Constraint class part exten‐
sion field with a record type of NULLQUARK and if the get_val‐
ues_hook() field in the extension record is non-NULL, then XtGetVal‐
ues() calls these get_values_hook() procedures in superclass-to-sub‐
class order.
Structures
An Arg is defined as follows:
typedef struct {
String name;
XtArgVal value;
} Arg, *ArgList;
See AlsoXtSetArg(1), XtSetValues(1), XtVaGetValues(1), XtVaSetValues(1),
get_values_hook(4).
Xt - Resource Management XtGetValues()
