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

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 silently ignored, or the operation as a whole can fail but application should not rely on exact behavior).

Data Structures
struct	MC_TABLECELL
	Structure describing a table cell. More...

Typedefs
typedef void *	MC_HTABLE
	Opaque table handle. More...

MC_TABLECELL::fMask Bits

#define	MC_TCMF_VALUE 0x00000001
	Set if MC_TABLECELL::hValue are valid. More...

#define	MC_TCMF_FOREGROUND 0x00000002
	Set if MC_TABLECELL::crForeground is valid. More...

#define	MC_TCMF_BACKGROUND 0x00000004
	Set if MC_TABLECELL::crBackground is valid. More...

#define	MC_TCMF_FLAGS 0x00000008
	Set if MC_TABLECELL::dwFlags is valid. More...

MC_TABLECELL::dwFlags Bits

#define	MC_TCF_ALIGNDEFAULT 0x00000000
	Paint the cell value aligned horizontally as default for the value type. More...

#define	MC_TCF_ALIGNLEFT 0x00000001
	Paint the cell value aligned horizontally to left. More...

#define	MC_TCF_ALIGNCENTER 0x00000003
	Paint the cell value aligned horizontally to center. More...

#define	MC_TCF_ALIGNRIGHT 0x00000002
	Paint the cell value aligned horizontally to right. More...

#define	MC_TCF_ALIGNVDEFAULT 0x00000000
	Paint the cell value aligned vertically as normal for the value type. More...

#define	MC_TCF_ALIGNTOP 0x00000004
	Paint the cell value aligned vertically to top. More...

#define	MC_TCF_ALIGNVCENTER 0x0000000C
	Paint the cell value aligned vertically to center. More...

#define	MC_TCF_ALIGNBOTTOM 0x00000008
	Paint the cell value aligned vertically to bottom. More...

Functions
MC_HTABLE	mcTable_Create (WORD wColumnCount, WORD wRowCount, DWORD dwReserved)
	Create new table. More...

void	mcTable_AddRef (MC_HTABLE hTable)
	Increment reference counter of the table. More...

void	mcTable_Release (MC_HTABLE hTable)
	Decrement reference counter of the table. More...

WORD	mcTable_ColumnCount (MC_HTABLE hTable)
	Retrieve count of table columns. More...

WORD	mcTable_RowCount (MC_HTABLE hTable)
	Retrieve count of table rows. More...

BOOL	mcTable_Resize (MC_HTABLE hTable, WORD wColumnCount, WORD wRowCount)
	Resize the table. More...

void	mcTable_Clear (MC_HTABLE hTable)
	Clear the table. More...

BOOL	mcTable_SetValue (MC_HTABLE hTable, WORD wCol, WORD wRow, MC_HVALUE value)
	Set value. More...

const MC_HVALUE	mcTable_GetValue (MC_HTABLE hTable, WORD wCol, WORD wRow)
	Get value. More...

MC_HVALUE	mcTable_SwapValue (MC_HTABLE hTable, WORD wCol, WORD wRow, MC_HVALUE value)
	Swap contents of a cell. More...

BOOL	mcTable_SetCell (MC_HTABLE hTable, WORD wCol, WORD wRow, MC_TABLECELL *pCell)
	Set contents of a cell. More...

BOOL	mcTable_GetCell (MC_HTABLE hTable, WORD wCol, WORD wRow, MC_TABLECELL *pCell)
	Get contents of a cell. More...

Data Structure Documentation

struct MC_TABLECELL

Structure describing a table cell.

Note that only members corresponding to the set bits of the fMask are considered valid. (fMask itself is always valid of course.)

See Also: mcTable_SetCell mcTable_GetCell

Data Fields
DWORD	fMask	Bit-mask specifying what other members are valid. See MC_TCMF_xxxx.
MC_HVALUE	hValue	Cell value.
COLORREF	crForeground	Foreground color. It's up to the value type if it respects it.
COLORREF	crBackground	Background color.
DWORD	dwFlags	Cell flags. See MC_TCF_xxxx.

Macro Definition Documentation

#define MC_TCMF_VALUE 0x00000001

Set if MC_TABLECELL::hValue are valid.

#define MC_TCMF_FOREGROUND 0x00000002

Set if MC_TABLECELL::crForeground is valid.

#define MC_TCMF_BACKGROUND 0x00000004

Set if MC_TABLECELL::crBackground is valid.

#define MC_TCMF_FLAGS 0x00000008

Set if MC_TABLECELL::dwFlags is valid.

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

Typedef Documentation

typedef void* MC_HTABLE

Opaque table handle.

Function Documentation

MC_HTABLE mcTable_Create	(	WORD	wColumnCount,
		WORD	wRowCount,
		DWORD	dwReserved
	)

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.
	dwReserved	Reserved. Set to zero.

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

void mcTable_AddRef ( MC_HTABLE hTable)

Increment reference counter of the table.

Parameters

[in] hTable The table.

void 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 mcTable_ColumnCount ( MC_HTABLE hTable)

Retrieve count of table columns.

Parameters

[in] hTable The table.

Returns: The count.

WORD mcTable_RowCount ( MC_HTABLE hTable)

Retrieve count of table rows.

Parameters

[in] hTable The table.

Returns: The count.

BOOL 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 heterogeneous table) or to NULL values (for homogeneous table).

Parameters

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

Returns: TRUE on success, FALSE otherwise.

void mcTable_Clear ( MC_HTABLE hTable)

Clear the table.

All values are destroyed. In case of homogeneous table, all cells are reset to NULL values of the particular value type, in case of homogeneous table the table becomes empty.

Parameters

[in] hTable The table.

BOOL mcTable_SetValue	(	MC_HTABLE	hTable,
		WORD	wCol,
		WORD	wRow,
		MC_HVALUE	value
	)

Set value.

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 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]	value	The value.

Returns: TRUE on success, FALSE otherwise.

const MC_HVALUE mcTable_GetValue	(	MC_HTABLE	hTable,
		WORD	wCol,
		WORD	wRow
	)

Get value.

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.

Returns: Value of the cell, or NULL on failure.

MC_HVALUE mcTable_SwapValue	(	MC_HTABLE	hTable,
		WORD	wCol,
		WORD	wRow,
		MC_HVALUE	value
	)

Swap contents of a cell.

This function swaps value of the cell for the one provided. The table becomes responsible for the new cell, while the application gets responsibility for the returned value in the exchange.

Parameters

[in]	hTable	The table.
[in]	wCol	Column index.
[in]	wRow	Row index.
[in]	value	The new value of the cell.

Returns: The previous value of the cell, or NULL on failure.

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

Set contents of a cell.

If pCell->fMask includes the bit MC_TCMF_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.

BOOL mcTable_GetCell	(	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 attributes of the cell 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.

Detailed Description

Data Structures

Typedefs

MC_TABLECELL::fMask Bits

MC_TABLECELL::dwFlags Bits

Functions

Data Structure Documentation

Macro Definition Documentation

Typedef Documentation

Function Documentation