diff --git a/doc/Learn/Maui/ThirdParty-MauiCommunityToolkit.md b/doc/Learn/Maui/ThirdParty-MauiCommunityToolkit.md index 9f58632dce..dbf65358e4 100644 --- a/doc/Learn/Maui/ThirdParty-MauiCommunityToolkit.md +++ b/doc/Learn/Maui/ThirdParty-MauiCommunityToolkit.md @@ -9,22 +9,64 @@ The controls from MauiCommunityToolkit can be used in an Uno Platform applicatio An existing sample app that showcases the controls is available [here](https://github.com/unoplatform/Uno.Samples/tree/master/UI/MauiEmbedding/MauiCommunityToolkitApp). +> [!NOTE] +> MauiCommunityToolkitApp SDK for .NET is currently only compatible with Windows, Android, iOS, and Mac Catalyst when used with Uno Platform. + ## Getting Started 1. Create a new application using the `unoapp` template, enabling .NET MAUI Embedding. In this case, we're going to use the Blank template (`-preset blank`) and include .NET MAUI Embedding support (`-maui`). ```dotnetcli - dotnet new unoapp -preset blank -maui -o MauiEmbeddingApp + dotnet new unoapp -preset blank -maui -o MauiCommunityToolkitApp ``` +### [Visual Studio](#tab/vs) +> [!NOTE] +> If you don't have the **Uno Platform Extension for Visual Studio** installed, follow [these instructions](xref:Uno.GetStarted.vs2022). + +- Launch **Visual Studio** and click on **Create new project** on the Start Window. Alternatively, if you're already in Visual Studio, click **New, Project** from the **File** menu. + +- Type `Uno Platform` in the search box + +- Click **Uno Platform App**, then **Next** + +- Name the project `MauiCommunityToolkitApp` and click **Create** + +At this point you'll enter the **Uno Platform Template Wizard**, giving you options to customize the generated application. + +- Select **Blank** in **Presets** selection + +- Select the **Platforms** tab and unselect **Desktop** and **Web Assembly** platforms + +- Select the **Features** tab and click on **.NET MAUI Embedding** + + Click **Create** to complete the wizard -1. Add a reference to the [CommunityToolkit.Maui NuGet package](https://www.nuget.org/packages/CommunityToolkit.Maui) to the MauiEmbeddingApp.MauiControls project. +The template will create a solution with a single cross-platform project, named `MauiCommunityToolkitApp`, ready to run. -1. In the `AppBuilderExtensions` class, on `MauiEmbeddingApp.MauiControls` project, update the `UseMauiControls` extension method to call the `UseMauiCommunityToolkit` method. +For more information on all the template options, see [Using the Uno Platform Template](xref:Uno.GettingStarted.UsingWizard). + +### [Command Line](#tab/cli) + +> [!NOTE] +> If you don't have the **Uno Platform dotnet new templates** installed, follow [dotnet new templates for Uno Platform](xref:Uno.GetStarted.dotnet-new). +Create a new application using the `unoapp` template, enabling .NET MAUI Embedding. In this case, we're going to use the Blank template (`-preset blank`) and include .NET MAUI Embedding support (`-maui`). + +```bash +dotnet new unoapp -preset blank -maui -platforms "android" -platforms "ios" -platforms "maccatalyst" -platforms "windows" -o MauiCommunityToolkitApp +``` + +This will create a new folder called **MauiCommunityToolkitApp** containing the new application. + +--- + +1. Add a reference to the [CommunityToolkitApp.Maui NuGet package](https://www.nuget.org/packages/CommunityToolkit.Maui) to the MauiCommunityToolkitApp.MauiControls project. + +1. In the `AppBuilderExtensions` class, on `MauiCommunityToolkitApp.MauiControls` project, update the `UseMauiControls` extension method to call the `UseMauiCommunityToolkit` method. ```cs using CommunityToolkit.Maui; - namespace MauiEmbeddingApp; + namespace MauiCommunityToolkitApp; public static class AppBuilderExtensions { @@ -33,22 +75,22 @@ An existing sample app that showcases the controls is available [here](https://g .UseMauiCommunityToolkit() .ConfigureFonts(fonts => { - fonts.AddFont("MauiEmbeddingApp/Assets/Fonts/OpenSansRegular.ttf", "OpenSansRegular"); - fonts.AddFont("MauiEmbeddingApp/Assets/Fonts/OpenSansSemibold.ttf", "OpenSansSemibold"); + fonts.AddFont("Assets/Fonts/OpenSansRegular.ttf", "OpenSansRegular"); + fonts.AddFont("Assets/Fonts/OpenSansSemibold.ttf", "OpenSansSemibold"); }); } ``` ## Adding DrawingView -1. Update the EmbeddedControl.xaml in the `MauiEmbedding.MauiControls` project with the following XAML that includes the `DrawingView` control +1. Update the EmbeddedControl.xaml in the `MauiCommunityToolkitApp.MauiControls` project with the following XAML that includes the `DrawingView` control ```xml - @@ -107,10 +149,10 @@ An existing sample app that showcases the controls is available [here](https://g ``` -1. It's time to create the ViewModel that will hold the properties that will be data bound to the `DrawingView` control. On `MauiEmbeddingApp` project, create a new folder called `ViewModels` and add a new class called `MainViewModel`. This class will have the following code: +1. It's time to create the ViewModel that will hold the properties that will be data bound to the `DrawingView` control. On `MauiCommunityToolkitApp` project, create a new folder called `ViewModels` and add a new class called `MainViewModel`. This class will have the following code: - ```cs - namespace MauiEmbeddingApp.ViewModels; +```cs +namespace MauiCommunityToolkitApp.ViewModels; partial class MainViewModel : ObservableObject { @@ -122,15 +164,15 @@ An existing sample app that showcases the controls is available [here](https://g } ``` -1. The `MainViewModel` uses the `ObservableObject` base class that comes from the `CommunityToolkit.MVVM` NuGet package. This significantly reduces the amount of boilerplate code required. Add a reference to the [CommunityToolkit.Mvvm NuGet package](https://www.nuget.org/packages/CommunityToolkit.Mvvm) to the MauiEmbeddingApp project. +1. The `MainViewModel` uses the `ObservableObject` base class that comes from the `CommunityToolkit.MVVM` NuGet package. This significantly reduces the amount of boilerplate code required. Add a reference to the [CommunityToolkit.Mvvm NuGet package](https://www.nuget.org/packages/CommunityToolkit.Mvvm) to the MauiCommunityToolkitApp project. 1. The final step is to add the `MainViewModel` as the `DataContext` of the `Page` in the `MainPage.xaml` file. Here's how the final xaml should look. ```xml - - @@ -162,7 +204,9 @@ An existing sample app that showcases the controls is available [here](https://g 1. Now the project is good to go! Press F5 and you should see the `DrawingView` control working as expected. And tweaking the `ToggleSwitch` controls should change the `DrawingView` behavior. -## App Render Output +For more detailed instructions specific to each platform, refer to the [Debug the App](xref:Uno.GettingStarted.CreateAnApp.VS2022#debug-the-app) documentation. + +**App Render Output** - **Android:** - ![Android CommunityToolkit](Assets/Screenshots/Android/CommunityToolkit.png)