Log In
[Expand]General Information
[Collapse]WinForms Controls
 [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
     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]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]Popup Menus
   [Expand]Saving and Restoring Layouts
   [Expand]Visual Elements
   [Expand]Design-Time Features
   [Expand]End-User Capabilities
    Included Components
  [Expand]Vertical Grid
  [Expand]Pivot Grid
  [Expand]Tree List
  [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]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]Report Server
[Expand]eXpressApp Framework
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation

Process Group Rows

This topic provides information on how rows are organized in a Grid View in a grouped mode. You should take this into account when iterating through and manipulating group rows. For information on grouping, refer to the Grouping Overview document.

Expanded Online Video

Learn how to customize grid behavior using the group row API.

Expanded Group Rows

When grouping is applied, group rows organize data into a tree. Group rows are virtual objects. They do not exist in a bound data source, which only stores data rows. They are only created in a grouped mode in order to combine records with identical values into grouping columns. If you group against a single column, the Grid View creates group rows for unique column values and then places data records in an appropriate group. If you group data against multiple columns, nested data groups are created. Data rows are displayed at the bottommost hierarchy level and they can be accessed by expanding group rows recursively.

Each data and group row (visible or hidden) is identified by a unique integer value called a row handle. Handles for data rows are non-negative. The top group's row handle is -1. The handle of the following group row is -2, etc. Row handles determine the order in which rows appear within a View according to the sorting, grouping and filtering settings. The following image shows row handles for a sample Grid View.

For more information on row handles and how to use them to reference particular rows, see the Identifying Rows and Cards section.

To find out whether a row handle refers to a group or data row, use the GridView.IsGroupRow method.

As stated above, all rows in grouped mode form a hierarchy. You can get the group level of each row, i.e. its position within the group hierarchy, by using the GridView.GetRowLevel function. For rows displayed at the top hierarchy level, the function returns 0. For immediate child rows of root rows, the function returns 1, etc. The maximum group level index matches the number of grouping columns. For all the data rows in the above image GridView.GetRowLevel will return 2. You can also return a group level for a particular row by its visible index. For this purpose, use the GridView.GetVisibleRowLevel method. For more information on visible indexes, see the Identifying Rows and Cards document.

To iterate through child rows belonging to a particular group row, you can use the following methods.
  • GridView.GetChildRowCount returns the number of immediate child rows for the group row. For instance, for group row "Category ID: 1" (row handle is -1), the function returns 5, since the row has five immediate children (group rows with handles from -2 to -6).
  • GridView.GetChildRowHandle returns the handle of a particular child row. The child row is referenced by its index amongst the other children and this can vary from 0 to GridView.GetChildRowCount minus one. For instance, for the group row "Category ID: 1" in the above image, the indexes of its child rows can vary from 0 to 4.
  • GridView.GetParentRowHandle gets the handle of the immediate parent row. For instance, for the "Supplier ID: 12" group row (row handle is -5), this function returns -1. This refers to the "Category ID: 1" group row.
  • GridView.GetDataRowHandleByGroupRowHandle allows you to get the handle of the first data row belonging to a group. This method can be used even if the target data row is not an immediate child.
It isn't necessary to expand collapsed group rows before using these methods.

Expanded Manipulating Rows Within a Group

Always bear in mind that changing the values of rows while grouping, sorting or filtering is applied, may result in rows being reordered. When changing the values of multiple rows, you should not use row handles to refer to particular rows, because row handles reflect the row order. Instead, use row objects to reference them. You can get row objects for specific row handles via the ColumnView.GetRow and ColumnView.GetDataRow methods. These methods take a row handle as a parameter and return an object that represents the corresponding row in a data source. ColumnView.GetRow can be applied regardless of the type of a data source. ColumnView.GetDataRow is in effect only when a bound data source represents a System.Data.DataView object. In this case, the function returns the corresponding System.Data.DataRow. For other data sources, this function returns null (Nothing in Visual Basic).

Before changing multiple rows, you should store the associated objects in a list. Then use the methods provided by the data source to modify the data of stored rows.

The following example shows how to change the "Price" column value for all the data rows belonging to the focused data group. In the buttonDiscount_Click event handler, an array list (rowsToDiscount) is created to store the rows that need changing. Next, if the focused row represents a group row, its child data rows are added to the list by using the getChildRows method. If a data row is focused, only this row is added to the list.

The getChildRows method searches for data rows that belong to a particular data group and adds them to an array list. It uses the GridView.GetChildRowCount and GridView.GetChildRowHandle methods to traverse through a data group. The getChildRows method adds row objects but not row handles to the list. Also note that a row isn't added if it is already in the list.

The inspected View needs to be bound to a System.Data.DataView data source. For this data source type, the ColumnView.GetRow method used in the example retrieves corresponding System.Data.DataRowView objects. In the discount method, list items are type cast to System.Data.DataRowView first. System.Data.DataRow objects are then obtained via the System.Data.DataRowView.Row property and this is used to modify the rows.

The Adding and Deleting Records topic illustrates how you can add a row to a particular data group.

To delete a specific group row, the ColumnView.DeleteRow method can be used.

Expanded Expanding and Collapsing Group Rows

An end-user can expand or collapse rows using the mouse, keyboard or group panel context menu. You can refer to the end-user Capabilities. Expanding and Collapsing Rows section for more information.

To get the expansion status of a group row, use the GridView.GetRowExpanded method. This returns true or false depending upon whether the inspected group row is expanded or collapsed. The GridView.ExpandGroupRow, GridView.CollapseGroupRow and GridView.SetRowExpanded methods can be used to expand and collapse group rows. These methods also have overloads to expand/collapse group rows recursively (nested group rows will be expanded/collapsed in this case).

The following example demonstrates how to toggle an expansion status for a focused group row.
If you need to make a particular row visible, you can call the GridView.MakeRowVisible method. In grouped mode, this method expands the group rows required and scrolls the View to display the row. To make a row visible and move focus to it at the same time, assign a target row handle to the ColumnView.FocusedRowHandle property.

The next example shows how to display the rows whose "Is In Stock" column values are set to false.

You can expand or collapse all groups at once by using the GridView.ExpandAllGroups and GridView.CollapseAllGroups methods. These methods change the expansion states of the rows recursively.

Before expanding a group row, the Grid View generates the GridView.GroupRowExpanding event and this allows you to prevent the row from being expanded. After the row has been expanded, the GridView.GroupRowExpanded event is fired.

The Grid View provides the GridView.GroupRowCollapsing and GridView.GroupRowCollapsed events that occur before and after a row is collapsed. The GridView.GroupRowCollapsing event can be used to prevent a particular row from being collapsed.

Below are some details on the functioning of the GridView.GroupRowExpanding, GridView.GroupRowExpanded, GridView.GroupRowCollapsing and GridView.GroupRowCollapsed events:

  • when all group rows are expanded/collapsed at once (via code or the context menu), corresponding events are fired only once (not repeatedly for each group row being expanded); in this case, an event's RowHandle parameter is set to the GridControl.InvalidRowHandle value.
  • when a group row is expanded/collapsed recursively (nesting rows should also be expanded/collapsed), corresponding events are fired only once (for this row); yhe event's parameter refers to this row; for nesting rows the events are not fired.
  • the events are not fired when group rows are expanded as a result of calling the GridView.MakeRowVisible method or assigning a row handle to the ColumnView.FocusedRowHandle property.

Expanded See Also

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