mCtrl  0.9.8
Data Structures | Macros | Typedefs
table.h File Reference

Go to the source code of this file.

Detailed Description

Table (data model for grid control)

The table is actually a container which manages set of values arranged in a two-dimensional matrix. It serves as a back-end for the grid control (MC_WC_GRID).

Cell

To set or get an information about a cell, application uses the structure MC_TABLECELL. The main data associated with each cell is a text (string) or value (MC_HVALUE). Note the cell can only hold one or the other, but not both.

When the cell is holding a string and an application sets the cell to a value, the string is freed. When the cell is holding a value and app sets the cell to a string, then the value is destroyed. The cell holds whatever is set last to it. Any attempt to set both at the same time (i.e. using mask MC_TCMF_TEXT | MC_TCMF_VALUE with a setter function) causes a failure of the setter function.

When getting a cell and the mask MC_TCMF_TEXT | MC_TCMF_VALUE is used, then on output either MC_TABLECELL::pszText or MC_TABLECELL::hValue is NULL, depending on what the cell holds. (Both can be NULL if the cell does not neither string nor value.)

Column and Row Headers

The table also holds a cell for each column and row. The grid uses data of these cells as headers for columns and rows (with its default styles; the control provides some styles changing this behavior).

The cells are manipulated the same way as ordinary cells. Just to address the header cells, the macro MC_TABLE_HEADER has to be used instead of column index (for row header) or row index (for column header).

Data Structures

struct  MC_TABLECELLW
 Structure describing a table cell (Unicode variant). More...
 
struct  MC_TABLECELLA
 Structure describing a table cell (ANSI variant). More...
 

Macros

#define MC_TABLE_HEADER   0xffff
 ID of column/row headers. More...
 

Typedefs

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

MC_TABLECELL::fMask Bits

#define MC_TCMF_TEXT   0x00000001
 Set if MC_TABLECELLW::pszText or MC_TABLECELLA::pszText is valid. More...
 
#define MC_TCMF_VALUE   0x00000002
 Set if MC_TABLECELLW::hValue or MC_TABLECELLA::hValue is valid. More...
 
#define MC_TCMF_PARAM   0x00000004
 Set if MC_TABLECELLW::lParam or MC_TABLECELLA::lParam is valid. More...
 
#define MC_TCMF_FLAGS   0x00000008
 Set if MC_TABLECELLW::dwFlags or MC_TABLECELLA::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, DWORD dwWhat)
 Clear the table. More...
 
BOOL mcTable_SetCellW (MC_HTABLE hTable, WORD wCol, WORD wRow, MC_TABLECELLW *pCell)
 Set contents of a cell (Unicode variant). More...
 
BOOL mcTable_SetCellA (MC_HTABLE hTable, WORD wCol, WORD wRow, MC_TABLECELLA *pCell)
 Set contents of a cell (ANSI variant). More...
 
BOOL mcTable_GetCellW (MC_HTABLE hTable, WORD wCol, WORD wRow, MC_TABLECELLW *pCell)
 Get contents of a cell (Unicode variant). More...
 
BOOL mcTable_GetCellA (MC_HTABLE hTable, WORD wCol, WORD wRow, MC_TABLECELLA *pCell)
 Get contents of a cell (ANSI variant). More...
 

Unicode Resolution

#define MC_TABLECELL   MCTRL_NAME_AW(MC_TABLECELL)
 
#define mcTable_SetCell   MCTRL_NAME_AW(mcTable_SetCell)
 
#define mcTable_GetCell   MCTRL_NAME_AW(mcTable_GetCell)
 

Data Structure Documentation

struct MC_TABLECELLW

Structure describing a table cell (Unicode variant).

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

Bitmask specifying what other members are valid. See MC_TCMF_xxxx.

WCHAR * pszText

Cell text.

See Also
Cell
int cchTextMax

Number of characters in pszText. Used only on output.

MC_HVALUE hValue

Cell value.

See Also
Cell
LPARAM lParam

User data.

DWORD dwFlags

Cell flags. See MC_TCF_xxxx.

struct MC_TABLECELLA

Structure describing a table cell (ANSI variant).

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

Bitmask specifying what other members are valid. See MC_TCMF_xxxx.

char * pszText

Cell text.

See Also
Cell
int cchTextMax

Number of characters in pszText. Used only on output.

MC_HVALUE hValue

Cell value.

See Also
Cell
LPARAM lParam

User data.

DWORD dwFlags

Cell flags. See MC_TCF_xxxx.

Macro Definition Documentation

#define MC_TABLE_HEADER   0xffff

ID of column/row headers.

To set or get a contents of column or row header, specify this constant as row/column index.

For example, to set value label of a column identified with wCol:

mcTable_SetCell(hTable, wCol, MC_TABLE_HEADER, pCell);
#define MC_TCMF_TEXT   0x00000001

Set if MC_TABLECELLW::pszText or MC_TABLECELLA::pszText is valid.

See Also
Cell
#define MC_TCMF_VALUE   0x00000002

Set if MC_TABLECELLW::hValue or MC_TABLECELLA::hValue is valid.

See Also
Cell
#define MC_TCMF_PARAM   0x00000004
#define MC_TCMF_FLAGS   0x00000008
#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.

#define MC_TABLECELL   MCTRL_NAME_AW(MC_TABLECELL)

Unicode-resolution alias.

See Also
MC_TABLECELLW MC_TABLECELLA
#define mcTable_SetCell   MCTRL_NAME_AW(mcTable_SetCell)

Unicode-resolution alias.

See Also
mcTable_SetCellW mcTable_SetCellA
#define mcTable_GetCell   MCTRL_NAME_AW(mcTable_GetCell)

Unicode-resolution alias.

See Also
mcTable_GetCellW mcTable_GetCellA

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]wColumnCountColumn count.
[in]wRowCountRow count.
dwReservedReserved. 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]hTableThe 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]hTableThe table.
WORD mcTable_ColumnCount ( MC_HTABLE  hTable)

Retrieve count of table columns.

Parameters
[in]hTableThe table.
Returns
The count.
WORD mcTable_RowCount ( MC_HTABLE  hTable)

Retrieve count of table rows.

Parameters
[in]hTableThe 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]hTableThe table.
[in]wColumnCountColumn count.
[in]wRowCountRow count.
Returns
TRUE on success, FALSE otherwise.
void mcTable_Clear ( MC_HTABLE  hTable,
DWORD  dwWhat 
)

Clear the table.

Clears all cells of the table satisfying the condition as specified by dwWhat.

Parameters
[in]hTableThe table.
[in]dwWhatSpecification of the cells to be cleared. When set to zero, all table contents (including header cells) is cleared. When non-zero, the value is interpreted as a bit-mask of cells to clear: Set bit 0x1 to clear all ordinary cells, 0x2 to clear column headers and bit 0x4 to clear row cells.
BOOL mcTable_SetCellW ( MC_HTABLE  hTable,
WORD  wCol,
WORD  wRow,
MC_TABLECELLW pCell 
)

Set contents of a cell (Unicode variant).

Parameters
[in]hTableThe table.
[in]wColColumn index.
[in]wRowRow index.
[in]pCellSpecifies attributes of the cell to set.
Returns
TRUE on success, FALSE otherwise.
BOOL mcTable_SetCellA ( MC_HTABLE  hTable,
WORD  wCol,
WORD  wRow,
MC_TABLECELLA pCell 
)

Set contents of a cell (ANSI variant).

Parameters
[in]hTableThe table.
[in]wColColumn index.
[in]wRowRow index.
[in]pCellSpecifies attributes of the cell to set.
Returns
TRUE on success, FALSE otherwise.
BOOL mcTable_GetCellW ( MC_HTABLE  hTable,
WORD  wCol,
WORD  wRow,
MC_TABLECELLW pCell 
)

Get contents of a cell (Unicode variant).

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

Parameters
[in]hTableThe table.
[in]wColColumn index.
[in]wRowRow index.
[out]pCellSpecifies retrieved attributes of the cell.
Returns
TRUE on success, FALSE otherwise.
BOOL mcTable_GetCellA ( MC_HTABLE  hTable,
WORD  wCol,
WORD  wRow,
MC_TABLECELLA pCell 
)

Get contents of a cell (ANSI variant).

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

Parameters
[in]hTableThe table.
[in]wColColumn index.
[in]wRowRow index.
[out]pCellSpecifies retrieved attributes of the cell.
Returns
TRUE on success, FALSE otherwise.