docs(UnoCTK) added examples for usage of converters

[DevTKSS]

the documentation was only including UI things. Non-UI elements are slightly different and especially for beginners this example is expected to fill the missing piece in this topic and is expected to improve the learning curve, because they can see how to implement this different two types (UI and Non-UI). Also added the Link to the CommunityToolkit Documentation, so its easyer to find similar Non-UI tools.

GitHub Issue (If applicable): closes #18669

PR Type

What kind of change does this PR introduce?

• Documentation content changes

What is the current behavior?

Converters section code is missing the import which might have been pointing to a wpf application, because the compiler wants to add a XCeed.WPF... using. Doing this in a WinUI Application is not recommended and is expected to fail or cause problems and issues that can be avoided by adding this informations on this documentation page and the Converters page in the listed below path. Additional, the current CommunityToolkit doc on uno documentation is including a example for UI element, but since its slightly but not irrelevant, different I would like that information to be added so the Workflow on this can be followed more smoothly.

What is the new behavior?

PR Checklist

Please check if your PR fulfills the following requirements:

• Docs have been added/updated which fit documentation template (for bug fixes / features)
• Unit Tests and/or UI Tests for the changes have been added (for bug fixes / features) (if applicable)
• Validated PR Screenshots Compare Test Run results.
• Contains NO breaking changes
• [?] Associated with an issue (GitHub or internal) and uses the automatic close keywords.
• Commits must be following the Conventional Commits specification.

Other information

TODO: Add link to this page from

uno.extensions/doc/Learn/Markup/Converters.md

so the needed workflow and missing import (in Non-WPF Applications) is clear and followable also for Beginners on xaml/uno.
TODO: Formatting on the added content here is expected to be not optimal because GitHub Web seems to have problems on that. E.g. Headlines intend and Tab-Panel for examples was not visible for me in the preview, but that was also the case on the existing one so please have a look.

Internal Issue (If applicable):

[CLAassistant]

All committers have signed the CLA.

[jeromelaban]

Thanks for the contribution!

I'm wondering though, what's the difference with what is already in https://learn.microsoft.com/en-us/dotnet/communitytoolkit/windows/converters ? We can definitely add a link to useful resources to the community toolkit, though.

[DevTKSS]

seems like something went wrong on the commit + PR, sorry.
Fortunatly I did copy and save the added text, it just deleted kind of all of it.

I did move the "getting help" section below my added text:

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

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.

2. 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 Documentation for future Usage Guide, the general Import is done from here on.

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

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

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"/>
```

---

[!includegetting-help]

[DevTKSS]

Converters.docx

dont know if you can extract the text from the reply so here is the document additionally. Seems like my github and internet is having problems at the moment sorry.

[DevTKSS]

I did try to put the two examples here in two tabs, but seems like it didnt worked

[DevTKSS]

the Link I wrote to be added here in the PR text, would be additionally. With the Example for the Non-UI element the workflow of "How to use Converters in non WPF" in Uno should be closed and followable also for beginners

[jeromelaban]

Thanks. Could you fix the PR's errors? The markdown linter is mentioning errors. Also, the comments formatting does not support - in the docs():, it's best if you rewrite your history to use docs(wct): or something similar.

Once the build passes, we can take a look at the formatting and see how we can have a section about this.

[DevTKSS]

😅 I think the markdown arrows you to see our closely related to my problems with The x bind 😞🙈 i think you should see the code I try to use for the sample in the Repo i linked you in the sample request. I think it was the third commits behind from current state just before set it back to use binding again.😞 So for fixing the lockdown issues I think it's will put in wait line tell me to set topic in the sample request🙈

[unodevops]

⚠️⚠️ The build 149973 has failed on Uno.UI - docs.

[DevTKSS]

Please check if the provided samples to be correct, having constant NullReferenceException when working with e.g. viewModel x:Bind in my code, want to make sure this code here is correct

[unodevops]

⚠️⚠️ The build 150250 has failed on Uno.UI - docs.

[DevTKSS]

@jeromelaban could you or any of the team take a quick look on the problem? Really do not have an Idea, what is happening there added issue for the KI not stops running and failing on my forked repo also, that is not said in the docs and very annoying if no idea what to do there... If its obsolete, please tell the KI just to delete it instead of constantly building this uwp branch while uno is not even using uwp (ref to uno.extensions readme)

[unodevops]

⚠️⚠️ The build 150304 has failed on Uno.UI - docs.

[DevTKSS]

@jeromelaban I tryed to edit the name as you told it needs to, now it did delete it??? Do I have to do the PR again for finalization?

[mergify]

⚠️ The sha of the head commit of this PR conflicts with #19086. Mergify cannot evaluate rules on this PR. ⚠️