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
  [Expand]Data Grid
  [Collapse]Vertical Grid
    [Expand]Binding to Data
     [Collapse]Row Operations
       Creating a Tree-Like Structure of Rows
       Accessing Rows
       Scrolling and Focusing Rows
       Using the Rows Iterator
       Expanding and Collapsing Rows
      Row Class Structure
      Row Properties
      Category Rows
      Editor Rows
      Multi-Editor Rows
      Fixed Rows
    [Expand]In-place Editors
     Hit Information
    [Expand]Custom Painting
    [Expand]Alpha Blending and Background Images
    [Expand]Customization Form
     Batch Modifications
    [Expand]Drag and Drop
   [Expand]Visual Elements
   [Expand]Design-Time Features
   [Expand]End-User Capabilities
   [Expand]Member Tables
  [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

Accessing Rows

Obtaining an object which represents a row is a common task when using the vertical grid control (VGridControl or PropertyGridControl). This can be used to modify a desired row's settings, such as its expanded state or the data cell style. Also you may need row objects to set the values of some properties or to pass them as parameters to some methods. For instance, you may need a row object to supply it to the VGridControlBase.FocusedRow property or the VGridControlBase.MoveRow method. This particular topic covers all the possible ways of obtaining objects which represent the desired rows.

Expanded Accessing a Specific Row

The first and easiest way to access the desired row is to use its name in code. A row's name is set using the BaseRow.Name property. When adding rows to a control at design time, their names are initialized with strings which are constructed in a specific manner. If you add a single row (using the Add button of the Row Designer designer page) its name is constructed with a string which denotes the row type and a unique number (for instance, 'editorRow1'). If the Retrieve Fields button is used, the row gets a name comprised of the 'row' string and the bound field name (for instance, 'rowFirstName'). However if a row with the same name already exists on the form, the first method is used for name generation.

Accessing rows using their names is possible because rows are derived from the BaseRow class which, is itself derived from the Component class. However you cannot access a row in code by its name if the rows have been created at runtime using the VGridControlBase.RetrieveFields method.

The line of code below, shows how to use this method for obtaining row objects. It changes the caption of the row bound to the 'FirstName' field.

The second method for accessing the desired row is to use the collection index, represented by the VGridControlBase.Rows property. If an index is specified, the search is performed only within the collection elements, not on child rows. If you specify the row's name (BaseRow.Name), the row will be found at any nesting level. So, the first method is likely to be used when there is a need to visit rows that are located at root level. The code below demonstrates how to collapse all root level category rows using the index method of access.

The second way for obtaining rows using the VGridControlBase.Rows property is useful when you need to get a specific row by its name. Note that this must be done in the following two cases, if you don't know the required row name when developing an application (for instance, the name is stored in a string variable set at runtime). The second case is when rows have been created at runtime using the VGridControlBase.RetrieveFields method because in this instance rows cannot be directly accessed by their names. In all other situations it is more convenient to access a row directly by its name as in the first example.

The sample code line below shows how to change the visibility state for the rowFirstName row.

A similar method for obtaining row objects is to use the BaseRow.ChildRows property. This property is represented by the VGridRows class as the VGridControlBase.Rows property. So, you can also specify the row index to access its immediate children, if a row name is specified a search will be performed on all the row's children independent of their nesting level.

Expanded Obtaining Rows

The vertical grids provide direct access to the currently focused row. Read the VGridControlBase.FocusedRow property value to obtain an object which represents it. The code sample below demonstrates how to move the focused row into first position at root level. The VGridControlBase.MoveRow method is used for this purpose.

There are also a number of methods that can be used to obtain rows which are neighbors to the specified one, and the top and bottom rows within a control. These are the VGridControlBase.GetPrev, VGridControlBase.GetNext, VGridControlBase.GetFirst and VGridControlBase.GetLast methods. Note that these methods return rows independent of their nesting level. For instance, if a row has child rows, its first child row will be considered the next row, not the next row on the same level. Also, the VGridControlBase.GetLast method returns the row displayed at the bottom of the control (if visible), but not the last row on the root level.

There is another set of methods which are equivalent to those already mentioned except for one difference, that they can return only visible rows. These methods are GetFirstVisible, VGridControlBase.GetNextVisible, VGridControlBase.GetPrevVisible and VGridControlBase.GetLastVisible. Note that when all rows are visible, both sets of methods return the same values, as is illustrated in the image below.

The next image shows the same vertical grid control where the 'Price', 'Transmission' and 'Length' rows are not visible (they are displayed in the Customization Form). In this case these methods will return different values.

As you can see these two sets of methods can be used to traverse through all rows or just all visible rows within the vertical grid. However this is not the best way to perform an iteration, if you need to access all rows within a control the Rows Iterator should be used. It provides faster processing and using it results in more readable code. Methods described in this topic are best used when obtaining small subsets of neighboring rows.

The sample code below handles the KeyDown event for the vertical grid control. It is used to respond to SHIFT-Up and SHIFT-Down key combinations. When the SHIFT-Up key combination is pressed, the focused row becomes a child of the previous visible row. If the SHIFT-Down combination is pressed, the focused row becomes the parent of the next visible row. The VGridControlBase.GetNextVisible and VGridControlBase.GetPrevVisible methods are used to obtain the next and previous rows. The focused row is obtained using the VGridControlBase.FocusedRow property. The VGridControlBase.MoveRow method is used to move rows.

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