windowsforms-devexpress-dot-xtraeditors-7ce7f602.md
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.v25.2.dll
NuGet Package : DevExpress.Win.Navigation
public class CheckedComboBoxEdit :
PopupContainerEdit
Public Class CheckedComboBoxEdit
Inherits PopupContainerEdit
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.
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");
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")
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
};
Partial Public Class Form1
Inherits Form
Public Sub New()
InitializeComponent()
checkedComboBoxEdit1.Properties.SetFlags(GetType(MultiHue))
End Sub
End Class
<Flags>
Public Enum MultiHue
None = 0
Black = 1
Red = 2
Green = 4
Blue = 8
End Enum
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;
}
}
}
}
}
Imports DevExpress.XtraEditors.Repository
<Flags> _
Enum MyColors
None = &H0
Black = &H1
White = &H2
Blue = &H4
Yellow = &H8
Green = Blue Or Yellow 'combined flag
End Enum
Public Class Form1
Private Sub Form1_Load(sender As Object, e As EventArgs) Handles MyBase.Load
' Populate the Items collection with all available flags.
CheckedComboBoxEdit1.Properties.SetFlags(GetType(MyColors))
' Remove items that correspond to compound flags.
removeCombinedFlags(CheckedComboBoxEdit1.Properties)
' Set an initial value.
CheckedComboBoxEdit1.SetEditValue(MyColors.Black Or MyColors.Green)
End Sub
' Traverse through items and remove those that correspond to bitwise combinations of simple flags.
Private Sub removeCombinedFlags(ri As RepositoryItemCheckedComboBoxEdit)
For i As Integer = ri.Items.Count - 1 To 1 Step -1
Dim val1 As [Enum] = TryCast(ri.Items(i).Value, [Enum])
For j As Integer = i - 1 To 0 Step -1
Dim val2 As [Enum] = TryCast(ri.Items(j).Value, [Enum])
If val1.HasFlag(val2) Then
ri.Items.RemoveAt(i)
Exit For
End If
Next
Next
End Sub
End Class
To populate CheckedComboBoxEdit from an external source, you need to specify three properties:
RepositoryItemCheckedComboBoxEdit.DataSourceThe object that stores data (a data table, a BindingSource component, a DbContext component, etc.).RepositoryItemCheckedComboBoxEdit.ValueMemberThe name of a data field that stores item values.RepositoryItemCheckedComboBoxEdit.DisplayMemberThe 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.
ListBoxItem.ValueEvery 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.
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
checkedComboBoxEdit1.Properties.SeparatorChar = ";"c
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.
Partial Public Class Form1
Inherits Form
Public Sub New()
InitializeComponent()
checkedComboBoxEdit1.Properties.SetFlags(GetType(MultiHue))
checkedComboBoxEdit1.CheckAll()
End Sub
End Class
<Flags>
Public Enum MultiHue
None = 0
Black = 1
Red = 2
Green = 4
Blue = 8
End Enum
' 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
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.
There are multiple ways to check or uncheck items.
CheckedComboBoxEdit controls. Instead, use the CheckedComboBoxEdit.SetEditValue(Object) method.csharp// 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);vb' Regular items, the EditValueType is CSV checkedComboBoxEdit1.SetEditValue("One, 2, True") ' Regular items, the EditValueType is List checkedComboBoxEdit1.SetEditValue(New List(Of Object)() From {"One", 2, True}) ' Flags checkedComboBoxEdit2.SetEditValue(MultiHue.Black Or MultiHue.Blue Or MultiHue.Red)
csharpcheckedComboBoxEdit1.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;vbcheckedComboBoxEdit1.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
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.
csharpbool 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; } }vbPrivate subscribe As Boolean = True Private checkedItems As New List(Of CheckedListBoxItem)() Private Sub checkedComboBoxEdit1_Popup(ByVal sender As Object, ByVal e As EventArgs) If subscribe Then ' 1st approach Dim list As CheckedListBoxControl = (TryCast(sender, IPopupControl)).PopupWindow.Controls.OfType(Of PopupContainerControl)().First().Controls.OfType(Of CheckedListBoxControl)().First() AddHandler list.ItemCheck, AddressOf list_ItemCheck subscribe = False End If ' 2nd approach ' CheckedListBoxControl list = (sender as IPopupControl).PopupWindow.Controls.OfType<PopupContainerControl>().First().Controls.OfType<CheckedListBoxControl>().First(); ' list.ItemCheck -= list_ItemCheck; ' list.ItemCheck += list_ItemCheck; ' End Sub Private Sub list_ItemCheck(ByVal sender As Object, ByVal e As DevExpress.XtraEditors.Controls.ItemCheckEventArgs) 'retrieve the embedded CheckedListBoxControl Dim list As CheckedListBoxControl = TryCast(sender, CheckedListBoxControl) If e.State = CheckState.Checked Then ' 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 Then For Each item As CheckedListBoxItem In list.Items If checkedItems.Contains(item) Then item.CheckState = CheckState.Checked Else item.Enabled = False End If Next item End If Else ' If an item is unchecked, unlock all items checkedItems.Remove(list.Items(e.Index)) For Each item As CheckedListBoxItem In list.Items item.Enabled = True Next item End If End Sub
RepositoryItemCheckedComboBoxEdit.SelectAllItemVisible, RepositoryItemCheckedComboBoxEdit.SelectAllItemCaptionAllow you to hide or rename the Select All item in the editor drop-down list.RepositoryItemCheckedComboBoxEdit.DropDownRowsThe maximum drop-down list height (the number of visible items).RepositoryItemPopupBase.PopupFormSizeThe drop-down list size. If you change this value, the editor ignores the DropDownRows property setting.
This example assigns a ToolTipController component to the CheckedComboBoxEdit control and handles the ToolTipController.GetActiveObjectInfo event to show a custom super tooltip for items/values displayed in the edit box.
Show 13 items
Object MarshalByRefObject Component Control DevExpress.XtraEditors.XtraControl ControlBase BaseControl BaseEdit TextEdit ButtonEdit PopupBaseEdit PopupContainerEdit CheckedComboBoxEdit
See Also