Scrolling and Focusing Rows
- 6 minutes to read
The vertical grid controls (VGridControl and PropertyGridControl) allow you to navigate through rows via code. This can be used to facilitate end-users in finding information if there is a large amount of data available. This topic describes means which can be used to move focus from one row to another and techniques to scroll the view vertically. For information on navigating through records, please refer to the Navigating Through Records topic.
Moving Focus between Rows
End-users can navigate through rows in a vertical grid control using either the mouse or keyboard as described in the Navigating Through Cells topic located in the end-user Capabilities section. However, if there is a large volume of data displayed by the vertical grid you can facilitate end-users in finding the required data by changing focus to the desired row via code. This can be done in various ways which are described below.
If you need to move focus to a specific row use the VGridControlBase.FocusedRow grid property. This property is of the BaseRow type and so, objects representing rows of any type can be assigned to it. Please refer to the Accessing Rows topic for details on how to obtain objects which represent rows.
The vertical grid also provides the VGridControlBase.FocusFirst and VGridControlBase.FocusLast methods which allow you to move focus to the first and last visible rows respectively. The VGridControlBase.FocusNext and VGridControlBase.FocusPrev methods move focus to the previous visible or next visible row in relation to the currently focused row. For instance, if a row which is expanded has children, the next row will be its first visible child row (not the next row on the same level).
The following sample code gives focus to the rowPrice row, if it is visible. Otherwise, the first visible row will get focus.
if (rowPrice.Visible)
vGridControl1.FocusedRow = rowPrice;
else
vGridControl1.FocusFirst();
Note that the methods mentioned above can be used to shift focus sequentially through rows. For instance, the following sample code handles the VGridControlBase.HiddenEditor event which fires when closing a cell editor. The event handler then moves focus to the next row and activates that cell’s editor, when the last row is reached the first row will receive focus and the view is scrolled to the next record. Changing row focus is implemented in a separate MoveNext method.
private void vGridControl1_HiddenEditor(object sender, System.EventArgs e) {
VGridControl vGrid = sender as VGridControl;
MoveNext(vGrid);
while ((vGrid.FocusedRow is CategoryRow) || !vGrid.CanShowEditor)
MoveNext(vGrid);
vGrid.ShowEditor();
}
// moves focus to the next row or to the first row when the last one has been achieved
private void MoveNext(VGridControl grid) {
if (grid.FocusedRow == grid.GetLastVisible()) {
grid.FocusFirst();
grid.FocusedRecord++;
}
else
grid.FocusNext();
}
There are two more members that are useful for managing row focus:
- The VGridOptionsRow.AllowFocus row option, this can be accessed via the BaseRow.OptionsRow property. If the property is set to false the row cannot be focused either by end-users or via code.
- The VGridControlBase.FocusedRowChanged grid control event, this event enables you to respond to the focused row changing. Please refer to this member description for an example of using it.
Scrolling Rows
End-users are able to scroll vertically through the control if the number of rows is too large to fit in the control. This is performed using the vertical scroll bar, if it has not been disabled using the VGridControlBase.ScrollVisibility property. However, you can also perform vertical scrolling via code, this could be useful in some circumstances e.g. :
- You need to facilitate end-users in finding a specific piece of information and don’t want to change the focused row. Note that if you don’t need to keep focus on the current row you can simply assign the desired row to the VGridControlBase.FocusedRow property. The control will then scroll the view to the specified row.
- You need to ensure that multiple rows are visible simultaneously. Note again, that if you only need a single row to be visible, assign it to the VGridControlBase.FocusedRow property.
- You need to ensure that a specific row is displayed at a specified position. For instance, you may want a row to be displayed at the top of the grid control.
- You need to synchronize the vertical grid control with a different control which displays related data.
Vertical scrolling can be performed in three different ways. The list below describes these and illustrates their usage.
Using the VGridControlBase.MakeRowVisible method. This method accepts a row as a parameter and makes it visible. If the specified row doesn’t reside at root level, all its parent rows will be expanded and made visible. The row’s BaseRow.Visible property is then set to true, however if the row is still invisible the grid control scrolls the view vertically. If the row is located “above” the view, the control scrolls downwards so that the desired row becomes the topmost visible. Otherwise, the view is scrolled upwards and the row becomes the last visible.
The image below shows the row structure in the vertical grid and demonstrates an example of using the VGridControlBase.MakeRowVisible method. First, the ‘Price‘ row is hidden within the collapsed ‘Model‘ row. Then when the VGridControlBase.MakeRowVisible method is called the ‘Model‘ row is expanded and the view is scrolled to show the ‘Price‘ row.
Using the VGridControlBase.TopVisibleRowIndex property. This property specifies the zero-based index for the top visible row, you will need to assign 0 to this property to scroll the view to the top. The image below illustrates using this property.
Using the VGridControlBase.VertScroll method. This method takes the number of rows to be scrolled as the parameter. If the parameter is negative, the view scrolls upwards, otherwise the view scrolls downwards. Using this method is equivalent to adding the parameter value to the VGridControlBase.TopVisibleRowIndex property. The image below illustrates how this method can be used.
Note that the last two members simply imitate the behavior of the vertical scroll bar. They are capable of scrolling the view, but not of making the rows visible. So you will most likely use these when you are sure that the desired rows are visible and you know their exact position you can also use them to provide your own scrolling facilities (if for instance, the vertical scroll bar is disabled using the VGridControlBase.ScrollVisibility property). You could also use the VGridControlBase.MakeRowVisible method to find the desired row even if it is hidden within collapsed rows or is invisible. But unlike using the VGridControlBase.TopVisibleRowIndex property or the VGridControlBase.VertScroll method, you cannot predict in what direction or by how much the view will be scrolled.