get_values_hook()get_values_hook()Nameget_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 exam‐
ples below. When using objects rather than subparts, it is also possi‐
ble 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 AlsoXtGetSubvalues(1), XtGetValues(1),
Core(3).
Xt - Intrinsics Methods get_values_hook()
