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.v20.1.dll

Declaration

public class CheckedComboBoxEdit :
    PopupContainerEdit
Public Class CheckedComboBoxEdit
    Inherits PopupContainerEdit

Remarks

Populate a CheckedComboBox with Items

You can populate a CheckedComboBox 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 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 CheckedComboBox 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 a CheckedComboBoxEdit from an external source, you need to specify three properties.

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 to 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. In the code sample from the "Add Items" section above, the first parameter of each "Add" method is an item value.

  • CheckedListBoxItem.Description - if you do not specify this property, users will see item values converted to strings at runtime. The Description 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 provides 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 items' values. For non-flag items, this is a string that contains item values, separators (comma by default, 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 Checked Item Number

CheckedComboBox editors are designed to allow users to check any number of drop-down list items they need.

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

  • If you need to limit a 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

See Also