Edit

TextBoxExtensions

The TextBoxExtensions type provides additional features for the TextBox control through extension methods and attached properties.

Text regex

The Regex attached property allows text validation using a regular expression or using built in validation types.

The developer adds a regular expression to validate the TextBox Text against the regular expression throw Regex property or from selecting ValidationType property on the TextBox.

The validation has 3 modes (TextBoxExtensions.ValidationMode):

  1. Normal (Default): this mode will set the IsValid attached property to false or true whether the TextBox text is a valid or not against the Regex property.
  2. Forced: this mode sets the IsValid property and removes the TextBox text if not valid when the TextBox loses focus.
  3. Dynamic: this mode extends Normal and if is the newest input of the TextBox is invalid, the character which is invalid will be deleted. Note that the TextBoxExtensions.ValidationType values Email and PhoneNumber don't support this validation mode. If you set the validation mode to Dynamic, Normal is selected automatically instead.
<Page x:Class="ExtensionsExperiment.Samples.TextBoxExtensions.RegexSample"
      xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
      xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
      xmlns:converters="using:CommunityToolkit.Converters"
      xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
      xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
      xmlns:ui="using:CommunityToolkit.WinUI"
      mc:Ignorable="d">

    <Page.Resources>
        <Style x:Key="TextBoxRegexStyle"
               TargetType="TextBox">
            <Setter Property="VerticalAlignment" Value="Top" />
            <Setter Property="TextWrapping" Value="Wrap" />
        </Style>
        <DataTemplate x:Key="HeaderTemplate">
            <StackPanel>
                <TextBlock Text="{Binding}"
                           TextWrapping="WrapWholeWords" />
            </StackPanel>
        </DataTemplate>
    </Page.Resources>

    <Grid>
        <Grid RowSpacing="32">
            <Grid.RowDefinitions>
                <RowDefinition />
                <RowDefinition />
                <RowDefinition />
                <RowDefinition />
                <RowDefinition />
            </Grid.RowDefinitions>

            <StackPanel>
                <TextBox Name="PhoneNumberValidator"
                         ui:TextBoxExtensions.Regex="^\s*\+?\s*([0-9][\s-]*){9,}$"
                         Header="Text box with Regex extension for phone number, validation occurs on TextChanged"
                         HeaderTemplate="{StaticResource HeaderTemplate}"
                         Style="{StaticResource TextBoxRegexStyle}" />
                <TextBlock Foreground="{ThemeResource TextFillColorSecondaryBrush}">
                    <Run Text="Is valid: " />
                    <Run FontWeight="SemiBold"
                         Text="{Binding (ui:TextBoxExtensions.IsValid), ElementName=PhoneNumberValidator}" />
                </TextBlock>
            </StackPanel>

            <StackPanel Grid.Row="1">
                <TextBox Name="CharactValidator"
                         ui:TextBoxExtensions.ValidationMode="Dynamic"
                         ui:TextBoxExtensions.ValidationType="Characters"
                         Header="Text box with ValidationType=Characters, validation occurs at input with ValidationMode=Dynamic and clear only single character when value is invalid"
                         HeaderTemplate="{StaticResource HeaderTemplate}"
                         Style="{StaticResource TextBoxRegexStyle}"
                         Text="abcdef" />
                <TextBlock Foreground="{ThemeResource TextFillColorSecondaryBrush}">
                    <Run Text="Is valid: " />
                    <Run FontWeight="SemiBold"
                         Text="{Binding (ui:TextBoxExtensions.IsValid), ElementName=CharactValidator}" />
                </TextBlock>
            </StackPanel>

            <StackPanel Grid.Row="2">
                <TextBox Name="EmailValidator"
                         ui:TextBoxExtensions.ValidationType="Email"
                         Header="Text box with ValidationType=Email, validation occurs on TextChanged"
                         HeaderTemplate="{StaticResource HeaderTemplate}"
                         Style="{StaticResource TextBoxRegexStyle}" />
                <TextBlock Foreground="{ThemeResource TextFillColorSecondaryBrush}">
                    <Run Text="Is valid: " />
                    <Run FontWeight="SemiBold"
                         Text="{Binding (ui:TextBoxExtensions.IsValid), ElementName=EmailValidator}" />
                </TextBlock>
            </StackPanel>

            <StackPanel Grid.Row="3">
                <TextBox Name="DecimalValidatorForce"
                         ui:TextBoxExtensions.ValidationMode="Forced"
                         ui:TextBoxExtensions.ValidationType="Decimal"
                         Header="Text box with ValidationType=Decimal, validation occurs on TextChanged and force occurs on lose focus with ValidationMode=Force (333,111 or 333.111)"
                         HeaderTemplate="{StaticResource HeaderTemplate}"
                         Style="{StaticResource TextBoxRegexStyle}" />
                <TextBlock Foreground="{ThemeResource TextFillColorSecondaryBrush}">
                    <Run Text="Is valid: " />
                    <Run FontWeight="SemiBold"
                         Text="{Binding (ui:TextBoxExtensions.IsValid), ElementName=DecimalValidatorForce}" />
                </TextBlock>
            </StackPanel>

            <StackPanel Grid.Row="4">
                <TextBox Name="NumberValidatorDynamic"
                         ui:TextBoxExtensions.ValidationMode="Dynamic"
                         ui:TextBoxExtensions.ValidationType="Number"
                         Header="Text box with ValidationType=Number, validation occurs at input with ValidationMode=Dynamic and clear only single character when value is invalid"
                         HeaderTemplate="{StaticResource HeaderTemplate}"
                         Style="{StaticResource TextBoxRegexStyle}" />
                <TextBlock Foreground="{ThemeResource TextFillColorSecondaryBrush}">
                    <Run Text="Is valid: " />
                    <Run FontWeight="SemiBold"
                         Text="{Binding (ui:TextBoxExtensions.IsValid), ElementName=NumberValidatorDynamic}" />
                </TextBlock>
            </StackPanel>
        </Grid>
    </Grid>
</Page>

// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.
// See the LICENSE file in the project root for more information.

namespace ExtensionsExperiment.Samples.TextBoxExtensions;

[ToolkitSample(id: nameof(RegexSample), "Regex Extension", description: "A sample for showing how to use the Regex Extension.")]
public sealed partial class RegexSample : Page
{
    public RegexSample()
    {
        this.InitializeComponent();
    }
}

Text mask

The Mask attached property allows a user to more easily enter fixed width text in TextBox control where you would like them to enter the data in a certain format, ex: phone number, postal code.

The developer adds the mask property to prevent end user to enter any other format but the required one (eg. a postal code in the format "aaa-9999").

The Mask property provides 3 built-in variable characters that can be used to define a mask:

  1. a which represents [a-Z]
  2. 9 which represents [0-9]
  3. * which represents a or 9

At the post code example the user will only be allowed to enter from a to Z in the first 3 characters, then there is a fixed character - which the user can change or remove, and the last part which the user can change by entering from 0 to 9 at each character. The Mask property prevents the TextBox from having non specified characters (eg. if you entered 1 or 2 into a mask like 9999).

The Mask property also supports 2 type of characters:

  1. Variable: which the user can change like a,9,*
  2. Fixed: which the user can't change and it is any non variable character (eg. the - in the first example)

Variable characters a represented to end user in form of placeholder so the user can know which characters he can change and which he can't, ex mask aaa-9999 will be presented to user as ___-____. The default placeholder is _, but you can change it using the MaskPlaceholder property.

You can escape variable by using \ (eg. the mask +\964 will be presented to the user as +964). This way, the 9 in the mask is treated as a fixed character, not as a variable. If you needed \ in the mask then you can write it as \\ (eg. 99\\99\\9999 will be presented to the user as __\__\__).

In case you want to add a custom variable character you can use the CustomMask property. You can add a character that represents certain regex as c:[a-c] and once you use character c in the mask the mask will prevent any characters but from a to c inside the TextBox, also you specify multiple variable characters by adding comma , after every character and its representation. This feature is helpful if you want to allow certain language characters (eg. French or Arabic only TextBox).

<Page x:Class="ExtensionsExperiment.Samples.TextBoxExtensions.TextBoxMaskSample"
      xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
      xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
      xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
      xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
      xmlns:ui="using:CommunityToolkit.WinUI"
      xmlns:win="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
      mc:Ignorable="d">


    <Page.Resources>
        <Style x:Key="MaskedTextBoxStyle"
               TargetType="TextBox">
            <Setter Property="VerticalAlignment" Value="Top" />
            <Setter Property="TextWrapping" Value="Wrap" />
        </Style>
        <DataTemplate x:Key="HeaderTemplate">
            <StackPanel>
                <TextBlock Text="{Binding}"
                           TextWrapping="WrapWholeWords" />
            </StackPanel>
        </DataTemplate>
    </Page.Resources>

    <Grid>
        <StackPanel Spacing="24">
            <TextBox ui:TextBoxExtensions.Mask="9a9a-a9a*"
                     Header="Text box with Mask 9a9a-a9a* (9 allows from 0 to 9, a allow from a to Z and * allows both a and 9)"
                     HeaderTemplate="{StaticResource HeaderTemplate}"
                     Style="{StaticResource MaskedTextBoxStyle}"
                     Text="TextBoxMask" />

            <TextBox ui:TextBoxExtensions.Mask="+1999-9999"
                     ui:TextBoxExtensions.MaskPlaceholder=" "
                     Header="Text box with Mask +1999-9999 and placeHolder as space (placeholder represents the characters the user can change on runtime)"
                     HeaderTemplate="{StaticResource HeaderTemplate}"
                     Style="{StaticResource MaskedTextBoxStyle}" />

            <TextBox ui:TextBoxExtensions.Mask="+\964 799 999 9999"
                     Header="Text box with Mask +964 799 999 9999 (Notice how we escape the first 9 with a backslash)"
                     HeaderTemplate="{StaticResource HeaderTemplate}"
                     Style="{StaticResource MaskedTextBoxStyle}" />

            <TextBox ui:TextBoxExtensions.Mask="99\\99\\9999"
                     Header="Text box with Mask 99\99\9999 (You can escape a backslash with another backslash)"
                     HeaderTemplate="{StaticResource HeaderTemplate}"
                     Style="{StaticResource MaskedTextBoxStyle}" />

            <TextBox ui:TextBoxExtensions.CustomMask="5:[1-5],c:[a-c]"
                     ui:TextBoxExtensions.Mask="a5c-5c*9"
                     Header="Text box with CustomMask in case you want to define your own variable character like a, 9 and *. Mask: a5c-5c*9, 5: [1-5], c: [a-c]"
                     HeaderTemplate="{StaticResource HeaderTemplate}"
                     Style="{StaticResource MaskedTextBoxStyle}" />

        </StackPanel>
    </Grid>
</Page>

// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.
// See the LICENSE file in the project root for more information.

namespace ExtensionsExperiment.Samples.TextBoxExtensions;

[ToolkitSample(id: nameof(TextBoxMaskSample), "TextBoxMask Extension", description: "A sample for showing how to use the TextBoxMask Extension.")]
public sealed partial class TextBoxMaskSample : Page
{
    public TextBoxMaskSample()
    {
        this.InitializeComponent();
    }
}

Surface Dial support

The SurfaceDialOptions property adds features from the Surface Dial control to a numeric TextBox. This enables you to modify the content of the TextBox when rotating the Surface Dial (increasing or decreasing the value) and optionally go to the next focus element by tapping the Surface Dial click button. The various options are set through the SurfaceDialOptions type, which is declared in XAML and used to set all the values to use for a given TextBox from a single place. Here is an example of the visual result when scrolling on a Surface Dial over a TextBox:

<Page x:Class="ExtensionsExperiment.Samples.TextBoxExtensions.SurfaceDialOptionsSample"
      xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
      xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
      xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
      xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
      xmlns:ui="using:CommunityToolkit.WinUI"
      xmlns:win="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
      mc:Ignorable="d">


    <win:TextBox HorizontalAlignment="Left"
                 VerticalAlignment="Top"
                 Header="For this sample, you need a Surface Dial"
                 Text="0">
        <ui:TextBoxExtensions.SurfaceDialOptions>
            <ui:SurfaceDialOptions EnableHapticFeedback="True"
                                   EnableMinMaxValue="True"
                                   EnableTapToNextControl="False"
                                   Icon="Ruler"
                                   MaxValue="100"
                                   MinValue="0"
                                   RotationResolutionInDegrees="12"
                                   StepValue="1" />
        </ui:TextBoxExtensions.SurfaceDialOptions>
    </win:TextBox>
</Page>

// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.
// See the LICENSE file in the project root for more information.

namespace ExtensionsExperiment.Samples.TextBoxExtensions;

[ToolkitSample(id: nameof(SurfaceDialOptionsSample), "SurfaceDialOptions Extension", description: "A sample for showing how to use the SurfaceDialOptions Extension.")]
public sealed partial class SurfaceDialOptionsSample : Page
{
    public SurfaceDialOptionsSample()
    {
        this.InitializeComponent();
    }
}

Examples

You can find more examples in the unit tests.

  • Last updated on