CGXGridCore::SetMergeCellsMode

void SetMergeCellsMode(WORD nMode, BOOL bRedraw = TRUE);

nMode

nMode can be one of:

  • gxnMergeDisable - Disable merging cells

  • gxnMergeDelayEval - Delay evaluation of merge cells (recommended)

  • gxnMergeEvalOnDisplay- Always evaluate cells before they are displayed (can be slow)
    combined with

  • gxnMergeHorzOnly - calculate only horizontal merge cells

  • gxnMergeVertOnly - calculate only vertical merge cells

  • gxnMergeOverHidden - skip hidden rows and columns when merging cells.
    If neither gxnMergeHorzOnly nor gxnMergeVertOnly is specified, cells will be merged both horizontally and vertically.

bRedraw

TRUE if grid shall be redrawn, FALSE if not.

Remarks

With SetMergeCellsMode you can turn on and off the calculation of merge cells in the grid.

Merge cells are cells that automatically join neighboring cells when both cells have the same value or style settings.

A very popular use for merge cells is the display of cross tables or other reports where the information is grouped by different categories.

For example, if you have report like


 Year Month Value
  1997 Jan 5
  1997 Feb 4
  1997 Mar 4
  1997 Apr 2
  1997 Jun 8
  ....

with merge cells, the year will only be displayed as one big cell and not repeated for every row.

How can I use merge cells?

To enable merge cells, add the following line in your view class

SetMergeCellsMode(nMode);

nMode can be one of:

  • gxnMergeDisable - Disable merging cells

  • gxnMergeDelayEval - Delay evaluation of merge cells

  • gxnMergeEvalOnDisplay - Always reevaluate merge cells before they are displayed

combined with

  • gxnMergeHorzOnly - Cells can only be merged horizontally

  • gxnMergeVertOnly - Cells can only be merged vertically

If you want cells to merge both horizontally and vertically you should not specify gxnMergeHorzOnly or gxnMergeVertOnly.

?gxnMergeOverHidden - Use this flag if you want that hidden rows and columns should be ignored and merging cells should be possible over hidden cells.

You can enable/disable merging for individual cells with

CCGXStyle::SetMergeCell(nMode)

nMode can be one of:

  • GX_MERGE_DISABLED - don’t allow this cell to merge

  • GX_MERGE_HORIZONTAL - allow cell to merge horizontally

  • GX_MERGE_VERTICAL - allow cell to merge vertically

combined with

  • GX_MERGE_COMPVALUE - merge cells if they have the same value

  • GX_MERGE_COMPSTYLE - merge cells only if all style attributes are equal

Check out grisvw12.cpp in the gridapp sample application for an example with merge cells.

How does it work?

Merge cells work very much like floated cells and covered cells. The difference between merge cells and floated cells is that cells will only be joined into one big cell if both cells have the same value or style settings. Floated cells will only expand one cell when the text does not fit into the first cell and the neighboring cell is empty.

The difference between merge cells and covered cells is that you can still access and change the individual cells of the covered cell. For example, if cells A5 to A10 are joined together, you can still click and change cells in the range A5 to A10. If, for example, you change cell A8, the cell ranges will automatically be reevaluated, and the result is that A5 to A7 will be joined, A8 will be a single cell and A9 to A10 will be joined.

Example:


A5  - VALUE                  VALUE
A6  - VALUE                  VALUE
A7  - VALUE                  VALUE
A8  - VALUE  --> Change A8   NEW VALUE
A9  - VALUE                  VALUE
A10 - VALUE                  VALUE

A5 to A10 are --> Change A8  A5 to A7 are joined and
joined                       A9 to A10 are joined.

Merge cells have to be calculated depending on the value or style settings of neighboring cells. When you type text in a cell, the cells will automatically join if both cells have the same value.

As with floating cells, Objective Grid solves performance problems with reevaluating merge cells by delaying their evaluation until they are displayed. The user will not notice any delay when you change the style attributes of a column.

You can use merge cells in two modes:

  • gxnMergeDelayEval - Delays evaluation of merge cells and stores the merge cell information in the grid. After a range of cells has been evaluated it will be marked as evaluated and will not be recalculated again (unless the user changes the column again or performs any other operation).

  • gxnMergeEvalOnDisplay - Always evaluates cells before they are displayed. Evaluated ranges will not be marked in the grid and will always be reevaluated before the grid displays those ranges.

gxnMergeDelayEval improves performance a lot and is recommended.

gxnMergeEvalOnDisplay has the advantage that you don’t have to worry about marking cells to be reevaluated when you use the grid by overriding GetStyleRowCol, and the values of the cells can change without notification to the grid.

With gxnMergeDelayEval, the method DelayMergeCells is called to mark ranges of cells to be reevaluated when they will be displayed in the grid:

Typical reasons for calling this function are

·When you want all cells to be reevaluated:

DelayMergeCells(CGXRange().SetTable());

·When you want some specific columns to be reevaluated:

DelayMergeCells(CGXRange().SetCols(nFromCol, nToCol+1));

All grid operations (changing the styles of cells, inserting, removing or dragging columns or rows, etc.) take care of properly calling DelayMergeCells. You will have to call this function very rarely.

The evaluation of merge cells is done on demand with the method EvalMergeCells when the user scrolls though the grid.

EvalMergeCells checks the given range if there are cells to be reevaluated and will then mark these cells so that they will not be reevaluated again.

To check if a specific cell is a merged cell, you can call GetMergeCellsRowCol.

If you want to check if a specific cell is a spanned cell, no matter whether it is covered, floated or merged, you can call GetCellRangeRowCol.

Tip

If you want to group several columns in a report, there may be the problem that the second column should only merge when the first column is equal.

In the following example, column 2 of the last two rows will be merged, but this is often unwanted behavior:

Year Month Day
  1997 Jan 5
  1997 Jan 5
  1997 Jan 5
  1997 Feb 4
  1997 Feb 4
  1998 Feb 4

To avoid this behavior, you can override GetStyleRowCol, and for all cells in column 2, assign the value of column 1 to a custom user attribute in column 2, e.g,. IDS_UA_YEAR. Then, Objective Grid will only merge the two cells if both the year and the month are equal.

Example:

void CMyGrid::GetStyleRowCol(ROWCOL nRow, ROWCOL nCol, CGXStyle& style, GXModifyType mt, int nType)
{
   if (!CGXGridCore::GetStyleRowCol(nRow, nCol, style, mt, nType))
      return FALSE;
   if (nRow > 0 && nCol == 2)
   {
      style.SetUserAttribute(IDS_UA_YEAR, GetValueRowCol(nRow, 1));
      style.SetMergeCell(GX_MERGE_VERTICAL|GX_MERGE_COMPSTYLE);
   }
   return TRUE;
}

Control-Factory Specific ->

This method has been implemented using the abstraction mechanism as discussed in the chapter "Reducing the size of your application" in the user's guide. A call to the ImplementMergeCells method from within the control factory class' InitializeGridComponents method will make the concrete implementation of this method available to your application.

If no concrete implementation is available this method performs no action. A warning will be displayed in the debug window.

END Control-Factory Specific

See Also

 CGXGridCore::GetMergeCellsMode  CGXGridCore::DelayMergeCells  CGXGridCore::EvalMergeCells  CGXGridCore::GetMergedCellsRowCol  CGXGridCore::GetCellRangeRowCol  CGXStyle::SetMergeCell  CGXStyle::SetFloodCell  CGXControl::CanMergeCell

CGXGridCore

 Class Overview |  Class Members