Detailed Description

Grid control (MC_WC_GRID).

The grid control provides user interface for presentation of a lot of data in, as the name of the control suggests, a grid.

Data Model

By default, the control uses MC_HTABLE data model to manage the data displayed by the control. Then, actually, all messages manipulating with data hold by the control just call corresponding function manipulating with the underlying MC_HTABLE.

By default, the control creates an empty table during its creation, of size 0 x 0. So, usually, one of the first messages sent to the control by any application is MC_GM_RESIZE.

Alternatively, you can use the style MC_GS_NOTABLECREATE. In that case the control does not create any table during its creation, and you must associate an existing table with the control with the message MC_GM_SETTABLE. Until you do so, all messages attempting to modify the underlying table will just fail.

Messages which do not manipulate with the table determine how the table is presented and these are tied to the control. I.e. if any table is attached to multiple control, each of the controls can present the table in other way (e.g. have another dimensions for each cell etc.).

Virtual Grid

The grid can defer management of the data to the parent window instead of using the MC_HTABLE. To do this, application has to apply the style MC_GS_OWNERDATA.

The control then uninstalls any table currently associated with it (if any), and whenever painting a cell, it asks its parent for the data it needs. The control uses the notification MC_GN_GETDISPINFO to retrieve the data.

The virtual grid is especially useful to present data calculated on the fly or retrieved from some large database, so that only the required amount of the data is calculated and retrieved, which can result in saving a lot of memory and CPU cycles.

The control actually only remembers dimensions of the virtual table as set by MC_GM_RESIZE.

If the retrieval of the data is expensive operation, the application may want to implement some caching scheme. For this purpose the control sends the notification MC_GN_ODCACHEHINT, which informs the application about the region of cells it may ask most frequently. Note however the control is free to ask for any cell, not just the one included in the range as specified by the latest MC_GN_ODCACHEHINT.

To force repainting of one or more items, when the underlying data change, the application is supposed to use the message MC_GM_REDRAWCELLS.

Please remember that when the style MC_GS_OWNERDATA is used, some control messages and styles behave differently:

Message MC_GM_RESIZE does not resize a table associated with the control but only informs the control how large the virtual table is (and application then has to be ready to provide data for any cell within the dimensions).

Column and Row Headers

The application can manipulate also with headers of columns and rows. For many purposes, the control treats them as any ordinary cells, but of course there are also differences.

The header cells have to be addressed by special index MC_TABLE_HEADER. Column header uses index of the column of interest and row index MC_TABLE_HEADER and, similarly, row header uses column header MC_TABLE_HEADER and the row index.

For example, to get or set contents of header cells, the application can use exactly the same messages as for ordinary cells, i.e. messages MC_GM_GETCELL and MC_GM_SETCELL respectively, where one of the indexes is set to MC_TABLE_HEADER.

Selection

The grid control supports four distinct selection modes. These modes determine how the cells may or may not be selected:

With style MC_GS_NOSEL, selection is disabled altogether and no cell can be selected. This is default.

With style MC_GS_SINGLESEL, only single cell may be selected at any time.

With style MC_GS_RECTSEL, only a set of cells which form a block of rectangular shape may be selected.

With style MC_GS_COMPLEXSEL, any set of cells, even discontinuous one, may be selected.

The mode influences how the control reacts on mouse and keyboard events with respect to the selection, and also how the control processes various selection related messages and notifications.

Note that the selection may also be changed with keyboard only if the style ref MC_GS_FOCUSEDCELL is also used.

Focused Cell

With the style MC_GS_FOCUSEDCELL, the control supports a cell focus. Then, exactly one cell has a status of the focused cell.

Certain aspects of control behavior change when the style is enabled:

The focused cell has a focus rectangle painted around it (if the control has focus).

Navigation keys (like arrow keys, page up/down, home/end etc.) move the focus from a given cell to another one, as appropriate to the given key. (When the style is not used the keys translate directly to a scrolling action.)

Depending on the selection mode, the style MC_GS_FOCUSEDCELL enables changing the current selection with keyboard.

Cell Label Editing

When the style MC_GS_EDITLABELS is enabled, user can edit cell labels. The editing is started when user clicks on the focused cell, when user presses ENTER, or when the application explicitly sends the message MC_GM_EDITLABEL.

When the label editing starts, application gets the notification MC_GN_BEGINLABELEDIT which allows it to suppress the editing mode, or to customize the embedded edit window. The code handling the notification may use the message MC_GM_GETEDITCONTROL to retrieve handle of the edit control.

Likewise, when the edit mode ends, the application gets the notification MC_GN_ENDLABELEDIT, which allows the application to accept or reject the new text for the label.

If it is accepted by returning non-zero from the notification, the control saves the new text label within the table or it tells the parent to remember it via MC_GN_SETDISPINFO if the parent maintains the table or cell contents (this happens when the control uses the style MC_GS_OWNERDATA or when the cell uses the magic value MC_LPSTR_TEXTCALLBACK).

Gets handle of table attached to the control or NULL if none is attached.

Note that calling the message does not change reference counter of the returned table. If you want to preserve the handle, you should call mcTable_AddRef() on it and then mcTable_Release() when you no longer need it.

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

Application does not provide any buffer. In this case the application has to set MC_GSELECTION::uDataCount to (UINT)-1. Instead of copying, the control sets MC_GSELECTION::rcData to point into its internal buffer. In this mode application must not free or modify the contents of the internal buffer, and also it must not retain the pointer for later use as it may become invalid any time.

Parameters

wParam

Reserved, set to zero.

[in,out]

lParam

(MC_GSELECTION*) Pointer to structure to be filled by the control, or NULL. Application has initialize some members of the structure as described above.

Returns

(UINT) Count of rectangles required for MC_GSELECTION::rcData on success. Zero means the selection is empty.

If any edit operation is in progress, the message causes a notification MC_GN_ENDLABELEDIT to be sent.

Parameters

wParam

Reserved, set to zero.

lParam

Reserved, set to zero.

Returns

None.

#define MC_GN_ODCACHEHINT (MC_GN_FIRST + 0)

Notification providing a hint for data caching strategy for grids with virtual table.

The notification is sent only when the control has the style MC_GS_OWNERDATA. The notification informs the application about region of cells it is likely to ask for (via MC_GN_GETDISPINFO).

If the retrieval of assorted data by the application is slow (e.g. because it requires remote access to a database system), the application should cache locally the data for cells in the rectangular cell region as specified by the MC_NMGCACHEHINT.

The structure never specify header cells, however if the control has style MC_GS_COLUMNHEADERNORMAL and/or MC_GS_ROWHEADERNORMAL, it should also cache data needed for column/row headers corresponding for the cells in the region.

Fired when control needs to tell parent to update some cell data it manages (Unicode variant).

When sending the notification, the control sets MC_NMGDISPINFO::wColumn and MC_NMGDISPINFO::wRow to identify the cell. The control also sets MC_NMTLDISPINFO::cell::lParam (however if the style MC_GS_OWNERDATA is in effect, it is always set to zero).

The control specifies what members in MC_NMGDISPINFO::cell the application should remember with the MC_NMGDISPINFO::cell::fMask.

Fired when control needs to tell parent to update some cell data it manages (ANSI variant).

When sending the notification, the control sets MC_NMGDISPINFO::wColumn and MC_NMGDISPINFO::wRow to identify the cell. The control also sets MC_NMGDISPINFO::cell::lParam (however if the style MC_GS_OWNERDATA is in effect, it is always set to zero).

The control specifies what members in MC_NMGDISPINFO::cell the application should remember with the MC_NMGDISPINFO::cell::fMask.

When sending the notification, the control sets MC_NMGDISPINFO::wColumn and MC_NMGDISPINFO::wRow to identify the cell. The control also sets MC_NMGDISPINFO::cell::lParam (however if the style MC_GS_OWNERDATA is in effect, it is always set to zero).

The control specifies what members in MC_NMGDISPINFO::cell the application should fill with the MC_NMGDISPINFO::cell::fMask.

When sending the notification, the control sets MC_NMGDISPINFO::wColumn and MC_NMGDISPINFO::wRow to identify the cell. The control also sets MC_NMTLDISPINFO::cell::lParam (however if the style MC_GS_OWNERDATA is in effect, it is always set to zero).

The control specifies what members in MC_NMGDISPINFO::cell the application should fill with the MC_NMGDISPINFO::cell::fMask.

The control sets MC_NMGDISPINFO provided via LPARAM to describe change of the label. MC_NMGDISPINFO::wCol and wRow determine the cell. MC_NMGDISPINFO::cell::pszText is set to the new label or to NULL if the label editing is being canceled.

If MC_NMGDISPINFO::cell::pszText is not NULL, return TRUE to allow change of the label, FALSE to suppress it. If the pszText is NULL, the return value is ignored and no label change happens.

#define MC_GN_ENDLABELEDITA (MC_GN_FIRST + 20)

Fired when control is about to end label editing (ANSI variant).

The control sets MC_NMGDISPINFO provided via LPARAM to describe change of the label. MC_NMGDISPINFO::wCol and wRow determine the cell. MC_NMGDISPINFO::cell::pszText is set to the new label or to NULL if the label editing is being canceled.