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
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.
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.
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.
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
CheckStateenumeration includes theIndeterminatevalue, 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.
- You cannot modify the EditValue property directly for standalone
CheckedComboBoxEditcontrols. Instead, use the CheckedComboBoxEdit.SetEditValue(Object) method.
// 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);
- When you populate an editor manually, use the item CheckedListBoxItem.CheckState property.
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;
- Call the CheckedComboBoxEdit.CheckAll() method to check all editor items at once.
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.