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.ToString()

System.Object.Equals(System.Object)

System.Object.Equals(System.Object, System.Object)

System.Object.ReferenceEquals(System.Object, System.Object)

System.Object.GetHashCode()

System.Object.GetType()

System.Object.MemberwiseClone()

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	Description
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	Description
System.Data.DataView

originalFilterOnTable

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

Declaration

protected string originalFilterOnTable

Field Value

Type	Description
System.String

originalSortOnTable

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

Declaration

protected string originalSortOnTable

Field Value

Type	Description
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	Description
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	Description
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	Description
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	Description
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	Description
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	Description
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	Description
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	Description
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.