TokenEdit Class

An editor for single or multiple item selection with a predefined item source.

Assembly : DevExpress.Maui.Editors.dll

NuGet Package : DevExpress.Maui.Editors

Declaration

csharp

[DXLicenseMAUI]
public class TokenEdit :
    ComboBoxEditBase,
    ITokenEditController,
    IItemsController,
    IEditController,
    IDXViewController,
    IElementController

Remarks

The TokenEdit allows a user to select multiple tokens from a predefined list:

If you need an editor that allows a single item to be selected, refer to the following control: ComboBoxEdit.

If you have a large item source, we recommend that you use AutoCompleteTokenEdit and load its items asynchronously.

Add a TokenEdit to the App

Before you proceed, first read the following topics:

The following markup shows how to add a TokenEdit to a page:

View Example

XAML

xaml

<ContentPage ...
             xmlns:dxe="clr-namespace:DevExpress.Maui.Editors;assembly=DevExpress.Maui.Editors">
    <ScrollView>
        <VerticalStackLayout Spacing="25" Padding="30,0" VerticalOptions="Start">
            <dxe:TokenEdit />
            <!-- Other controls here. -->
        </VerticalStackLayout>
    </ScrollView>
</ContentPage>

Specify a List of Available Tokens

Use a TokenEdit‘s ItemsSource property to populate the editor’s drop-down list with items.

Bind to a List of Primitive Types

You can bind the ItemsSource property to a list of primitive types (string, integers, and so on).

The following code populates the TokenEdit drop-down list with string values:

XAML

xaml

<ContentPage.BindingContext>
    <local:ViewModel />
</ContentPage.BindingContext>
<ScrollView>
    <VerticalStackLayout Spacing="25" Padding="30,0" VerticalOptions="Start">
        <dxe:TokenEdit ItemsSource="{Binding ItemsSource}"/>
        <!--...-->
    </VerticalStackLayout>
</ScrollView>

csharp

public class ViewModel {
    public ViewModel() {
        ItemsSource = new ObservableCollection<string> {
        "Black",
        "White",
        "Gray",
        "Blue",
        "Green"
    };
    }
    public ObservableCollection<string> ItemsSource { get; }
}

Bind to a List of Complex Objects

You can also bind the ItemsSource property to a collection of custom objects. Use the DisplayMember and ValueMember properties to specify the names of data source fields that contain captions for items in the drop-down list and their values. Values can be used to specify selected items. For more information, refer to the following section: Manage Selected Items.

The following example binds a TokenEdit to a collection of Person objects:

XAML

xaml

<dxe:TokenEdit ItemsSource="{Binding}"
    DisplayMember="Name"
    ValueMember="Age" 
    WidthRequest="400"/>

csharp

public partial class MainPage : ContentPage {
    public MainPage() {
        InitializeComponent();
        this.BindingContext = new ObservableCollection<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; }
}

Specify How to Display Items

You can manage how items look in the editor’s drop-down list. To do this, specify the editor’s ItemTemplate property. Note that to specify the text used in selected tokens, set the editor’s DisplayMember property. Define the TokenEdit.TokenAppearance property to specify the token content in the edit box.

XAML

xaml

<dxe:TokenEdit ItemsSource="{Binding}"
               DisplayMember="Name"
               ValueMember="Age" 
               WidthRequest="400">
    <dxe:TokenEdit.ItemTemplate>
        <DataTemplate>
            <Grid ColumnDefinitions="*,*,*">
                <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}" />
            </Grid>
        </DataTemplate>
    </dxe:TokenEdit.ItemTemplate>
</dxe:TokenEdit>

csharp

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; }
}

Also see the following section for drop-down customization options: Customize Drop-Down Menu and Its Items.

Manage Selected Items

Users can tap items in the editor’s drop-down list to select tokens.

You can predefine selected items and obtain a list of selected items. To do this, use the following properties:

The example below uses item values to specify items selected in a token editor:

XAML

xaml

<ContentPage.BindingContext>
    <local:ViewModel/>
</ContentPage.BindingContext>
<ScrollView>
    <VerticalStackLayout Spacing="25" Padding="30,0" VerticalOptions="Start">
        <dxe:TokenEdit ItemsSource="{Binding ItemsSource}"
                       SelectedValues="{Binding SelectedValues}"
                       DisplayMember="Name"
                       ValueMember="Location"
                       WidthRequest="400"/>
    </VerticalStackLayout>
</ScrollView>

csharp

public class ViewModel {
    public ViewModel() {
        ItemsSource = new ObservableCollection<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"}
        };
        SelectedValues = new ObservableCollection<string> { "Atlanta", "Houston" };
    }
    public ObservableCollection<Person> ItemsSource { get; }
    public ObservableCollection<string> SelectedValues { get; }
}

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

Use the SelectionChangedCommand property to specify the command executed when the collection of selected items is changed. You can also handle the SelectionChanged event that occurs when the selection changes.

Enable Filtering

Set the editor IsFilterEnabled property to true to allow users to filter drop-down list items:

The following example filters items that start with the text a user types into the edit box. Note that the editor filters items against values that the DisplayMember specifies. So, you need to define the DisplayMember property before you enable filtering.

XAML

xaml

<dxe:TokenEdit ItemsSource="{Binding}"
               DisplayMember="Name"
               IsFilterEnabled="True"
               FilterCondition="StartsWith"
               FilterComparisonType="CurrentCultureIgnoreCase" 
               WidthRequest="400">
    <dxe:TokenEdit.ItemTemplate>
        <DataTemplate>
            <Grid ColumnDefinitions="*,*,*">
                <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}" />
            </Grid>
        </DataTemplate>
    </dxe:TokenEdit.ItemTemplate>
</dxe:TokenEdit>

csharp

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; }
}

If you want to predefine a filter expression, specify the FilterText property.

To add any custom logic on changes in the filter text, handle the FilterTextChanged event or use the FilterTextChangedCommand property.

Disable Edit Operations

Use the editor’s IsEnabled property to disable or activate the editor. If you need to hide the editor, set its IsVisible property to False. If you want to allow a user to select and copy the editor text and prohibit text editing, set the editor’s IsReadOnly property to true.

Add 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:

LabelColor, FocusedLabelColor, and DisabledLabelColor – Specify label text color for different editor states.
LabelFontSize, TextFontFamily, TextFontAttributes – Configure the label font settings.

The following example adds the label to a TokenEdit and specifies its color and font size:

XAML

xaml

<dxe:TokenEdit ...
               LabelText="Color" 
               LabelColor="DarkGreen" 
               LabelFontSize="14"/>

Show Help Text

Specify the editor’s HelpText property to display a text prompt (so-called “null text”) under the edit box.

The following API members configure the help text appearance depending on the editor state:

HelpTextColorGets or sets the color of the help text shown below the edit box. This is a bindable property.DisabledHelpTextColorGets or sets the color of the help text shown below the disabled editor. This is a bindable property.

The following markup specifies a TokenEdit‘s help text:

XAML

xaml

<dxe:TokenEdit x:Name="tokenEdit" WidthRequest="400" 
               ...
               HelpText="Expand the drop-down list to select colors"
               HelpTextColor="DarkGray"/>

Show Error Message

Specify the ErrorText property and set the HasError property to true to show an error message:

The following example shows an error message when a user clicks the Submit button while no tokens are selected:

XAML

xaml

<dxe:TokenEdit x:Name="tokenEdit" WidthRequest="400"
               ErrorText="This field is required"
               ErrorColor="DarkRed"/>
<Button Clicked="Button_Clicked" Text="Submit" WidthRequest="100"/>

csharp

private void Button_Clicked(object sender, EventArgs e) {
    if (tokenEdit.SelectedItems == null)
        tokenEdit.HasError = true;
    else
        tokenEdit.HasError = false;
}

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.

Specify the editor’s ErrorColor property to set the error text fill color.

To replace the default error icon with a custom icon, use the ErrorIcon property. Specify the ErrorIconColor property to customize the icon’s fill color.

You can also implement any custom logic when a user clicks the error icon. To do this, handle the ErrorIconClicked event or use the ErrorIconCommand and ErrorIconCommandParameter properties.

Show Icons

The TokenEdit control can display all combo box editor icons within its box. You can also configure Token icons in the editor.

Use the following API to configure Token icons in the TokenEdit control:

IconMemberGets or sets the data source member that contains Token icons.IsTokenIconVisibleGets or sets whether to show Token icons.TokenIconSizeGets or sets Token icon size.TokenAppearanceGets or sets appearance settings applied to visible tokens.

Customize Token Appearance

The following example configures the appearance of token icons and token outline:

XAML

xaml

<ContentPage.BindingContext>
    <local:ViewModel />
</ContentPage.BindingContext>

<dxe:TokenEdit x:Name="tokenEdit" WidthRequest="400" 
               LabelText="Color" 
               ItemsSource="{Binding ItemsSource}"
               ClearIconVisibility="Always"
               DisplayMember="ColorName"
               IconMember="ColorSampleIcon" 
               IsTokenIconVisible="True">
    <dxe:TokenEdit.TokenAppearance>
        <dxe:TokenAppearance BorderColor="CornflowerBlue" 
                             BorderThickness="2"
                             CornerRadius="14"
                             FontFamily="Univia-Pro"
                             FontSize="14" />
    </dxe:TokenEdit.TokenAppearance>
</dxe:TokenEdit>

csharp

public class ViewModel {
    public ViewModel() {
        ItemsSource = new List<ColorInfo> {
            new ColorInfo("Black","#000000"),
            new ColorInfo("White","#ffffff"),
            new ColorInfo("Gray", "#e5e5e5"),
            new ColorInfo("Blue", "#0000ff"),
            new ColorInfo("Green", "#00ff00")
        };
    }
    public IList<ColorInfo> ItemsSource { get; }
}

public class ColorInfo {
    public string ColorName { get; set; }
    public ImageSource ColorSampleIcon { get; set; }
    public ColorInfo(string name, string color) {
        ColorName = name;
        ColorSampleIcon = new FontImageSource() { Glyph = $"{name[0]}", Color = Color.FromArgb(color) };
    }
}

For more information about font icons, refer to the following page: Fonts in .NET MAUI – Display font icons.

Use the IsDropDownIconVisible property to manage the editor’s drop-down menu icon visibility. When you need to determine whether the drop-down menu is shown, use the IsDropDownOpen property.

The following properties allow you to configure the appearance options for the drop-down menu and its items:

DropDownBackgroundColorGets or sets the drop-down list background color. This is a bindable property.DropDownIconGets or sets the custom drop-down icon image. This is a bindable property.DropDownIconColorGets or sets the color of the drop-down/drop-up icon. This is a bindable property.DropDownItemFontAttributesGets or sets the drop-down item’s font attributes. This is a bindable property.DropDownItemFontFamilyGets or sets the drop-down item’s font family. This is a bindable property.DropDownItemFontSizeGets or sets the drop-down item’s font size. This is a bindable property.DropDownItemPaddingGets or sets the drop-down item’s padding. This is a bindable property.DropDownItemTextColorGets or sets the text color of the drop-down list items. This is a bindable property.DropDownSelectedItemBackgroundColorGets or sets the background color of an item selected in the drop-down list. This is a bindable property.DropDownSelectedItemTextColorGets or sets the color of a selected item’s text in the drop-down list. This is a bindable property.