Focus and Scroll Records

Sep 03, 2021
4 minutes to read

This topic explains how to focus and scroll records in code. For example, you can:

scroll the view to a record and activate an editor
provide a custom control that navigates through records
scroll to a record that satisfies the condition

To learn how users can focus and scroll records, see Navigating Through Cells.

Focus and Scroll Records in Code

Use the following vertical grid’s API to focus and scroll records in code:

FocusedRecord — gets or sets the focused record’s zero-based index
RecordCount — gets the number of records
HorzScroll — scrolls the view by the specified number of records or bands if bands do not fit in the width
LeftVisibleRecord — gets or sets the index of the leftmost visible record
MakeRecordVisible — scrolls the view to the specified record
LocateByValue — returns the handle of the record that contains the specified value in the specified row/filed
LocateByDisplayText — returns the handle of the record that displays the specified text in the specified row
GetRecordIndex — returns the handle of the vertical grid record that corresponds to the data source record with the specified index
GetDataSourceRecordIndex — returns the index of the data source record that corresponds to the vertical grid record with the specified handle

Whether the focus moves when the view is scrolled, depends on the current layout:

single record view and bands view — when the view is scrolled, the focus moves accordingly
multiple records view — when the view is scrolled, the focus does not change

Custom Data Navigator

This example shows how to create a custom data navigator. The control comprises navigation buttons and a check box as shown below.

The table below lists the elements of this navigation panel, their names, and explains their purpose.

Element	Description	Name
	If checked, the navigation panel’s buttons move focus. Otherwise, they scroll the view horizontally.	chbMoveFocus
	If the check box is checked, focuses the first record. Otherwise, scrolls the view so that the first record is visible leaving the focus unchanged.	btnFirst
	If the check box is checked, shifts focus backwards one record. Otherwise, scrolls the view left by one record leaving the focus unchanged.	btnPrev
	Makes the focused record visible.	btnShowFocused
	If the check box is checked, shifts focus forward one record. Otherwise, scrolls the view right by one record leaving the focus unchanged.	btnNext
	If the check box is checked, focuses the last record. Otherwise, scrolls the view so that the last record is visible leaving the focus unchanged.	btnLast

Handle the Click events as the code below shows. The vertical grid should apply the multiple records view to see the difference between when you move the focus and when you scroll the view.

C#
VB.NET

csharp

private void btnShowFocused_Click(object sender, System.EventArgs e) {
   vGridControl1.MakeRecordVisible(vGridControl1.FocusedRecord);
}
private void btnFirst_Click(object sender, System.EventArgs e) {
   if (chbMoveFocus.Checked)
      vGridControl1.FocusedRecord = 0;
   else
      vGridControl1.LeftVisibleRecord = 0;
}
private void btnPrev_Click(object sender, System.EventArgs e) {
   if (chbMoveFocus.Checked)
      vGridControl1.FocusedRecord--;
   else
      vGridControl1.HorzScroll(-1);
}
private void btnNext_Click(object sender, System.EventArgs e) {
   if (chbMoveFocus.Checked)
      vGridControl1.FocusedRecord++;
   else
      vGridControl1.HorzScroll(1);
}
private void btnLast_Click(object sender, System.EventArgs e) {
   if (chbMoveFocus.Checked)
      vGridControl1.FocusedRecord = vGridControl1.RecordCount - 1;
   else
      vGridControl1.MakeRecordVisible(vGridControl1.RecordCount - 1);
}

Private Sub btnShowFocused_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles btnShowFocused.Click
   VGridControl1.MakeRecordVisible(VGridControl1.FocusedRecord)
End Sub

Private Sub btnFirst_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles btnFirst.Click
   If chbMoveFocus.Checked Then
      VGridControl1.FocusedRecord = 0
   Else
      VGridControl1.LeftVisibleRecord = 0
   End If
End Sub

Private Sub btnPrev_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles btnPrev.Click
   If chbMoveFocus.Checked Then
      VGridControl1.FocusedRecord -= 1
   Else
      VGridControl1.HorzScroll(-1)
   End If
End Sub

Private Sub btnNext_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles btnNext.Click
   If (chbMoveFocus.Checked) Then
      VGridControl1.FocusedRecord += 1
   Else
      VGridControl1.HorzScroll(1)
   End If
End Sub

Private Sub btnLast_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles btnLast.Click
   If (chbMoveFocus.Checked) Then
      VGridControl1.FocusedRecord = VGridControl1.RecordCount - 1
   Else
      VGridControl1.MakeRecordVisible(VGridControl1.RecordCount - 1)
   End If
End Sub