This reference page is linked to from the following overview topics: Softimage 2014, Property Callbacks, Interacting with the User.

#include <xsi_griddata.h>

Class Description

This object represents a 2-dimensional array of data. The word Grid refers to the visual presentation of 2-Dimensional data on a grid control (sometimes called a table or spreadsheet control). The word Cell refers to a single element of the array.

The dimensions of the array can be dynamically resized and many types of data can be stored as Cell data. The Columns and Rows can be labeled and it is possible to refer to the data by these label strings rather than by indices.

Each cell in the GridData is a CValue object, so strings, integers, doubles and many other types of data can be stored in the GridData. However not all data types may be properly displayed in the associated User Interface. Also, although it is possible to store object references (as CRef objects) inside a GridData, these cannot be persisted so it is better to store the SIObject::GetFullName as the cell value.

There are three main uses for the GridData object:

Data for a ::siGridControl on a custom object (see CustomProperty::AddGridParameter): In this case the user can view and edit the data and the data is saved inside the scene along with the CustomProperty. This can be an effective way to store lists, vectors or even arrays of vectors related to a plug-in. Some aspects of the visual representation of the GridData object are set directly on the GridData object (for example GridData::PutColumnType) but most attributes are set inside the PPGLayout using PPGItem::PutAttribute. ::siPPGItemAttributes that apply to the ::siGridControl include ::siUIGridColumnWidths and ::siUIGridHideRowHeader.

Store hidden data that is intended for internal use by a plug-in: In this case it is still part of a CustomProperty but it is not exposed to the user, which is easily done by not including the GridData Parameter in the PPGLayout.

Temporary convenience object for dealing with 2-dimensional arrays: This is most useful for scripting languages like JScript which do not support 2-dimensional arrays, but also may be interesting in some cases for C++ developers. For example, because it employs range checking, it is more robust and safe to use when compared with raw pointer-based C++ arrays.

See also:: PPGLayout, CustomProperty, PPG

Since:: 4.0

Example:: Demonstrates how to use a GridData object to display data on a custom object.

                using namespace XSI;
                Application app ;
                Model root = app.GetActiveSceneRoot(); ;

                CustomProperty prop ;
                root.AddProperty( L"CustomProperty", false, L"GridDataDemo", prop) ;

                // Put two grids on this Custom Property
                Parameter grid1param = prop.AddGridParameter( L"grid1" ) ;
                Parameter grid2param = prop.AddGridParameter( L"grid2" ) ;

                // Unlike basic parameters that have strings, ints or
                // floats as their values, for a Grid parameter the
                // value is an entire GridData object
                GridData grid1 = grid1param.GetValue() ;
                GridData grid2 = grid2param.GetValue() ;

                //
                // The first grid is a typical array of vectors
                //
                grid1.PutColumnCount( 3 ) ;
                grid1.PutRowCount( 4 ) ;

                grid1.PutColumnLabel( 0, L"X" ) ;
                grid1.PutColumnLabel( 1, L"Y" ) ;
                grid1.PutColumnLabel( 2, L"Z" ) ;

                // Fill in some data
                CValueArray gridcontents( grid1.GetRowCount() *
                                                                  grid1.GetColumnCount() ) ;
                gridcontents[0] = 0.0; gridcontents[1]  = 0.5; gridcontents[2]  = 0.2;
                gridcontents[3] = 0.1; gridcontents[4]  = 1.0; gridcontents[5]  = 0.0;
                gridcontents[6] = 1.0; gridcontents[7]  = 1.0; gridcontents[8]  = 9.0;
                gridcontents[9] = 0.3; gridcontents[10] = 0.4; gridcontents[11] = 0.5;
                grid1.PutData(gridcontents) ;

                // Change our mind about the value of the cell at Column 0,
                // row 3
                grid1.PutCell( 0, 3, 99.9 ) ;

                //
                // Setup the second GridData
                // It only has 1 column so it is more like a list than
                // a 2-Dimensional array
                //

                grid2.PutColumnCount( 1 ) ;
                grid2.PutRowCount( 12 ) ;
                grid2.PutColumnLabel( 0, L"Column 0" ) ;
                grid2.PutColumnType( 0, siColumnCombo ) ;

                CValueArray enumInfo( 4 ) ;
                enumInfo[0] = L"Option value 0" ;
                enumInfo[1] = 0l ;
                enumInfo[2] = L"Option value 10" ;
                enumInfo[3] = 10l ;
                grid2.PutColumnComboItems( 0, enumInfo ) ;

                LONG i;
                for ( i = 0 ; i < grid2.GetRowCount() ; i++ )
                {
                        grid2.PutRowLabel( i, L"Row " + CValue( i ).GetAsText() ) ;
                }

                //
                // Populate it with some data
                //

                CValueArray items( grid2.GetRowCount() ) ;

                // First two items will use the first item in the combo box
                items[0] = 0l ;
                items[1] = 0l ;

                // rest of the items will select the second option
                for ( i = 2 ; i < items.GetCount() ; i++ )
                {
                        items[i] = 10l ;
                }

                grid2.PutColumnValues( L"Column 0", items ) ;


                //
                // Set up some Layout to fine-tune the
                // appearance of the grids
                //

                PPGLayout layout = prop.GetPPGLayout() ;

                PPGItem item = layout.AddItem( L"grid1", NULL, siControlGrid ) ;
                item.PutAttribute( siUIValueOnly, true ) ;

                // We didn't label the rows, so we can hide that column
                item.PutAttribute( siUIGridHideRowHeader, true ) ;



                item = layout.AddItem( L"grid2", NULL, siControlGrid ) ;

                // Specify the width for the row label column and
                // then the data column
                item.PutAttribute( siUIGridColumnWidths, L"100:140" ) ;
                item.PutAttribute( siUIValueOnly, true ) ;

                // Specify a specific height.  This forces the use of
                // a scroll bar
                item.PutAttribute( siUICY, 200l ) ;

                // Make sure that the Column header doesn't get scrolled out
                // of view
                item.PutAttribute( siUIGridLockColumnHeader, true ) ;

Inheritance diagram for GridData:

List of all members.

Public Member Functions
	GridData ()
	~GridData ()
	GridData (const CRef &in_ref)
	GridData (const GridData &in_obj)
bool	IsA (siClassID in_ClassID) const
siClassID	GetClassID () const
GridData &	operator= (const GridData &in_obj)
GridData &	operator= (const CRef &in_ref)
CValueArray	GetData () const
CStatus	PutData (const CValueArray &in_items)
CStatus	PutColumnCount (LONG in_val)
LONG	GetColumnCount () const
CStatus	PutRowCount (LONG in_val)
LONG	GetRowCount () const
CStatus	PutCell (LONG in_Column, LONG in_Row, const CValue &in_CellValue)
CStatus	PutCell (const CString &in_ColumnLabel, const CString &in_RowLabel, const CValue &in_CellValue)
CValue	GetCell (LONG in_Column, LONG in_Row) const
CValue	GetCell (const CString &in_ColumnLabel, const CString &in_RowLabel) const
CStatus	PutColumnValues (LONG in_Column, const CValueArray &in_ColumnItems)
CStatus	PutColumnValues (const CString &in_ColumnLabel, const CValueArray &in_ColumnItems)
CValueArray	GetColumnValues (LONG in_Column) const
CValueArray	GetColumnValues (const CString &in_ColumnLabel) const
CStatus	PutRowValues (LONG in_Row, const CValueArray &in_RowItems)
CStatus	PutRowValues (const CString &in_RowLabel, const CValueArray &in_RowItems)
CValueArray	GetRowValues (LONG in_Row) const
CValueArray	GetRowValues (const CString &in_RowLabel) const
CStatus	PutRowLabel (LONG in_RowIndex, const CString &in_RowLabel)
CString	GetRowLabel (LONG in_RowIndex) const
CStatus	PutColumnLabel (LONG in_ColumnIndex, const CString &in_ColumnLabel)
CString	GetColumnLabel (LONG in_ColumnIndex) const
CStatus	BeginEdit ()
CStatus	EndEdit ()
CStatus	PutColumnType (LONG in_ColumnIndex, siGridWidgetColumnType in_Type)
siGridWidgetColumnType	GetColumnType (LONG in_ColumnIndex) const
CStatus	PutColumnComboItems (LONG in_ColumnIndex, const CValueArray &in_Items)
CValueArray	GetColumnComboItems (LONG in_ColumnIndex)
GridWidget	GetGridWidget ()
CStatus	SetRowBackgroundColor (LONG in_Row, const CColor &in_Color)
CColor	GetRowBackgroundColor (LONG in_Row)
CStatus	SetIntColumnDef (LONG in_lColumnIndex, LONG in_lMin=INT_MIN, LONG in_lMax=INT_MAX, LONG in_lInc=1)
CStatus	GetIntColumnDef (LONG in_lColumnIndex, LONG &out_lMin, LONG &out_lMax, LONG &out_lInc) const
CStatus	SetFloatColumnDef (LONG in_lColumnIndex, double in_dMin=DBL_MIN, double in_dMax=DBL_MAX, double in_dInc=1.0, short in_sDecimal=2)
CStatus	GetFloatColumnDef (LONG in_lColumnIndex, double &out_dMin, double &out_dMax, double &out_dInc, short &out_sDecimal) const
CStatus	SetVectorColumnDef (LONG in_lColumnIndex, short in_sVectorSize, double in_dMin=DBL_MIN, double in_dMax=DBL_MAX, double in_dInc=1.0, short in_sDecimal=2)
CStatus	GetVectorColumnDef (LONG in_lColumnIndex, short &out_sVectorSize, double &out_dMin, double &out_dMax, double &out_dInc, short &out_sDecimal) const
CStatus	SetFileColumnDef (LONG in_lColumnIndex, const CString &in_csBrowseType="File", const CString &in_csStartupPath="/", const CString &in_csFilter=".*")
CStatus	GetFileColumnDef (LONG in_lColumnIndex, CString &out_csBrowseType, CString &out_csStartupPath, CString &out_csFilter) const
CStatus	SetShaderBallColumnDef (LONG in_lColumnIndex, LONG in_lThumbnailSize=28)
CStatus	GetShaderBallColumnDef (LONG in_lColumnIndex, LONG &out_lThumbnailSize) const
CStatus	SetImageClipColumnDef (LONG in_lColumnIndex, LONG in_lThumbnailSize=28)
CStatus	GetImageClipColumnDef (LONG in_lColumnIndex, LONG &out_lThumbnailSize) const
CStatus	InsertRow (LONG in_lRowIndex)
CStatus	RemoveRow (LONG in_lRowIndex)
CStatus	InsertColumn (LONG in_lColumnIndex)
CStatus	RemoveColumn (LONG in_lColumnIndex)
CStatus	SetCellBackgroundColor (LONG in_lCol, LONG in_lRow, const CColor &in_Color)
CColor	GetCellBackgroundColor (LONG in_lCol, LONG in_lRow) const
CStatus	SetColumnsVisibility (const CLongArray &in_alCols, bool in_bVisible)
CStatus	SetRowsVisibility (const CLongArray &in_alRows, bool in_bVisible)
CStatus	SetCellReadOnlyFlags (const CLongArray &in_alCells, bool in_bROFlag)
CStatus	GetCellReadOnlyFlags (const CLongArray &in_alCells, CBitArray &out_aROFlags) const
CStatus	PutMultiSelectionMode (XSI::siGridDataMultiSelectionMode in_eSelectionMode)
XSI::siGridDataMultiSelectionMode	GetMultiSelectionMode () const
CStatus	PutReadOnly (bool in_bROFlag)
bool	GetReadOnly () const

Constructor & Destructor Documentation

GridData ( )

Default constructor.

~GridData ( )

Default destructor.

GridData ( const CRef & in_ref )

Constructor.

Parameters:

in_ref constant reference object.

GridData ( const GridData & in_obj )

Copy constructor.

Parameters:

in_obj constant class object.

Member Function Documentation

bool IsA ( siClassID in_ClassID ) const [virtual]

CStatus PutCell	(	LONG	in_Column,
		LONG	in_Row,
		const CValue &	in_CellValue
	)

in_Column	Column index (zero-based)
in_Row	Row index (zero-based)
in_CellValue	Value to set in the specified cell

CStatus PutCell	(	const CString &	in_ColumnLabel,
		const CString &	in_RowLabel,
		const CValue &	in_CellValue
	)

in_ColumnLabel	Column label
in_RowLabel	Row label
in_CellValue	Value for the cell

CValue GetCell	(	const CString &	in_ColumnLabel,
		const CString &	in_RowLabel
	)		const

CStatus PutColumnValues	(	LONG	in_Column,
		const CValueArray &	in_ColumnItems
	)

in_Column	Column index (zero-based)
in_ColumnItems	1-dimensional array of values to set. The size should be equal to GridData::GetRowCount.

in_ColumnLabel	Column label (see GridData::PutColumnLabel)
in_ColumnItems	1-dimensional array of values to set. The size should be equal to GridData::GetRowCount.

CStatus PutRowValues	(	LONG	in_Row,
		const CValueArray &	in_RowItems
	)

in_Row	Row index (zero-based)
in_RowItems	1-dimensional array of values to set. The size should be equal to GridData::GetColumnCount.

in_RowLabel	row label (see GridData::PutRowLabel)
in_RowItems	1-dimensional array of values to set. The size should be equal to GridData::GetColumnCount.

CStatus PutRowLabel	(	LONG	in_RowIndex,
		const CString &	in_RowLabel
	)

in_RowIndex	Index of the row to label.
in_RowLabel	Row label to use.

CStatus PutColumnLabel	(	LONG	in_ColumnIndex,
		const CString &	in_ColumnLabel
	)

in_ColumnIndex	Index of the column to label.
in_ColumnLabel	Column label to use.

CStatus PutColumnType	(	LONG	in_ColumnIndex,
		siGridWidgetColumnType	in_Type
	)

in_ColumnIndex	Index of the column to modify.
in_Type	Type of control (plain data, check box, combo box). See siGridWidgetColumnType for a complete list of possible control types.

CStatus PutColumnComboItems	(	LONG	in_ColumnIndex,
		const CValueArray &	in_Items
	)

in_ColumnIndex	Column index (zero based)
in_Items	CValueArray containing the label/value pairs

CStatus SetRowBackgroundColor	(	LONG	in_Row,
		const CColor &	in_Color
	)

Class Description

Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation

in_Row	Index of the row to color.
in_Color	Color to appear in the specified row (as a CColor).

CStatus SetIntColumnDef	(	LONG	in_lColumnIndex,
		LONG	in_lMin = `INT_MIN`,
		LONG	in_lMax = `INT_MAX`,
		LONG	in_lInc = `1`
	)

in_lColumnIndex	The column of interest.
in_lMin	Minimum valid value.
in_lMax	Maximum valid value.
in_lInc	Increment that is used while scrubbing.

CStatus GetIntColumnDef	(	LONG	in_lColumnIndex,
		LONG &	out_lMin,
		LONG &	out_lMax,
		LONG &	out_lInc
	)		const

in_lColumnIndex	The column of interest.
out_lMin	Minimum valid value.
out_lMax	Maximum valid value.
out_lInc	Increment that is used while scrubbing.

CStatus SetFloatColumnDef	(	LONG	in_lColumnIndex,
		double	in_dMin = `DBL_MIN`,
		double	in_dMax = `DBL_MAX`,
		double	in_dInc = `1.0`,
		short	in_sDecimal = `2`
	)

in_lColumnIndex	The column of interest.
in_dMin	Minimum valid value.
in_dMax	Maximum valid value.
in_dInc	Increment that is used while scrubbing.
in_sDecimal	Number of decimals to be displayed.

CStatus GetFloatColumnDef	(	LONG	in_lColumnIndex,
		double &	out_dMin,
		double &	out_dMax,
		double &	out_dInc,
		short &	out_sDecimal
	)		const

in_lColumnIndex	The column of interest.
out_dMin	Minimum valid value.
out_dMax	Maximum valid value.
out_dInc	Increment that is used while scrubbing.
out_sDecimal	Number of decimals to be displayed.

CStatus SetVectorColumnDef	(	LONG	in_lColumnIndex,
		short	in_sVectorSize,
		double	in_dMin = `DBL_MIN`,
		double	in_dMax = `DBL_MAX`,
		double	in_dInc = `1.0`,
		short	in_sDecimal = `2`
	)