Group and Outline

Add outline by group rows or columns

29 (1)
To add outline on rows or columns:

sheet.AddOutline(RowOrColumn.Row, 3, 5);      // group rows from 3, number of rows is 5
sheet.AddOutline(RowOrColumn.Column, 5, 2);   // group columns

Note: AddOutline may throw the following exceptions:

  • OutlineIntersectedException – when the outline to be added, intersects with another one which was already on the worksheet.
  • OutlineAlreadyDefinedException – when the outline to be added,  same to another one which was already on the worksheet.
  • OutlineTooMuchException – when the number of levels of outline reached the maximum available levels 10.
  • OutlineOutOfRangeException – when the position specified to create an outline, which outs of the available range of the worksheet. (p.s. since that outline needs a thumb for collapsing and expanding, the last row and last column on the worksheet cannot be grouped into any outlines.

Collapse and Expand outlines

The AddOutline method returns the instance of an outline, which has two methods.

var outline = sheet.AddOutline(RowOrColumn.Row, 3, 5);
outline.Collapse();    // collapse
outline.Expand();      // expand

Or directly call CollapseOutline and ExpandOutline method of the control, then pass the position to specify which outline should be changed.

sheet.CollapseOutline(RowOrColumn.Row, 3, 5);
sheet.ExpandOutline(RowOrColumn.Row, 3, 5);

Note: These methods above may throw the OutlineNotFoundException when no outline was found at the specified position (in this example, it must start at row 3, and the number of rows must be 5).

Remove outlines by ungrouping rows or columns

To remove an outline, use the RemoveOutline method.

sheet.RemoveOutline(RowOrColumn.Row, 3, 5);

Note: RemoveOutline may throw the OutlineNotFoundException when no outline was found from the specified position.

There is another method ClearOutlines which can be used to remove all outlines from a worksheet, Use RowOrColumn enumerator to decide what type of outline should be removed.

sheet.ClearOutlines(RowOrColumn.Row);

Auto Collapse and Expanding

If an expanded outline, which attaching to (ending at) the row has been hidden, or height of the row has set to zero, the outline will be collapsed automatically. If any rows which are grouped by a collapsed outline is visible, or the height of row has set to non-zero, the outline will be expanded automatically. This behavior cannot be disabled, but the event of collapsing/expanding for outlines will be fired.

Outline

After adjusting the height of the rows:

Outline Auto Hide

Auto Remove

If an outline, which attaches to the rows or columns are all removed, this outline will be removed automatically. This behavior cannot be disabled, but the event of OutlineRemoved will be fired.

Event of outline

When an outline has been added or removed, the following two events of the worksheet will be fired.

sheet.OutlineAdded += (s, e) => MessageBox.Show(
     "outline added from " + e.Outline.Start + " to " + e.Outline.End);
sheet.OutlineRemoved += (s, e) => MessageBox.Show(
     "outline removed from " + e.Outline.Start + " to " + e.Outline.End);

Since remove rows will automatically remove the outlines associated with the rows, the OutlineRemoved event also will be raised.

sheet.DeleteRows(4, 5);

After the code above executed, the message will be displayed:

outline removed from 5 to 3

Both instances of outline and worksheet provide the event to handle the operation of collapse/expand from an outline.

var outline = sheet.AddOutline(RowOrColumn.Column, 1, 3);

// event from instance
outline.BeforeCollapse += (s, e) => MessageBox.Show("before collapse");
outline.BeforeExpand += (s, e) => MessageBox.Show("before expand");
outline.AfterCollapse += (s, e) => MessageBox.Show("after collapse");
outline.AfterExpand += (s, e) => MessageBox.Show("after expand");

// event from control
sheet.BeforeOutlineCollapse += (s, e) => MessageBox.Show("worksheet - before collapse");
sheet.AfterOutlineCollapse += (s, e) => MessageBox.Show("worksheet - after collapse");
sheet.BeforeOutlineExpand += (s, e) => MessageBox.Show("worksheet - before expand");
sheet.AfterOutlineExpand += (s, e) => MessageBox.Show("worksheet - after expand");

Like other before-event of ReoGrid, there is a property called IsCancelled that can be set to true to prevent the action of event.

// prevent collapse or expand by set IsCancelled as true
sheet.BeforeOutlineCollapse += (s, e) => e.IsCancelled = true;

For all the events of control, see Events.

Hide outline interface panel

It is possible to hide the user interface of outlines to prevent outline operations from end-user. By programming to access the instance of outline to perform actions such as collapsing or expanding.

// allow or not to show both row and column outlines
sheet.SetSettings(ReoGridSettings.View_AllowShowOutlines, false);

// add outline 1 and collapse it
var outline1 = grid.AddOutline(RowOrColumn.Row, 1, 3);
outline1.Collapse();

// add outline 2 and collapse it
var outline2 = grid.AddOutline(RowOrColumn.Row, 5, 2);
outline2.Collapse();

Custom Header
Anytime to show the outline interface panel, set the setting to true.

sheet.SetSettings(ReoGridSettings.View_AllowShowOutlines, true);

Learn about how to add check-boxes, see Built-in Cell Types.


Next: Column filter & sort