windowsforms-devexpress-dot-xtraeditors-c8927bd5.md
A text editor that allows a user to select predefined items (typically, strings) from a drop-down list. The drop-down item list cannot be populated from a data source. Use lookup editors to display data source items in the drop-down list—LookUpEdit, GridLookUpEdit, SearchLookUpEdit, and TreeListLookUpEdit.
Namespace : DevExpress.XtraEditors
Assembly : DevExpress.XtraEditors.v25.2.dll
NuGet Package : DevExpress.Win.Navigation
[DXLicenseWinFormsEditors]
public class ComboBoxEdit :
PopupBaseAutoSearchEdit,
IDxHtmlDesignerDataProvider
<DXLicenseWinFormsEditors>
Public Class ComboBoxEdit
Inherits PopupBaseAutoSearchEdit
Implements IDxHtmlDesignerDataProvider
The following members return ComboBoxEdit objects:
Note
ComboBoxEdit displays a static list of items in its drop-down window. The control cannot retrieve items from a data source. Use Lookup Editors if you need an editor that can be populated with items from a data source.
A combo box control combines the functionality of a single-line text editor with a drop-down window. The drop-down window displays a list of items that a user can select.
Use the RepositoryItemComboBox.Items property to specify the collection of items to display in the drop-down window.
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. Otherwise, an item’s ToString method determines the item’s display text.
Note
To ensure that the editor works correctly, items in the RepositoryItemComboBox.Items collection must be unique objects.
When a user selects an item from the drop-down window, the editor assigns a corresponding object from the Items collection to the ComboBoxEdit.SelectedItem property, and to the ComboBoxEdit.EditValue property.
To select a specific item in code, you can use the following techniques:
If the RepositoryItemButtonEdit.TextEditStyle property is set to TextEditStyles.Standard, a 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.
Auto-Complete FunctionalityUse the RepositoryItemComboBox.AutoComplete property to activate the auto completion feature, which enables a user to select items by typing initial characters in the edit box.Loop Through ItemsUse the RepositoryItemComboBox.CycleOnDblClick property to enable a user to loop through items on an edit box double-click.Specify Display Text When No Item is SelectedYou can display custom text within the editor’s edit box when no item is selected. To do this, handle the RepositoryItem.CustomDisplayText event. This event does not fire when the edit value is null. To display custom text when the editor’s value is set to null, use the RepositoryItem.NullText property.Specify Item HeightThe RepositoryItemComboBox.DropDownItemHeight property allows you to change the height of items in the drop-down list. Use the RepositoryItemComboBox.ItemAutoHeight property to calculate the item height automatically to fit the item’s contents.
Handle the CustomDisplayText event to display custom text within the edit box.
public Form1() {
InitializeComponent();
comboBoxEdit1.Properties.Items.AddRange(new object[] {
"Alex White",
"Mike Norton",
"Ann Arnaz",
"Terry Bradley"
});
comboBoxEdit1.CustomDisplayText += ComboBoxEdit1_CustomDisplayText;
}
private void ComboBoxEdit1_CustomDisplayText(object sender, DevExpress.XtraEditors.Controls.CustomDisplayTextEventArgs e) {
e.DisplayText = String.Format("Employee: {0}", e.Value);
}
Public Sub New()
InitializeComponent()
comboBoxEdit1.Properties.Items.AddRange(New Object() { "Alex White", "Mike Norton", "Ann Arnaz", "Terry Bradley" })
AddHandler comboBoxEdit1.CustomDisplayText, AddressOf ComboBoxEdit1_CustomDisplayText
End Sub
Private Sub ComboBoxEdit1_CustomDisplayText(ByVal sender As Object, ByVal e As DevExpress.XtraEditors.Controls.CustomDisplayTextEventArgs)
e.DisplayText = String.Format("Employee: {0}", e.Value)
End Sub
Tip
Handle the DrawItem event to paint items as needed.
Example: How to Custom Paint ComboBoxEdit’s Items
ComboBoxEdit can render its drop-down items from HTML and CSS-based templates. Templates allow you to display multiple text and image elements in each drop-down item.
Do the following to create an HTML-CSS template:
See the following demo to find the complete code that renders this UI:
Note
The HTML/CSS-aware controls and components support a limited set of HTML tags and CSS styles, listed in the following topics:
The main features of HTML-CSS templates include:
Data bindingThe ${FieldName} syntax in HTML markup inserts field values of the control’s items. See the following topic for details: Data Binding.ImagesThe `` HTML tag allows you to add images.ButtonsThe HTML-CSS markup allows you to add elements to emulate buttons.Mouse actions
ComboBox controls contain events to respond to mouse actions on HTML elements: RepositoryItemComboBox.HtmlElementMouseClick, RepositoryItemComboBox.HtmlElementMouseDown, and RepositoryItemComboBox.HtmlElementMouseUp.
You can also subscribe to mouse events for elements in HTML markup, and when using Fluent API.
Dynamic item customizationHandle the RepositoryItemComboBox.CustomizeItem event to change the visibility and appearance settings of individual template elements dynamically in combo box items.Multiple item templates
The first template in the RepositoryItemComboBox.HtmlTemplates collection becomes the default template. This template is initially used to render all items.
The Template Editor allows you to create multiple templates in a template collection, and apply them to different items, or in different situations.
To assign templates to items dynamically, handle the RepositoryItemComboBox.CustomItemTemplate event.
See the following topic for information about other controls that use HTML-CSS templates, and about supported HTML and CSS tags: HTML-CSS-based Desktop UI.
The following code creates a ComboBoxEdit control, and adds three items to the control. Items are PersonInfo class objects. Each item stores a person’s first and last names.
The example uses the ComboBoxItemCollection.BeginUpdate and ComboBoxItemCollection.EndUpdate methods to prevent excessive updates when the item collection is changed.
The ComboBoxEdit.SelectedIndex property is set to -1 for demonstration purposes (the property is initially set to -1). This ensures that no item is selected on application startup.
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;
}
}
Dim Combo As ComboBoxEdit = New ComboBoxEdit
Dim Coll As ComboBoxItemCollection = 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()
End Try
Combo.SelectedIndex = -1
Controls.Add(Combo)
'...
Public Class PersonInfo
Private _firstName As String
Private _lastName As String
Public Sub New(ByVal firstName As String, ByVal lastName As String)
_firstName = firstName
_lastName = lastName
End Sub
Public Overrides Function ToString() As String
Return _firstName + " " + _lastName
End Function
End Class
This example temporarily hides ComboBoxEdit items.
Show 29 items
Object MarshalByRefObject Component Control DevExpress.XtraEditors.XtraControl ControlBase BaseControl BaseEdit TextEdit ButtonEdit PopupBaseEdit PopupBaseAutoSearchEdit ComboBoxEdit BreadCrumbEdit
StorageBindedImageComboBoxEdit
See Also