ColumnView.LocateByValue(Int32, GridColumn, Object, OperationCompleted[]) Method

Locates rows by cell values.

Namespace: DevExpress.XtraGrid.Views.Base

Assembly: DevExpress.XtraGrid.v24.2.dll

Declaration

C#

public virtual int LocateByValue(
    int startRowHandle,
    GridColumn column,
    object val,
    params OperationCompleted[] completed
)

VB.NET

Public Overridable Function LocateByValue(
    startRowHandle As Integer,
    column As GridColumn,
    val As Object,
    ParamArray completed As OperationCompleted()
) As Integer

Parameters

Name	Type	Description
startRowHandle	Int32	An integer value specifying the handle of the row where the search starts. In server mode, this parameter must be set to 0.
column	GridColumn	The GridColumn object (or descendant) that is the column whose cells’ values are compared to the search value.
val	Object	An object representing the value to search for.
completed	DevExpress.Data.OperationCompleted[]	A DevExpress.Data.OperationCompleted method that will be called when the requested operation is completed. The method’s argument will contain the requested value. This parameter is optional and is only required in Instant Feedback Mode.

Returns

Type	Description
Int32	If the specified value is loaded, the method returns an integer value specifying the handle of the row found. In Instant Feedback Mode, the DevExpress.Data.DataController.OperationInProgress value is returned if the requested search value is not currently loaded. The GridControl.InvalidRowHandle value, if no row is found that matches the specified condition.

Remarks

The LocateByValue method doesn’t support a data search against compound field names (e.g. “Address.City”).

In regular binding mode, the LocateByValue method uses the Object.Equals method’s overload with two parameters to compare values.

In Server and Instant Feedback Modes, data is compared using the methods provided by an internal DataController. The startRowHandle parameter must be set to 0 in server mode.

Note

This note applies when Instant Feedback Mode is enabled.

In this mode, data is loaded by the grid control dynamically, in portions. When calling the LocateByValue method, the requested search value may not be currently loaded. If the value is not loaded, the LocateByValue method will immediately return a special DevExpress.Data.DataController.OperationInProgress value.

To load the requested row and get its row handle, define a method of the DevExpress.Data.OperationCompleted type, and call the LocateByValue method, passing your OperationCompleted method as the fourth parameter. Your OperationCompleted method will be called when the corresponding row has been loaded. The method’s argument will contain the row handle of the requested row, or it will contain the GridControl.InvalidRowHandle value if no row is found that matches the specified condition.

Example

This example shows how to use the LocateByValue method to search for a row in Instant Feedback Mode mode.

C#

using DevExpress.XtraGrid.Views.Grid;

private void locateRowButton_Click(object sender, EventArgs e) {
    int rowHandle = gridView1.LocateByValue("Oid", 53498, OnRowSearchComplete);
    if (rowHandle != DevExpress.Data.DataController.OperationInProgress)
        FocusRow(gridView1, rowHandle);
}

void OnRowSearchComplete(object rh) {
    int rowHandle = (int)rh;
    if (gridView1.IsValidRowHandle(rowHandle))
        FocusRow(gridView1, rowHandle); 
}

public void FocusRow(GridView view, int rowHandle) {
    view.FocusedRowHandle = rowHandle;
}

VB.NET

Imports DevExpress.XtraGrid.Views.Grid

Private Sub locateRowButton_Click(sender As Object, e As EventArgs) Handles locateRowButton.Click
    Dim rowHandle As Integer = gridView1.LocateByValue("Oid", 35265, AddressOf OnRowSearchComplete)
    If Not (rowHandle = DevExpress.Data.DataController.OperationInProgress) Then
        FocusRow(gridView1, rowHandle)
    End If
End Sub

Private Sub OnRowSearchComplete(rh As Object)
    Dim rowHandle As Integer = CInt(rh)
    If gridView1.IsValidRowHandle(rowHandle) Then
        FocusRow(gridView1, rowHandle)
    End If
End Sub

Public Sub FocusRow(view As GridView, rowHandle As Integer)
    view.FocusedRowHandle = rowHandle
End Sub

Related GitHub Examples

The following code snippet (auto-collected from DevExpress Examples) contains a reference to the LocateByValue(Int32, GridColumn, Object, OperationCompleted[]) method.

Note

The algorithm used to collect these code examples remains a work in progress. Accordingly, the links and snippets below may produce inaccurate results. If you encounter an issue with code examples below, please use the feedback form on this page to report the issue.

C#

winforms-preserve-grid-state-on-refresh/CS/RefreshHelperClass.cs#L60

protected void ExpandRowByRowInfo(RowInfo rowInfo){
    int dataRowHandle = view.LocateByValue(0, view.Columns[keyFieldName], rowInfo.Id);
    if(dataRowHandle != GridControl.InvalidRowHandle){

VB.NET

winforms-preserve-grid-state-on-refresh/VB/RefreshHelperClass.vb#L66

Protected Sub ExpandRowByRowInfo(ByVal rowInfo As RowInfo)
    Dim dataRowHandle As Integer = view.LocateByValue(0, view.Columns(keyFieldName), rowInfo.Id)
    If dataRowHandle <> GridControl.InvalidRowHandle Then