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

docs(UnoCTK)Added examples for usage of converters second try from initial #18726 #19086

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open
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
94 changes: 94 additions & 0 deletions doc/articles/uno-community-toolkit-v8.md
Original file line number Diff line number Diff line change
Expand Up @@ -184,6 +184,100 @@ You can set the `Header`, `HeaderIcon`, `Description`, and `Content` properties

A complete working sample, along with additional examples, is available on GitHub: [Uno Windows Community Toolkit SettingsCard Sample](https://github.com/unoplatform/Uno.Samples/tree/master/UI/WindowsCommunityToolkit/Version-8.x/UnoWCTSettingsCardSample)

## Using Non-UI Elements from the CommunityToolkit: Converters

The CommunityToolkit is providing some ready-to-use Converters for e.g. x:Bind in Xaml, whithout having to write already existing basic Converters yourself.
[List of CommunityToolkit Converters | Windows Toolkit Documentation](https://learn.microsoft.com/en-us/dotnet/communitytoolkit/windows/converters/)

The implementation of those are quite similar to the example of the SettingsControl above, but there are small adjustments to be done to use them:

1. Import of the Package

Change this:

```CommunityToolkit.WinUI.Controls.SettingsControls```

to Converters namespace:

```CommunityToolkit.WinUI.Converters```

while the Version will stay the same as above.

1. Add the related needed namespace(s)

> [!NOTE]
> In WCT version 8.x, the namespaces between UWP and WinAppSDK were merged.

### WinUI / WinAppSDK / UWP

In XAML:
```xmlns:converters="using:CommunityToolkit.WinUI.Converters"```

In C#:
```using CommunityToolkit.WinUI.Converters;```

In case you are developing a App that's using C# Markup and you want to use the Converters, you can now switch to [C#-Markup Converters](https://platform.uno/docs/articles/external/uno.extensions/doc/Learn/Markup/Converters.html) Documentation for future Usage Guide, the general Import is done from here on.

1. Xaml Definition

Important Difference to the previous seen SettingsCard Control Example, a Non-UI Converter has to be imported to the Page.Ressources Section to StaticRessources like this for using it, since there is no single Namespace per Converter like on the Controls:

### [Example StringToVisibilityConverter](#tab/string-visible-conv)

StringToVisibilityConverter is a Converter that has to be bound to a String typed Property and will return a Visibility State.

```
<Page.Resources>
<converters:StringVisibilityConverter x:Key="YourStringVisibilityConverter"/>
</Page.Resources>
```

Somewhere in your Page Content:

```xml
<TextBox x:Name="tbName"
Text="{Binding Name, Mode=TwoWay}"
PlaceholderText="Enter your name:"/>
<Button x:Name="StartButton"
Content="Start a cool simple Game!"
AutomationProperties.AutomationId="StartAGameButton"
Command="{Binding GoToStart}"
HorizontalAlignment="Center"
Visibility="{x:Bind tbName.Text, Converter={StaticResource StringVisibilityConverter}, Mode=OneWay}"/>
```

### [Example BoolToObjectConverter](#tab/bool-obj-conv)

BoolToObjectConverter is a Converter that has to be bound to a Boolean typed Property and can return any Object you will give to it.
You only have to tell it what to return on True or False. If you would like to use it for switching color on validation:

```
BoolToObjectConverter x:Key="BoolToColorConverter" TrueValue="{ThemeResource SystemFillColorSuccessBackgroundBrush}"
FalseValue="{ThemeResource SystemFillColorCriticalBackgroundBrush}"/>
```

> [!NOTE]
> The used ThemeResource Brushes can be found in the WinUI Gallery for example.
> Feel free to use your own Colors e.g. from ColorPaletteOverrides

Somewhere in your Page Content:

```xml
<TextBox x:Name="tbName"
Text="{Binding Name, Mode=TwoWay}"
PlaceholderText="Enter your name:"
BackgroundColor="{x:Bind tbName.Text, Converter={StaticResource BoolToColorConverter},Mode=OneWay}/>
<Button x:Name="StartButton"
Content="Start a cool simple Game!"
AutomationProperties.AutomationId="StartAGameButton"
Command="{Binding GoToStart}"
HorizontalAlignment="Center"/>
```

---

[!include[getting-help](includes/getting-help.md)]

---

[!include[getting-help](includes/getting-help.md)]
Loading