hpux man page for get_values_hook

get_values_hook()														 get_values_hook()

Name
  get_values_hook - Object class method for obtaining values of resources that do not appear in the resource list.

Synopsis
  typedef void (*XtArgsProc)(Widget, ArgList, Cardinal *);
	 Widget w;
	 ArgList args;
	 Cardinal *num_args;

Inputs
  w	    Specifies the widget or object that is having its resources queried.

  args	    Specifies the argument list that was passed to XtGetValues().

  num_args  Specifies the number of arguments in the argument list.

Description
  The get_values_hook() method is registered on the get_values_hook field of the Object, RectObj, or Core class part structure, and is called
  by XtGetValues() to give the widget a chance to supply the value of any resources that do not appear in  the	widget's  resource  list  (by
  calling XtGetSubvalues() on a subpart, for example) or to modify any of the returned values.

  The  get_values_hook()  method  is  chained  in  superclass-to-subclass  order,  and	cannot	be  inherited.	 Classes  that	do not need a
  get_value_hook() method should specify NULL in the get_values_hook field of their class structure.

  See XtGetValues(1) for more information on when this method is invoked.

Usage
  If a widget or object has subparts with resources that do not appear in the resource list of the object itself, it  can  use	the  get_val-
  ues_hook()  method to call XtGetSubvalues() passing a pointer to the subpart, the subpart resource list, and the args and num_args argument
  list.  Using this technique, the application programmer will be able to query the value of subpart resources as if they were normal  widget
  resources.

  Note	that  since the Object class was added in Release 4, it is often easier to use objects rather than subparts, because objects get more
  automatic resource handling by the Intrinsics than subparts do.  A get_values_hook() procedure is not limited to calling  XtGetSubvalues();
  it  can call XtGetValues() on a widget or object, as shown in the examples below.  When using objects rather than subparts, it is also pos-
  sible to give the application programmer direct control over creating those objects.	If the programmer keeps  a  pointer  to  the  created
  object, then she can directly set and query the resource values of the object, and no get_values_hook() is necessary in the parent.

  The get_values_hook() method can also be used to modify the resource values in args that would otherwise be returned to the user.  A widget
  that displays a string, for example, might want to return a copy of that string to the programmer rather than the string itself, so that if
  the  programmer  modifies the string, the widget will not be affected.  Widgets that use the get_values_hook() method in this way should be
  sure to document which resources are copied in this way and must be freed by the user.  (None of the Intrinsics widgets nor the Xaw widgets
  do this.)

  Note that the get_values_hook() method is not obsolete as are the other hook methods, initialize_hook() and set_values_hook().

Example
  The two procedures below are the get_values_hook() methods of the Xaw Dialog and Xaw Text widget classes.  Note that both use XtGetValues()
  to obtain resources of a child widget or object, which they "export" as one of their own resources.

  The Dialog method checks the incoming argument list for a resource named XtNvalue, and only queries the child  for  that  single  resource.
  The Text method simply passes the entire argument list in XtGetValues() calls to two different child objects.  This method assumes that the
  Text widget and its two children objects do not have any resources by the same name, so there is not potential  for  name  conflicts.   The
  Text	widget	controls  the  types  of  its  subobjects,  so this is a reasonable assumption.  Since all objects have an XtNdestroyCallback
  resource, however, if you were to query the value of this resource for the Text widget, you would get the callback  list  for  one  of  its
  internal  objects  instead.	(This  is not a practical problem because the callback list is in an internal compiled form and should not be
  queried anyway.)

     static void
     GetValuesHook(w, args, num_args)
     Widget w;
     ArgList args;
     Cardinal * num_args;
     {
       Arg a[1];
       String s;
       DialogWidget src = (DialogWidget) w;
       register int i;

       for (i=0; i < *num_args; i++)
	 if (streq(args[i].name, XtNvalue)) {
	   XtSetArg(a[0], XtNstring, &s);
	   XtGetValues(src->dialog.valueW, a, 1);
	   *((char **) args[i].value) = s;
	 }
     }

     static void
     GetValuesHook(w, args, num_args)
     Widget w;
     ArgList args;
     Cardinal * num_args;
     {
       XtGetValues( ((TextWidget) w)->text.source, args, *num_args );
       XtGetValues( ((TextWidget) w)->text.sink, args, *num_args );
     }

See Also
  XtGetSubvalues(1), XtGetValues(1),
  Core(3).

Xt - Intrinsics Methods 													 get_values_hook()