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()