DataSampled Object Reference

DataSampled Object Class

Overview

The DataSampled object class is used to manipulate a one-dimensional array of values. For instance, a DataSampled object may appear as a row or column of data in a table, a series of bars in a bar chart, a plotted line in a graph and so forth. The type of data contained in a DataSampled Object can be float, short, integer, long, or double.

When the one-dimensional array is viewed in a two-dimensional context such as a chart, the second dimension (or implied direction) is generated from a start and an increment which are specified using resource XmNrange.

Example

The following example shows programming code used to define a typical DataSampled object.

   static int population[] = {142000, 256000, 320000, 340000}
   Object population_data;
   XintRange range;
   ...
   range.start = 1990;
   range.increment =1;
   population_growth = (Object) XtVaCreateWidget("population"),
                                    (WidgetClass) xintDataSampledObjectClass,
                                    parent,
                                    XmNdataArray, population,
                                    XmNdataType, XintDATA_TYPE_INTEGER,
                                    XmNsampledRange, &range,
                                    XmNdataGroup, data_group,
                                    NULL);

Inherited Resources and Behavior

The DataSampled object class does not inherit behavior and resources from any other object class.

The class pointer is xintDataSampledObjectClass.
The class name is XintDataSampled.
The header file is included as <Xint/DataSampled.h>.

The following resources can be defined for the DataSampled object class:
Name	Type	Default	Access
XmNcopyData	Boolean	True	CSG
XmNcount	int	0	CSG
XmNdataArray	XtPointer	NULL	CSG
XmNdataGroup	Object	NULL	CSG
XmNdataType	int	XintDATA_TYPE_FLOAT	CSG
XmNeditable	Boolean	True	CSG
XmNlastViewDestroy	Boolean	True	CSG
XmNsampledRange	XintRange *	NULL	CSG
XmNupdateCallback	XtCallbackList	NULL	CSG

Resource Value Description
XintDATA_TYPE_FLOAT Data type is float (default).
XintDATA_TYPE_SHORT Data type is short.
XintDATA_TYPE_INTEGER Data type is integer.
XintDATA_TYPE_LONG Data type is long.
XintDATA_TYPE_DOUBLE Data type is double.

Resource Value	Description
XintDATA_TYPE_FLOAT	Data type is float (default).
XintDATA_TYPE_SHORT	Data type is short.
XintDATA_TYPE_INTEGER	Data type is integer.
XintDATA_TYPE_LONG	Data type is long.
XintDATA_TYPE_DOUBLE	Data type is double.

XmNeditable

Specifies whether or not this data series can be edited when displayed in a view.

XmNlastViewDestroy

Specifies whether or not to automatically destroy this data object when there are no more views connected to the data. If this data object is inserted into a DataGroup, you only need to set this resource for the DataGroup object.

XmNsampledRange

Specifies the start and increment used to generate the implied direction. This is particularly useful for axis scaling in a chart view. If this resource is not specified, the start is assumed to be 0 and the increment 1.

This resource is specified as a pointer to a data structure of type XintRange, which takes the following form:

   typedef struct {
                   float start;
                   float increment;
   } XintRange;

where:

Member Description
start Minimum value.
increment Increment.

Member	Description
start	Minimum value.
increment	Increment.

XmNupdateCallback

This resource allows you to attach a callback to the object, as described in the following section.

Callback

The callback XmNupdateCallback provides notification of changes in sampled data objects. As for any widget, you can register callbacks using the Xt function XtAddCallback. The callback structure takes the following form:

   typedef struct {
                   int reason;
                   XEvent *event;
                   Object object;
                   int start;
                   int count;
                   float minimum;
                   float maximum;
   } XintDataSampledUpdateCallbackStruct;

This callback is specific to the DataSampled object and must be registered for each separate data object in a group. If you prefer to monitor updates at the group level, you should register callback XmNupdateCallback only for the DataGroup object and use the XintDataGroupUpdateCallbackStruct discussed earlier in this manual.

The DataSampled update callback contains information that indicates why and how the object was modified. The following ordered table lists the members of XintDataSampledUpdateCallbackStruct in their required sequence:

Data Type Member Description
int reason Indicates why the callback was invoked (see table 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.
int start Starting index of the data updated (starts at 0).
int count Number of items updated.
float minimum New minimum value of the object.
float maximum New maximum value of the object.

Data Type	Member	Description
int	reason	Indicates why the callback was invoked (see table 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.
int	start	Starting index of the data updated (starts at 0).
int	count	Number of items updated.
float	minimum	New minimum value of the object.
float	maximum	New maximum value of the object.

The callback structure includes information explaining the reason why a particular update occurred.

Reason Description
XintCR_DATA_UPDATE
XintCR_DATA_BATCH Entire data array has been changed, no more information is available.
XintCR_DATA_REPLACE Data was replaced in the object. (as specified by start and count).
XintCR_DATA_EXTEND Data was added to the object (count values were added).
XintCR_DATA_SHIFT Data was shifted in the object (count values were shifted).

Reason	Description
XintCR_DATA_UPDATE XintCR_DATA_BATCH	Entire data array has been changed, no more information is available.
XintCR_DATA_REPLACE	Data was replaced in the object. (as specified by start and count).
XintCR_DATA_EXTEND	Data was added to the object (count values were added).
XintCR_DATA_SHIFT	Data was shifted in the object (count values were shifted).

Functions

The following functions are defined for creating, updating or retrieving information regarding a particular sampled data object.

Function Name Description
XintCreateDataSampled Creates a DataSampled object.
XintDataSampledDataExtend Extends the data in a sampled array.
XintDataSampledGetDataArray Returns part of the data array and converts it to float.
XintDataSampledGetSampledArray Returns the sampled values.
XintDataSampledDataReplace Replaces a range of values in a sampled array.
XintDataSampledDataShift Shifts the data in a sampled array.

Function Name	Description
XintCreateDataSampled	Creates a DataSampled object.
XintDataSampledDataExtend	Extends the data in a sampled array.
XintDataSampledGetDataArray	Returns part of the data array and converts it to float.
XintDataSampledGetSampledArray	Returns the sampled values.
XintDataSampledDataReplace	Replaces a range of values in a sampled array.
XintDataSampledDataShift	Shifts the data in a sampled array.

XintCreateDataSampled

This function creates a data sampled object and defines all the resources for it.

     Object XintCreateDataSampled (...)

Widget parent Parent of new data sampled object.
char * name Name of new data sampled.
ArgList arglist List of resource settings for the new data object.
Cardinal argcount Number of resources set by arglist.

XintDataSampledDataExtend

This function adds more data to the end of a sampled array. The function returns False if there is a bad argument, if the function cannot be performed, or if CopyData is false.

     Boolean XintDataSampledDataExtend (...)

Object object Object ID of the sampled array to be extended.
XtPointer array Array of data values to be added to the original sampled array. The data type for this array should be the same as the type specified by XmNdataType.
int count Number of values being added.

XintDataSampledGetDataArray

This function returns any part of a specified data array as an array of float values. If the data is not already stored as float, it converts the data type to float. You will need to free the returned array after it is no longer needed.

     float *XintDataSampledGetDataArray (...)

Object object Object ID of the sampled array containing the desired data.
int start Index of first value to be returned (starts at 0).
int count Total number of values to be returned.

XintDataSampledGetSampledArray

Since a sampled data object contains only a single array of data values, the data along the implied direction is generated from the XmNsampledRange resource. This function lets you retrieve any part of the synthetic array by specifying the index of the first value and the total number of values (count) to be retrieved. Count cannot be more than the total number of values available, otherwise this function returns NULL. You will need to free the returned array after it is no longer needed.

     float *XintDataSampledGetSampledArray (...)

Object object ID of the sampled array.
int start Index of first value to be retrieved.
int count Number of values to be retrieved.

XintDataSampledDataReplace

This function replaces a range of values in a sampled array. The function returns False if there is a bad argument or the function cannot be performed.

     Boolean XintDataSampledDataReplace (...)

Object object Object ID of the sampled array that requires values replaced.
XtPointer array Array of new values to be used to replace existing values. The data type for this array should be the same as the type specified by XmNdataType.
int start Index of first value to be replaced (starts at 0).
int count Number of values being replaced.

XintDataSampledDataShift

This function shifts the data in the sampled array by discarding a certain number of values (count) at the beginning of the array and adding an equal number of values to the end of the array. The values to be added must be specified in a separate array.

     Boolean XintDataSampledDataShift (...)

Object object Object ID of the array to be shifted
XtPointer array An array of values to be appended to the end of the current array in the DataSampled object. The data type for this array should be the same as the type specified by XmNdataType.
int count Number of values to be discarded at the front of the array and appended to the end of the array.

Macros

Macro XintIsDataSampled returns True if the specified object is a DataSampled object.

     Boolean XintIsDataSampled (Object object)

Widget	parent	Parent of new data sampled object.
char *	name	Name of new data sampled.
ArgList	arglist	List of resource settings for the new data object.
Cardinal	argcount	Number of resources set by arglist.

Object	object	Object ID of the sampled array to be extended.
XtPointer	array	Array of data values to be added to the original sampled array. The data type for this array should be the same as the type specified by XmNdataType.
int	count	Number of values being added.

Object	object	Object ID of the sampled array containing the desired data.
int	start	Index of first value to be returned (starts at 0).
int	count	Total number of values to be returned.

Object	object	ID of the sampled array.
int	start	Index of first value to be retrieved.
int	count	Number of values to be retrieved.

Object	object	Object ID of the sampled array that requires values replaced.
XtPointer	array	Array of new values to be used to replace existing values. The data type for this array should be the same as the type specified by XmNdataType.
int	start	Index of first value to be replaced (starts at 0).
int	count	Number of values being replaced.

Object	object	Object ID of the array to be shifted
XtPointer	array	An array of values to be appended to the end of the current array in the DataSampled object. The data type for this array should be the same as the type specified by XmNdataType.
int	count	Number of values to be discarded at the front of the array and appended to the end of the array.