FormListPickerItem Class

A list element that allows users to select options in a picker. This component serves as a single item in a composite UI structure such as a data entry form, profile page, menu, action sheet, or settings panel. You can show picker list items in a page, bottom sheet or popup.

Namespace: DevExpress.Maui.Editors

Assembly: DevExpress.Maui.Editors.dll

NuGet Package: DevExpress.Maui.Editors

Declaration

[ContentProperty("Content")]
public class FormListPickerItem :
    FormPickerItemBase,
    FormItemBase.ContentTemplateConnector.IContentElement,
    FormItemBase.InlineContentTemplateConnector.IInlineContentElement

Remarks

A FormListPickerItem can display header text, description, arrow, icon, and additional custom content. Users can select an option from a set in the form item picker displayed on tap. The picker supports multiple display modes: a separate page, a bottom sheet, or a popup. You can use the FormListPickerItem as an alternative to the ComboBoxEdit, AutoCompleteEdit, AutoCompleteTokenEdit, and TokenEdit components that also allow users to choose an option from a list.

The following diagram depicts a form picker item and its main elements:

DevExpress Form Items - Picker item anatomy

For a list of all available form items, refer to the following help topic: Form Items.

Add a Form Picker Item to a Page

Before you proceed, read the following topic:

Get Started with DevExpress Controls for .NET Multi-platform App UI (.NET MAUI)

Once you completed the general setup steps outlined in the article above, declare the DevExpress.Maui.Editors namespace in your markup:

XAML

<ContentPage
    xmlns:dxe="clr-namespace:DevExpress.Maui.Editors;assembly=DevExpress.Maui.Editors">
    <!--...-->
</ContentPage>

You can use any layout class to arrange form items on the form. The following example adds FormListPickerItem objects to a VerticalStackLayout. To combine form items into groups, you can use the FormGroupItem:

XAML

<ScrollView>
    <VerticalStackLayout>
        <dxe:FormGroupItem>
            <dxe:FormListPickerItem .../>
            <dxe:FormListPickerItem .../>
            <!--...-->
        </dxe:FormGroupItem>
    </VerticalStackLayout>
</ScrollView>

Refer to our repo on GitHub to review the complete source code:

View Example

Specify the ItemsSource property to populate the picker option list with items.

XAML

<dxe:FormListPickerItem
    ItemsSource="{Binding Languages}"/>

Initially, the picker shows a search box to allow users to filter available options. Use the ShowSearchPanel property to hide the search box.

The PickerShowMode property specifies how to show picker content: in a page, popup, or bottom sheet. You can use the PickerTitle property to define the picker header:

DevExpress FormListPickerItem for MAUI - Picker show modes

Note that to invoke the picker in Page mode, your app should be a Shell app. Alternatively, you can invoke the picker page from a Navigation Page.

To configure display text for picker items, use the DisplayFormat and DisplayMember properties.

Respond to User Taps

The API members below allow you to respond to user taps:

AllowTap: Specifies whether taps on the form item are allowed.
TapCommand: Defines the command that is executed when a user taps the form item.
TapCommandParameter: Specifies the Tap command parameter.
Tap: Occurs when a user taps the form item.

The following example executes a command when a user taps a form item:

XAML

<dxe:FormListPickerItem ... 
              TapCommand="{Binding OnTapCommand}">

using System.ComponentModel;
using System.Runtime.CompilerServices;
using System.Windows.Input;

namespace FormItemsTestApp;

public partial class MainPage : ContentPage {
    public MainPage() {
        InitializeComponent();
        this.BindingContext = new MainPageViewModel();
    }
}

public class MainPageViewModel {
    //...
    public ICommand OnTapCommand => new Command(OnFormItemTap);
    private void OnFormItemTap() {
        // Perform actions when the form item is tapped.
        // ...
    }

}

Process Selected Items

The FormListPickerItem shows the selected item as the Inline Content to the left of the arrow:

DevExpress FormListPickerItem for MAUI -- Single item selected

You can use InlineContent and InlineContentTemplate property to customize the single selected item appearance. To hide the selected item, set InlineContent to {x:Null}.

Set the IsMultipleSelectionEnabled property to True to allow users to select multiple options in the picker. Selected items appear as tokens:

DevExpress FormListPickerItem for MAUI -- Selected item tokens

The FormListPickerItem uses its Content property to display selected items. You can configure Content or ContentTemplate to customize the appearance of selected items. For more information on how to do this, refer to the following section: Customize Selected Item Appearance. To hide selected item tokens, set Content to {x:Null}.

If a picker allows multiple selection, it displays Apply and Cancel buttons. To change button captions, use ApplyButtonText and CancelButtonText properties.

Access Selected Items

Use the properties below to obtain selected picker items. The properties store objects used to populate the picker ItemsSource with items:

To customize how selected items look in the picker list, specify the PickerSelectedItemBackgroundColor, PickerSelectedItemTextColor, and PickerSelectedItemTemplate properties.

Example: Customize Selected Item Appearance

The following example uses the Content property to show selected items as a single text line:

DevExpress FormListPickerItem for MAUI -- Customized selected items

XAML

<ContentPage.BindingContext>
    <local:SettingsViewModel />
</ContentPage.BindingContext>
<!--...-->
    <dxe:FormListPickerItem ...
        Content="{Binding Blacklist, Converter={helpers:BlacklistCollectionConverter}, Mode=TwoWay}" >

SettingsViewModel.xaml.cs

using System.Collections.ObjectModel;
using System.Collections.Specialized;
using System.ComponentModel;
using System.Runtime.CompilerServices;
using System.Windows.Input;
namespace FormItemExample;
public class SettingsViewModel : INotifyPropertyChanged {
    public SettingsViewModel() {
        //...
        Blacklist.CollectionChanged += OnBlacklistCollectionChanged;
    }
    public ObservableCollection<string> Blacklist { get; } = new();
    void OnBlacklistCollectionChanged(object sender, NotifyCollectionChangedEventArgs e) {
        OnPropertyChanged(nameof(Blacklist));
    }
}

BlacklistCollectionConverter.cs

public class BlacklistCollectionConverter : IValueConverter {
    public object Convert(object value, Type targetType, object parameter, CultureInfo culture) {

        if (value is IList<string> contacts) {
            return String.Join("; ", contacts.Select(x => x));
        }
        return String.Empty;
    }
    public object ConvertBack(object value, Type targetType, object parameter, CultureInfo culture) {
        return null;
    }

}

Add a Clear Button

The Clear button allows users to reset selected options. To show the Clear button, specify ClearButtonText and ClearButtonVisibility properties.

You can also use the Clear command to clear the selected picker items. For example, bind the DXButton.Command property to the FormPickerItemBaseCommands.Clear property to reset the selected options on a button tap.

Invoke Picker

Use the Show command to invoke the picker. The following snippet binds the DXButton.Command property to the FormPickerItemBaseCommands.Show property to open the picker on a button tap.

XAML

<dx:DXStackLayout Orientation="Vertical">
    <dxe:FormListPickerItem x:Name="dxFormListPickerItem" .../>
    <dx:DXButton Command="{Binding Source={x:Reference dxFormListPickerItem}, Path=Commands.Show}"/>
</dx:DXStackLayout>

You can handle the PickerShowing event to customize the picker form before it appears.

Customize Text Settings

The Text specifies the FormListPickerItem‘s primary text (header). Use the following properties to configure text and its appearance:

Text: Specifies the content of a form item’s primary text.
TextColor: Specifies the form item text’s color.
TextFontAttributes: Defines font attributes for the form item’s text. You can use the following options: Bold, Italic, or None.
TextFontFamily: Specifies the text’s font name. You can only use fonts previously registered in the app. For more information, refer to: Register Fonts.
TextFontSize: Defines the text’s font size.
TextLineBreakMode: Specifies the line break mode for a font item’s text.
TextMargin: Allows you to set the gaps between the text and other form item elements.
TextMaxLineCount: Defines the maximum number of text lines.

The following code sample specifies the Text value based on the View Model’s property (Language, in this example):

XAML

<ContentPage.BindingContext>
    <local:SettingsViewModel />
</ContentPage.BindingContext>
<!--...-->
    <dxe:FormListPickerItem ...
                        Text="{Binding Language}" />

using System.ComponentModel;
using System.Runtime.CompilerServices;
using System.Windows.Input;
namespace FormItemExample;
public class SettingsViewModel : INotifyPropertyChanged {
    string language;
    public SettingsViewModel() {
        Language = "English";
    }
    public string Language {
        get => this.language;
        set {
            this.language = value;
            OnPropertyChanged();
        }
    }
    public event PropertyChangedEventHandler PropertyChanged;
    void OnPropertyChanged([CallerMemberName] string propertyName = null) {
        PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
    }
}

Customize Detail Text Settings

The Detail specifies the FormListPickerItem’s secondary text (description). Use the following properties to configure detail text and its appearance:

Detail: Specifies the content of a form item’s secondary text.
DetailColor: Specifies the form item detail’s color.
DetailFontAttributes: Defines font attributes for the form item’s detail. You can use the following options: Bold, Italic, or None.
DetailFontFamily: Specifies the detail’s font name. You can only use fonts previously registered in the app. For more information, refer to: Register Fonts.
DetailFontSize: Defines the detail’s font size.
DetailLineBreakMode: Specifies the line breaking mode for a font item’s detail.
DetailMargin: Allows you to set the gaps between the detail and other form item elements.
DetailMaxLineCount: Defines the maximum number of detail lines.

Customize the Image

The properties listed in this section allow you to configure form item icon settings:

ImageSource

Specifies the image source. In XAML, use the name of an image in the Resources/Images folder to define the source. Ensure that the image’s Build Action is MauiImage.

For more information about images, refer to the following page: Add images to a .NET MAUI app project.

ImageColor

Defines the tint color of the form item’s image.

ImageHeight

Specifies the height of the form item’s image.

ImageWidth

Specifies the width of the form item’s image.

ImageMargin

Allows you to set the gaps between the image and other form item elements.

ImageVerticalOptions

Specifies how the image is positioned vertically. You can use the following options: Fill, Center, Start, and End.

ImageTemplate

Defines a template that configures image appearance.

Customize Arrow

An Arrow indicates that a user can tap the form item to perform an action. Use the following settings to display the arrow and customize it:

ShowArrow: Specifies whether to show the form item’s arrow.
ArrowColor: Sets the arrow’s fill color.
ArrowTemplate: Specifies a template that configures the arrow’s appearance.
ArrowMargin: Allows you to set the gaps between the arrow and other form item elements.
ArrowVerticalOptions: Specifies how the arrow is positioned vertically. You can use the following options: Fill, Center, Start, and End.

Customize Appearance

The following properties configure picker item appearance:

ItemTemplate - Specifies the template for separate picker items.
PickerContentTemplate - Defines the template that configures picker appearance.
PickerItemFontAttributes - Defines font attributes for picker items. You can use the following options: Bold, Italic, or None.
PickerItemFontFamily - Specifies the picker item font name. You can only use fonts previously registered in the app. For more information, refer to: Register Fonts.
PickerItemFontSize - Defines the font size for picker items.
PickerItemPadding - Specifies item paddings.
PickerItemTextColor - Specifies the color for picker items.
PickerBackgroundColor - Defines the picker background fill color.