DataGroup Object Class

Overview

• group data objects in a hierarchical relationship
• determine the maximum/minimum range of all data in the group (e.g., for axis scaling).
• find and retrieve specific objects in the group

A set of function calls can be used to manipulate ranges of data within specified arrays or individual data points in any array. You can also extend, replace, or shift data in an array.

• The class pointer is xintDataGroupObjectClass.
• The class name is XintDataGroup.
• The header file is included as <Xint/DataGroup.h>.

The minimum/maximum limits are defined through the data structure XintLimits, which takes the following form:

   typedef struct {
                   float      minimum;
                   float      maximum;
   } XintLimits;

where:

Member	Description
minimum	Minimum value of data in the group.
maximum	Maximum value of data in the group.

Callback Structure

   typedef struct {
                   int         reason;
                   XEvent      *event;
                   Object      object;
                   union {
                          XintDataUpdateCallbackStruct        *data;
                          XintDataSampledUpdateCallbackStruct *sampled;
                          XintDataSeriesUpdateCallbackStruct  *series;
                          XintDataGridUpdateCallbackStruct    *grid;
                   } callback_struct;
   } XintDataGroupUpdateCallbackStruct;

This particular callback is especially convenient because it provides notification of updates to any child of the group, regardless of the data object type. Callback XmNupdateCallback and update callbacks structures are also provided for each separate data object type (e.g., XintDataSeriesUpdateCallbackStruct), but it is more convenient to use a single callback for the whole group than trying to install update notification for each member of the group.

The callback indicates which type of object was modified and why. This information can help optimize the redrawing and updating of the window. The following ordered table lists members of XintDataGroupUpdateCallbackStruct in their required sequence:

Data Type	Member	Description
int	reason	Indicates why the callback was invoked (see discussion below).
XEvent *	event	Standard member of a Motif callback structure not used in this context (will always be NULL).
Object	object	ID of the updated object.
XintDataLabelCallbackStruct *	label	Indicates what update was performed if object is a DataLabel object..
XintDataSampledUpdateCallbackStruct *	sampled	Indicates what update was performed if object is a DataSampled object.
XintDataSeriesUpdateCallbackStruct *	series	Indicates what update was performed if object is a DataSeries object.
XintDataGridUpdateCallbackStruct *	grid	Indicates what update was performed if object is a DataGrid object.

The callback structure includes information explaining the reason why a particular update occurred. The possible reasons returned by this callback are:

Reason	Description
XintCR_DATA_BATCH	A batch update has been performed and any number of changes on the objects in the group could have happen. No information about the changes is available in the callback structure.
XintCR_DATA_GROUP_INSERT_CHILD	Child was inserted using the XmNDataGroup resource of the child. The ID of the data object that was inserted is set in member object.
XintCR_DATA_GROUP_DELETE_CHILD	Child was deleted through external command (e.g., XtDestroy). The ID of the data object that was destroyed is set in member object.
XintCR_DATA_GROUP_UPDATE_CHILD	Child object was updated. Information about the type of update is available in callback structure (use member label if object is a DataLabel, use member sampled if object is a DataSampled, etc.)

Functions

Function Name	Description
XintCreateDataGroup	Creates a data group.
XintDataBatchUpdate	To turn on/off propagation of updates to views.
XintDataRangeX	Determines the total range of data in the X direction.
XintDataRangeY	Determines the total range of data in the Y direction.
XintDataRangeZ	Determines the total range of data in the Z direction.
XintDataGroupFind	Finds a data object of a certain name in a data group.
XintDataGroupIterate	Retrieves the nth data object of a specified class from a data group.

     Object XintCreateDataGroup (...)

Widget	parent	Name of the parent DataObject widget containing this new data group.
char *	name	Name of the new data group.
ArgList	arglist	List of resources to be set for the new data group.
Cardinal	argcount	Total number of resources set by arglist.

     Object XintDataBatchUpdate (...)

Object	data	ID of the data object (usually a data group).
Boolean	state	Set to True to freeze updates. Set to False to allow updates.

   Boolean XintDataRangeX (...)
   Boolean XintDataRangeY (...)
   Boolean XintDataRangeZ (...)

Object	object	Object ID of the data group to be examined.
float	minimum	Minimum value in the data range.
float	maximum	Maximum value in the data range.

     Object XintDataGroupFind (...)

Object	object	Object ID of the data group to be searched.
char *	name	Name of object to be found.
Object	context	Normally NULL, but can be used to search for multiple objects with the same name (e.g., if called with NULL and return value is not NULL, it uses the return value as the context argument of the next call).

     Object XintDataGroupIterate (...)

Object	object	ID of the data group.
ObjectClass	data_class	Class name of the data object class to be retrieved (e.g., xintDataSampledObjectClass). Specify NULL to retrieve data objects from any type.
int	index	Index number of the data object to be retrieved.

Macros

     Boolean XintIsDataGroup (Object object)