ComboBoxEdit Class

The text editor that allows you to select predefined items from a dropdown list. List items are typically represented by strings.

Namespace: DevExpress.XtraEditors

Assembly: DevExpress.XtraEditors.v20.1.dll

Declaration

public class ComboBoxEdit :
    PopupBaseAutoSearchEdit
Public Class ComboBoxEdit
    Inherits PopupBaseAutoSearchEdit

Related API Members

The following members accept/return ComboBoxEdit objects:

Remarks

A combo box control combines the functionality of a single-line text editor with a drop-down window. The drop-down displays a list of items that can be selected by an end-user. Selecting an item changes the editor's edit value. If the RepositoryItemButtonEdit.TextEditStyle property is set to TextEditStyles.Standard, the end-user is able to type any text in the edit box, which may not match an item in the drop-down list. To require the user to select only values from the drop-down list, set the RepositoryItemButtonEdit.TextEditStyle property to TextEditStyles.DisableTextEditor.

The image below shows a sample combo box editor.

ComboBoxEditor

Customize the combo box control by using the ComboBoxEdit.Properties property, which allows you to:

Items in the RepositoryItemComboBox.Items collection can be of any type. If items are of the String type, the item value and display text match. In other cases, an item's display text is determined by the item's ToString method.

When an end-user selects an item from the drop-down window, a corresponding object from the item collection is automatically assigned to the ComboBoxEdit.SelectedItem property. This property value is then assigned to the editor's ComboBoxEdit.EditValue property.

NOTE

To ensure that the editor works correctly, items in the RepositoryItemComboBox.Items collection must be unique objects.

The currently selected item can also be specified by its index using the ComboBoxEdit.SelectedIndex property.

When no item is selected, you can display custom text within the editor's edit box. To do this, handle the RepositoryItem.CustomDisplayText event. This event does not fire when the edit value is null. To provide custom display text when the editor's value is set to null, use the RepositoryItem.NullText property.

Examples

The following code creates a combo box editor and adds three items to the item collection. Each item in the example is a PersonInfo class object, which stores a person's first and last names.

The ComboBoxItemCollection.BeginUpdate and ComboBoxItemCollection.EndUpdate methods are called to prevent excessive updates when the item collection is changed (three items are added).

The BaseListBoxControl.SelectedIndex property is set to -1 for demonstration purposes (the property is set to -1 by default). This ensures that no item is currently selected in the combo box.

  ComboBoxEdit combo = new ComboBoxEdit();
  ComboBoxItemCollection coll = combo.Properties.Items;
  coll.BeginUpdate();
  try {
    coll.Add(new PersonInfo("Sven", "Petersen"));
    coll.Add(new PersonInfo("Cheryl", "Saylor"));
    coll.Add(new PersonInfo("Dirk", "Luchte"));
  }
  finally {
    coll.EndUpdate();
  }
  combo.SelectedIndex = -1;

  Controls.Add(combo);


//...

  public class PersonInfo {
    private string _firstName;
    private string _lastName;

    public PersonInfo(string firstName, string lastName) {
      _firstName = firstName;
      _lastName = lastName;
    }

    public override string ToString() {
      return _firstName + " " + _lastName;
    }
  }
See Also