[Expand]General Information
[Collapse]WinForms Controls
  .NET Core Support
 [Expand]What's Installed
 [Expand]Build an Application
 [Collapse]Controls and Libraries
  [Expand]Forms and User Controls
  [Expand]Messages, Notifications, and Dialogs
  [Expand]Editors and Simple Controls
  [Expand]Ribbon, Bars and Menu
  [Expand]Application UI Manager
  [Expand]Docking Library
  [Collapse]Data Grid
   [Collapse]Get Started With Data Grid and Views
     [Expand]Appearance and Conditional Formatting
     [Expand]Data Editing
     [Expand]Hit Information
     [Expand]Data Binding and Working with Columns
     [Expand]Grid View - Columns, Rows and Cells
     [Expand]Banded Views
     [Expand]WinExplorer View
     [Expand]Tile View
       Tutorial: Custom Grouping Algorithms
       Tutorial: Group Row API
       Tutorial: Grouping Basics
     [Expand]Filter and Search
     [Expand]Split Presentation
     [Expand]Row Preview Sections
   [Expand]Data Binding
    Unbound Columns
   [Expand]Data Editing and Validation
   [Expand]Filter and Search
   [Expand]Focus and Selection Handling
    Format Cell Values
   [Expand]Master-Detail Relationships
   [Expand]Asynchronous Image Load
   [Expand]Export and Printing
   [Expand]Appearance and Conditional Formatting
    Split Presentation
    Row Preview Sections
   [Expand]Batch Modifications
    Hit Information
    Popup Menus
   [Expand]Save and Restore Layout
   [Expand]Visual Elements
   [Expand]Design-Time Features
   [Expand]End-User Capabilities
    Included Components
  [Expand]Vertical Grid
  [Expand]Property Grid
  [Expand]Pivot Grid
  [Expand]Tree List
  [Expand]Gantt Control
  [Expand]Chart Control
  [Expand]Map Control
  [Expand]Rich Text Editor
  [Expand]Spell Checker
  [Expand]Form Layout Managers
  [Expand]Navigation Controls
  [Expand]PDF Viewer
  [Expand]TreeMap Control
  [Expand]Sunburst Control
 [Expand]Common Features
  Get More Help
 [Expand]API Reference
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]ASP.NET Core Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Office File API
[Expand]Report and Dashboard Server
[Expand]eXpressApp Framework
[Expand]eXpress Persistent Objects
[Expand]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation
View this topic on docs.devexpress.com (Learn more)

Tutorial: Group Row API

This walkthrough is a transcript of the Group Row API video available on the DevExpress YouTube Channel.

The tutorial will customize grid behavior using the group row API. You will create a sample application where:

  • the grid automatically expands focused group rows on the root level;
  • end-users cannot collapse those rows;
  • other root-level group rows are collapsed automatically;
  • parent or child row data is automatically displayed in the status bar.

Expanded Starting Point

To learn the basics of identifying and traversing group rows, begin with an application that has a GridControl with grouping already applied.

Expanded Displaying the Focused Row Handle

First, display the focused row handle in the status bar. Select the grid View and handle its ColumnView.FocusedRowChanged event, which is raised when focus moves between rows. The currently focused row is specified by the event's FocusedRowChangedEventArgs.FocusedRowHandle parameter. A separate method is used to display the information in the status bar.

Run the application. Since the top group row is now focused, the status bar displays its handle that is equal to -1. Focus the following group row and see that its handle is -2. As you see, group row handles are negative integer numbers starting with -1. Note that rows are numbered from top to bottom, regardless of their nesting level.

Data row handles are non-negative integer numbers starting with 0. The first data row's handle is 0, then 1, and so on.

Expanded Expanding the Focused Root Group Row

Now modify the grid's functionality so that root-level group rows are automatically expanded when they are focused. Add one more method call to the ColumnView.FocusedRowChanged event handler. In that method, check whether the focused row is a root group row using the GridView.GetRowLevel method. For group rows displayed at the top hierarchy level, the method returns 0. After that, expand the focused group row by calling the GridView.SetRowExpanded method. Pass the following parameters to this method: the focused row handle, true to expand the group row and true to additionally expand child group rows at all nesting levels.

Run the application. The focused root group row is automatically expanded along with its nested groups.

Expanded Collapsing Non-Focused Root Group Rows

Now modify the behavior so that only one root-level group row is expanded at a time. Add one more method call to the event handler – CollapseFirstLevelGroupRows. The method iterates all group rows by counting down from -1 and until the counter reaches an invalid row handle. Non-focused root group rows are collapsed along with their nesting group rows using the GridView.SetRowExpanded method with false passed as its second parameter.

Now run the application again. When a root group row receives focus, this group is automatically expanded along with its nested groups, while other groups are collapsed. So, a single root group can be expanded at any time. Note that end-users can collapse the focused group row. There's a way to change this behavior too.

Expanded Preventing End-Users from Collapsing the Expanded Root Group Row

Close the application. Declare a variable that will store the handle of the root group row that was expanded last. Handle the View's GridView.GroupRowExpanded event, which is fired after a group row has been expanded. Save the currently expanded root group row using the previously declared variable. After that, handle the View's GridView.GroupRowCollapsing event, which is raised when end-users attempt to collapse a group row. To prevent the currently expanded root group row from being collapsed, set the event's RowAllowEventArgs.Allow parameter to false.

Run the application to see the result. Now you cannot collapse the focused root group row. So, one root group row is always expanded. Its nested group rows can have any status.

Expanded Displaying Group Information

Now return to design time and further modify the ColumnView.FocusedRowChanged event handler. Display information on the current group when a group row or data row is focused.

Create the DisplayParentChildInfo function and call it in the event handler. To determine whether the focused row handle refers to a group row, use the GridView.IsGroupRow method. The GridView.GetChildRowCount function returns the number of children for a specific group row.

For a focused data row, the status bar should display information on its parent group rows at all levels. Go up the group row hierarchy using the GridView.GetParentRowHandle method. At every hierarchical level, read the text displayed within a group row using the GridView.GetGroupRowDisplayText method.

Run the application and see the result. When you focus a group row, the status bar displays the number of its children. If the focused row is a data row, the status bar displays information about parent group rows at all levels.

Expanded Complete Code

Expanded See Also

Is this topic helpful?​​​​​​​