ComboBoxEdit Class

A combo box editor.

Namespace: DevExpress.XamarinForms.Editors

Assembly: DevExpress.XamarinForms.Editors.dll

Declaration

public class ComboBoxEdit :
    EditBase,
    IComboBoxEditController,
    IEditController,
    IElementController

Remarks

ComboBoxEdit allows selection from a drop-down list of predefined items.

It consists of an edit box and drop-down list that appears when a user taps the edit box or a drop-down icon. The editor allows users to quickly locate items by their names (see Item Filtering).

The combo box can also include the following optional elements:

  1. Label
  2. Help Text
  1. Icons
  2. Error Message

Use the ItemsSource property to define a drop-down item list.

<dxe:ComboBoxEdit>
  <dxe:ComboBoxEdit.ItemsSource>
    <x:Array Type="{x:Type x:String}">
      <x:String>Item 1</x:String>
      <x:String>Item 2</x:String>
      <x:String>Item 3</x:String>
    </x:Array>
  </dxe:ComboBoxEdit.ItemsSource>
</dxe:ComboBoxEdit>

The following properties allow you to manage the selected item.

  • SelectedItem - Gets or sets an object that specifies a data source's item to which the combo box' selected item corresponds.

  • SelectedIndex - Specifies an index of an item in the data source to which the combo box' selected item corresponds.

Bind to a List of Primitive Types

You can bind the ItemsSource property to a list of primitive types (string, integer values, etc.):

using System.Collections.Generic;
using System.ComponentModel;
using Xamarin.Forms;

namespace ComboBoxExample {
    public partial class MainPage : ContentPage {
        public MainPage() {
            InitializeComponent();
            this.BindingContext = new List<string>() { "Milk", "Tea", "Coffee" };
        }
    }
}
<dxe:ComboBoxEdit ItemsSource="{Binding}"/>

Bind to a Collection of Custom Objects

You can also bind the ItemsSource property to a collection of custom objects. Use DisplayMember property to specify the name of a data source field as the drop-down list items:

using System.Collections.Generic;
using System.ComponentModel;
using Xamarin.Forms;

namespace ComboBoxExample {
    public partial class MainPage : ContentPage {
        public MainPage() {
            InitializeComponent();
            this.BindingContext = new List<Person>() {
                new Person {Name = "Devin", Age = 50, Location = "Atlanta"},
                new Person {Name = "Brenda", Age = 25, Location = "Memphis"},
                new Person {Name = "Sean", Age = 36, Location = "Houston"}
            };
        }
    }

    public class Person {
        public string Name { get; set; }
        public int Age { get; set; }
        public string Location { get; set; }
    }
}
<dxe:ComboBoxEdit ItemsSource="{Binding}"
                  DisplayMember="Name"/>

Define Item Template

The combo box allows you to define a drop-down list item template with the ItemTemplate property. Use the DisplayMember property to specify the data source field whose values are displayed in the edit box when a user selects an item.

using System.Collections.Generic;
using System.ComponentModel;
using Xamarin.Forms;

namespace ComboBoxExample {
    public partial class MainPage : ContentPage {
        public MainPage() {
            InitializeComponent();
            this.BindingContext = new List<Person>() {
                new Person {Name = "Devin", Age = 50, Location = "Atlanta"},
                new Person {Name = "Brenda", Age = 25, Location = "Memphis"},
                new Person {Name = "Sean", Age = 36, Location = "Houston"}
            };
        }
    }

    public class Person {
        public string Name { get; set; }
        public int Age { get; set; }
        public string Location { get; set; }
    }
}
<dxe:ComboBoxEdit ItemsSource="{Binding}"
                  DisplayMember="Name">
    <dxe:ComboBoxEdit.ItemTemplate>
      <DataTemplate>
        <Grid>
          <Label Padding="10" Text="{Binding Name}" FontAttributes="Bold" />
          <Label Padding="10" Grid.Column="1" Text="{Binding Age}" />
          <Label Padding="10" Grid.Column="2" Text="{Binding Location}" HorizontalTextAlignment="End" />
        </Grid>
      </DataTemplate>
    </dxe:ComboBoxEdit.ItemTemplate>
</dxe:ComboBoxEdit>

Item Filtering

Enable the IsFilterEnabled property to allow users to search for drop-down items by their display text.

The following list shows related properties:

Label

A label is the editor's input prompt string (LabelText). Editors display this string inside the edit box (when the editor is empty and not focused) or at the top of the editor.

To pin the label to the top edge of the editor box, set the IsLabelFloating property to false.

To customize the label's appearance settings, use the following properties:

Property

Description

LabelColor / FocusedLabelColor
DisabledLabelColor / ErrorColor

Specify the label color for each state of the combo-box-label editor.

LabelFontSize
TextFontFamily
TextFontAttributes

Configure the label font settings.

Help Text and Error Message

You can display the following labels below an editor:

The BottomTextTopIndent property specifies the indent between the editor's bottom border and help or error text.

To specify the color and font attributes for the help/error text, use the following properties:

Property

Description

HelpTextColor
DisabledHelpTextColor

Specify the help text color for different states of an editor.

ErrorColor

Specifies the error message text color.

BottomTextFontSize
BottomTextFontFamily
BottomTextFontAttributes

Configure font settings.

If HelpText is not set, ErrorText appears as an additional line below the edit box and page content shifts down. To prevent this behavior, set the ReserveBottomTextLine property to true.

Icons

The combo box can display three icons in the edit box.

  • Drop-down/drop-up icon - toggles the visibility of a drop-down list.
  • Error icon - appears in the error state (HasError is true).
  • Custom icons - can be shown on the left or right within the box.

Use the following members to manage the combo box icons:

Icon

Property

Description

Drop-Down and Drop-Up Icons

DropDownIcon

Gets or sets the custom drop-down icon image.

DropUpIcon

Gets or sets the custom drop-up icon image.

IsDropDownIconVisible

Specifies the drop-down icon visibility.

Error Icon

ErrorIcon

Specifies the error icon image.

ErrorIconClicked / ErrorIconCommand

Allows you perform an action when a user clicks the error icon.

Custom Icons

StartIcon / EndIcon

Specifies a custom icon.

StartIconClicked / StartIconCommand
EndIconClicked / EndIconCommand

Allows you to perform an action when a user clicks a custom icon.

IsStartIconVisible / IsEndIconVisible

Specifies an icon visibility.

Common

IconColor / DisabledIconColor

Specifies icon colors for different states of the text editor.

IconIndent

Gets or sets the distance between an icon and input text (affix).

IconSpacing

Gets or sets the distance between icons.

IconVerticalAlignment

Gets or sets the vertical alignment of icons.

Editor Appearance

You can customize the editor's appearance settings for different states using the following properties:

Combo Box State

Properties

Default

BorderColor
BorderThickness
BackgroundColor
TextColor

Focused

FocusedBorderColor
FocusedBorderThickness
DropDownBackgroundColor
DropDownItemTextColor
DropDownSelectedItemBackgroundColor
DropDownSelectedItemTextColor

Disabled

DisabledBorderColor
DisabledBorderThickness
DisabledBackgroundColor
DisabledTextColor

Error

ErrorColor

The following list shows common appearance settings applied in all states:

Property

Description

CornerMode

Gets or sets whether editor box corners are rounded or cut.

CornerRadius

Specifies the radius of the combo box and drop-down list corners.

TextFontAttributes
TextFontFamily
TextFontSize

Adjust the font settings.

Examples

The following example shows how to customize combo box appearance and set up item filtering.

State

Appearance

Unfocused

Focused

Filtered

<dxe:ComboBoxEdit ItemsSource="{Binding}"

                  LabelText="Employee"
                  IsLabelFloating="True"
                  HelpText="Select an e-mail"
                  BorderColor="Black"
                  FocusedBorderColor="DarkOrange"
                  BackgroundColor="Beige"
                  LabelColor="Black"
                  FocusedLabelColor="DarkOrange"
                  CornerRadius="10"
                  CornerMode="Cut"
                  DropDownBackgroundColor="Beige"
                  DropDownSelectedItemBackgroundColor="Brown"
                  DropDownSelectedItemTextColor="White"

                  IsFilterEnabled="True"
                  FilterMode="StartsWith"
                  FilterComparisonType="CurrentCultureIgnoreCase">

  <dxe:ComboBoxEdit.ItemTemplate>
    <DataTemplate>
      <Grid>
        <Label Margin="10,15,0,15" Text="{Binding Name}" FontAttributes="Bold"/>
        <Label Margin="0,15,0,15" Grid.Column="1" Text="{Binding Age}"/>
        <Label Margin="0,15,10,15" Grid.Column="2" Text="{Binding Location}" HorizontalTextAlignment="End"/>
      </Grid>
    </DataTemplate>
  </dxe:ComboBoxEdit.ItemTemplate>
</dxe:ComboBoxEdit>
using System.Collections.Generic;
using System.ComponentModel;
using Xamarin.Forms;

namespace ComboBoxExample {
    public partial class MainPage : ContentPage {
        public MainPage() {
            InitializeComponent();
            this.BindingContext = new List<Person>() {
                new Person {Name = "Jane", Age = 43, Location = "Atlanta"},
                new Person {Name = "Margaret", Age = 25, Location = "Memphis"},
                new Person {Name = "Debbie", Age = 28, Location = "New-York"},
                new Person {Name = "John", Age = 19, Location = "Detroit"},
                new Person {Name = "Derek", Age = 36, Location = "Houston"}
            };
        }
    }

    public class Person {
        public string Name { get; set; }
        public int Age { get; set; }
        public string Location { get; set; }
    }
}

Implements

Xamarin.Forms.IAnimatable
Xamarin.Forms.IViewController
Xamarin.Forms.IVisualElementController
Xamarin.Forms.Internals.IGestureController
Xamarin.Forms.IElementController

Inheritance

Object
Xamarin.Forms.BindableObject
Xamarin.Forms.Element
Xamarin.Forms.NavigableElement
Xamarin.Forms.VisualElement
View
EditBase
ComboBoxEdit
See Also