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:
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 ) ;
#include <xsi_griddata.h>
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) |
GridData | ( | ) |
Default constructor.
~GridData | ( | ) |
Default destructor.
bool IsA | ( | siClassID | in_ClassID | ) | const [virtual] |
Returns true if a given class type is compatible with this API class.
in_ClassID | class type. |
Reimplemented from CBase.
siClassID GetClassID | ( | ) | const [virtual] |
Creates an object from another object.
in_obj | constant class object. |
Creates an object from a reference object. The newly created object is set to empty if the input reference object is not compatible.
in_ref | constant class object. |
CValueArray GetData | ( | ) | const |
Returns the entire 2-dimensional array of cell data. The data is represented as a CValueArray, with the data organized row by row.
CStatus PutData | ( | const CValueArray & | in_items | ) |
Sets the content of the entire GridData object with a single call. The array must contain Row
*
Column
items, and the data is interpreted to be ordered row by row rather than column by column.
in_items | Data to set. |
CStatus PutColumnCount | ( | LONG | in_val | ) |
LONG GetColumnCount | ( | ) | const |
Returns the number of columns contained in the GridData object.
CStatus PutRowCount | ( | LONG | in_val | ) |
LONG GetRowCount | ( | ) | const |
Returns the number of rows contained in the GridData object.
Changes the value of a single element inside the GridData object. The coordinates must be within the valid range of the GridData's dimensions.
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 | ||
) |
Changes the value of a single element inside the GridData object. In this variation of GridData::PutCell the cell is specified by the row and column labels rather than by index. This is a slightly slower approach but it makes the code easier to read. See GridData::PutColumnLabel and GridData::PutRowLabel.
in_ColumnLabel | Column label |
in_RowLabel | Row label |
in_CellValue | Value for the cell |
CValue GetCell | ( | LONG | in_Column, |
LONG | in_Row | ||
) | const |
Returns the value stored on a specific cell of the GridData object.
in_Column | Column index (zero-based) |
in_Row | Row index (zero-based) |
Returns the value stored on the GridData.
In this variation of GridData::GetCell the cell is specified by the row and column labels rather than by index. This is a slightly slower approach but it makes the code easier to read. See GridData::PutColumnLabel and GridData::PutRowLabel.
in_ColumnLabel | Column label |
in_RowLabel | Row label |
CStatus PutColumnValues | ( | LONG | in_Column, |
const CValueArray & | in_ColumnItems | ||
) |
Sets values on a single column of a GridData object.
in_Column | Column index (zero-based) |
in_ColumnItems | 1-dimensional array of values to set. The size should be equal to GridData::GetRowCount. |
CStatus PutColumnValues | ( | const CString & | in_ColumnLabel, |
const CValueArray & | in_ColumnItems | ||
) |
Sets values for a single column of a GridData object.
in_ColumnLabel | Column label (see GridData::PutColumnLabel) |
in_ColumnItems | 1-dimensional array of values to set. The size should be equal to GridData::GetRowCount. |
CValueArray GetColumnValues | ( | LONG | in_Column | ) | const |
Returns a 1-dimensional array containing all the elements in the requested column.
in_Column | Column index (zero-based) |
CValueArray GetColumnValues | ( | const CString & | in_ColumnLabel | ) | const |
Returns a 1-dimensional array containing all the elements in the requested column.
in_ColumnLabel | Column label (see GridData::PutColumnLabel) |
CStatus PutRowValues | ( | LONG | in_Row, |
const CValueArray & | in_RowItems | ||
) |
Sets values for a single row of a GridData object.
in_Row | Row index (zero-based) |
in_RowItems | 1-dimensional array of values to set. The size should be equal to GridData::GetColumnCount. |
CStatus PutRowValues | ( | const CString & | in_RowLabel, |
const CValueArray & | in_RowItems | ||
) |
Sets values for a single row of a GridData object.
in_RowLabel | row label (see GridData::PutRowLabel) |
in_RowItems | 1-dimensional array of values to set. The size should be equal to GridData::GetColumnCount. |
CValueArray GetRowValues | ( | LONG | in_Row | ) | const |
Returns a 1-dimensional array containing all the elements in the requested row.
in_Row | Row index (zero-based) |
CValueArray GetRowValues | ( | const CString & | in_RowLabel | ) | const |
Returns a 1-dimensional array containing all the elements in the requested row.
in_RowLabel | Row label (see GridData::PutRowLabel) |
Sets the label for a Row. Labels are optional. The visual appearance of row labels can be tweaked with the ::siUIGridHideRowHeader and ::siUIGridLockRowHeader attributes (see the ::siPPGItemAttribute enum). Once labels are specified it is possible to access data via the labels rather than the cell index via functions like GridData::PutCell and GridData::GetRowValues.
in_RowIndex | Index of the row to label. |
in_RowLabel | Row label to use. |
CString GetRowLabel | ( | LONG | in_RowIndex | ) | const |
Returns the label string of a row.
in_RowIndex | Index of the row with the label to get. |
Sets the label for a Column. Labels are optional. The visual appearance of column labels can be tweaked with the ::siUIGridHideColumnHeader and ::siUIGridLockColumnHeader attributes (see the ::siPPGItemAttribute enum). Once labels are specified it is possible to access data via the labels rather than the cell index via functions like GridData::PutCell and GridData::GetColumnValues.
in_ColumnIndex | Index of the column to label. |
in_ColumnLabel | Column label to use. |
CString GetColumnLabel | ( | LONG | in_ColumnIndex | ) | const |
Returns the label string of a column.
in_ColumnIndex | Index of the column with the label to get. |
CStatus BeginEdit | ( | ) |
Call this function to signal that a large portion of the GridData contents has changed. This prevents all updates of the user interface associated with the GridData. If GridData is not associated with a GridControl or if the Property Page with the GridControl is not being inspected then this call has no effect. Hence the most likely place to use this function is inside logic code (see PPGLayout::PutLogic and PPGLayout::GetLogic).
CStatus EndEdit | ( | ) |
Call this function to signal the end of major updates to the GridData. At this point all views on the data are rebuilt. For example the user interface may redraw itself. Each call to GridData::EndEdit should match a previous call to GridData::BeginEdit.
CStatus PutColumnType | ( | LONG | in_ColumnIndex, |
siGridWidgetColumnType | in_Type | ||
) |
Specifies a type of control to use for a particular column. This function is optional because the default column type, siColumnStandard, is suitable for strings, numbers and most other data.
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. |
siGridWidgetColumnType GetColumnType | ( | LONG | in_ColumnIndex | ) | const |
Returns the type of a column (for example siColumnCombo or siColumnBool).
in_ColumnIndex | Index of the column to retrieve. |
CStatus PutColumnComboItems | ( | LONG | in_ColumnIndex, |
const CValueArray & | in_Items | ||
) |
Sets the combo items associated with a column of type siColumnCombo. The items are specified in a 1-dimensional CValueArray, with a label string and associated integer value for each combo item. For example the array ("A", 0, "B", 12) specifies two items for the combo box, one with label "A" and value 0 and the other with label "B" and value 12.
in_ColumnIndex | Column index (zero based) |
in_Items | CValueArray containing the label/value pairs |
CValueArray GetColumnComboItems | ( | LONG | in_ColumnIndex | ) |
Returns the definition of a GridData column having the type siColumnCombo.
in_ColumnIndex | Column index (zero based) |
GridWidget GetGridWidget | ( | ) |
Returns a pointer to the user interface control as a GridWidget object. The GridWidget object displays the GridData information on a Property Page (PPG object) which allows you to access information about selected cells.
Sets the background color on the specified row.
in_Row | Index of the row to color. |
in_Color | Color to appear in the specified row (as a CColor). |
CColor GetRowBackgroundColor | ( | LONG | in_Row | ) |
Returns the background color of the specified row.
in_Row | Index of the row to access. |