Log In
Home
Support
Demos
Documentation
Blogs
Training
Webinars
[Expand]General Information
[Collapse]WinForms Controls
  Prerequisites
 [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
   [Expand]Getting Started
   [Expand]Binding to Data
   [Expand]Grid View
   [Expand]View Technology
   [Collapse]Grouping
     Grouping Overview
     Grouping Modes and Custom Grouping
     Tutorial: Custom Grouping Algorithms
     Tutorial: Group Row API
     Tutorial: Grouping Basics
     Process Group Rows
     Applying Styles to Group Rows
     Member Table: Grouping
     Member Table: Group Row API and Behavior
     Member Table: Group Summaries
     Member Table: Size, Style, Appearance and Animation
     Member Table: Grouping Modes and Custom Grouping
   [Expand]Sorting
   [Expand]Summaries
   [Expand]Data Editing
   [Expand]Filtering and Locating Rows
   [Expand]Focus and Selection Handling
   [Expand]Processing Rows
   [Expand]Formatting Cell Values
   [Expand]Master-Detail Relationships
   [Expand]Asynchronous Image Load
   [Expand]Export and Printing
   [Expand]Appearance and Conditional Formatting
   [Expand]Batch Modifications
   [Expand]Hit Information
   [Expand]Hints
   [Expand]Popup Menus
   [Expand]Saving and Restoring Layouts
   [Expand]Visual Elements
   [Expand]Design-Time Features
   [Expand]Examples
   [Expand]End-User Capabilities
    Included Components
  [Expand]Vertical Grid
  [Expand]Pivot Grid
  [Expand]Tree List
  [Expand]Chart Control
  [Expand]Diagrams
  [Expand]Gauges
  [Expand]Map Control
  [Expand]Scheduler
  [Expand]Spreadsheet
  [Expand]Rich Text Editor
  [Expand]Spell Checker
  [Expand]Form Layout Managers
  [Expand]Navigation Controls
  [Expand]Printing-Exporting
  [Expand]PDF Viewer
   Reporting
  [Expand]Snap
  [Expand]TreeMap Control
 [Expand]Common Features
  Get More Help
 [Expand]API Reference
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Document Server
[Expand]Reporting
[Expand]Report Server
[Expand]Dashboard
[Expand]eXpressApp Framework
[Expand]CodeRush
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation

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

How would you rate this topic?​​​​​​​