GridX Grouping Engine

Overview

The GridX grouping engine provides multi-level nested grouping on any column in the data grid. Groups are rendered as collapsible header rows with summary aggregate rows (sum, avg, count, min, max) below each group. The engine supports up to N-levels of nested grouping — each new GroupDescriptor added creates a sub-group within the previous level.

Key classes:

GridGroupEngine (436 lines)

GridGroupEngine is the central coordinator attached to every BeepGridPro instance via the GroupEngine property. It owns the descriptor collection, the group tree, and delegates grouping logic to the injected IGridGrouper.

Methods

GroupDescriptor

GroupDescriptor defines one level of grouping. Multiple descriptors create a nested group hierarchy — e.g., {Country, City} produces Country groups with City sub-groups inside each.

GroupAggregate has properties: Function (enum: Sum, Average, Count, Min, Max), ColumnName (target numeric column), and DisplayFormat (e.g., "SUM: {0:N2}").

IGridGrouper

The grouping algorithm is abstracted behind IGridGrouper, enabling custom grouping logic injection. The built-in DefaultGridGrouper uses hash-based partitioning with stable sort order.

public interface IGridGrouper
{
    List<GridGroup> BuildGroups(
        IEnumerable dataSource,
        List<GroupDescriptor> descriptors,
        int level);

    List<GridGroup> BuildSubGroups(
        GridGroup parentGroup,
        List<GroupDescriptor> descriptors,
        int level);
}

DefaultGridGrouper uses PropertyDescriptor to access column values, groups by ColumnName using a Dictionary<object, List> partition, sorts groups by SortDirection, and recursively calls BuildSubGroups for each subsequent descriptor level. To inject a custom grouper:

grid.GroupEngine.Grouper = new MyCustomGrouper();

GridGroup Model

GridGroup is a tree node representing one group at any nesting level. Each group holds its child rows and optional sub-groups.

The group tree is built by a recursive walk: root-level Groups contain SubGroups which contain further SubGroups, with leaf Rows at the deepest level. A flattened view for rendering is computed by GetHeaderCountBeforeRow() and GetTotalHeightBeforeRow().

Group Header Rendering

GridGroupHeaderRenderer draws each group's visual header row. It renders:

• Chevron icon — Expandable/collapsible indicator (▶ collapsed, ▼ expanded) drawn at left margin with level-based indentation
• Group key + display value — Column name prefix + formatted value, e.g., "Country: USA"
• Item count — Number of leaf rows in this group, displayed as "(247 items)"
• Summary row — When ShowSummaryRow = true, an additional row below the group rows displays aggregate values (Sum, Avg, Count, Min, Max) per the Aggregates list

Header height varies by level: GetHeaderHeight(int level) returns the pixel height, defaulting to 32px for level 0 and 28px for deeper levels. The renderer respects theme tokens via GridThemeHelper for colors and fonts.

Sort-Within-Groups

Rows inside each group can be independently sorted without affecting group ordering. SortWithinGroups(columnName, direction) iterates all groups and sorts their Rows by the given column. SortGroupsByColumn(columnName, direction) reorders the groups themselves at the top level.

var engine = grid.GroupEngine;

engine.AddDescriptor(new GroupDescriptor("Country", SortDirection.Ascending));
engine.AddDescriptor(new GroupDescriptor("City", SortDirection.Ascending));

engine.SortWithinGroups("Population", SortDirection.Descending);

engine.SortGroupsByColumn("Country", SortDirection.Descending);

Sort direction uses the standard SortDirection enum (Ascending / Descending). When no sort is specified within groups, rows retain their original order from the data source.

Expand/Collapse

Each group can be independently collapsed or expanded. The engine provides both per-group and bulk operations:

When a parent group is collapsed, all its child rows and sub-groups are hidden from rendering. The GetTotalContentHeight() method accounts for collapse state — collapsed groups contribute only their header height to the scroll height. The GetHeaderCountBeforeRow() method skips collapsed sub-groups when computing flat-to-visual row mapping.

Examples

Two-Level Grouping with Aggregates

var engine = grid.GroupEngine;

engine.AddDescriptor(new GroupDescriptor
{
    ColumnName = "Category",
    SortDirection = SortDirection.Ascending,
    DisplayFormat = "Category: {0}",
    ShowSummaryRow = true,
    Aggregates =
    {
        new GroupAggregate { Function = AggregateFunction.Sum, ColumnName = "Sales", DisplayFormat = "Total: {0:C}" },
        new GroupAggregate { Function = AggregateFunction.Average, ColumnName = "Sales", DisplayFormat = "Avg: {0:C}" },
        new GroupAggregate { Function = AggregateFunction.Count, ColumnName = "ProductId", DisplayFormat = "Count: {0}" }
    }
});

engine.AddDescriptor(new GroupDescriptor
{
    ColumnName = "Region",
    SortDirection = SortDirection.Ascending,
    DisplayFormat = "Region: {0}",
    ShowSummaryRow = true,
    Aggregates =
    {
        new GroupAggregate { Function = AggregateFunction.Sum, ColumnName = "Sales", DisplayFormat = "Subtotal: {0:C}" }
    }
});

engine.ApplyGrouping();

Collapse All, Then Toggle One

grid.GroupEngine.CollapseAll();

var rootGroups = grid.GroupEngine.Groups;
if (rootGroups.Count > 0)
{
    grid.GroupEngine.ToggleCollapse(rootGroups[0]);

    if (rootGroups[0].SubGroups.Count > 0)
    {
        grid.GroupEngine.ToggleCollapse(rootGroups[0].SubGroups[0]);
    }
}