# Filter

## Content

Filtering in True DBGrid lets you narrow down display records according to a specified condition applied on a column. It is useful in case of big data sets as it lets you easily analyze data by displaying specific type of records only.

In some cases, you might want to allow users to filter the underlying record set at run time by limiting the number of items in a given field or fields. By using the [FilterBar](/componentone/docs/win/online-truedbgrid/) and [AllowFilter](/componentone/docs/win/online-truedbgrid/) properties at design time, and entering the filter text appropriately at run time, the number of field entries can be reduced almost effortlessly.

When the [FilterBar](/componentone/docs/win/online-truedbgrid/) property of a **TrueDbGrid** control is set to **True**, a blank row with a gray separator line appears directly above the uppermost data row in the grid:

![](https://cdn.mescius.io/document-site-files/images/a1b176e5-6638-4b1f-a786-e41a817558bb/images/filter-bar-grid.png)

In order to implement the filter in the grid, the [AllowFilter](/componentone/docs/win/online-truedbgrid/) property must be set to **True** (default), which will tell the grid to implement the filtering process. If the [FilterBar](/componentone/docs/win/online-truedbgrid/) and [AllowFilter](/componentone/docs/win/online-truedbgrid/) properties are both set to **True**, the filter bar will appear in the grid and the grid will also handle automatically the handling of the DataSet.

## Manually Filtering Data

In the event that you would prefer to handle the filtering process yourself, leaving the [AllowFilter](/componentone/docs/win/online-truedbgrid/) property as **False** will not implement the grid's automatic filter. In order to create a filter, the [FilterChange](/componentone/docs/win/online-truedbgrid/) event, must be used to manually sort the data. This event fires whenever there the user changes the state of the filter bar.

In this event, a handler would have to be created which filters the dataset for each character the user enters. For example, if the user types "B" in a filter bar cell, the underlying dataset would have to be limited to just those column items whose values start with the letter B. If the user then extended the filter to "BR", then the list would have to be reduced to only those whose values that start with BR.

## Adding Watermark to FilterBar

You can now easily add a text watermark to the filter bar so that it appears with default text. You can use this watermark to add instructions for filtering text, or adding default values to give users a better understanding of what values can be entered in particular filter bar cells. All you need to do to have text appear in the filter bar is set the [FilterWatermark](/componentone/docs/win/online-truedbgrid/) property to a string.

For example in the following code, the [FilterWatermark](/componentone/docs/win/online-truedbgrid/) in the first filter bar cell is set to "Filter Me":

```csharp
// Set the C1DataColumn.FilterWatermark property of the first column.
this.c1TrueDBGrid1.Columns[0].FilterWatermark = "Filter Me";
```

Notice that the background color of the filter bar cell with a watermark has changed:

![](https://cdn.mescius.io/document-site-files/images/a1b176e5-6638-4b1f-a786-e41a817558bb/images/watermark-grid.png)

In the following code, the [FilterWatermark](/componentone/docs/win/online-truedbgrid/) is set to the value of each column's caption text:

```csharp
int colcount;
colcount = 0;
while (c1TrueDBGrid1.Columns.Count > colcount)
{
    // Set the C1DataColumn.FilterWatermark property of each column to its caption.
    this.c1TrueDBGrid1.Columns[colcount].FilterWatermark = c1TrueDBGrid1.Columns[colcount].Caption;
    colcount = colcount + 1;
}
```

The grid appears like the following:

![](https://cdn.mescius.io/document-site-files/images/a1b176e5-6638-4b1f-a786-e41a817558bb/images/watermark-captiontext.png)

Notice that when text is filtered, the watermark is no longer visible:

You can change the appearance of the style of the [FilterWatermark](/componentone/docs/win/online-truedbgrid/) using the [FilterWatermarkStyle](/componentone/docs/win/online-truedbgrid/) property. See [Styles Collection Editor](/componentone/docs/win/online-truedbgrid/design-time/collection-editors#style-collection-editor) for more information about styles.

## Filtering Grid with Multiple Criteria

You can now easily filter the grid with multiple filter criteria at run time. For example, you can filter the grid so that only items starting with the letter A or the letter B appear in the grid (instead of limiting the filter to one or the other). All you need to do to have text appear in the filter bar is set the [FilterMultiSelect](/componentone/docs/win/online-truedbgrid/) property to **True**.

For example in the following code, the [FilterMultiSelect](/componentone/docs/win/online-truedbgrid/) property in the first filter bar cell is set to **True**:

```csharp
// Display the filter bar
this.c1TrueDBGrid1.FilterBar = true;
// Allow the first column to be filtered by multiple items
this.c1TrueDBGrid1.Columns[0].FilterMultiSelect = true;
```

If you run the application, you'll notice that you can filter the first cell with multiple criteria. For example type "a,b" in the filter bar and notice that items starting with the letter A and the letter B are displayed. You can customize the character used for separating filter items by setting the [FilterSeparator](/componentone/docs/win/online-truedbgrid/) property.

## Adding Filter DropDown

In addition to the filter bar, you can also include a drop-down filter list in the filter bar. The drop-down list lists every item in that column and provides a simple way that users can choose what items to filter the column by without entering their own value.

For example in the following code, the [FilterDropDown](/componentone/docs/win/online-truedbgrid/) property in the second filter bar cell is set to **True**:

```csharp
// Display the filter bar.
this.c1TrueDBGrid1.FilterBar = true;
// Allow the first column to be filtered by multiple items.
this.c1TrueDBGrid1.Columns[1].FilterDropdown = true;
// Allow the first column to be filtered by multiple items.
this.c1TrueDBGrid1.Columns[1].FilterMultiSelect = true;
```

If you run the application, you'll notice that you can select the filter drop-down list to choose what to filter the column by:

![](https://cdn.mescius.io/document-site-files/images/a1b176e5-6638-4b1f-a786-e41a817558bb/images/filter-dropdown-grid.png)

Click check boxes to choose items that will be displayed. Checked items will be displayed and items with cleared check boxes will not be displayed. Click the **Apply** button in the filter bar to apply the filter criteria. Click the **Clear** button to clear the filter. Click the **Close** button to close the drop-down list.

## Custom Filtering

You can create your own filtering method using the [FilterDefinition](/componentone/docs/win/online-truedbgrid/) property to save/load custom filters in code. You can apply one of a few pre-defined filters by reading the [FilterDefinition](/componentone/docs/win/online-truedbgrid/) property from a xml file like the following:

```csharp
void ReadFilter(string name)
{
    c1TrueDBGrid1.Splits[0].FilterDefinition = System.IO.File.ReadAllText(name + ".xml");
}
```

The custom filter can then be applied to the grid and saved as custom like the following:

```csharp
private void btnSave_Click(object sender, EventArgs e)
{
    SaveCustomFilter();
}
```

>type=note
> **Note**: For a complete sample using this FilterDefinition property, see the **FilterDefinitionTdbg** sample installed with **WinForms Edition**.