DataGrid Reference

DataGrid Object

Overview

The DataGrid object class is used to store, retrieve and manipulate two-dimensional arrays or grids of data. Each data group may contain multiple grid objects, such as multiple blocks of cells in a table. The grid is described by pointing to a defined two- dimensional array, then describing:

the total count of X and Y values in the array
the order or orientation of data in the array (e.g., X-oriented, Y-oriented)
the min/max limits of the data

The type of data contained in a DataGrid Object can be float, short, integer, long, or double.

Example

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

   float grid[NX*NY];
   Object grid_data;
   ...
   for (i=0; i<NX*NY; i++) grid [i] = i
        grid_data = (Object) XtVaCreateWidget("Grid",
	                         (WidgetClass)xintDataGridObjectClass, 
	                         edit,
	                         XmNgridArray, grid,
	                         XmNxCount, NX,
	                         XmNyCount, NY,
	                         XmNgridOrder, XintX_VECTOR,
	                         XmNdataGroup, data_group, NULL);

Inherited Resources and Behavior

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

The class pointer is xintDataGridObjectClass.
The class name is XintDataGrid.
The header file is included as <Xint/DataGrid.h>.

The following resources are defined by the DataGrid object class:
Name	Type	Default	Access
XmNcopyData	Boolean	True	CSG
XmNdataGroup	Object	NULL	CSG
XmNdataType	int	XintDATA_TYPE_FLOAT	CSG
XmNeditable	Boolean	True	CSG
XmNgridArray	XtPointer	NULL	CSG
XmNgridOrder	int	XintX_VECTOR	CSG
XmNlastViewDestroy	Boolean	True	CSG
XmNupdateCallback	XtCallbackList	NULL	CSG
XmNxCount	int	0	CSG
XmNyCount	int	0	CSG
XmNxRange	XintRange *	NULL	CSG
XmNyRange	XintRange *	NULL	CSG

Resource Value Description
XintDATA_TYPE_FLOAT (default) Data type is float.
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 (default)	Data type is float.
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.

XmNgridArray

This resource specifies the name of the array containing the gridded data. The data type of the array can be defined using the XmNdataType resource.

XmNgridOrder

This resource specifies the direction in which the grid is ordered. For example, in a table with Y orientation, the array values are arranged column-by-column; in X orientation they are arranged row-by-row. The selected X or Y orientation is maintained when the data is transferred to chart views and the data is plotted accordingly.

The following constants describe the grid orientation for the XmNgridOrder resource.

Resource Value Description
XintX_VECTOR Grid is ordered in the X direction.
XintY_VECTOR (default) Grid is ordered in the Y direction.

Resource Value	Description
XintX_VECTOR	Grid is ordered in the X direction.
XintY_VECTOR (default)	Grid is ordered in the Y direction.

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 Grid object that is invoked each time the data has changed. See the following section for more information on this callback.

XmNxCount, XmNyCount

These resources specify the size of the grid in the X and Y directions. In a table, X count is the number of rows, and Y count is the number of columns.

XmNxRange, XmNyRange

These resources let you define the grid data range in the X or Y direction as a start and an increment. If you don't specify a value for this resource, the starting value is set to be 0 and the increment 1.

The actual start/increment values are defined through the data structure XintRange, which takes the following form:

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

where:

Member Description
start Starting value.
increment Increment.

Member	Description
start	Starting value.
increment	Increment.

Callback

Callback XmNupdateCallback provides notification of changes in a grid object. This notification can be used to ensure that updates to one view are properly reflected in all other views. The callback structure takes the following form:

   typedef struct {
                   int        reason;
                   XEvent     *event;
                   Object     object;
                   int        x_start;
                   int        y_start;
                   int        x_count;
                   int        y_count;
                   float      minimum;
                   float      maximum;
   } XintDataGridUpdateCallbackStruct;

If you have multiple DataGrid or other objects in a group, this callback must be registered separately for each individual data object. If you prefer to control updates at the group level, you should register this callback only once for the DataGroup object and use the XintDataGroupUpdateCallbackStruct discussed earlier in this manual.

Structure XintDataGridUpdateCallbackStruct contains information that indicates why and how the object was modified. This information can help optimize the redrawing and updating of the appropriate views. The following ordered table lists the members of structure XintDataGridUpdateCallbackStruct:

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 alwa ys be NULL).
Object object ID of the updated object.
int x_start Starting index of X value updated (starts at 0).
int y_start Starting index of Y value updated (starts at 0).
int x_count Total number of X values updated.
int y_count Total number of Y values being updated.
float minimum New minimum of updated values.
float maximum New maximum of updated values.

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 alwa ys be NULL).
Object	object	ID of the updated object.
int	x_start	Starting index of X value updated (starts at 0).
int	y_start	Starting index of Y value updated (starts at 0).
int	x_count	Total number of X values updated.
int	y_count	Total number of Y values being updated.
float	minimum	New minimum of updated values.
float	maximum	New maximum of updated values.

Member reason provides information explaining why and how the update occurred. Possible values for member reason are:

Reason Description
XintCR_DATA_UPDATE XintCR_DATA_BATCH Entire data grid has been changed, no more information is available.
XintCR_DATA_REPLACE A portion of the grid (as specified by x_start, y_start, x_count and y_count) has been replaced.

Reason	Description
XintCR_DATA_UPDATE XintCR_DATA_BATCH	Entire data grid has been changed, no more information is available.
XintCR_DATA_REPLACE	A portion of the grid (as specified by x_start, y_start, x_count and y_count) has been replaced.

Functions

The following functions are available for creating and manipulating grid data objects.

Function Name Description
XintCreateDataGrid Creates a new data grid object.
XintDataGridGetGridArray Retrieves any part of a grid.
XintDataGridDataReplace Replaces data in a grid.

Function Name	Description
XintCreateDataGrid	Creates a new data grid object.
XintDataGridGetGridArray	Retrieves any part of a grid.
XintDataGridDataReplace	Replaces data in a grid.

XintCreateDataGrid

The XintCreateDataGrid function lets you create a new data grid object. The function argument list should contain any resource settings that you want to specify for the new grid object.

     Object XintCreateDataGrid(...)

Widget parent Parent of new data grid object.
char * name Name of new data grid object.
ArgList arglist List of resources to be set for this data grid.
Cardinal argcount Total number of resources being set.

XintDataGridGetGridArray

The XintDataGridGetGridArray function retrieves any part of a DataGrid object as a floating point array. You will have to free the array after it is no longer needed.

     float *XintDataGridGetGridArray (...)

Object object Object ID of the data grid in which data is being retrieved.
int x_start Starting X value in the area of the grid to be retrieved.
int y_start Starting Y value in the area of the grid to be retrieved.
int x_count Total number of X values to be retrieved.
int y_count Total number of Y values to be retrieved.

XintDataGridDataReplace

The XintDataGridDataReplace function lets you replace the data within a specified area of a specified grid. The function arguments let you specify a predefined array to be inserted, along with the starting x,y values and the number of values to be replaced in both the X and Y directions. The function returns False if there is a bad argument or the function cannot be performed.

     Boolean XintDataGridDataReplace (...)

Object object Object ID of the data grid in which data is being replaced.
XtPointer array Array containing the replacement data. The data type for this array should be the same as the type specified by XmNdataType.
int x_start Starting X value in the area of the grid being replaced.
int y_start Starting Y value in the area of the grid being replaced.
int x_count Total number of X values being replaced.
int y_count Total number of Y values being replaced.

Macros

Macro XintIsDataGrid returns True if the specified object is a DataGrid object.

     Boolean XintIsDataGrid (Object object)

Widget	parent	Parent of new data grid object.
char *	name	Name of new data grid object.
ArgList	arglist	List of resources to be set for this data grid.
Cardinal	argcount	Total number of resources being set.

Object	object	Object ID of the data grid in which data is being retrieved.
int	x_start	Starting X value in the area of the grid to be retrieved.
int	y_start	Starting Y value in the area of the grid to be retrieved.
int	x_count	Total number of X values to be retrieved.
int	y_count	Total number of Y values to be retrieved.