Accessing Rows
- 7 minutes to read
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.
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.
using DevExpress.XtraVerticalGrid.Rows;
// ...
for (int i = 0; i < vGridControl1.Rows.Count; i++) {
if (vGridControl1.Rows[i] is CategoryRow)
vGridControl1.Rows[i].Expanded = false;
}
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.
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.
private void vGridControl1_KeyDown(object sender, KeyEventArgs e) {
VGridControl vGrid = sender as VGridControl;
BaseRow row = vGrid.FocusedRow;
BaseRow prevRow = vGrid.GetPrevVisible(row);
BaseRow nextRow = vGrid.GetNextVisible(row);
if ((e.KeyCode == Keys.Up) && (e.Shift)) {
if ((row == null) || (prevRow == null)) return;
vGrid.MoveRow(row, prevRow, false);
}
if ((e.KeyCode == Keys.Down) && (e.Shift)) {
if ((row == null) || (nextRow == null)) return;
vGrid.MoveRow(nextRow, row, false);
}
}