Class ComboBox

Namespace: Alternet.UI

Assembly: Alternet.UI.Common.dll

Represents a combo box control.

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

Inheritance: object

BaseObject

BaseObjectWithId

BaseObjectWithAttr

DisposableObject

FrameworkElement

AbstractControl

Control

ListControl<object>

ListControl

ComboBox

Implements: IBaseObjectWithId

IDisposableObject

IBaseObject

ISupportInitialize

IFocusable

ITextProperty

IComponent

INotifyDataErrorInfo

IReadOnlyStrings

IListControl<object>

IListControl

IControl

IDisposable

IWin32Window

IListControlItemContainer

Derived: ColorComboBox

FontComboBox

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;
    App.Log(text);
}

private void ComboBox_SelectedItemChanged(object? sender, EventArgs e)
{
    App.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 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.

A ComboBox can have owner-draw and styled items with custom colors, font, border and image. Use ListControlItem as an item of a ComboBox in order to have the ability to customize style and behavior options.

ComboBox with styled items

Constructors

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

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

Fields

DefaultDisabledTextColor: Gets or sets default disabled text color.

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.

DrawMode: Gets or sets a value indicating whether your code or the operating system will handle drawing of elements in the list.

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

DroppedDown: Gets a value indicating whether the combo box is displaying its drop-down portion.

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.

OwnerDrawItemDefaults: Gets or sets defaults which are used when items are painted in the popup listbox in the case when item is ListControlItem and owner draw mode is turned on.

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, Func<object, bool>?): 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.

GetBestSizeWithoutPadding(SizeD): Gets size of the native control without padding.

GetDisabledTextColor(): Gets text color when control is disabled.

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

InvalidateBestSize(): Resets the cached best size value so it will be recalculated the next time it is needed.

OnDropDown(EventArgs): Called when the DropDown event is fired.

OnDropDownClosed(EventArgs): Called when the DropDownClosed event is fired.

OnHandleCreated(EventArgs): Called when the conrol's handle is created.

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

PerformLayout(bool): Forces the control to apply layout logic to child controls.

RaiseDropDown(): Raises the DropDown event and calls OnDropDown(EventArgs) method.

RaiseDropDownClosed(): Raises the DropDownClosed event and calls OnDropDownClosed(EventArgs) method.

RaiseFontChanged(EventArgs): Raises the FontChanged event and calls OnFontChanged(EventArgs) method.

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

DropDown: Occurs when the drop-down portion of a ComboBox is shown.

DropDownClosed: Occurs when the drop-down portion of the ComboBox is no longer visible.

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