maui-devexpress-dot-maui-dot-editors-0807e0ef.md
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
[ContentProperty("Content")]
[DXLicenseMAUI]
public class FormListPickerItem :
FormPickerItemBase,
FormItemBase.ContentTemplateConnector.IContentElement,
FormItemBase.InlineContentTemplateConnector.IInlineContentElement
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:
For a list of all available form items, refer to the following help topic: Form Items.
Before you proceed, read the following topic:
Once you completed the general setup steps outlined in the article above, declare the DevExpress.Maui.Editors namespace in your markup:
<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:
<ScrollView>
<VerticalStackLayout>
<dxe:FormGroupItem>
<dxe:FormListPickerItem .../>
<dxe:FormListPickerItem .../>
<!--...-->
</dxe:FormGroupItem>
</VerticalStackLayout>
</ScrollView>
Refer to our repo on GitHub to review the complete source code:
Specify the ItemsSource property to populate the picker option list with items.
<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:
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.
The API members below allow you to respond to user taps:
AllowTapSpecifies whether taps on the form item are allowed.TapCommandDefines the command that is executed when a user taps the form item.TapCommandParameterSpecifies the Tap command parameter.TapOccurs when a user taps the form item.
The following example executes a command when a user taps a form item:
<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.
// ...
}
}
The FormListPickerItem shows the selected item as the Inline Content to the left of the arrow:
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:
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.
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.
The following example uses the Content property to show selected items as a single text line:
<ContentPage.BindingContext>
<local:SettingsViewModel />
</ContentPage.BindingContext>
<!--...-->
<dxe:FormListPickerItem ...
Content="{Binding Blacklist, Converter={helpers:BlacklistCollectionConverter}, Mode=TwoWay}" >
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));
}
}
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;
}
}
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.
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.
<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.
The Text specifies the FormListPickerItem‘s primary text (header). Use the following properties to configure text and its appearance:
TextSpecifies the content of a form item’s primary text.TextColorSpecifies the form item text’s color.TextFontAttributesDefines font attributes for the form item’s text. You can use the following options: Bold, Italic, or None.TextFontFamilySpecifies the text’s font name. You can only use fonts previously registered in the app. For more information, refer to: Register Fonts.TextFontSizeDefines the text’s font size.TextLineBreakModeSpecifies the line break mode for a font item’s text.TextMarginAllows you to set the gaps between the text and other form item elements.TextMaxLineCountDefines 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):
<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));
}
}
The Detail specifies the FormListPickerItem’s secondary text (description). Use the following properties to configure detail text and its appearance:
DetailSpecifies the content of a form item’s secondary text.DetailColorSpecifies the form item detail’s color.DetailFontAttributesDefines font attributes for the form item’s detail. You can use the following options: Bold, Italic, or None.DetailFontFamilySpecifies the detail’s font name. You can only use fonts previously registered in the app. For more information, refer to: Register Fonts.DetailFontSizeDefines the detail’s font size.DetailLineBreakModeSpecifies the line breaking mode for a font item’s detail.DetailMarginAllows you to set the gaps between the detail and other form item elements.DetailMaxLineCountDefines the maximum number of detail lines.
The properties listed in this section allow you to configure form item icon settings:
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.
ImageColorDefines the tint color of the form item’s image.ImageHeightSpecifies the height of the form item’s image.ImageWidthSpecifies the width of the form item’s image.ImageMarginAllows you to set the gaps between the image and other form item elements.ImageVerticalOptionsSpecifies how the image is positioned vertically. You can use the following options: Fill, Center, Start, and End.ImageTemplateDefines a template that configures image appearance.
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:
ShowArrowSpecifies whether to show the form item’s arrow.ArrowColorSets the arrow’s fill color.ArrowTemplateSpecifies a template that configures the arrow’s appearance.ArrowMarginAllows you to set the gaps between the arrow and other form item elements.ArrowVerticalOptionsSpecifies how the arrow is positioned vertically. You can use the following options: Fill, Center, Start, and End.
The following properties configure picker item appearance:
The following featured scenario shows how you can use the FormListPickerItem class:
Use Form Items to Build a Settings Page
Show 17 items
Microsoft.Maui.Controls.ITabStopElement
Microsoft.Maui.IFrameworkElement
Show 11 items
System.Object BindableObject Element NavigableElement VisualElement View Layout DevExpress.Maui.Editors.Internal.BaseFormItem FormItemBase FormPickerItemBase FormListPickerItem
YieldIfNotNull<FormListPickerItem>()
See Also