xtgetsubvalues(1) [hpux man page]
XtGetSubvalues() XtGetSubvalues()
Name
XtGetSubvalues - copy resource values from a subpart data structure to an argument list.
Synopsis
void XtGetSubvalues(base, resources, num_resources, args, num_args)
XtPointer base;
XtResourceList resources;
Cardinal num_resources;
ArgList args;
Cardinal num_args;
Inputs
base Specifies the base address of the subpart data structure for which the resources should be retrieved.
resources Specifies the subpart resource list.
num_resources
Specifies the number of resources in the resource list.
args Specifies an array of name/address pairs that contain 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.
Description
For each argument in args, XtGetSubvalues() uses the argument name field to look up the resource in resources, and uses the information in
that resource structure to copy the resource value from the subpart structure pointed to by base to the location specified by the argument
value field.
If the argument list contains a resource name that is not found in the resources, the memory pointed to by the argument value field will
not be modified.
The value field of each element in args must contain the address into which to store the corresponding resource value. It is the caller's
responsibility ensure that there is enough memory at the given location for the requested resource, and to free this memory if it was
dynamically allocated.
See XtGetApplicationResources() for a description of the various fields of a XtResource structure and an example of initializing an XtRe-
sourceList.
Usage
XtGetSubvalues() is normally called in the get_values_hook() method of a widget with a subpart in order to get the values of requested sub-
part resources that cannot be automatically fetched by the widget. See XtSetSubvalues() for more information.
Note that an application cannot call XtGetSubvalues() for a widget because it does not have access to a widget's subpart resource list.
To set a widget's subpart resource values, see XtSetSubvalues().
See XtGetSubresources() for more explanation of subpart resources.
To get subpart resource values using a variable-length argument list rather than a single ArgList array, use XtVaGetSubvalues().
Structures
XtResource is defined as follows:
typedef struct _XtResource {
String resource_name; /* Resource name */
String resource_class; /* Resource class */
String resource_type; /* Representation type desired */
Cardinal resource_size; /* Size in bytes of representation */
Cardinal resource_offset;/* Offset from base to put resource value */
String default_type; /* Representation type of specified default */
XtPointer default_addr; /* Address of resource default value */
} XtResource, XtResourceList;
See XtGetApplicationResources() for an explanation of the fields of this structure.
An Arg is defined as follows:
typedef struct {
String name;
XtArgVal value;
} Arg, *ArgList;
See Also
XtGetSubresources(1), XtVaGetSubvalues(1),
get_values_hook(4).
Xt - Resource Management XtGetSubvalues()
Check Out this Related Man Page
XtGetSubresources() XtGetSubresources()
Name
XtGetSubresources - get subpart values from the resource database.
Synopsis
void XtGetSubresources(object, base, subpart_name, subpart_class, resources, num_resources, args, num_args)
Widget object;
XtPointer base;
String subpart_name;
String subpart_class;
XtResourceList resources;
Cardinal num_resources;
ArgList args;
Cardinal num_args;
Inputs
object Specifies the object used to qualify the subpart resource name and class; may be of class Object or any subclass thereof.
base Specifies the base address of the subpart data structure into which the resource values will be written.
subpart_name
Specifies the resource name of the subpart.
subpart_class
Specifies the resource class name of the subpart.
resources Specifies the resource list for the subpart.
num_resources
Specifies the number of resources in the resource list.
args Specifies the argument list to override any other resource specifications.
num_args Specifies the number of arguments in the argument list.
Outputs
base Returns the resource values from the argument list, the resource database, or the resource list defaults.
Description
XtGetSubresources() is similar to XtGetApplicationResources(). It retrieves resource values for "subparts" of a widget or object that are
not themselves widgets or objects. For each resource in resources, XtGetSubresources() sets a value in the structure pointed to by base.
This value comes from the argument list args, or if no value for the resource is found in the argument list, from the resource database
associated with object, or if no value is found in the database, from the default_addr field of the resource itself. Once the value is
determined, it is copied into the structure at base using the resource_offset and resource_size fields of the resource.
The database is searched for resources that appear beneath the specified object in the name hierarchy-subpart resources should be specified
in a database as if as if the subpart were a child object, with name subpart_name and class subpart_class.
XtGetSubresources() may overwrite the specified resource list with an equivalent representation in an internal format that optimizes access
time if the list is used repeatedly. The resource list must be allocated in writable storage and the caller must not modify the list con-
tents after the call if the same list is to be used again. Any per-display resources fetched by XtGetSubresources() will not be freed from
the resource cache until the display is closed.
See XtGetApplicationResources() for an explanation and example of how to create a resource list.
Usage
Using subparts in a widget or object can be a useful way to modularize that object. The Release 3 Athena Text widget, for example, had
subparts for its data source and data sink. In Release 4 and later, however, it is often easier to use non-widget objects instead of sub-
parts. The Athena Text widget now uses this approach.
If you use subpart resources, the user will see the subpart hierarchy and will automatically be able to set subpart resources from a
resource file. To allow the user to set and query subpart resources using the standard C XtSetValues()/XtGetValues() interface, however,
your widget's set_values() (or set_values_hook() prior to Release 4) method must call XtSetSubvalues() and your get_values_hook() method
must call XtGetSubvalues(). An alternative is to provide public functions with your widget to set and query subpart values.
Note that XtGetSubresources() differs from XtGetApplicationResources() in that it looks for resources in a named "subpart" of object,
rather than resources that appear at the same level in the hierarchy as object's own resources.
You can use XtVaGetSubresources() to get subpart resource values using a variable length argument list rather than a single ArgList argu-
ment.
Structures
XtResource is defined as follows:
typedef struct _XtResource {
String resource_name; /* Resource name */
String resource_class; /* Resource class */
String resource_type; /* Representation type desired */
Cardinal resource_size; /* Size in bytes of representation */
Cardinal resource_offset;/* Offset from base to put resource value */
String default_type; /* Representation type of specified default */
XtPointer default_addr; /* Address of resource default value */
} XtResource, XtResourceList;
An Arg is defined as follows:
typedef struct {
String name;
XtArgVal value;
} Arg, *ArgList;
See Also
XtGetApplicationResources(1), XtGetSubvalues(1), XtSetSubvalues(1), XtVaGetSubresources(1),
get_values_hook(4), set_values(4).
Xt - Resource Management XtGetSubresources()