CheckedComboBoxEdit Class
Allows you to display and edit a set of Boolean options and bit fields in a popup window.
Namespace: DevExpress.XtraEditors
Assembly: DevExpress.XtraEditors.v18.1.dll
Declaration
[SmartTagFilter(typeof(CheckedComboBoxEditFilter))]
[SmartTagAction(typeof(CheckedComboBoxEditActions), "Items", "Edit Items", SmartTagActionType.CloseAfterExecute)]
[ToolboxTabName("DX.18.1: Common Controls")]
[ToolboxBitmap(typeof(ToolboxIconsRootNS), "CheckedComboBoxEdit")]
public class CheckedComboBoxEdit :
PopupContainerEditRemarks
This editor allows you to display and edit a set of Boolean Options and Bit Fields in the popup window. Boolean options and bit fields are represented by check boxes, which can be independently checked/unchecked.
By default, the editor’s dropdown contains a ‘Show All’ item at the top. Clicking this item checks/unchecks all other items. To rename this item, use the RepositoryItemCheckedComboBoxEdit.SelectAllItemCaption property, accessible via the CheckedComboBoxEdit.Properties object. To hide this item, use the RepositoryItemCheckedComboBoxEdit.SelectAllItemVisible property.
Like other BaseEdit descendants, the CheckedComboBoxEdit control can be used standalone and for in-place editing within container controls (XtraGrid, XtraTreeList, etc). To learn how to embed editors into container controls, see Repositories and Repository Items. When embedding to grid or treelist columns, ensure that the column’s data type is consistent with edit values being formed by the CheckedComboBoxEdit control.
Boolean Options
You can populate a CheckedComboBoxEdit with Boolean options manually or by reading them from a data source.
To manually provide a set of Boolean options, add corresponding items to the RepositoryItemCheckedComboBoxEdit.Items collection. Each item is represented by a CheckedListBoxItem object, providing the following options:
- ListBoxItem.Value - The item’s value. This property must specify a unique string or any unique object.
- CheckedListBoxItem.Description - The item’s display text.
- CheckedListBoxItem.CheckState - The item’s check state (checked or unchecked). The indeterminate state is not supported.
- CheckedListBoxItem.Enabled - Specifies whether the item’s state can be changed by an end-user.
The editor’s edit value (BaseEdit.EditValue) identifies all the selected options in the dropdown. With the RepositoryItemCheckedComboBoxEdit.EditValueType property, you can specify whether to form the edit value as a string or a list.
EditValueType Property Value | Edit Value |
|---|---|
EditValueType=CSV (default) | The edit value is a string, which is formed by concatenating check item values (text representation of these values), delimited by a separator character (RepositoryItemCheckedComboBoxEdit.SeparatorChar) and a space character. |
EditValueType=List | The edit value is a List<object> (a generic list of objects). Objects in the list match the values of checked options in the dropdown window. |
Note
To set the editor’s value when the control is used for standalone editing, use the CheckedComboBoxEdit.SetEditValue method. Do not set the editor’s EditValue property directly.
The editor’s display text is formed as follows:
- If all checked items have descriptions, the display text is formed by concatenating the item descriptions (CheckedListBoxItem.Description).
- If some checked items (not all) have descriptions, their descriptions are included in the resulting display text as is. Checked items that do not have descriptions are presented in the resulting display text by empty strings.
- If all checked items do not have descriptions, the display text is formed by concatenating the item values (ListBoxItem.Value).
It’s possible to populate the CheckedComboBoxEdit control’s item collection from a data source. To specify the data source, use the RepositoryItemCheckedComboBoxEdit.DataSource property. If the data source contains fields providing values and displays text for the check items, you can use these values automatically. To initialize the check item values and display text with the values of these fields, assign the names of the fields to the RepositoryItemCheckedComboBoxEdit.ValueMember and RepositoryItemCheckedComboBoxEdit.DisplayMember properties.
Bit Fields
The CheckedComboBoxEdit control allows a bit field (a set of flags) to be displayed and edited. A bit field is an enumeration declared with the FlagsAttribute attribute. To initialize the control’s item collection with flags, use the RepositoryItemCheckedComboBoxEdit.SetFlags method. After adding flags, you can delete individual items from the Items collection, if required. However, do not add custom items when the control is bound to a bit field. When the editor displays a set of flags, its edit value is of the enumeration type, and it represents a combination of checked flags.
Note
To set the editor’s value when the control is used for standalone editing, use the CheckedComboBoxEdit.SetEditValue method. Do not set the editor’s EditValue property directly.
Example
This example demonstrates how to display a set of Boolean options in a CheckedComboBoxEdit control. Check items representing the options to be edited are added directly to the RepositoryItemCheckedComboBoxEdit.Items collection.
The edit value (string) is assigned using the CheckedComboBoxEdit.SetEditValue method. Note that the items in the edit value string are separated using the delimiter specified by the RepositoryItemCheckedComboBoxEdit.SeparatorChar property.
The following image shows the CheckedComboBoxEdit control after executing the code:
// Add check items to the control's dropdown.
string[] itemValues = new string[] {
"Circle", "Rectangle", "Ellipse",
"Triangle", "Square" };
foreach (string value in itemValues)
checkedComboBoxEdit1.Properties.Items.Add(value, CheckState.Unchecked, true);
// Specify the separator character.
checkedComboBoxEdit1.Properties.SeparatorChar = ';';
// Set the edit value.
checkedComboBoxEdit1.SetEditValue("Circle; Ellipse");
// Disable the Circle item.
checkedComboBoxEdit1.Properties.Items["Circle"].Enabled = false;
Example
The following example shows how to edit bit fields (a set of flags) in a CheckedComboBoxEdit control.
The control displays values of a custom MyColors enum, which has five simple flags (None through Yellow) and one combined flag (Green). Combined flags are not supported by the CheckedComboBoxEdit control. Items that correspond to these flags must be manually removed from the RepositoryItemCheckedComboBoxEdit.Items collection (see the removeCombinedFlags method which performs this operation).
The RepositoryItemCheckedComboBoxEdit.SetFlags method populates the RepositoryItemCheckedComboBoxEdit.Items collection with items corresponding to all available flags (except for a flag with a zero value). Then, the removeCombinedFlags method is called to remove items corresponding to combined flags. Finally, the editor’s initial value is specified using the CheckedComboBoxEdit.SetEditValue method.
The following image shows the result:
Note that the Green flag is not present in the dropdown list, although you can set this flag to the control’s value.
using DevExpress.XtraEditors.Repository;
[Flags]
enum MyColors {
None = 0x00,
Black = 0x01,
White = 0x02,
Blue = 0x04,
Yellow = 0x08,
Green = Blue | Yellow
}
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;
}
}
}
}
}
Related GitHub Examples
The following code snippets (auto-collected from DevExpress Examples) contain references to the CheckedComboBoxEdit class.
Note
The algorithm used to collect these code examples remains a work in progress. Accordingly, the links and snippets below may produce inaccurate results. If you encounter an issue with code examples below, please use the feedback form on this page to report the issue.