Skip to main content

FormSwitchItem Class

A switch element that serves as a single item in a composite UI structure such as a data entry form, profile page, menu, action sheet, or settings panel.

Namespace: DevExpress.Maui.Editors

Assembly: DevExpress.Maui.Editors.dll

NuGet Package: DevExpress.Maui.Editors

Declaration

public class FormSwitchItem :
    FormCheckItemBase

Remarks

A FormSwitchItem can display header text, description, icon, switch, and arrow. Users can toggle a FormSwitchItem to invoke an action.

The following diagram depicts elements of a switch form item:

DevExpress Form Items for MAUI - Form switch item anatomy

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

Add a Form Switch to a Page

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 FormSwitchItem objects to a VerticalStackLayout. To combine form items into groups, you can use the FormGroupItem:

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

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

View Example

Customize Text Settings

The Text specifies the FormSwitchItem‘s primary text (header). Use the following properties to configure a form item’s 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 markup below adds a text header to a form switch item and specifies text settings:

<dxe:FormSwitchItem Text="Private Chat"
                    TextColor="Gray"
                    TextFontAttributes="Bold"
                    TextFontFamily="OpenSansRegular"
                    TextFontSize="18"
                    TextLineBreakMode="CharacterWrap"
                    TextMargin="4"
                    TextMaxLineCount="2"/>

Customize Detail Text Settings

The Detail specifies the FormSwitchItem’s secondary text (description). Use the following properties to configure a form switch item’s 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.

The markup below adds secondary text for a form item and configures text options :

<dxe:FormSwitchItem Detail="This setting allows you to
                            receive private messages
                            from other users."
                    DetailColor="Gray"
                    DetailFontAttributes="Italic"
                    DetailFontFamily="OpenSansRegular"
                    DetailFontSize="14"
                    DetailLineBreakMode="TailTruncation"
                    DetailMargin="4"
                    DetailMaxLineCount="2" />

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:

<ContentPage ...>
    <ContentPage.BindingContext>
        <local:SettingsViewModel />
    </ContentPage.BindingContext>
        <!--...-->
            <dxe:FormSwitchItem ...
                                AllowTap="True"
                                TapCommand="{Binding OnTapCommand}"/>
        <!--...-->
</ContentPage>
using System.ComponentModel;
using System.Windows.Input;

namespace FormItemExample;

public class SettingsViewModel : INotifyPropertyChanged {
    //...
    public ICommand OnTapCommand => new Command(OnFormItemTap);
    private void OnFormItemTap() {
        // Invoke actions when user taps the form check item.
        // ...
    }
}

When a user taps the form switch item, the switch state changes. Use the IsToggled property to receive the current switch item state. Specify the ThumbColor property to set the switch color in the toggled state.

Customize Image

The properties listed in this section allow you to configure the settings of a form switch item image:

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.
<dxe:FormSwitchItem ...
                    ImageSource="lock"
                    ImageHeight="36"
                    ImageWidth="36"
                    ImageVerticalOptions="Start">
</dxe:FormSwitchItem>

Customize Arrow

You can additionally show an Arrow for the form switch item. 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.

The following markup customizes default arrow settings for a form item:

<dxe:FormSwitchItem ShowArrow="True"
                    ArrowColor="Gray"
                    ArrowMargin="10"
                    ArrowVerticalOptions="Center"/>

Customize Separator

The Separator is a line that separates form items. The settings below allow you to show a form item’s separator and define its appearance:

ShowSeparator
Specifies whether the separator is visible.
SeparatorColor
Defines the separator’s fill color.
SeparatorThickness
Specifies the separator’s thickness.
<dxe:FormSwitchItem ShowSeparator="True"
                    SeparatorColor="LightGray"
                    SeparatorThickness="1">

The following featured scenario shows how you can use the FormSwitchItem class:

Use Form Items to Build a Settings Page Replicate Settings Page with Forms Items Featured Scenario

Inheritance

Show 11 items
See Also