A newer version of this page is available. Switch to the current version.

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.2.dll

Declaration

[SmartTagFilter(typeof(CheckedComboBoxEditFilter))]
[SmartTagAction(typeof(CheckedComboBoxEditActions), "Items", "Edit Items", SmartTagActionType.CloseAfterExecute)]
[ToolboxBitmap(typeof(ToolboxIconsRootNS), "CheckedComboBoxEdit")]
public class CheckedComboBoxEdit :
    PopupContainerEdit

Remarks

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.

CheckedComboBoxEdit

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:

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

The code below populates the RepositoryItemCheckedComboBoxEdit.Items collection with five items, each item stores a string value.

The CheckedComboBoxEdit.SetEditValue method is called to select “Circle” and “Ellipse” items. The “Circle” item is then disabled so that users cannot de-select it.

CheckedComboBoxEdit_ex

Note that the code modifies the RepositoryItemCheckedComboBoxEdit.SeparatorChar property to change the edit value separator char from the default comma (“,”) to a semicolon (“;”). The same separator char must be used in the SetEditValue method parameter.

// 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;

Examples

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:

CheckedComboBoxEdit_ex_Flags

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;
                }
            }
        }
    }
}
See Also