Class ComboBox

Namespace: Alternet.UI

Assembly: Alternet.UI.Common.dll

Represents a combo box control.

[ControlCategory("Common")]
public class ComboBox : ListControl, IBaseObject, IDisposableObject, ISupportInitialize, IFocusable, ITextProperty, IComponent, IControl, IDisposable, IWin32Window, INotifyDataErrorInfo, IReadOnlyStrings

Inheritance: object

BaseObject

DisposableObject

DispatcherObject

DependencyObject

UIElement

FrameworkElement

Control

ListControl

ComboBox

Implements: IBaseObject

IDisposableObject

ISupportInitialize

IFocusable

ITextProperty

IComponent

IControl

IDisposable

IWin32Window

INotifyDataErrorInfo

IReadOnlyStrings

Derived: ColorComboBox

Examples

Here is how to declare a ComboBox in UIXML:

<ComboBox Name="comboBox" Margin="8" IsEditable="false" VerticalAlignment="Top" HorizontalAlignment="Left"
          SelectedItemChanged="ComboBox_SelectedItemChanged" TextChanged="ComboBox_TextChanged" />

And the corresponding event handler in the code-behind:

private void ComboBox_TextChanged(object? sender, EventArgs e)
{
    var text = comboBox.Text == "" ? "\"\"" : comboBox.Text;
    Application.Log(text);
}

private void ComboBox_SelectedItemChanged(object? sender, EventArgs e)
{
    Application.Log($"Selected Item Text: {comboBox.SelectedItem}" + "\n" +
                    $"Index: {comboBox.SelectedIndex}");
}

Also, a ComboBox can be created from code:

var comboBox = new Alternet.UI.ComboBox();
comboBox.Items.Add("One");
comboBox.Items.Add("Two");
comboBox.Items.Add("Three");
comboBox.SelectedIndex = 1;
comboBox.SelectedItemChanged += ComboBox_SelectedItemChanged;

Remarks

A ComboBox displays a text box combined with a ListBox, which enables the user to select items from the list or enter a new value. The IsEditable property specifies whether the text portion can be edited.

To add or remove objects in the list at run time, use methods of the object returned by the Items property of the ComboBox. The list then displays the default string value for each object. You can add individual objects with the Add method of the ComboBox.Items object. You can delete items with the Remove method or clear the entire list with the Clear method.

In addition to display and selection functionality, the ComboBox also provides features that enable you to add items to the ComboBox and to find text within the items of the list. With the BeginUpdate() and EndUpdate() methods, you can add a large number of items to the ComboBox without the control being repainted each time an item is added to the list.

You can use the Text property to specify the string displayed in the editing field, the SelectedIndex property to get or set the current item, and the SelectedItem property to get or set a reference to the selected object.

Examples of how a ComboBox can look on different platforms:

ComboBox on Windows

Set Text property to specify the text displayed on the control. A ComboBox, like any other Control, can be disabled by setting its Enabled property to false.

Constructors

ComboBox(): Initializes a new instance of the ComboBox class.

Fields

DefaultImageBorderColor: Gets or sets default color of the image border.

DefaultImageTextDistance: Gets or sets default distance between image and text in the item.

DefaultImageVerticalOffset: Gets or sets default vertical offset of the item's image for the items with images.

Properties

ControlKind: Returns control identifier.

DropDownStyle: Gets or sets a value specifying the style of the combo box.

EmptyTextHint: Gets or sets a hint shown in an empty unfocused text control.

HasBorder: Gets or sets a value indicating whether the control has a border.

IsEditable: Gets or a value that enables or disables editing of the text in text box area of the ComboBox.

ItemPainter: Gets or sets item painter associated with the control.

OwnerDrawItem: Gets or sets whether item is owner drawn.

OwnerDrawItemBackground: Gets or sets whether background of the item is owner drawn.

SelectedIndex: Gets or sets the index specifying the currently selected item.

SelectedItem: Gets or sets currently selected item in the combo box.

Text: Gets or sets the text displayed in the ComboBox.

TextMargin: Gets text margin. It is the empty space between borders of control and the text itself.

TextSelectionLength: Gets the number of characters selected in the editable portion of the combo box.

TextSelectionStart: Gets the starting index of text selected in the combo box.

Methods

BindEnumProp(object, string): Binds property specified with instance and propName to the ComboBox. After binding ComboBox will edit the specified property.

CreateHandler(): Creates a handler for the control.

DefaultItemPaint(ComboBoxItemPaintEventArgs): Default item paint method.

GetItemImageRect(ComboBoxItemPaintEventArgs): Gets suggested rectangles of the item's image and text.

OnSelectedItemChanged(EventArgs): Called when the value of the SelectedItem property changes.

RaiseSelectedItemChanged(): Raises the SelectedItemChanged event and calls OnSelectedItemChanged(EventArgs).

SelectAllText(): Selects all the text in the editable portion of the ComboBox.

SelectTextRange(int, int): Selects a range of text in the editable portion of the ComboBox.

ShouldPaintHintText(): Gets whether hint text should be painted.

Events

IsEditableChanged: Occurs when the IsEditable property value changes.

SelectedIndexChanged: Same as SelectedItemChanged. Added for the compatibility.

SelectedItemChanged: Occurs when the SelectedItem property value changes.

Table of Contents