ColumnFilter
Namespace: Wisej.Web.Ext.ColumnFilter
Assembly: Wisej.Web.Ext.ColumnFilter (4.1.0.0)
Extender component that adds a filter button to the header of DataGridViewColumn columns. Clicking the button opens a ColumnFilterPanel that filters the rows of the DataGridView.
- C#
- VB.NET
public class ColumnFilter : Component, IWisejExtenderProvider, IExtenderProvider, ISupportInitialize
Public Class ColumnFilter
Inherits Component
Implements IWisejExtenderProvider, IExtenderProvider, ISupportInitialize
Set FilterPanelType to the ColumnFilterPanel subclass to use (i.e. SimpleColumnFilterPanel or WhereColumnFilterPanel) and enable the button on each column using the ShowFilter extender property or SetShowFilter. Filters are applied by hiding the rows that don't match; they are re-applied automatically when the DataGridView is sorted or its data binding completes.
Example:
Adding a filter button to all the columns of a DataGridView:
var columnFilter = new ColumnFilter();
columnFilter.FilterPanelType = typeof(SimpleColumnFilterPanel);
columnFilter.RowsFiltered += (s, e) => this.labelCount.Text = $"{e.FilteredRowCount} rows";
foreach (DataGridViewColumn column in this.dataGridView1.Columns)
{
columnFilter.SetShowFilter(column, true);
}
Constructors
ColumnFilter()
Initializes a new instance of the ColumnFilter class.
The ImageSource of the filter button is initialized to "icon-search".
ColumnFilter(container)
Initializes a new instance of the ColumnFilter class with a specified container.
| Name | Type | Description |
|---|---|---|
| container | IContainer | An IContainer that represents the container of the component. |
Throws:
- ArgumentNullException container is null.
Properties
FilteredImage
Image: Returns or sets the image that is displayed in the filter button when there is an active filter. Can be null.
Value: The Image to display.
The image is assigned to the filter button of each column that has an active filter when the filters are applied. When both FilteredImage and FilteredImageSource are null, the button keeps its current image.
FilteredImageSource
String: Returns or sets the theme name or URL for the image to display in the filter button when there is an active filter. Can be null.
Value: The theme name or URL for the image to display in the filter button.
Used only when FilteredImage is null. The value is assigned to the filter button of each column that has an active filter when the filters are applied.
FilterPanelType
Type: Returns or sets the type of the ColumnFilterPanel to associate with this ColumnFilter extender. (Default: null)
The type must be a subclass of ColumnFilterPanel with a public parameterless constructor. A new instance is created for each column the first time the user clicks its filter button and it's reused afterwards; changing this property doesn't replace panels that have already been created. This property must be set before the user clicks a filter button: the default value null causes an exception.
Throws:
- ArgumentException The value is not a subclass of ColumnFilterPanel.
Example:
Using the built-in panel that lets the user build conditions with operators:
this.columnFilter1.FilterPanelType = typeof(WhereColumnFilterPanel);
Using a custom panel derived from ColumnFilterPanel:
public class MyFilterPanel : ColumnFilterPanel
{
protected override bool OnApplyFilter()
{
// hide the rows that don't match and return true when a filter is active.
return false;
}
}
this.columnFilter1.FilterPanelType = typeof(MyFilterPanel);
Image
Image: Returns or sets the image that is displayed in the filter button.
Value: The Image to display.
The image is copied to each filter button when the button is created and it's also restored when a column's filter is cleared. Changing it at runtime doesn't update the buttons already created until the filters of the column are re-applied. When both Image and ImageSource are set, Image takes precedence.
ImageSize
Size: Returns or sets the size of the filter button in the column header, in pixels. (Default: {Width=24, Height=24})
The default value is 24 x 24. Changing the value resizes the filter buttons of all the registered columns. The image is centered in the button and it's not scaled.
ImageSource
String: Returns or sets the theme name or URL for the image to display in the filter button.
Value: The theme name or URL for the image to display in the filter button.
The default value is "icon-search". The value is copied to each filter button when the button is created and it's restored when a column's filter is cleared.
Example:
Using a different theme icon for the filter button and for the active filter state:
this.columnFilter1.ImageSource = "icon-filter";
this.columnFilter1.FilteredImageSource = "Images/filter-active.svg";
ShowOnHover
Boolean: Returns or sets whether the filter button is shown only when the mouse is over the column header. (Default: False)
When true, the filter button remains visible while the column has an active filter or its filter panel is open.
SortItems
Boolean: Returns or sets whether the filter panel sorts the items before displaying them.
Since 3.2.6 (Default: False)
Only supported by SimpleColumnFilterPanel: the value is copied to SortItems when the panel for a column is created (the first time its filter button is clicked). Changing it later doesn't affect panels that have already been created.
Methods
ApplyFilters(dataGridView)
Re-applies the filters to the specified DataGridView.
| Parameter | Type | Description |
|---|---|---|
| dataGridView | DataGridView | The DataGridView to filter. |
The filters of all the columns of dataGridView are applied using the first ColumnFilterPanel found. Filter panels are created when the user first clicks a filter button, so this method doesn't do anything until at least one panel exists. Filters are re-applied automatically when the DataGridView is sorted or its data binding completes. The built-in panels fire the RowsFiltered event after applying the filters.
Example:
Re-applying the filters after changing the data in code:
private void buttonRefresh_Click(object sender, EventArgs e)
{
this.dataGridView1.Rows.Add("Rome", "Italy");
this.columnFilter1.ApplyFilters(this.dataGridView1);
}
CreateFilterButton(column)
Creates the filter button to add to the target column's header.
| Parameter | Type | Description |
|---|---|---|
| column | DataGridViewColumn | The DataGridViewColumn that will display the filter button. |
Returns: Control. The Control to place in the column header. The default implementation returns a PictureBox docked to the right, sized to ImageSize, showing Image or ImageSource.
Called by SetShowFilter when a column is registered. The click and mouse enter/leave handlers that open the filter panel and implement ShowOnHover are attached by the default implementation; an override should call the base implementation and customize the returned control. Other members of the library (i.e. FilterButton) expect the control to be a PictureBox.
Example:
Customizing the filter button in a derived extender:
public class MyColumnFilter : ColumnFilter
{
public override Control CreateFilterButton(DataGridViewColumn column)
{
var button = base.CreateFilterButton(column);
button.ToolTipText = "Filter " + column.HeaderText;
return button;
}
}
GetShowFilter(column)
Returns whether the specified DataGridViewColumn shows the filter button in its header.
| Parameter | Type | Description |
|---|---|---|
| column | DataGridViewColumn | The DataGridViewColumn to query. |
Returns: Boolean. True if the DataGridViewColumn shows the filter button.
Throws:
- ArgumentNullException column is null.
Example:
Toggling the filter button of a column:
var column = this.dataGridView1.Columns["Country"];
this.columnFilter1.SetShowFilter(column, !this.columnFilter1.GetShowFilter(column));
OnRowsFiltered(filteredRowCount)
Fires the RowsFiltered event.
| Parameter | Type | Description |
|---|---|---|
| filteredRowCount | Int32 | The number of rows that are visible after applying the filters. |
Called by SimpleColumnFilterPanel and WhereColumnFilterPanel after applying the filters. Custom ColumnFilterPanel implementations should call it to notify the application.
Example:
Firing the event from a custom filter panel after the rows have been filtered:
var dataGrid = this.DataGridViewColumn.DataGridView;
this.ColumnFilter.OnRowsFiltered(dataGrid.Rows.GetRowCount(DataGridViewElementStates.Visible));
SetShowFilter(column, show)
Shows or hides the filter button on a DataGridViewColumn header panel.
| Parameter | Type | Description |
|---|---|---|
| column | DataGridViewColumn | The DataGridViewColumn for which to show or hide the filter button. |
| show | Boolean | True to show the filter button or false to remove it. |
Showing the filter button replaces the control in the column's header cell (column.HeaderCell.Control) with the control returned by CreateFilterButton. Removing it disposes that control and sets it to null. If the column was associated with a different ColumnFilter, it's detached from it and its existing filter panel is disposed.
Throws:
- ArgumentNullException column is null.
Example:
Showing the filter button on all the columns except the first:
foreach (DataGridViewColumn column in this.dataGridView1.Columns)
{
this.columnFilter1.SetShowFilter(column, column.Index > 0);
}
Events
RowsFiltered
EventHandler<RowsFilteredEventArg> Event is fired when all filters are applied.