ColumnView.ShowFilterPopupListBox Event

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

Namespace: DevExpress.XtraGrid.Views.Base

Assembly: DevExpress.XtraGrid.v20.1.dll

Declaration

[DXCategory("Behavior")]
public event FilterPopupListBoxEventHandler ShowFilterPopupListBox
<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.

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.

CD_Filtering_FilterDDown_Today

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:

CD_Filtering_FilterDDown_ThisMonthApplied

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.

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;
}

Examples

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):

CD_Filtering_FilterDDown_Customize1

Selecting this item applies the ("[CustomerID] = 'DUMON'") filter to the bound data source:

CD_Filtering_FilterDDown_Customize2

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();
    }
}
See Also