Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Various] Sample tweaks #231

Merged
merged 5 commits into from
Sep 21, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions components/CameraPreview/samples/CameraPreviewSample.xaml
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
<!-- 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. -->
<!-- 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. -->
<Page x:Class="CameraPreviewExperiment.Samples.CameraPreviewSample"
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
Expand All @@ -14,7 +14,8 @@
Spacing="12">
<Button HorizontalAlignment="Center"
Click="CaptureButton_Click"
Content="Capture" />
Content="Capture"
Style="{StaticResource AccentButtonStyle}" />
<controls:CameraPreview x:Name="CameraPreviewControl"
Height="320"
IsFrameSourceGroupButtonVisible="{x:Bind ShowCamera, Mode=OneWay}" />
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@

namespace ExtensionsExperiment.Samples.ListViewExtensions;

[ToolkitSample(id: nameof(SmoothScrollIntoViewSample), "SmoothScrollIntoView Extension", description: "A sample for showing how to the SmoothScrollIntoViewWithIndexAsync API.")]
[ToolkitSample(id: nameof(SmoothScrollIntoViewSample), "SmoothScrollIntoView Extension", description: "A sample for showing how to use the SmoothScrollIntoViewWithIndexAsync API.")]
public sealed partial class SmoothScrollIntoViewSample : Page
{
public ObservableCollection<string> Items { get; set; } = new();
Expand Down
123 changes: 16 additions & 107 deletions components/Extensions/samples/TextBoxExtensions.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,20 @@ icon: Assets/Extensions.png

The `TextBoxExtensions` type provides additional features for the [`TextBox`](https://learn.microsoft.com/uwp/api/windows.ui.xaml.controls.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.

> [!SAMPLE RegexSample]

## 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.
Expand All @@ -39,119 +53,14 @@ You can escape variable by using `\` (eg. the mask `+\964` will be presented to

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`).

### Syntax

```xaml
<Page ...
xmlns:ui="using:CommunityToolkit.WinUI">
<StackPanel>

<!-- Mask = "9a9a-a9a*" (9 means [0-9], a means [a-Z], * allows both)-->
<TextBox ui:TextBoxExtensions.Mask="9a9a-a9a*"/>

<!-- A mask of "+1999-9999" and an empty space as placeholder. That is,
characters not yet filled in by the user will just be blank spaces. -->
<TextBox
ui:TextBoxExtensions.Mask="+1999-9999"
ui:TextBoxExtensions.MaskPlaceholder=" "/>

<!-- Mask = "+964 799 999 9999" (note the escape fore the first 9) -->
<TextBox ui:TextBoxExtensions.Mask="+\964 799 999 9999"/>

<!-- Mask = "99\99\9999" (a backslash can be escaped with another backslash) -->
<TextBox ui:TextBoxExtensions.Mask="99\\99\\9999"/>

<!-- Custom mask with some user-defined special characters. In this case,
we define 5 to mean [1-5], and c to mean [a-c]. The mask is "a5c-5c*9" -->
<TextBox
ui:TextBoxExtensions.CustomMask="5:[1-5],c:[a-c]"
ui:TextBoxExtensions.Mask="a5c-5c*9"/>
</StackPanel>
</Page>
```

### Sample output

A `TextBox` with `Mask` set to `+1999-9999` and `MaskPlaceholder` as space (the placeholder represents the characters the user can change on runtime) will be displayed as follows:

![TextBoxMask animation](../resources/images/Extensions/TextBoxMask.gif)

## 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.

### Syntax

```xaml
<TextBox
xmlns:ui="using:CommunityToolkit.WinUI"
ui:TextBoxExtensions.Regex="^\s*\+?\s*([0-9][\s-]*){9,}$" />

<TextBox
xmlns:ui="using:CommunityToolkit.WinUI"
ui:TextBoxExtensions.ValidationMode="Forced"
ui:TextBoxExtensions.ValidationType="PhoneNumber"
Text="+61616161611" />

<TextBox
xmlns:ui="using:CommunityToolkit.WinUI"
ui:TextBoxExtensions.ValidationType="Email" />

<TextBox
xmlns:ui="using:CommunityToolkit.WinUI"
ui:TextBoxExtensions.ValidationMode="Forced"
ui:TextBoxExtensions.ValidationType="Decimal" />
```

### Sample output

Here is a `TextBox` with `ValidationType="Email"`, with the validation occurring when `TextChanged` is raised:

![TextBoxRegex animation](../resources/images/Extensions/TextBoxRegex.gif)
> [!SAMPLE TextBoxMaskSample]

## 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.

### Syntax

```xaml
<Page ...
xmlns:ui="using:CommunityToolkit.WinUI">

<TextBox
Text="0"
Width="106"
HorizontalAlignment="Left"
VerticalAlignment="Top">
<ui:TextBoxExtensions.SurfaceDialOptions>
<ui:SurfaceDialOptions
EnableHapticFeedback="True"
EnableMinMaxValue="True"
EnableTapToNextControl="False"
StepValue="1"
RotationResolutionInDegrees="12"
MinValue="0"
MaxValue="100"
Icon="Ruler"/>
</ui:TextBoxExtensions.SurfaceDialOptions>
</TextBox>
</Page>
```

### Sample output

Here is an example of the visual result when scrolling on a Surface Dial over a `TextBox`:

![SurfaceDialTextbox animation](../resources/images/Extensions/SurfaceDialTextbox.gif)
> [!SAMPLE SurfaceDialOptionsSample]

## Examples

Expand Down
104 changes: 104 additions & 0 deletions components/Extensions/samples/TextBoxExtensions/RegexSample.xaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,104 @@
<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>
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
// 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();
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
<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>
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
// 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();
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
<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>
Loading
Loading