[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
  [Expand]Data Grid
  [Collapse]Vertical Grid
   [Expand]Binding to Data
   [Collapse]Data Layout: Records, Rows and Cells
      Scrolling and Focusing Rows
      Using the Rows Iterator
      Expanding and Collapsing Rows
    [Expand]Customization Form
     Data Layout: Records, Rows, and Cells
   [Expand]Data Editing and Validation
    Formatting Values
   [Expand]Drag and Drop
   [Expand]Appearance and Custom Painting
   [Expand]Visual Elements
   [Expand]Design-Time Features
   [Expand]End-User Capabilities
    Hit Information
    Batch Modifications
   [Expand]Member Tables
  [Expand]Property 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]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)

Using the Rows Iterator

Rows in the vertical grids (VGridControl and PropertyGridControl) can be organized in a tree-like structure. Basically, you will need to write recursive code to visit all rows is such a case. However, the Rows Iterator technology introduced by the vertical grids enables you to avoid this and make traversing through rows a trivial task. This topic provides an overview of the Rows Iterator and several examples of using it.

Expanded Rows Iterator Overview

Rows Iterator is an object which can be accessed via the VGridControlBase.RowsIterator grid property. This object is capable of traversing through rows arranged into a tree (it implements recursive code for this purpose). So, you do not have to write any code to traverse through the grid's rows. The only thing you need to do is to process each row accessed. The following steps need to be performed:

  • Create an operation class - a descendant of the RowOperation. The main thing to be done when creating the operation class is to override the RowOperation.Execute method, this method is called each time a row is visited. The visited row is then passed to this method as its parameter.
  • Call the VGridRowsIterator.DoOperation or VGridRowsIterator.DoLocalOperation method of the Rows Iterator and pass the operation object to it. These methods differ in the scope of rows they process, the first scans through all rows within the control; the second only the rows of a sub-tree whose parent is specified by the parameter.

Actually, the row iterator provides more capabilities than are described in the list above, they are described later on in this topic. Before reading that information review the following two simple examples for using the rows iterator.

Expanded Row Counter Sample

This example will use the rows iterator to get the total number of rows within the grid. The operation class will have an internal counter for this purpose which is incremented by one each time a row is accessed. There will also be a public property which allows access to the counter value after row traversal has finished. So the code for the operation class is:

To get the total number of rows within the grid you need to create a new CountOperation object and pass it to the VGridRowsIterator.DoOperation method of the rows iterator and then read its TotalRows property value. The code below shows how this can be done.

Expanded Extended Capabilities of The Rows Iterator

When creating an operation class, you can override not only the RowOperation.Execute method. The RowOperation class provides two more virtual members that can be used to specify which rows need to be accessed. The list below enumerates these methods and explains their purpose.

  • The RowOperation.NeedsFullIteration property. If this property returns false only rows that have children are visited. Otherwise the rows iterator visits all rows within the range. As implemented in the RowOperation class, this property returns true. So it is not necessary to override it if you want to traverse through rows regardless of whether they have children or not.

    Of course, you can manually check whether the processed row has children in it RowOperation.Execute method implementation. However, in this case the operation will require much more time to complete, since the iterator will still visit every row and call the RowOperation.Execute method for them. Overriding the RowOperation.NeedsFullIteration property however will bring a performance benefit if you need to perform an operation which only processes parent rows (for instance, expanding and collapsing specific rows).

  • The RowOperation.NeedsVisitChildren method, this method is called each time a row containing child rows is visited. This parent row is then passed to the RowOperation.NeedsVisitChildren method as the parameter which is then examined to return a Boolean value. The value returned depends on the RowOperation.NeedsFullIteration property value, if the RowOperation.NeedsFullIteration property value is true then the method will return a value indicating it is necessary to visit all the children of the specified row. Otherwise, the method returns a value specifying whether to process the parent row itself together with its child rows.

    Overriding the RowOperation.NeedsVisitChildren method will provide a performance benefit to your applications. For instance, you may want to process rows residing on the first two levels only. In this case, the RowOperation.NeedsVisitChildren method returns false for each parent row which resides on the second level so that lower level rows are not processed.

The next two examples demonstrate how to use the RowOperation.NeedsFullIteration property and the RowOperation.NeedsVisitChildren method when constructing operation classes.

Expanded Obtain Rows Sample

This sample demonstrates how to obtain a collection of rows residing at a specific level. For this purpose the operation class declares a local variable which stores the level index, this variable is initialized in the constructor. If a row belonging to the specified level is found, it is added to the internal rows collection. The operation class also declares a public property which allows access to the collection of obtained rows.

The operation class introduced in the sample overrides the RowOperation.NeedsVisitChildren method for its base class. This is used to prevent rows whose nesting level is greater than that specified from being accessed. This increases application performance.

After such an operation has been declared, you can use the following code to restrict the resizing of all rows residing at the second nesting level.

Expanded Collapse Rows Sample

This example shows how to create an operation class that will collapse all rows which do not contain the specified row as their child, So only the row's parents will be expanded as a result.

The operation class accepts the row as its constructor parameter and stores it in an internal variable. The Execute method then checks whether the processed row contains the specified row as a child, if not, the processed row is collapsed. The operation class also overrides the RowOperation.NeedsFullIteration base class property to process only rows that have children. This gives a performance benefit when working with large row structures.

So, the code for this operation class is:

If such an operation is declared you could for instance, collapse all the rows that do not contain the focused row as a child. The following code line should be used for this purpose.

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