|
mCtrl 0.8.0
|
Table (data model for grid control) More...
Go to the source code of this file.
Typedefs | |
| typedef void * | MC_TABLE |
| Opaque table handle. | |
Functions | |
| MC_TABLE MCTRL_API | mcTable_Create (WORD wColumnCount, WORD wRowCount, MC_VALUETYPE hType, DWORD dwFlags) |
| Create new table. | |
| void MCTRL_API | mcTable_AddRef (MC_TABLE hTable) |
| Increment reference counter of the table. | |
| void MCTRL_API | mcTable_Release (MC_TABLE hTable) |
| Decrement reference counter of the table. | |
| WORD MCTRL_API | mcTable_ColumnCount (MC_TABLE hTable) |
| Retrieve count of table columns. | |
| WORD MCTRL_API | mcTable_RowCount (MC_TABLE hTable) |
| Retrieve count of table rows. | |
| BOOL MCTRL_API | mcTable_Resize (MC_TABLE hTable, WORD wColumnCount, WORD wRowCount) |
| Resize the table. | |
| void MCTRL_API | mcTable_Clear (MC_TABLE hTable) |
| Clear the table. | |
| BOOL MCTRL_API | mcTable_SetCell (MC_TABLE hTable, WORD wCol, WORD wRow, MC_VALUETYPE type, MC_VALUE value) |
| Set contents of a cell. | |
| BOOL MCTRL_API | mcTable_GetCell (MC_TABLE hTable, WORD wCol, WORD wRow, MC_VALUETYPE *phType, MC_VALUE *phValue) |
| Get contents of a cell. | |
Table (data model for grid control)
The table is actually a container which manages set of values (MC_VALUE) in two-dimensional matrix. It serves as a back-end for the grid control (MC_WC_GRID).
When the table is created with the function mcTable_Create(), the caller determines whether the table shall be homogenous or heterogenous.
Homogenous tables can hold only values of the same type (MC_VALUETYPE), specified during creation of the table. Homogenous table is less memory consuming, as it just holds MC_VALUE handle for each cell.
However it severly limits flexibility of the table. Any attempt to cet any cell of the table to other type then specified will fail.
After the homogenous table is created, you can never reset it to be heterogenous, or to use other value type for its cells.
Furthermore even in the initial state after the creation, the table cannot generally be considered empty: All the values (for each cell) are just set to NULL. It depends on particular value type how this value is interpreted.
When NULL is used as the value type during table creation, then a heterogenous table is created.
Heterogenous table holds pair of MC_VALUETYPE and MC_VALUE for each cell. Initially the table is empty (both the handles of each cell are NULL).
This allows to set values of any type arbitrarily and types of cells can change dynamically during the table lifetime as different types are specified in mcTable_SetCell().
| MC_TABLE MCTRL_API mcTable_Create | ( | WORD | wColumnCount, |
| WORD | wRowCount, | ||
| MC_VALUETYPE | hType, | ||
| DWORD | dwFlags | ||
| ) |
Create new table.
The table is initially empty and has its reference counter set to 1.
| [in] | wColumnCount | Column count. |
| [in] | wRowCount | Row count. |
| [in] | hType | Type of all cells for homogenous table, or NULL for heterogenous table. |
| dwFlags | Reserved, set to zero. |
NULL on failure. | void MCTRL_API mcTable_AddRef | ( | MC_TABLE | hTable | ) |
Increment reference counter of the table.
| [in] | hTable | The table. |
| void MCTRL_API mcTable_Release | ( | MC_TABLE | hTable | ) |
Decrement reference counter of the table.
If the reference counter drops to zero, all resources allocated for the table are released.
| [in] | hTable | The table. |
| WORD MCTRL_API mcTable_ColumnCount | ( | MC_TABLE | hTable | ) |
Retrieve count of table columns.
| [in] | hTable | The table. |
| WORD MCTRL_API mcTable_RowCount | ( | MC_TABLE | hTable | ) |
Retrieve count of table rows.
| [in] | hTable | The table. |
| BOOL MCTRL_API mcTable_Resize | ( | MC_TABLE | hTable, |
| WORD | wColumnCount, | ||
| WORD | wRowCount | ||
| ) |
Resize the table.
If a table dimension decreases, the values from excessive cells are destroyed. If a table dimension increases, the new cells are initialized to empty values (in case of heterogenous table) or to NULL values (for homogenous table).
| [in] | hTable | The table. |
| [in] | wColumnCount | Column count. |
| [in] | wRowCount | Row count. |
TRUE on success, FALSE otherwise. | void MCTRL_API mcTable_Clear | ( | MC_TABLE | hTable | ) |
Clear the table.
All values are destroyed. In case of homogenous table, all cells are reset to NULL values of the particular value type, in case of homogenous table the table becomes empty.
| [in] | hTable | The table. |
| BOOL MCTRL_API mcTable_SetCell | ( | MC_TABLE | hTable, |
| WORD | wCol, | ||
| WORD | wRow, | ||
| MC_VALUETYPE | type, | ||
| MC_VALUE | value | ||
| ) |
Set contents of a cell.
Note that (in case of success) the table takes responsibility for the value. I.e. when the table is later deallocated, or if the particular cell is later reset, the value is destroyed.
To reset the cell, set both the parameters type and value to NULL. The reset leads to destroying of a value actually stored in the cell as a side-effect.
| [in] | hTable | The table. |
| [in] | wCol | Column index. |
| [in] | wRow | Row index. |
| [in] | type | Value type. In case of homogenous table the type must match the type used during table creation. |
| [in] | value | The value. |
TRUE on success, FALSE otherwise. | BOOL MCTRL_API mcTable_GetCell | ( | MC_TABLE | hTable, |
| WORD | wCol, | ||
| WORD | wRow, | ||
| MC_VALUETYPE * | phType, | ||
| MC_VALUE * | phValue | ||
| ) |
Get contents of a cell.
Note that you don't get a responsibility for the value. If you want to store it elsewhere and/or modify it, you should do so on your copy. You may use mcValue_Duplicate() for that purpose.
| [in] | hTable | The table. |
| [in] | wCol | Column index. |
| [in] | wRow | Row index. |
| [out] | phType | Value type is filled here. |
| [out] | phValue | Value handle is filled here. |
TRUE on success, FALSE otherwise.