Tutorial: Filtering and Locating Rows API

• May 26, 2023
• 5 minutes to read

This walkthrough is a transcript of the Filtering and Locating Rows API video available on the DevExpress YouTube Channel.

The tutorial provides information on the DevExpress WinForms Grid’s API that allows you to filter data and locate rows. You will learn how to apply a filter condition to an entire view or to individual columns, how to clear the existing filter conditions and how to locate rows by cell values or display text.

Filtering Rows API

The DevExpress WinForms Grid’s API allows you to apply a filter condition to a View or to individual columns. This tutorial will show both, by assigning Click handlers to buttons in the View Filtering and Column Filtering groups.

• Applying a Filter to a View

  First, handle the Click event of the Apply Filter button in the View Filtering group. In the event handler, assign the filter expression to the View’s ColumnView.ActiveFilterString property.

  The filter expression contains three clauses combined by OR and AND logical operators. First and second clauses are grouped using parentheses. Filter conditions use various comparison operators such as Is greater than or Not equal to. Date-time constants must be wrapped with the ‘#’ characters, while string constants must be enclosed within single quotation marks.

  C#

  private void btn_ApplyViewFilter_ItemClick(object sender, ItemClickEventArgs e) {
      gridView.ActiveFilterString = "([UnitPrice] < 20 OR [OrderDate] >= #06/1/2015#) AND [ProductName] <> 'Chang'";
  }
  

  Now write the event handler for the Clear Filter button. To clear filer settings for the View and all its columns, call the Clear method of the View’s ColumnView.ActiveFilter property.

  C#

  private void btn_ClearViewFilter_ItemClick(object sender, ItemClickEventArgs e) {
      gridView.ActiveFilter.Clear();
  }
  

  Run the application to see the result. Click the Apply Filter button to select records where the unit price is less than 20 or order date is greater than June 1 and the product name is not ‘chang’. The grid will display filter buttons for columns that are involved in the filter expression. However, filter dropdowns in these columns do not contain items that would clear the filter.

  

  Click the Clear Filter button to remove filter settings for the entire View.

• Applying a Filter to a Column

  Close the application and switch to the Column Filtering group. Handle the Click event of the Apply Filter button to select records whose unit price is greater than 20 and less than 30. To do this, create a new ColumnFilterInfo object with the desired filter condition and assign it to the Unit Price column’s GridColumn.FilterInfo property.

  C#

  private void btn_ApplyColumnFilter_ItemClick(object sender, ItemClickEventArgs e) {
      string filterString = "[UnitPrice] > 20 AND [UnitPrice] < 30";
      gridView.Columns["UnitPrice"].FilterInfo = new ColumnFilterInfo(filterString);
  }
  

  In the Clear Filter button’s Click event handler, call the target column’s GridColumn.ClearFilter method.

  C#

  private void btn_ClearColumnFilter_ItemClick(object sender, ItemClickEventArgs e) {
      gridView.Columns["UnitPrice"].ClearFilter();
  }
  

  Run the application and click the Apply Filter button in the Column Filtering group to filter data against the Unit Price column. Now the target column’s dropdown contains the (All) item that clears the column’s filter.

  

  Remove the filter applied to the column by clicking the corresponding Clear Filter button.

  To change the text displayed within the filter panel, add a parameter to the ColumnFilterInfo object constructor.

  C#

  private void btn_ApplyColumnFilter_ItemClick(object sender, ItemClickEventArgs e) {
      string filterString = "[UnitPrice] > 20 AND [UnitPrice] < 30";
      string displayText = "[UnitPrice] Is between $20.00 and $30.00";
      gridView.Columns["UnitPrice"].FilterInfo = new ColumnFilterInfo(filterString, displayText);
  }
  

  Run the application again to see the result. When you click the Apply Filter button in the Column Filtering group, the grid filters data against the Unit Price column and displays the specified text within the filter panel.

  

Locating Rows API

Return to design time and write code for the Locate Row button.

• Locating Rows by Cell Values

  Call the View’s ColumnView.LocateByValue method with three parameters: the first specifies the row handle where the search starts; the second narrows search down to a specific column and the third specifies the search value. The Category column uses the ImageComboBoxEdit in-place editor, which represents underlying integer values as strings with images. The value of 1 corresponds to the “Beverages” category. After the row is found, move focus to it by setting the View’s ColumnView.FocusedRowHandle property.

  C#

  private void btn_LocateRow_ItemClick(object sender, ItemClickEventArgs e) {
      int rowHandle = gridView.LocateByValue(gridView.FocusedRowHandle + 1, gridView.Columns["Category"], 1);
      gridView.FocusedRowHandle = rowHandle;
  }
  

  Run the application and click the Locate Row button. As a result, the grid focuses the nearest row that contains “Beverages” in the Category column. Subsequent clicks iterate through all rows with the “Beverages” category.

• Locating Rows by Display Text

  Close the application and modify the handler code to locate rows by display text. To do this, use the ColumnView.LocateByDisplayText method and pass the “Beverages” string as the third parameter.

  C#

  private void btn_LocateRow_ItemClick(object sender, ItemClickEventArgs e) {
      int rowHandle = gridView.LocateByDisplayText(gridView.FocusedRowHandle + 1, gridView.Columns["Category"], "Beverages");
      gridView.FocusedRowHandle = rowHandle;
  }
  

  Run the application again and click the Locate Row button to see the result.