ColumnView.ShowFilterPopupListBox Event

Enables you to customize a particular column’s filter dropdown list.

Namespace: DevExpress.XtraGrid.Views.Base

Assembly: DevExpress.XtraGrid.v24.2.dll

Declaration

C#

[DXCategory("Behavior")]
public event FilterPopupListBoxEventHandler ShowFilterPopupListBox

VB.NET

<DXCategory("Behavior")>
Public Event ShowFilterPopupListBox As FilterPopupListBoxEventHandler

Event Data

The ShowFilterPopupListBox event's data class is FilterPopupListBoxEventArgs. The following properties provide information specific to this event:

Property	Description
Column	Gets the grid column being processed. Inherited from FilterPopupEventArgs.
ComboBox	Gets an object providing access to the filter dropdown’s items.

Remarks

The ShowFilterPopupListBox event fires before the filter dropdown list is displayed. Write a handler for this event to manage the items within the list. Existing items can be deleted and new ones added with custom captions and corresponding filter values.

For details on customizing the filter dropdown list, see the Filter and Search topic.

Note

If you handle events from the list below, Data Grid switches from Excel-style filters to classic filtering menus. In this case, set the GridColumn.OptionsFilter.FilterPopupMode property to Excel to use Excel-style filters.

• ColumnView.ShowFilterPopupCheckedListBox
• ColumnView.ShowFilterPopupDate
• ColumnView.ShowFilterPopupListBox

Example

The following example illustrates how to use the ColumnView.ShowFilterPopupListBox event to add two custom items (“TODAY” and “THIS MONTH”) to the regular filter dropdown list for the OrderDate column.

When an end-user selects the TODAY item, an appropriate filter is applied to the column and this selects all the records whose OrderDate field contains a date between 12:00 AM and 11:59 PM today. Similarly, the THIS MONTH filter item selects the records which refer to the current month.

The next image shows the Grid View after selecting the ‘TODAY’ filter item:

Filter strings for the TODAY and THIS MONTH items are created via the custom getFilterString function. The text for the items to display in the filter panel is retrieved via the custom getFilterDisplayText function.

For information on creating ColumnFilterInfo objects to represent specific filter criteria, refer to the Advanced Filter and Search Concepts topic.

C#

using DevExpress.XtraGrid.Columns;
using DevExpress.XtraGrid.Views.Grid;

// Represents custom filter item types.
public enum ItemTypeEnum {itToday, itThisMonth};

private void gridView1_ShowFilterPopupListBox(object sender, FilterPopupListBoxEventArgs e) {
   if (e.Column.FieldName == "OrderDate") {
      // Get the index of the first value item.
      int index;
      for(index = 0; index < e.ComboBox.Items.Count; index++) {
         object item = e.ComboBox.Items[index];
         if(item is FilterItem) {
            object itemValue = ((FilterItem)item).Value;
            if(itemValue is FilterItem || itemValue is ColumnFilterInfo) continue;
            break;
         }
      }
      // Create filter criteria to select the records which refer to the current date.
      ColumnFilterInfo fInfo = new ColumnFilterInfo(getFilterString(e.Column.FieldName, 
        ItemTypeEnum.itToday), 
        getFilterDisplayText(e.Column.Caption, ItemTypeEnum.itToday));
      // Add the custom TODAY filter item.
      e.ComboBox.Items.Insert(index, new FilterItem("TODAY", fInfo));
      // Create filter criteria to select the records which refer to the current month.
      fInfo = new ColumnFilterInfo(getFilterString(e.Column.FieldName, ItemTypeEnum.itThisMonth), _
        getFilterDisplayText(e.Column.Caption, ItemTypeEnum.itThisMonth));
      // Add the custom THIS MONTH filter item.
      e.ComboBox.Items.Insert(index + 1, new FilterItem("THIS MONTH", fInfo));
   }
}

// Returns a filter expression for a custom filter item.
protected virtual string getFilterString(string columnName, ItemTypeEnum itemType) {
   string filter = "";
   DateTime date1, date2;
   string date1Str, date2Str;
   switch (itemType) {
      // The filter expression for the TODAY item.
      case ItemTypeEnum.itToday:
         date1 = DateTime.Today;
         date2 = date1.AddDays(1);
         date1Str = "#" + date1.ToString("g") + "#";
         date2Str = "#" + date2.ToString("g") + "#";
         filter = "([" + columnName + "] >= " + date1Str + " AND [" + columnName + "] < " 
           + date2Str + ")";
         break;
      // The filter expression for the THIS MONTH item.
      case ItemTypeEnum.itThisMonth:
         date1 = DateTime.Today.AddDays(1 - DateTime.Today.Day);
         date2 = date1.AddMonths(1);
         date1Str = "#" + date1.ToString("g") + "#";
         date2Str = "#" + date2.ToString("g") + "#";
         filter = "([" + columnName + "] >= " + date1Str + " AND [" + columnName + "] < " 
           + date2Str + ")";
         break;
   }
   return filter;
}

// Returns the filter display text for a custom filter item.
protected virtual string getFilterDisplayText(string columnName, ItemTypeEnum itemType) {
   string displayText="";
   switch (itemType) {
      case ItemTypeEnum.itToday:
         displayText = columnName + " = TODAY";
         break;
      case ItemTypeEnum.itThisMonth:
         displayText = columnName + " = THIS MONTH";
         break;
   }
   return displayText;
}

VB.NET

Imports DevExpress.XtraGrid.Columns
Imports DevExpress.XtraGrid.Views.Grid

' Represents custom filter item types.
Public Enum ItemTypeEnum
    itToday
    itThisMonth
End Enum

Private Sub GridView1_ShowFilterPopupListBox(ByVal sender As System.Object, ByVal e As FilterPopupListBoxEventArgs) Handles GridView1.ShowFilterPopupListBox
   If e.Column.FieldName = "OrderDate" Then
      ' Get the index of the first value item.
      Dim index As Integer
      For index = 0 To e.ComboBox.Items.Count - 1
         Dim item As Object = e.ComboBox.Items(index)
         If TypeOf item Is FilterItem Then
            Dim itemValue As Object = item.Value
            If (Not TypeOf itemValue Is FilterItem) And _
               (Not TypeOf itemValue Is ColumnFilterInfo) Then Exit For
         End If
      Next
      ' Create filter criteria to select the records which refer to the current date.
      Dim fInfo As ColumnFilterInfo = New ColumnFilterInfo( _
        getFilterString(e.Column.FieldName, ItemTypeEnum.itToday), _
        getFilterDisplayText(e.Column.Caption, ItemTypeEnum.itToday))
      ' Add the custom TODAY filter item.
      e.ComboBox.Items.Insert(index, New FilterItem("TODAY", fInfo))
      ' Create filter criteria to select the records which refer to the current month.
      fInfo = New ColumnFilterInfo( _
      getFilterString(e.Column.FieldName, ItemTypeEnum.itThisMonth), _
      getFilterDisplayText(e.Column.Caption, ItemTypeEnum.itThisMonth))
      ' Add the custom THIS MONTH filter item.
      e.ComboBox.Items.Insert(index + 1, New FilterItem("THIS MONTH", fInfo))
   End If
End Sub

' Returns a filter expression for a custom filter item.
Protected Overridable Function getFilterString(ByVal columnName As String, _
ByVal itemType As ItemTypeEnum) As String
   Dim filter As String = ""
   Dim date1, date2 As DateTime
   Dim date1Str, date2Str As String
   Select Case itemType
      Case ItemTypeEnum.itToday
         ' The filter expression for the TODAY item.
         date1 = DateTime.Today
         date2 = date1.AddDays(1)
         date1Str = "#" + date1.ToString("g") + "#"
         date2Str = "#" + date2.ToString("g") + "#"
         filter = "([" + columnName + "] >= " + date1Str + " AND [" + columnName + "] < " _
           + date2Str + ")"
         Exit Select
      Case ItemTypeEnum.itThisMonth
         ' The filter expression for the THIS MONTH item.
         date1 = DateTime.Today.AddDays(1 - DateTime.Today.Day)
         date2 = date1.AddMonths(1)
         date1Str = "#" + date1.ToString("g") + "#"
         date2Str = "#" + date2.ToString("g") + "#"
         filter = "([" + columnName + "] >= " + date1Str + " AND [" + columnName + "] < " _
           + date2Str + ")"
         Exit Select
   End Select
   Return filter
End Function

' Returns the filter display text for a custom filter item.
Protected Overridable Function getFilterDisplayText(ByVal columnName As String, _
ByVal itemType As ItemTypeEnum) As String
   Dim displayText As String = ""
   Select Case itemType
      Case ItemTypeEnum.itToday
         displayText = columnName + " = TODAY"
         Exit Select
      Case ItemTypeEnum.itThisMonth
         displayText = columnName + " = THIS MONTH"
         Exit Select
   End Select
   Return displayText
End Function

Example

The following code shows how to remove all the items in a regular filter dropdown list except for the predefined ones, and then add a new value item (‘VIP Client’) to the CustomerID column. It’s assumed that the columns’ MRU filter items are disabled (the ColumnViewOptionsFilter.AllowColumnMRUFilterList property is set to false):

Selecting this item applies the (“[CustomerID] = ‘DUMON’”) filter to the bound data source:

C#

using DevExpress.XtraGrid.Views.Grid;
// ...
gridView1.OptionsFilter.AllowColumnMRUFilterList = false;
// ...
private void gridView1_ShowFilterPopupListBox(object sender, FilterPopupListBoxEventArgs e) {
    GridView view = sender as GridView;
    if(e.Column != view.Columns["CustomerID"]) return;
    // New item value and display text.
    string itemDisplayText = "VIP Client";
    string itemValue = "DUMON";
    // Prevent excessive item updates.
    e.ComboBox.BeginUpdate();
    try {
        // Delete values items.
        while(e.ComboBox.Items.Count > 4) e.ComboBox.Items.RemoveAt(e.ComboBox.Items.Count - 1);
        // Add a new item.
        e.ComboBox.Items.Add(new FilterItem(itemDisplayText, itemValue));
    }
    finally {
        e.ComboBox.EndUpdate();
    }
}

VB.NET

Imports DevExpress.XtraGrid.Views.Grid
' ...
GridView1.OptionsFilter.AllowColumnMRUFilterList = False
' ...
Private Sub GridView1_ShowFilterPopupListBox(ByVal sender As Object, ByVal e As FilterPopupListBoxEventArgs) Handles GridView1.ShowFilterPopupListBox
    Dim view as GridView = sender
    If Not e.Column Is view.Columns("CustomerID") Then Return
    ' New item value and display text.
    Dim itemDisplayText As String = "VIP Client"
    Dim itemValue As String = "DUMON"
    ' Prevent excessive item updates.
    e.ComboBox.BeginUpdate()
    Try
        ' Delete values items.
        While (e.ComboBox.Items.Count > 4)
            e.ComboBox.Items.RemoveAt(e.ComboBox.Items.Count - 1)
        End While
        ' Add a new item.
        e.ComboBox.Items.Add(New FilterItem(itemDisplayText, itemValue))
    Finally
        e.ComboBox.EndUpdate()
    End Try
End Sub