menu

WinForms

  • Code Examples
  • Upgrade Guide
  • User Guide
  • Demos
  • Support
  • Forums
  • Download
Class GridFilterBar - WindowsForms API Reference | Syncfusion

    Show / Hide Table of Contents

    Class GridFilterBar

    Encapsulates the functionality of adding a header row of combo boxes to a GridDataBoundGrid so the rows displayed in the grid can be filtered using the combo boxes.

    Inheritance
    System.Object
    GridFilterBar
    GridDataBoundGridFilterBarExt
    Inherited Members
    System.Object.Equals(System.Object)
    System.Object.Equals(System.Object, System.Object)
    System.Object.GetHashCode()
    System.Object.GetType()
    System.Object.MemberwiseClone()
    System.Object.ReferenceEquals(System.Object, System.Object)
    System.Object.ToString()
    Namespace: Syncfusion.Windows.Forms.Grid
    Assembly: Syncfusion.Grid.Windows.dll
    Syntax
    public class GridFilterBar
    Remarks

    Please note that currently, FilterBars are only supported for simple GridDataBoundGrids that are not hierarchical.

    Constructors

    GridFilterBar()

    Initializes a new GridFilterBar object.

    Declaration
    public GridFilterBar()

    Fields

    GridFilterBarStrings

    String array that holds the strings used in GridFilterBar.

    Declaration
    public string[] GridFilterBarStrings
    Field Value
    Type
    System.String[]
    Remarks

    If you want to change these strings, you can set your new strings into the appropriate position in the GridFilterBarStrings array. Here is the code that shows the default settings. You should assign your new strings to the corresponding positions.

    The first two entries are the special items in the droplists for filter combo box cells. If you set one or both of these strings to the empty string, that option will not appear in the droplist.

    Examples

    Here is the code that shows position of each string in GridFilterBarStrings.

           public string[] GridFilterBarStrings = new string[]
           {
               "(none)",                                        //0
               "(custom)",                                        //1
               "equals",                                        //2
               "does not equal",                                //3
               "is greater than",                                //4
               "is greater than or equal to",                    //5
               "is less than",                                    //6
               "is less than or equal to",                        //7
               "begins with",                                    //8
               "does not begin with",                            //9
               "ends with",                                    //10
               "does not end with",                            //11
               "contains",                                        //12
               "does not contain",                                //13
               "Use * to represent any series of characters",    //14
               "Show rows where:",                                //15
               "Improper custom filter: ",                        //16
               "I and "                                        //17
           };

    originalDataView

    Used internally. Used to maintain original DataView in the table..

    Declaration
    protected DataView originalDataView
    Field Value
    Type
    System.Data.DataView

    originalFilterOnTable

    Used internally. Used to maintain original filter in the table.

    Declaration
    protected string originalFilterOnTable
    Field Value
    Type
    System.String

    originalSortOnTable

    Used internally. Used to maintain original sort in the table.

    Declaration
    protected string originalSortOnTable
    Field Value
    Type
    System.String

    Properties

    ParenthesesAroundColumnFilters

    Gets or sets a value indicating whether to enclosed each column filter in parentheses when they are ANDed to create the RowFilter string.

    Declaration
    public bool ParenthesesAroundColumnFilters { get; set; }
    Property Value
    Type
    System.Boolean
    Remarks

    The default value is true. This property only has an effect if you have multiple column filters set, and have also set a compound filter using an OR clause in the Custom dialog. In this case, the parentheses are needed to ensure the proper evaluation of the logical expression. Versions earlier than 4.1.0.0, did not provide these added parentheses. If you need this earlier behavior, then set this property to false.

    RowFilter

    Gets or sets the RowFilter for use as the DataView.RowFilter property for the DataView associated with the current GridDataBoundGrid.DataSource.

    Declaration
    public string RowFilter { get; set; }
    Property Value
    Type
    System.String
    Remarks

    Setting this property will apply the filter contained in the string to the default DataView of the GridDataBoundGrid. This member is set as you use the combo boxes on the FilterBar. But you can also set it explicitly as well.

    StyleInfo

    Gets or sets the default style for the cells in the FilterBar row.

    Declaration
    public GridStyleInfo StyleInfo { get; set; }
    Property Value
    Type
    GridStyleInfo
    Remarks

    You can use this property to control the basic appearance, such as BackColor or Font, of the cells on the FilterBar row.

    Wired

    Gets a value indicating whether this FilterBar object is associated with a GridDataBoundGrid.

    Declaration
    public bool Wired { get; }
    Property Value
    Type
    System.Boolean

    Methods

    CreateUniqueEntries(DataView, String)

    Creates a DataTable of unique choices for a FilterBar entry.

    Declaration
    protected virtual DataTable CreateUniqueEntries(DataView dv, string colName)
    Parameters
    Type Name Description
    System.Data.DataView dv

    The DataView that is being displayed in the grid.

    System.String colName

    The column name of the column whose FilterBar choices are being constructed.

    Returns
    Type Description
    System.Data.DataTable

    A DataTable.

    Remarks

    This method is called to generate the list of entries for the default drop-down cell. The method inserts (none) and (custom) as the first two entries in the list. The other entries are unique occurrences of entries from the specified column. The (none) and (custom) strings can be changed through GridFilterBarStrings.

    GetDataTable()

    The DataTable associated with the displayed data in the wired grid.

    Declaration
    protected virtual DataTable GetDataTable()
    Returns
    Type Description
    System.Data.DataTable

    The DataTable.

    GetFilterFromRow(GridDataBoundGrid)

    Returns the filter string based on current cell values in the FilterBar.

    Declaration
    protected virtual string GetFilterFromRow(GridDataBoundGrid grid)
    Parameters
    Type Name Description
    GridDataBoundGrid grid

    The grid holding the FilterBar.

    Returns
    Type Description
    System.String

    Returns a string that is appropriate to use as a DataView.RowFilter string.

    GetFilterRow()

    The row index for the FilterBar row.

    Declaration
    protected virtual int GetFilterRow()
    Returns
    Type Description
    System.Int32

    Returns the row index where the FilterBar is displayed.

    GetGrid()

    Accessory for the wired grid.

    Declaration
    protected virtual GridDataBoundGrid GetGrid()
    Returns
    Type Description
    GridDataBoundGrid

    Returns the wired GridDataBoundGrid object.

    GridCurrentCellAcceptedChanges(Object, CancelEventArgs)

    This event occurs when current cell accept the editing was completed.

    Declaration
    protected void GridCurrentCellAcceptedChanges(object sender, CancelEventArgs e)
    Parameters
    Type Name Description
    System.Object sender

    The source control.

    System.ComponentModel.CancelEventArgs e

    The System.ComponentModel.CancelEventArgsthat contains event data.

    GridCurrentCellCloseDropDown(Object, PopupClosedEventArgs)

    Used internally. This event occurs while closing current cell DropDown.

    Declaration
    protected void GridCurrentCellCloseDropDown(object sender, PopupClosedEventArgs e)
    Parameters
    Type Name Description
    System.Object sender

    The source control.

    PopupClosedEventArgs e

    The PopupClosedEventArgsthat contains event data.

    GridCurrentCellShowingDropDown(Object, GridCurrentCellShowingDropDownEventArgs)

    Used internally. This event occurs when Current cell drop down showing.

    Declaration
    protected void GridCurrentCellShowingDropDown(object sender, GridCurrentCellShowingDropDownEventArgs e)
    Parameters
    Type Name Description
    System.Object sender

    The source control

    GridCurrentCellShowingDropDownEventArgs e

    The GridCurrentCellShowingDropDownEventArgsthat contains event data.

    GridKeyDown(Object, KeyEventArgs)

    Used to process key Messages when pressed.

    Declaration
    protected void GridKeyDown(object sender, KeyEventArgs e)
    Parameters
    Type Name Description
    System.Object sender
    System.Windows.Forms.KeyEventArgs e

    OnCreatingColumnHeader(GridFilterBarCreatingColumnHeaderEventArgs)

    Raises the CreatingColumnHeader event.

    Declaration
    protected virtual void OnCreatingColumnHeader(GridFilterBarCreatingColumnHeaderEventArgs e)
    Parameters
    Type Name Description
    GridFilterBarCreatingColumnHeaderEventArgs e

    A GridFilterBarCreatingColumnHeaderEventArgs that contains the event data.

    OnFilterBarFilterCompleted(GridFilterBarTextChangedEventArgs)

    Raises the FilterBarTextChanged event.

    Declaration
    protected virtual void OnFilterBarFilterCompleted(GridFilterBarTextChangedEventArgs e)
    Parameters
    Type Name Description
    GridFilterBarTextChangedEventArgs e

    A GridFilterBarTextChangedEventArgs that contains the event data.

    OnFilterBarShowDialog(GridFilterBarShowDialogEventArgs)

    Raises the FilterBarShowDialog event.

    Declaration
    protected virtual void OnFilterBarShowDialog(GridFilterBarShowDialogEventArgs e)
    Parameters
    Type Name Description
    GridFilterBarShowDialogEventArgs e

    A GridFilterBarShowDialogEventArgs that contains the event data.

    OnFilterBarTextChanged(GridFilterBarTextChangedEventArgs)

    Raises the FilterBarTextChanged event.

    Declaration
    protected virtual void OnFilterBarTextChanged(GridFilterBarTextChangedEventArgs e)
    Parameters
    Type Name Description
    GridFilterBarTextChangedEventArgs e

    A GridFilterBarTextChangedEventArgs that contains the event data.

    ResetFilterRow(GridDataBoundGrid)

    Blanks the filter string on every column.

    Declaration
    public void ResetFilterRow(GridDataBoundGrid grid)
    Parameters
    Type Name Description
    GridDataBoundGrid grid

    The grid holding the FilterBar.

    SetDataTable(DataTable)

    Sets the DataTable associated with the displayed data in the wired grid.

    Declaration
    protected virtual void SetDataTable(DataTable dt)
    Parameters
    Type Name Description
    System.Data.DataTable dt

    The DataTable.

    SetFilterRow(Int32)

    Sets the row index where the FilterBar is displayed.

    Declaration
    protected virtual void SetFilterRow(int r)
    Parameters
    Type Name Description
    System.Int32 r

    The row index where the FilterBar is displayed.

    SetGrid(GridDataBoundGrid)

    Specifies the wired grid.

    Declaration
    protected virtual void SetGrid(GridDataBoundGrid g)
    Parameters
    Type Name Description
    GridDataBoundGrid g

    The GridDataBoundGrid object to be wired.

    UnwireGrid()

    Disassociates a grid with this FilterBar.

    Declaration
    public virtual void UnwireGrid()

    WireGrid(GridDataBoundGrid)

    Associates a GridDataBoundGrid with this FilterBar.

    Declaration
    public void WireGrid(GridDataBoundGrid grid)
    Parameters
    Type Name Description
    GridDataBoundGrid grid

    The GridDataBoundGrid.

    Examples

    This example shows how to wire the filter bar with the specified grid.

    // Creates the filter-bar instance.
    GridFilterBar myFilterBar = new GridFilterBar();
    // Wires the grid to the filter-bar.
    myFilterBar.WireGrid(this.gridDataBoundGrid1);
    ' Creates the filter-bar instance.
    Dim myFilterBar As New GridFilterBar()
    ' Wires the grid to the filter-bar.
    myFilterBar.WireGrid(Me.gridDataBoundGrid1)

    WireGrid(GridDataBoundGrid, GridStyleInfo)

    Associates a GridDataBoundGrid with this FilterBar.

    Declaration
    public virtual void WireGrid(GridDataBoundGrid grid, GridStyleInfo style)
    Parameters
    Type Name Description
    GridDataBoundGrid grid

    The GridDataBoundGrid.

    GridStyleInfo style

    The GridStyleInfo object that sets the appearance of cells in the FilterBar row.

    Examples

    This example shows how to wire the filter bar with the specified grid and it's style.

    // Creates the filter-bar instance.
    GridFilterBar myFilterBar = new GridFilterBar();
    // Creates the GridStyleinfo instance and specifies the style properties.
    GridStyleInfo myStyle1 = new GridStyleInfo();
    myStyle1.BackColor = Color.WhiteSmoke;
    myStyle1.Font.Italic = true;
    myStyle1.Borders.All = new GridBorder(GridBorderStyle.Dashed);
    myStyle1.ExclusiveChoiceList = true;
    myStyle1.CellType = "ComboBox";
    myStyle1.BaseStyle = "Standard";
    myFilterBar.WireGrid(this.gridDataBoundGrid1, myStyle1);
    ' Creates the filter-bar instance.
    Dim myFilterBar As New GridFilterBar()
    ' Creates the GridStyleinfo instance and specifies the style properties.
    Dim myStyle1 As New GridStyleInfo()
    myStyle1.BackColor = Color.WhiteSmoke
    myStyle1.Font.Italic = True
    myStyle1.Borders.All = New GridBorder(GridBorderStyle.Dashed)
    myStyle1.ExclusiveChoiceList = True
    myStyle1.CellType = "ComboBox"
    myStyle1.BaseStyle = "Standard"
    myFilterBar.WireGrid(Me.gridDataBoundGrid1, myStyle1)

    Events

    CreatingColumnHeader

    Lets you control whether or not a column will display a drop-down in the added filter row.

    Declaration
    public event GridFilterBarCreatingColumnHeaderEventHandler CreatingColumnHeader
    Event Type
    Type
    GridFilterBarCreatingColumnHeaderEventHandler
    Remarks

    To indicate that a column should not contain a filter cell, set the Cancel member of the EventArgs to True.

    FilterBarFilterCompleted

    Raised immediately after a filter has be completed.

    Declaration
    public event GridFilterBarFilterCompletedEventHandler FilterBarFilterCompleted
    Event Type
    Type
    GridFilterBarFilterCompletedEventHandler
    Remarks

    Use this event if you need to know when your user has completed a filter action.

    FilterBarShowDialog

    Lets you display a custom filter dialog of your choosing.

    Declaration
    public event GridFilterBarShowDialogEventHandler FilterBarShowDialog
    Event Type
    Type
    GridFilterBarShowDialogEventHandler
    Remarks

    Your dialog should provide a properly formatted e.FilterCriteria that will be assigned to the GridFilterBar.RowFilter property to determine the filtered contents of the grid. To indicate that your filter should be applied, set e.Result = DialogResult.OK and e.Handled = True. To cancel the filter operation and leave the filter state of the grid as is, set e.Result = DialogResult.Cancel and e.Handled = True.
    To have the grid display its default dialog, set e.Handled = False.

    Examples

    The following example displays some arbitrary dialog. The dialog returns information necessary to set the proper values in the GridFilterBarShowDialogEventArgs e. If you want the default dialog shown, set e.handled = False. If you do not want the default dialog displayed, you set e.Handled = True. When e.Handled = True, you can indicate that the value of e.FilterCriteria should be used to filter the display by setting e.Result = DialogResult.OK.

             //Show my own custom filter. 
             private void GridFilterBarShowDialogEventHandler(object send, GridFilterBarShowDialogEventArgs e)
             {
                 MyFilterDialog dlg = new MyFilterDialog();
                 DialogResult result = dlg.ShowDialog();
    

    if(result == DialogResult.Ignore) { //Show the default dialog. e.Handled = false; } else { //Otherwise, don't show default and set the result. e.Handled = true; e.Result = result; //cancel or OK-filter the grid with e.FilterCriteria e.FilterCriteria = dlg.textBox1.Text; // the filter string } }

    FilterBarTextChanged

    Raised immediately prior to the GridFilterBar.RowFilter property changing.

    Declaration
    public event GridFilterBarTextChangedEventHandler FilterBarTextChanged
    Event Type
    Type
    GridFilterBarTextChangedEventHandler
    Remarks

    Use this event if you need to know when the RowFilter is about to change. For example, handling this event will allow you to display the current row filter.

    Back to top Generated by DocFX
    Copyright © 2001 - 2025 Syncfusion Inc. All Rights Reserved