DataSeries Object Class

Overview

The DataSeries object class is used to store, retrieve, and manipulate any series of (x,y) data pairs. Each data group may contain multiple DataSeries objects (for instance, multiple columns from a table or multiple lines on a chart). The series is specified as an array of X data points, with a matching array of Y data points. Compared to the DataSampled object, the DataSeries object is more suitable for describing random series of irregularly spaced data points. The type of data contained in a DataSeries Object can be float, short, integer, long, or double.

Example

The following example shows the code structure for a typical DataSeries object.

   static float x_coord[] = {12.4, 23.5, 28.1, 31.5};
   static float y_coord[] = {123, 432, 234, 121};
   Object point_series;
   ...
   point_series = (Object) XtVaCreateWidget("series",
                               (WidgetClass)xintDataSeriesObjectClass, edit,
                               XmNxArray, x_coord,
                               XmNyArray, y_coord,
                               XmNcount, sizeof(x_coord)/sizeof(float),
                               XmNdataType, XintDATA_TYPE_FLOAT,
                               XmNcopyData, False,
                               NULL);

Inherited Resources and Behavior

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

The class pointer is xintDataSeriesObjectClass.
The class name is XintDataSeries.
The header file is included as <Xint/DataSeries.h>.

The following resources are defined by the DataSeries object class:
Name	Type	Default	Access
XmNcopyData	Boolean	True	CSG
XmNcount	int	0	CSG
XmNdataGroup	Object	NULL	CSG
XmNdataType	int	XintDATA_TYPE_FLOAT	CSG
XmNeditable	Boolean	False	CSG
XmNlastViewDestroy	Boolean	True	CSG
XmNupdateCallback	XtCallbackList	NULL	CSG
XmNxArray	XtPointer	NULL	CSG
XmNyArray	XtPointer	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.

XmNupdateCallback

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

XmNxArray, XmNyArray

Specifies the names of the pre-defined X and Y data arrays containing the data in this series. The array size is expressed through the resource XmNcount and the data type is specified by XmNdataType, discussed later in this section. The default value of this resource is NULL.

Callbacks

The callback XmNupdateCallback can be used to provide notification of changes in a DataSeries object. Similarly as for widgets, you can register this callback with the Xt function XtAddCallback. When connected to a view (Chart or Table for example), this notification is used to ensure that updates to one view are properly reflected in all other applicable views.

The callback structure takes the following form:

   typedef struct {
                   int    reason;
                   XEvent *event;
                   Object object;
                   int    x_start;
                   int    x_count;
                   int    y_start;
                   int    y_count;
  } XintDataSeriesUpdateCallbackStruct;

When used with DataSeries objects, this callback must be registered individually for each object. If you prefer to control updates at the group level, you should register the callback at the group level and use XintDataGroupUpdateCallbackStruct discussed earlier in this manual.

The callback provides information indicating why and how the object was modified. The following ordered table describes the members of XintDataSeriesUpdateCallbackStruct:

Data Type Member Description
int reason Indicates why callback was invoked (see table below).
XEvent * event Standard member in Motif callback structure; not used in this context (will always be NULL).
Object object ID of the updated object.
int x_start Starting index of X values updated (starts at 0).
int x_count Total number of X values updated.
int y_start Starting index of Y values updated (starts at 0).
int y_count Total number of Y values updated.

Data Type	Member	Description
int	reason	Indicates why callback was invoked (see table below).
XEvent *	event	Standard member in Motif callback structure; not used in this context (will always be NULL).
Object	object	ID of the updated object.
int	x_start	Starting index of X values updated (starts at 0).
int	x_count	Total number of X values updated.
int	y_start	Starting index of Y values updated (starts at 0).
int	y_count	Total number of Y values updated.

The callback structure includes information explaining the reason why a particular update occurred. The reasons below are contained in the header file Data.h.

Reason Description
XintCR_DATA_UPDATE
XintCR_DATA_BATCH Entire X and Y arrays have been changed, no more information is available.
XintCR_DATA_REPLACE Data was replaced in the object, as specified by members x_start, x_count, y_start and y_count;
XintCR_DATA_EXTEND Data was added to the object (x_count values where added).
XintCR_DATA_SHIFT Data was shifted in the object (x_count values where shifted).

Reason	Description
XintCR_DATA_UPDATE XintCR_DATA_BATCH	Entire X and Y arrays have been changed, no more information is available.
XintCR_DATA_REPLACE	Data was replaced in the object, as specified by members x_start, x_count, y_start and y_count;
XintCR_DATA_EXTEND	Data was added to the object (x_count values where added).
XintCR_DATA_SHIFT	Data was shifted in the object (x_count values where shifted).

Defined Functions

The following functions are defined for creating and manipulating DataSeries objects.

Function Name Description
XintCreateDataSeries Creates a DataSeries object.
XintDataSeriesDataExtend Adds extra data points to a data series.
XintDataSeriesDataReplace Replaces a specified range of values in a data series.
XintDataSeriesDataShift Shifts the data in a data series to a new range of values.
XintDataSeriesGetXArray Returns part of the X array and converts it to a float value.
XintDataSeriesGetYArray Returns part of the Y array and converts it to a float value.

Function Name	Description
XintCreateDataSeries	Creates a DataSeries object.
XintDataSeriesDataExtend	Adds extra data points to a data series.
XintDataSeriesDataReplace	Replaces a specified range of values in a data series.
XintDataSeriesDataShift	Shifts the data in a data series to a new range of values.
XintDataSeriesGetXArray	Returns part of the X array and converts it to a float value.
XintDataSeriesGetYArray	Returns part of the Y array and converts it to a float value.

XintCreateDataSeries

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

     Object XintCreateDataSeries (...)

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

XintDataSeriesDataExtend

This function adds additional data to the end of a series array. The values to be added must be defined in separate X and Y arrays. Both arrays must contain an equal number of values representing matched (x,y) pairs. The function returns False if there is a bad argument or resource XmNcopyData is False.

     Boolean XintDataSeriesDataExtend (...)

Object object Object ID of the data series array to be extended.
XtPointer x_array Array of X values to be added to the data series. The data type for this array should be the same as the type specified by XmNdataType.
XtPointer y_array Array of matching Y values to be added to the data series. The data type for this array should be the same as the type specified by XmNdataType.
int count Number of (x,y) pairs being added.

XintDataSeriesDataReplace

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

     Boolean XintDataSeriesDataReplace (...)

Object object ID of the data series object in which data is being replaced.
XtPointer x_array Array containing X replacement values. The data type for this array should be the same as the type specified by XmNdataType.
XtPointer y_array Array containing Y replacement 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 in the existing array.
int count Total number of (x,y) pairs being replaced.

XintDataSeriesDataShift

This function shifts the data contained in a DataSeries object by discarding a specified number of values at the beginning of the existing arrays, and adding an equal number of values to the end of the existing arrays. For example, you may want to discard the first four points in a data series and add four new points to the end of the data series.

The values to be added must be defined in separate X and Y arrays. Both arrays must contain an equal number of values representing matched (x,y) pairs, and the total number of values in the new arrays must equal the number of values to be discarded from the existing arrays. The function returns False if argument count is incorrect.

     Boolean XintDataSeriesDataShift (...)

Object object ID of the data series array.
XtPointer x_array Array of X values to be appended to the end of the current X array in the DataSeries object. The data type for this array should be the same as the type specified by XmNdataType.
XtPointer y_array Array of Y values to be appended to the end of the current Y array in the DataSeries 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 and appended to the end of the existing array.

XintDataSeriesGetXArray, XintDataSeriesGetYArray

This function retrieves any part of the X or Y array in an existing DataSeries object and returns it as an array of float values. If the data is not already classified as float, it converts the data type to float. You will need to free the returned array after it is no longer needed.

     float *XintDataSeriesGetXArray (...)

     float *XintDataSeriesGetYArray (...)

Object object ID of the DataSeries object containing the desired data.
int start Index of first value to be retrieved.
int count Number of values to be retrieved.

Macros

Macro XintIsDataSeries returns True if the specified object is a DataSeries object.

     Boolean XintIsDataSeries (Object object)

Widget	parent	Parent of new data series object.
char *	name	Name of new data series object.
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 data series array to be extended.
XtPointer	x_array	Array of X values to be added to the data series. The data type for this array should be the same as the type specified by XmNdataType.
XtPointer	y_array	Array of matching Y values to be added to the data series. The data type for this array should be the same as the type specified by XmNdataType.
int	count	Number of (x,y) pairs being added.

Object	object	ID of the data series object in which data is being replaced.
XtPointer	x_array	Array containing X replacement values. The data type for this array should be the same as the type specified by XmNdataType.
XtPointer	y_array	Array containing Y replacement 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 in the existing array.
int	count	Total number of (x,y) pairs being replaced.

Object	object	ID of the data series array.
XtPointer	x_array	Array of X values to be appended to the end of the current X array in the DataSeries object. The data type for this array should be the same as the type specified by XmNdataType.
XtPointer	y_array	Array of Y values to be appended to the end of the current Y array in the DataSeries 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 and appended to the end of the existing array.

Object	object	ID of the DataSeries object containing the desired data.
int	start	Index of first value to be retrieved.
int	count	Number of values to be retrieved.