Skip to main content

CheckedComboBoxEdit Class

An editor that displays a list of check boxes in a drop-down menu. Users can select multiple items.

Namespace: DevExpress.XtraEditors

Assembly: DevExpress.XtraEditors.v24.1.dll

NuGet Package: DevExpress.Win.Navigation

Declaration

public class CheckedComboBoxEdit :
    PopupContainerEdit

Remarks

Populate a Checked Combo Box with Items

You can populate a checked combo box with items manually, bind it to a data source, or pass a bit field (flag) enumerator to the editor so that it converts all flags into items.

Add Items Manually

Open the editor’s smart tag menu and click Edit Items.

additems

In code, you can modify the Items collection.

checkedComboBoxEdit1.Properties.Items.Clear();

checkedComboBoxEdit1.Properties.Items.Add("One", "Item with string value");
checkedComboBoxEdit1.Properties.Items.Add(2, "Item with integer value");
checkedComboBoxEdit1.Properties.Items.Add(true, "Item with boolean value");

Populate with Bit Fields (Flags)

To auto-populate a checked combo box editor with flags, use the RepositoryItemCheckedComboBoxEdit.SetFlags(Type) method.

public partial class Form1 : Form {
    public Form1() {
        InitializeComponent();
        checkedComboBoxEdit1.Properties.SetFlags(typeof(MultiHue));
    }
}

[Flags]
public enum MultiHue
{
    None = 0,
    Black = 1,
    Red = 2,
    Green = 4,
    Blue = 8
};

The following figure illustrates the result. Note that the flag that has the “0” value (“None” in the sample above) is selected when all other items are unchecked.

addflags

CheckedComboBoxEdit does not support combined flags (values that combine two or more regular flags). If you use an enumeration with such flags, remove them from the editor Items collection as shown in the following sample.

using DevExpress.XtraEditors.Repository;

[Flags]
enum MyColors {
    None = 0x00,
    Black = 0x01,
    White = 0x02,
    Blue = 0x04,
    Yellow = 0x08,
    Green = Blue | Yellow //combined flag
}

public partial class Form1 : Form {
    public Form1() {
        InitializeComponent();

        // Populate the Items collection with all available flags.
        checkedComboBoxEdit1.Properties.SetFlags(typeof(MyColors));
        // Remove items that correspond to compound flags.
        removeCombinedFlags(checkedComboBoxEdit1.Properties);
        // Set an initial value.
        checkedComboBoxEdit1.SetEditValue(MyColors.Black | MyColors.Green);
    }

    // Traverse through items and remove those that correspond to bitwise combinations of simple flags.
    private void removeCombinedFlags(RepositoryItemCheckedComboBoxEdit ri) {
        for (int i = ri.Items.Count - 1; i > 0; i--) {
            Enum val1 = ri.Items[i].Value as Enum;
            for (int j = i - 1; j >= 0; j--) {
                Enum val2 = ri.Items[j].Value as Enum;
                if (val1.HasFlag(val2)) {
                    ri.Items.RemoveAt(i);
                    break;
                }
            }
        }
    }
}

Bind to a Data Source

To populate CheckedComboBoxEdit from an external source, you need to specify three properties:

RepositoryItemCheckedComboBoxEdit.DataSource
The object that stores data (a data table, a BindingSource component, a DbContext component, etc.).
RepositoryItemCheckedComboBoxEdit.ValueMember
The name of a data field that stores item values.
RepositoryItemCheckedComboBoxEdit.DisplayMember
The name of a data field that stores item captions.

You can set up all three settings at design time: invoke the smart tag menu and check the Use data bound items option.

datasource

See the Data Binding Common Concepts section for more information.

Item Settings

ListBoxItem.Value
Every list box item must have a unique value. This value is used to identify currently selected items.
  • CheckedListBoxItem.Description - If you do not specify this property, users will see item values converted to strings at runtime. This property allows you to set up visible item captions that differ from values.

  • CheckedListBoxItem.CheckState - Allows you to identify whether the item is checked, and change its check state in code. Note that although the CheckState enumeration includes the Indeterminate value, the editor does not support this state and displays all indeterminate items as unchecked.

  • CheckedListBoxItem.Enabled - Set this property to false to disable the item.

Get Checked Items

The editor’s EditValue property returns a combination of all checked item values. For non-flag items, this is a string that contains item values, separators (the default separator is a comma; you can change the separator with the RepositoryItemCheckedComboBoxEdit.SeparatorChar property), and spaces.

checkedComboBoxEdit1.Properties.SeparatorChar = ';';
checkedComboBoxEdit1.Properties.Items.Add("One", "Item with string value", System.Windows.Forms.CheckState.Checked, true);
checkedComboBoxEdit1.Properties.Items.Add(2, "Item with integer value", System.Windows.Forms.CheckState.Checked, true);
checkedComboBoxEdit1.Properties.Items.Add(true, "Item with boolean value", System.Windows.Forms.CheckState.Checked, true);

// checkedComboBoxEdit1.EditValue returns the "One; 2; True" string

For editors that display bit fields, the EditValue property returns an object of the flag enumerator type.

public partial class Form1 : Form {
    public Form1() {
        InitializeComponent();
        checkedComboBoxEdit1.Properties.SetFlags(typeof(MultiHue));
        checkedComboBoxEdit1.CheckAll();
    }
}

[Flags]
public enum MultiHue
{
    None = 0,
    Black = 1,
    Red = 2,
    Green = 4,
    Blue = 8
};

// checkedComboBoxEdit1.EditValue returns the "Black | Red | Green | Blue" object of the MultiHue type.

If you change the RepositoryItemCheckedComboBoxEdit.EditValueType to EditValueTypeCollection.List, EditValue for an editor that shows non-flag items will return a System.Collections.Generic.List<object> instead of a string.

checkedComboBoxEdit1.Properties.EditValueType = EditValueTypeCollection.List;
checkedComboBoxEdit1.Properties.Items.Add("One", "String Item", System.Windows.Forms.CheckState.Checked, true);
checkedComboBoxEdit1.Properties.Items.Add(2, "Int Item", System.Windows.Forms.CheckState.Checked, true);
checkedComboBoxEdit1.Properties.Items.Add(true, "Boolean Item", System.Windows.Forms.CheckState.Checked, true);

// (checkedComboBoxEdit1.EditValue as System.Collections.Generic.List<Object>)[0] returns the "One" string
// (checkedComboBoxEdit1.EditValue as System.Collections.Generic.List<Object>)[1] returns 2
// (checkedComboBoxEdit1.EditValue as System.Collections.Generic.List<Object>)[2] returns true

You can also call the RepositoryItemCheckedComboBoxEdit.GetCheckedItems() method instead of reading the EditValue property value.

Set Checked Items

There are multiple ways to check or uncheck items.

// Regular items, the EditValueType is CSV
checkedComboBoxEdit1.SetEditValue("One, 2, True");

// Regular items, the EditValueType is List
checkedComboBoxEdit1.SetEditValue(new List<object>() { "One", 2, true });

// Flags
checkedComboBoxEdit2.SetEditValue(MultiHue.Black | MultiHue.Blue | MultiHue.Red);
checkedComboBoxEdit1.Properties.Items.Add(1, "Checked Item", System.Windows.Forms.CheckState.Checked, true);
checkedComboBoxEdit1.Properties.Items.Add(2, "Unchecked Item", System.Windows.Forms.CheckState.Unchecked, true);
// or
checkedComboBoxEdit1.Properties.Items[2].CheckState = System.Windows.Forms.CheckState.Checked;

Limit the Maximum Number of Checked Items

Checked combo box editors are designed to allow users to check any number of drop-down list items.

  • If you need no more than one item checked at a time, use the ComboBoxEdit or LookUpEdit editor instead.

  • If you need to limit the required number of simultaneously checked items (more than one), handle the editor’s Popup event to access an embedded CheckedListBoxControl and modify its behavior. The sample below locks all drop-down list items when there are three checked items.

bool subscribe = true;
List<CheckedListBoxItem> checkedItems = new List<CheckedListBoxItem>();

private void checkedComboBoxEdit1_Popup(object sender, EventArgs e)
{
    if (subscribe) // 1st approach
    {
        CheckedListBoxControl list = (sender as IPopupControl).PopupWindow.Controls.OfType<PopupContainerControl>().First().Controls.OfType<CheckedListBoxControl>().First();
        list.ItemCheck += list_ItemCheck;
        subscribe = false;
    }

    /*  2nd approach
    CheckedListBoxControl list = (sender as IPopupControl).PopupWindow.Controls.OfType<PopupContainerControl>().First().Controls.OfType<CheckedListBoxControl>().First();
    list.ItemCheck -= list_ItemCheck;   
    list.ItemCheck += list_ItemCheck;
    */
}

void list_ItemCheck(object sender, DevExpress.XtraEditors.Controls.ItemCheckEventArgs e)
{
    // Retrieve the embedded CheckedListBoxControl
    CheckedListBoxControl list = sender as CheckedListBoxControl;

    if (e.State == CheckState.Checked)
    {
        // If an item was checked, add it to the checked items collection
        checkedItems.Add(list.Items[e.Index]);
        // If the checked items collection size exceeds the maximum capacity, disable other items
        if (checkedItems.Count >= 3)
            foreach (CheckedListBoxItem item in list.Items)
            {
                if (checkedItems.Contains(item)) item.CheckState = CheckState.Checked;
                else item.Enabled = false;
            }
    }
    else
    {
        // If an item is unchecked, unlock all items
        checkedItems.Remove(list.Items[e.Index]);
        foreach (CheckedListBoxItem item in list.Items)
            item.Enabled = true;
    }
}

Additional Settings

RepositoryItemCheckedComboBoxEdit.SelectAllItemVisible, RepositoryItemCheckedComboBoxEdit.SelectAllItemCaption
Allow you to hide or rename the Select All item in the editor drop-down list.
* RepositoryItemCheckedComboBoxEdit.DropDownRows
The maximum drop-down list height (the number of visible items).
RepositoryItemPopupBase.PopupFormSize
The drop-down list size. If you change this value, the editor ignores the DropDownRows property setting.

Inheritance

See Also