Table (data model for grid control) More...

Data Structures
struct	MC_TABLECELL
	Structure describing a table cell. More...
Defines
Table Flags
See also: mcTable_Create()
#define	MC_TF_NOCELLFOREGROUND 0x00000001
	If set, the table does not store foreground colors for each cell.
#define	MC_TF_NOCELLBACKGROUND 0x00000002
	If set, the table does not store background colors for each cell.
#define	MC_TF_NOCELLFLAGS 0x00000004
	If set, the table does not store flags for each cell.
MC_TABLECELL::fMask Bits

#define	MC_TCM_VALUE 0x00000001
	Set if MC_TABLECELL::hType and MC_TABLECELL::hValue are valid.
#define	MC_TCM_FOREGROUND 0x00000002
	Set if MC_TABLECELL::crForeground is valid.
#define	MC_TCM_BACKGROUND 0x00000004
	Set if MC_TABLECELL::crBackground is valid.
#define	MC_TCM_FLAGS 0x00000008
	Set if MC_TABLECELL::dwFlags is valid.
MC_TABLECELL::dwFlags Bits

#define	MC_TCF_ALIGNDEFAULT 0x00000000
	Paint the cell value aligned horizontally as default for the value type.
#define	MC_TCF_ALIGNLEFT 0x00000001
	Paint the cell value aligned horizontally to left.
#define	MC_TCF_ALIGNCENTER 0x00000003
	Paint the cell value aligned horizontally to center.
#define	MC_TCF_ALIGNRIGHT 0x00000002
	Paint the cell value aligned horizontally to right.
#define	MC_TCF_ALIGNVDEFAULT 0x00000000
	Paint the cell value aligned vertically as normal for the value type.
#define	MC_TCF_ALIGNTOP 0x00000004
	Paint the cell value aligned vertically to top.
#define	MC_TCF_ALIGNVCENTER 0x0000000C
	Paint the cell value aligned vertically to center.
#define	MC_TCF_ALIGNBOTTOM 0x00000008
	Paint the cell value aligned vertically to bottom.
Typedefs
typedef void *	MC_HTABLE
	Opaque table handle.
Functions
MC_HTABLE MCTRL_API	mcTable_Create (WORD wColumnCount, WORD wRowCount, MC_HVALUETYPE hType, DWORD dwFlags)
	Create new table.
void MCTRL_API	mcTable_AddRef (MC_HTABLE hTable)
	Increment reference counter of the table.
void MCTRL_API	mcTable_Release (MC_HTABLE hTable)
	Decrement reference counter of the table.
WORD MCTRL_API	mcTable_ColumnCount (MC_HTABLE hTable)
	Retrieve count of table columns.
WORD MCTRL_API	mcTable_RowCount (MC_HTABLE hTable)
	Retrieve count of table rows.
BOOL MCTRL_API	mcTable_Resize (MC_HTABLE hTable, WORD wColumnCount, WORD wRowCount)
	Resize the table.
void MCTRL_API	mcTable_Clear (MC_HTABLE hTable)
	Clear the table.
BOOL MCTRL_API	mcTable_SetCell (MC_HTABLE hTable, WORD wCol, WORD wRow, MC_HVALUETYPE type, MC_HVALUE value)
	Set contents of a cell.
BOOL MCTRL_API	mcTable_GetCell (MC_HTABLE hTable, WORD wCol, WORD wRow, MC_HVALUETYPE phType, MC_HVALUE phValue)
	Get contents of a cell.
BOOL MCTRL_API	mcTable_SetCellEx (MC_HTABLE hTable, WORD wCol, WORD wRow, MC_TABLECELL *pCell)
	Set contents of a cell.
BOOL MCTRL_API	mcTable_GetCellEx (MC_HTABLE hTable, WORD wCol, WORD wRow, MC_TABLECELL *pCell)
	Get contents of a cell.

Detailed Description

Table (data model for grid control)

The table is actually a container which manages set of values (MC_HVALUE) 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, and optionally also what other attributes the table won't store.

Using homogenous table and/or setting one or more of those flags can be used to save some memory if you know your application never sets certain attributes of table cells.

If application sets some of such flags (e.g. MC_TF_NOCELLFOREGROUND) and later it attempts to set he corresponding attribute of the cell (e.g. foreground color), the behavior is undefined (setting of some attributes is silantly ignored, or the operation as a whole can fail but application should not rely on exact behavior).

If appplication attemps to insert a value of another type into a homogenous table expecting other value type, the operation fails.

Homogenous tables

Homogenous tables can hold only values of the same type (MC_HVALUETYPE), specified during creation of the table. Homogenous table is less memory consuming, as it just holds MC_HVALUE 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.

Heterogenous tables

When NULL is used as the value type during table creation, then a heterogenous table is created.

Heterogenous table holds pair of MC_HVALUETYPE and MC_HVALUE 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().

Function Documentation

MC_HTABLE MCTRL_API mcTable_Create	(	WORD	wColumnCount,
		WORD	wRowCount,
		MC_HVALUETYPE	hType,
		DWORD	dwFlags
	)

Create new table.

The table is initially empty and has its reference counter set to 1.

Parameters:

[in]	wColumnCount	Column count.
[in]	wRowCount	Row count.
[in]	hType	Type of all cells for homogenous table, or `NULL` for heterogenous table.
[in]	dwFlags	Table flags. See MC_TF_xxxx.

Returns:: Handle of the new table or NULL on failure.

void MCTRL_API mcTable_AddRef ( MC_HTABLE hTable )

Increment reference counter of the table.

Parameters:

[in] hTable The table.

void MCTRL_API mcTable_Release ( MC_HTABLE hTable )

Decrement reference counter of the table.

If the reference counter drops to zero, all resources allocated for the table are released.

Parameters:

[in] hTable The table.

WORD MCTRL_API mcTable_ColumnCount ( MC_HTABLE hTable )

Retrieve count of table columns.

Parameters:

[in] hTable The table.

Returns:: The count.

WORD MCTRL_API mcTable_RowCount ( MC_HTABLE hTable )

Retrieve count of table rows.

Parameters:

[in] hTable The table.

Returns:: The count.

BOOL MCTRL_API mcTable_Resize	(	MC_HTABLE	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).

Parameters:

[in]	hTable	The table.
[in]	wColumnCount	Column count.
[in]	wRowCount	Row count.

Returns:: TRUE on success, FALSE otherwise.

void MCTRL_API mcTable_Clear ( MC_HTABLE 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.

Parameters:

[in] hTable The table.

BOOL MCTRL_API mcTable_SetCell	(	MC_HTABLE	hTable,
		WORD	wCol,
		WORD	wRow,
		MC_HVALUETYPE	type,
		MC_HVALUE	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.

Parameters:

[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.

Returns:: TRUE on success, FALSE otherwise.

See also:: mcTable_SetCellEx

BOOL MCTRL_API mcTable_GetCell	(	MC_HTABLE	hTable,
		WORD	wCol,
		WORD	wRow,
		MC_HVALUETYPE *	phType,
		MC_HVALUE *	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.

Parameters:

[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.

Returns:: TRUE on success, FALSE otherwise.

BOOL MCTRL_API mcTable_SetCellEx	(	MC_HTABLE	hTable,
		WORD	wCol,
		WORD	wRow,
		MC_TABLECELL *	pCell
	)

Set contents of a cell.

If pCell->fMask includes the bit MC_TCM_VALUE, then (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 then destroyed.

Parameters:

[in]	hTable	The table.
[in]	wCol	Column index.
[in]	wRow	Row index.
[in]	pCell	Specifies attributes of the cell to set.

Returns:: TRUE on success, FALSE otherwise.

See also:: mcTable_SetCell

BOOL MCTRL_API mcTable_GetCellEx	(	MC_HTABLE	hTable,
		WORD	wCol,
		WORD	wRow,
		MC_TABLECELL *	pCell
	)

Get contents of a cell.

Before calling this function, the member pCell->fMask must specify what members of the structure to retrieve.

Parameters:

[in]	hTable	The table.
[in]	wCol	Column index.
[in]	wRow	Row index.
[out]	pCell	Specifies retrieved attributes of the cell.

Returns:: TRUE on success, FALSE otherwise.

See also:: mcTable_GetCell

mCtrl/table.h File Reference

Data Structures

Defines

Typedefs

Functions

Detailed Description

Homogenous tables

Heterogenous tables

Function Documentation