# Uno Platform
The Uno Platform is an Open-Source .NET platform for building single-codebase, cross-platform applications for mobile, web (using WebAssembly), desktop, and embedded apps quickly.
Important notes:
- The core framework is free and open-source under the Apache 2 license, since its release in 2018; optional enterprise support and advanced tooling (such as Hot Design) are offered under paid plans
- Skia (using a full-screen canvas) and Native (using native elements) renderers are available
- Uno Platform uses the WinUI (UI APIs) and WinRT (non-UI APIs) API definitions, but does not use WinAppSDK/WinUI. WinAppSDK is only used when running the `netX.0-windows` target, for the other targets, only Uno Platform code is used
- Uno Platform uses official .NET mobile bindings directly, but does not use MAUI
- Uno Platform offers a comprehensive C# and XAML Hot Reload support, under the free plan
- Uno Platform apps can run on iOS/iPadOS, Android, macOS, Windows, Linux, and Browsers supporting WebAssembly
## Table of Contents
- [Get Started](#Uno.GetStarted)
- [Setup](#Uno.GetStarted.vs2022)
- [Visual Studio](#Uno.GetStarted.vs2022)
- [VS Code](#Uno.GetStarted.vscode)
- [Rider](#Uno.GetStarted.Rider)
- [Claude Code](#Uno.GetStarted.AI.Claude)
- [Codex](#Uno.GetStarted.AI.Codex)
- [GitHub Copilot CLI](#Uno.GetStarted.AI.CopilotCLI)
- [Cursor](#Uno.GetStarted.AI.Cursor)
- [Sign in with Uno Platform](#Uno.GetStarted.Licensing)
- [Create an App](#Uno.GettingStarted.CreateAnApp.VS2022)
- [Visual Studio 2022/2026](#Uno.GettingStarted.CreateAnApp.VS2022)
- [VS Code](#Uno.GettingStarted.CreateAnApp.VSCode)
- [Rider](#Uno.GettingStarted.CreateAnApp.Rider)
- [Claude Code](#Uno.GettingStarted.CreateAnApp.AI.Claude)
- [Codex](#Uno.GettingStarted.CreateAnApp.AI.Codex)
- [GitHub Copilot CLI](#Uno.GettingStarted.CreateAnApp.AI.CopilotCli)
- [Cursor](#Uno.GettingStarted.CreateAnApp.AI.Cursor)
- [Build your app](#Uno.GetStarted.Explore)
- [AI Agents](#Uno.BuildYourApp.AI.Agents)
- [Hot Reload](#Uno.Features.HotReload)
- [App Structure](#Uno.Development.AppStructure)
- [Troubleshoot](#Uno.UI.CommonIssues)
- [Overview](#Uno.UI.CommonIssues)
- [Hot Reload](#Uno.Features.HotReload#troubleshooting)
- [Uno Platform Status](#Uno.Development.UnoPlatformStatus#troubleshooting)
- [Development Environments](#Uno.UI.CommonIssues.AllIDEs)
- [All Development Environments](#Uno.UI.CommonIssues.AllIDEs)
- [Visual Studio 2022/2026](#Uno.UI.CommonIssues.vs2022)
- [VS Code](#Uno.UI.CommonIssues.vscode)
- [Rider](#Uno.UI.CommonIssues.rider)
- [Android & iOS Emulators](#Uno.UI.CommonIssues.MobileDebugging)
- [AI Agents](#Uno.UI.CommonIssues.AIAgents)
- [Platforms](#Uno.UI.CommonIssues.Wasm)
- [WebAssembly](#Uno.UI.CommonIssues.Wasm)
- [Skia (Gtk/Wpf/Framebuffer)](#Uno.UI.CommonIssues.Skia)
- [iOS](#Uno.UI.CommonIssues.Ios)
- [Android](#Uno.UI.CommonIssues.Android)
- [Build Errors](#Uno.Development.Troubleshooting)
- [Troubleshooting build errors](#Uno.Development.Troubleshooting)
- [Build error codes](#Build.Solution.error-codes)
- [Samples & Tutorials](#Uno.SamplesTutorials.Overview)
- [Overview](#Uno.SamplesTutorials.Overview)
- [Counter](#Uno.Workshop.Counter)
- [Counter App](#Uno.Workshop.Counter)
- [XAML + MVUX](#Uno.Workshop.Counter.XAML.MVUX)
- [XAML + MVVM](#Uno.Workshop.Counter.XAML.MVVM)
- [C# Markup + MVUX](#Uno.Workshop.Counter.CSharp.MVUX)
- [C# Markup + MVVM](#Uno.Workshop.Counter.CSharp.MVVM)
- [Hot Design](#Uno.HotDesign.GetStarted.CounterTutorial)
- [Simple Calc](#Workshop.SimpleCalc.Overview)
- [Tube Player](#Workshop.TubePlayer.Overview)
- [Chefs](#Uno.Chefs.Overview)
- [Tutorials](#Uno.Tutorials.Intro)
- [Overview](#Uno.Tutorials.Intro)
- [How to deploy a WebAssembly app on Azure Static Web Apps](#Uno.Tutorials.AzureStaticWebApps)
- [How to use Windows Community Toolkit](#Uno.Development.CommunityToolkit)
- [Windows Community Toolkit - Version 8.x](#Uno.Development.CommunityToolkit.v8)
- [Windows Community Toolkit - Version 7.x](#Uno.Development.CommunityToolkit.v7)
- [How to manually add a splash screen](#Uno.Development.SplashScreen)
- [How to use native Frame navigation](#Uno.Tutorials.UseNativeFrameNav)
- [How to consume a web API](#Uno.Development.ConsumeWebApi)
- [How to localize text resources](#Uno.Tutorials.Localization)
- [How to change app language at runtime](#Uno.Tutorials.ChangeAppLanguage)
- [How to integrate SignalR](#Uno.Development.SignalR)
- [How to use MSAL for Azure Authentication](#Uno.Interop.MSAL)
- [How to authenticate with OpenID Connect](#Uno.Tutorials.OpenIDConnect)
- [How to implement a sign-in with Apple Button](#Uno.Tutorials.SignInWithApple)
- [Embed a JavaScript Component](#Uno.Interop.WasmJavaScript1)
- [Part 1](#Uno.Interop.WasmJavaScript1)
- [Part 2](#Uno.Interop.WasmJavaScript2)
- [Part 3](#Uno.Interop.WasmJavaScript3)
- [Deploy to Raspberry Pi](#Uno.RaspberryPi.Intro)
- [Community Tutorials](#Uno.Tutorials.CommunityTutorials)
- [Samples](#Uno.Samples)
- [Additional Resources](#Uno.GetStarted.NextSteps)
- **Overview**
- [Introduction](#Uno.Documentation.Intro)
- **Architecture**
- [Supported Platforms](#Uno.GettingStarted.Requirements)
- [.NET Version Support](#Uno.Development.NetVersionSupport)
- [Philosophy](#Uno.Overview.Philosophy)
- [How Uno Works](#Uno.Development.HowItWorks)
- **UI Renderers**
- [Skia Renderer](#uno.features.renderer.skia)
- [Native Renderer](#uno.features.renderer.native)
- [Best Practices](#Uno.Development.BestPractices)
- **Authoring**
- [Using the Uno.SDK](#Uno.Features.Uno.Sdk)
- [UI Markup](#uno.development.using.markup)
- [Platform-specific C# code](#Uno.Development.PlatformSpecificCSharp)
- [Platform-specific XAML markup](#Uno.Development.PlatformSpecificXaml)
- [Creating Custom Controls](#Uno.Tutorials.CreatingCustomControls)
- [Control Libraries](#Guide.HowTo.Create-Control-Library)
- [Adding New Platforms](#Uno.Guides.AddAdditionalPlatforms)
- [New Projects in Existing Solutions](#Uno.Guides.AddUnoToExistingSolution)
- [Using the Skia Desktop](#Uno.Skia.Desktop)
- [Linux Framebuffer](#Uno.Skia.Linux.Framebuffer)
- [Using Skia Desktop (macOS)](#Uno.Skia.macOS)
- [Getting Started With Tests](#Uno.Authoring.Tests)
- [Logging](#Uno.Development.Logging)
- [AppManifest (WebAssembly)](#Uno.Development.WasmAppManifest)
- [Using the server project](#Uno.Guides.UsingTheServerProject)
- [Hosting a WebAssembly app](#Uno.Development.HostWebAssemblyApp)
- **Debugging**
- [How to create a repro sample](#Uno.Development.Create-Repro)
- ['Debugging C# on WASM'](#Uno.Development.DebuggingWasm)
- [VS Code Advanced Mobile Debugging](#uno.vscode.mobile.advanced.debugging)
- [Generic Unhandled Exceptions handler](#Uno.Development.UnhandledExceptions)
- [Debugging Troubleshooting](#Uno.Debugging.Troubleshooting)
- **Embedding**
- [Uno Platform in WPF](#Uno.Tutorials.UnoIslands)
- [Native Views](#Uno.Development.NativeViews)
- [Native Views with Skia](#Uno.Skia.Embedding.Native)
- **Upgrading**
- [Upgrading NuGet Packages](#Uno.Development.UpgradeUnoNuget)
- [Upgrading from previous releases](#Uno.Development.MigratingFromPreviousReleases)
- [Upgrading to Single Project](#Uno.Development.MigratingToSingleProject)
- [Upgrading to Uno 6.0](#Uno.Development.MigratingToUno6)
- [Upgrading to Uno 5.0](#Uno.Development.MigratingToUno5)
- [Upgrading from .NET 9 to .NET 10](#Uno.Development.MigratingFromNet9ToNet10)
- [Upgrading from .NET 8 to .NET 9](#Uno.Development.MigratingFromNet8ToNet9)
- [Upgrading from .NET 7 to .NET 8](#Uno.Development.MigratingFromNet7ToNet8)
- [Upgrading from Xamarin to .NET 6](#Uno.Development.MigratingFromXamarinToNet6)
- [Upgrading to WinUI 3.0](#Uno.Development.UpdatingToWinUI3)
- **Migrating**
- [Xamarin Forms](#Uno.XamarinFormsMigration.Overview)
- **WPF**
- [Migrating WPF Apps to Web](#Uno.Development.WPFMigration)
- **UWP-only code**
- [Overview](#Uno.Development.MigrateExistingCode)
- [Checklist](#Uno.Development.MigratingBeforeYouStart)
- [Applications](#Uno.Development.MigratingApps)
- [Class libraries](#Uno.Development.MigratingLibraries)
- [General guidance](#Uno.Development.MigratingGuidance)
- [Silverlight](#Uno.SilverlightMigration.Landing)
- **Publishing**
- [Overview](#uno.publishing.overview)
- [Publishing for Desktop](#uno.publishing.desktop)
- [Publishing Your App for Desktop](#uno.publishing.desktop)
- [Publishing Your App for macOS](#uno.publishing.desktop.macos)
- [Publishing Your App for macOS - Advanced Topics](#uno.publishing.desktop.macos.advanced)
- [Publishing Your App for Linux](#uno.publishing.desktop.linux)
- [Publishing for WebAssembly](#uno.publishing.webassembly)
- [Publishing for Windows App SDK](#uno.publishing.windows)
- [Build Packaged Unsigned Apps](#uno.publishing.windows.sideload.packaged.unsigned)
- [Build Packaged Signed Apps](#uno.publishing.windows.sideload.packaged.signed)
- [Build Unpackaged Apps](#uno.publishing.windows.sideload.unpackaged.unsigned)
- [Publishing for iOS](#uno.publishing.ios)
- [Publishing for Android](#uno.publishing.android)
- **Performance**
- [Improving Build Times](#Build.Solution.TargetFramework-override)
- [Performance tips](#Uno.Development.Performance)
- [Memory Profiling](#Uno.Contributing.MemoryIssues)
- [How to profile applications](#Uno.Tutorials.ProfilingApplications)
- [IL Linker for WebAssembly](#uno.articles.features.illinker)
- [Skia Native Libraries Trimming](#Uno.Features.SkiaLibrariesTrimming)
- [Working with String Resource Trimming](#Uno.Features.StringResourceTrimming)
- [Working with XAML Trimming](#Uno.Features.ResourcesTrimming)
- [Error Monitoring & Crash Reporting with Raygun](#Monitoring.Raygun)
- **Contributing**
- [Overview](#Uno.Contributing.Intro)
- [Code of Conduct](https://github.com/unoplatform/uno/blob/master/CODE_OF_CONDUCT.md)
- [Ways to contribute](#Uno.Contributing.WaysToContribute)
- **How Uno works**
- [Overview](#Uno.Contributing.Overview)
- [Android](#Uno.Contributing.Android)
- [Layouting in Android](#Uno.Contributing.LayoutingAndroid)
- [iOS](#Uno.Contributing.iOS)
- [Layouting in iOS](#Uno.Contributing.LayoutingiOS)
- [WASM](#Uno.Contributing.Wasm)
- [macOS](#Uno.Contributing.macOS)
- [DependencyProperty backing generator](#Uno.Contributing.DependencyPropertyGenerator)
- [x:Bind in Uno Platform](#Uno.Contributing.xBind)
- [ListViewBase](#Uno.Contributing.ListViewBase)
- [ThemeResource](#Uno.Contributing.ThemeResource)
- [InteractionTracker internals](#articles-uno-development-interaction-tracker-internals)
- [Building Uno.UI](#Uno.Contributing.BuildingUno)
- [Debugging Uno.UI](#Uno.Contributing.DebuggingUno)
- [Using Codespaces](#Uno.Features.Codespaces)
- [Using Ona](#Uno.Features.Gitpod)
- [Inspecting the visual tree](#Uno.Contributing.InspectVisualTree)
- [Guidelines for code style](#Uno.Contributing.CodeStyle)
- [Using the SamplesApp](#Uno.Contributing.SamplesApp)
- **Guidelines for creating tests**
- [Overview](#Uno.Contributing.CreatingTests)
- [Mocked unit tests (Uno.UI.Tests)](#Uno.Contributing.CreateMockedTests)
- [Platform-runtime unit tests (Uno.UI.RuntimeTests)](#Uno.Contributing.CreateRuntimeTests)
- [UI tests with Uno.UITest](#Uno.Contributing.CreateUITests)
- [Debugging Solution Templates](#Uno.Contributing.DebuggingTemplates)
- [Conventional Commits format](#Uno.Contributing.ConventionalCommits)
- [Guidelines for pull-requests](#Uno.Contributing.PullRequests)
- [Guidelines for breaking changes](#Uno.Contributing.BreakingChanges)
- [Guidelines for updating dependencies](#Uno.Contributing.UpdatingDependencies)
- [Guidelines for issue triage](#Uno.Contributing.IssueTriage)
- [Guidelines for implementing a new WinUI/WinRT feature](#Uno.Contributing.ImplementWinUIWinRTAPI)
- [Adding documentation](#Uno.Contributing.Docs)
- [DocFX](#Uno.Contributing.DocFx)
- [Uno.UI release procedure](#Uno.Contributing.ReleaseProcedure)
- [Build Artifacts](#Uno.Contributing.Artifacts)
- **Advanced topics**
- [Adding functionality with API extensions](#Uno.Contributing.ApiExtensions)
- [The WeakEventHelper class](#Uno.Contributing.WeakEventHelper)
- [Debugging Uno.UI Java code with Android studio](#Uno.Contributing.AndroidStudio)
- [Troubleshooting Memory Issues](#Uno.Contributing.MemoryIssues)
- [Troubleshooting Source Generation](#Uno.Contributing.SourceGeneration)
- [The XAML Trimming phase](#Uno.Contributing.XamlResourceTrimming)
- [Hot Reload internals](#Uno.Contributing.Internals.HotReload)
- [Why use Uno Platform?](#Uno.Overview.WhyUno)
- [FAQ](#Uno.Development.FAQ)
- **Studio**
- [Overview](#Uno.Platform.Studio.Overview)
- [Uno MCPs](#Uno.Features.Uno.MCPs)
- [Hot Reload](#Uno.Platform.Studio.HotReload.Overview)
- [Feedback](#Uno.Platform.Studio.Feedback)
- **Reference**
- **Overview**
- [Developing with Uno Platform](#Uno.Development.Overview)
- [Features List](#Uno.Development.SupportedFeatures)
- [Feature Flags](#Uno.Development.FeatureFlags)
- **WinUI Compatibility**
- [Differences From WinUI](#Uno.Development.ApiDifferences)
- [About NotImplemented members](#Uno.Development.NotImplemented)
- [Uno and WinUI 3](#Uno.Development.UwpVsWinUI3)
- [WinAppSDK Specifics](#Uno.Features.WinAppSDK)
- **WinUI links**
- [Overview](#Uno.Development.WinUIDoc)
- [Tutorials](#Uno.Development.WinUITutorialsDoc)
- [Development](#Uno.Development.WinUIDevelopmentDoc)
- [Design](#Uno.Development.WinUIDesignDoc)
- **UI**
- **Controls**
- [Implemented Views](#articles-implemented-views)
- **Uno Specifics**
- [AdaptiveTrigger](#Uno.Features.AdaptiveTrigger)
- [Activities in Android](#Uno.Development.AndroidActivities)
- [ComboBox](#Uno.Controls.ComboBox)
- [CommandBar](#Uno.Controls.CommandBar)
- [DatePicker](#Uno.Controls.DatePicker)
- [ElevatedView](#Uno.Features.ElevatedView)
- [Fluent icon font](#Uno.Development.FluentAssets)
- [Flyout](#Uno.Controls.Flyout)
- [Frame](#Uno.Controls.Frame)
- [GLCanvasElement](#Uno.Controls.GLCanvasElement)
- [Image](#Uno.Features.Image)
- [ListView and GridView](#Uno.Controls.ListViewBase)
- [Lottie animations](#Uno.Features.Lottie)
- [MapControl](#Uno.Controls.MapControl)
- [MediaPlayerElement](#Uno.Controls.MediaPlayerElement)
- [MenuFlyout](#Uno.Controls.MenuFlyout)
- [NavigationView](#Uno.Controls.NavigationView)
- [Native control styles](#Uno.Development.NativeStyles)
- [Other features](#Uno.Development.AdditionalFeatures)
- [Pivot](#Uno.Controls.Pivot)
- [Popup](#Uno.Controls.Popup)
- [ProgressRing](#Uno.Features.ProgressRing)
- [RefreshContainer (Pull to Refresh)](#Uno.Controls.RefreshContainer)
- [ScrollViewer](#Uno.Controls.ScrollViewer)
- [SKCanvasElement](#Uno.Controls.SKCanvasElement)
- [TextBox](#Uno.Controls.TextBox)
- [TimePicker](#Uno.Controls.TimePicker)
- [ToggleSwitch](#Uno.Controls.ToggleSwitch)
- [URI Protocol activation](#Uno.Features.ProtocolActivation)
- [Using pointer cursors](#Uno.Features.Cursors)
- [Using SVG images](#Uno.Features.SVG)
- [VisibleBoundsPadding](#Uno.Features.VisibleBoundsPadding)
- [WebView (WebView2)](#Uno.Controls.WebView2)
- **Features**
- [Accessibility](#Uno.Features.Accessibility)
- [Animations](#Uno.Features.Animations)
- [Assets and image display](#Uno.Features.Assets)
- [Build telemetry](#Uno.Development.ToolchainTelemetry)
- [Composition API](#Uno.Development.Composition)
- [Customizing the UIApplicationDelegate on iOS](#Uno.Features.CustomizingUIApplicationDelegate)
- [Dialogs](#Uno.Features.Dialogs)
- [Fluent styles](#Uno.Features.FluentStyles)
- [Focus management](#Uno.Features.FocusManagement)
- [Fonts](#Uno.Features.CustomFonts)
- [Markup Extensions](#Uno.Features.WinUIMarkupExtension)
- [Native frame navigation](#Uno.Features.NativeFrameNav)
- [Orientation](#Uno.Features.Orientation)
- [Routed Events](#Uno.Features.RoutedEvents)
- [Shapes & Brushes](#Uno.Features.ShapesAndBrushes)
- [String resources and localization](#Uno.Features.Localization)
- [Succinct syntax](#Uno.Features.WinUISuccinctSyntax)
- [Themes](#Uno.Features.Themes)
- [User inputs - Keyboard, Pointers, Gestures, Manipulations, Drag and drop](#Uno.Features.UserInputs)
- [Using Fluent styles in legacy apps](#Uno.Features.WinUI2)
- [Windowing](#Uno.Features.WinUIWindow)
- [Preventing Window Closing](#Uno.Features.AppCloseHandler)
- [x:Bind](#Uno.Features.WinUIxBind)
- [3rd-party libraries](#Uno.Development.SupportedLibraries)
- **Non-UI**
- [Overview](#uno.features.uno.winrt)
- [Accelerometer](#Uno.Features.Accelerometer)
- [Android TV](#Uno.Features.AndroidTv)
- [App Actions](#Uno.Features.WinUIStartScreen)
- [App Suspension](#Uno.Features.WinUIApplication)
- [Application Data and Settings](#Uno.Features.ApplicationData)
- [Badge Notifications](#Uno.Features.WinUINotifications)
- [Barometer](#Uno.Features.Barometer)
- [Battery Information](#Uno.Features.WSPower)
- [Bluetooth](#Uno.Features.BluetoothDevice)
- [Capture (Camera)](#Uno.Features.Capture)
- [Clipboard](#Uno.Features.Clipboard)
- [Compass](#Uno.Features.Compass)
- [Contacts](#Uno.Features.WAMContacts)
- [Credential Storage](#Uno.Features.PasswordVault)
- [Device Enumeration](#Uno.Features.WDEnumeration)
- [Device Information](#Uno.Features.WSProfile)
- [E-mail](#Uno.Features.WAMEmail)
- [File and Folder Pickers](#Uno.Features.WSPickers)
- [File Management](#Uno.Features.FileManagement)
- [Flashlight](#Uno.Features.Flashlight)
- [Gamepad](#Uno.Features.Gamepad)
- [Geolocation (GPS)](#Uno.Features.WDGeolocation)
- [Gyrometer](#Uno.Features.Gyrometer)
- [Haptics](#Uno.Features.WDHaptics)
- [Hardware back button](#Uno.Features.HardwareBackButton)
- [Keeping Screen On](#Uno.Features.WSDisplay)
- [Light Sensor](#Uno.Features.LightSensor)
- [Magnetometer](#Uno.Features.Magnetometer)
- [MIDI](#Uno.Features.WDMidi)
- [Network Information](#Uno.Features.WNetworking)
- [Orientation Sensor](#Uno.Features.OrientationSensor)
- [Package Information](#Uno.Features.WAM)
- [Phone Calls](#Uno.Features.WAMCalls)
- [Proximity Sensor](#Uno.Features.ProximitySensor)
- [Settings](#Uno.Features.Settings)
- [Sharing](#Uno.Features.WAMDataTransfer)
- [SMS](#Uno.Features.WAMChat)
- [Speech Recognition](#Uno.Features.SpeechRecognition)
- [Step Counter](#Uno.Features.StepCounter)
- [Store Context](#Uno.Features.StoreContext)
- [Title Bar Customization](#Uno.Features.WinUIViewManagement)
- [URI Launcher](#Uno.Features.WS)
- [Vibration](#Uno.Features.WPDNotification)
- [Wallpaper and Lock Screen](#Uno.Features.WSUserProfile)
- [Web Authentication Broker](#Uno.Features.WAB)
- [Working with cookies](#Uno.Features.Cookies)
- **Tooling**
- [Uno Platform Status](#Uno.UnoPlatformStatus)
- [Dev Server](#Uno.DevServer)
- **VS Code Extension**
- [Visual Studio Code Extension](#Uno.vscode.additional)
- [C# Dev Kit Support](#Uno.GetStarted.vscode.DevKit)
- [Omnisharp Support](#Uno.GetStarted.vscode.OmniSharp)
- **Rider**
- [License Agreement](#Uno.Rider.EULA)
- **Templates**
- [Visual Studio Wizard](#Uno.GettingStarted.UsingWizard)
- [dotnet new Templates](#Uno.GetStarted.dotnet-new)
- [Get started wizard](#Uno.GetStarted.Wizard)
## Uno.vscode.additional
# Visual Studio Code Extension
To get started on using VS Code, [head over to our guides](#Uno.GetStarted.vscode).
In this page, you'll find other topics about VS Code support, such as code snippets or how to upgrade an existing app to use VS Code.
## Explore other features
The Uno Platform extension provides additional features to help you develop your application.
You can explore them by pressing `F1` or `Ctrl-Shift-P` and typing `Uno Platform` to see the list of available commands.
## Using code snippets
### Adding a new Page
1. In the MyApp folder, create a new file named `Page2.xaml`
2. Type `page` then press the `tab` key to add the page markup
3. Adjust the name and namespaces as needed
4. In the MyApp folder, create a new file named `Page2.xaml.cs`
5. Type `page` then press the `tab` key to add the page code behind C#
6. Adjust the name and namespaces as needed
### Adding a new UserControl
1. In the MyApp folder, create a new file named `UserControl1.xaml`
2. Type `usercontrol` then press the `tab` key to add the page markup
3. Adjust the name and namespaces as needed
4. In the MyApp folder, create a new file named `UserControl1.xaml.cs`
5. Type `usercontrol` then press the `tab` key to add the page code behind C#
6. Adjust the name and namespaces as needed
### Adding a new ResourceDictionary
1. In the MyApp folder, create a new file named `ResourceDictionary1.xaml`
2. Type `resourcedict` then press the `tab` key to add the page markup
### Other snippets
- `rd` creates a new `RowDefinition`
- `cd` creates a new `ColumnDefinition`
- `tag` creates a new XAML tag
- `set` creates a new `Style` setter
- `ctag` creates a new `TextBlock` close XAML tag
## Updating an existing application to work with VS Code
An existing application needs additional changes to be debugged properly.
1. At the root of the workspace, create a folder named `.vscode`
2. Inside this folder, create a file named `launch.json` and copy the [contents of this file](https://github.com/unoplatform/uno.templates/blob/main/src/Uno.Templates/content/unoapp/.vscode/launch.json).
3. Replace all instances of `MyExtensionsApp._1` with your application's name in `launch.json`.
4. Inside this folder, create a file named `tasks.json` and copy the [contents of this file](https://github.com/unoplatform/uno.templates/blob/main/src/Uno.Templates/content/unoapp/.vscode/tasks.json).
## Advanced debugging
You can find [advanced Code debugging topic here](#uno.vscode.mobile.advanced.debugging).
## Uno.Development.AndroidActivities
# Managing activities in Android
[Activities](https://developer.android.com/reference/android/app/Activity) are an integral element of the Android platform. By default your Uno Platform application runs in a single activity, but you might for example spawn a new activity when a user shares content, or picks an image from their device. This article covers Activity management in Uno.
## Android documentation links
- [Introduction to Activities](https://developer.android.com/guide/components/activities/intro-activities)
- [Understand the Activity Lifecycle](https://developer.android.com/guide/components/activities/activity-lifecycle)
## Creating/Using Android Activities
At the root of every Android Uno app, lies a `BaseActivity` class that extends from `Android.Support.V7.App.AppCompatActivity` which is part of the [Android v7 `AppCompat` Support Library](https://developer.android.com/topic/libraries/support-library/features.html#v7-appcompat). If you ever need to create a new Activity within your app or within Uno, you must be sure to extend `BaseActivity` and, if you need to apply a Theme to the activity, ensure that the Theme you set is a `Theme.AppCompat` theme (or descendant).
## Accessing Android main activity events
Uno Platform provides an API to get access to the events/overrides invoked in the main activity (commonly inheriting from `UI.Xaml.ApplicationActivity`) outside of the activity class.
In order to get access to these events, you can write the following:
```csharp
using Uno.UI.ViewManagement;
App()
{
// ...
ApplicationViewHelper.GetBaseActivityEvents().Create += OnCreateEvent;
// ...
}
private void OnCreateEvent(Android.OS.Bundle savedInstanceState)
{
}
```
Note that some events are raised early during the application lifecycle and may need to be registered from the `App` constructor.
## Uno.Development.ApiDifferences
# Differences between Uno.UI and WinUI
Uno Platform strives to closely replicate the WinUI API on all platforms and ensure that existing WinUI code is 100% compatible with Uno. This article covers areas where Uno.UI's implementation differs, typically to better integrate with the native platform, or where the capabilities of .NET differ due to inherent limitations of the native platform.
This article doesn't cover parts of the API that haven't been implemented yet. You can consult a [complete list of implemented and unimplemented controls here](implemented-views.md).
For a practical guide to addressing differences between Uno Platform and WinUI, [read this article](migrating-guidance.md).
## API differences
### `FrameworkElement` inherits from native base view types (Android, iOS, macOS)
As for WinUI, all visual elements in Uno.UI inherit from `FrameworkElement`, which inherits from `UIElement`. (At least, those that are publicly available.) On Windows, `UIElement` inherits from the `DependencyObject` class, which inherits from `System.Object`.
On Android, iOS, and macOS, `UIElement` instead inherits from the native base view type for each platform, as exposed to .NET by Xamarin Native. So, `ViewGroup` for Android, `UIView` for iOS, and `NSView` for macOS.
This allows native views (not defined by Uno.UI or inheriting from `FrameworkElement`) to be directly integrated into the visual tree, [in XAML markup or C# code](native-views.md).
### `DependencyObject` type is an interface (all non-Windows platforms)
This API difference follows directly from the previous one. In order to support native view inheritance, Uno.UI defines `DependencyObject` as an interface, rather than a class.
This is as transparent as possible to the application developer. For example, if a developer defines a class that inherits directly from `DependencyObject`, Uno.UI will automatically generate code that implements the `DependencyObject` interface methods. The only developer action required is to add the `partial` keyword to the class definition.
## Runtime differences
### iOS is AOT-only
.NET code [must be Ahead-Of-Time (AOT) compiled to run on iOS](https://learn.microsoft.com/xamarin/ios/internals/limitations), as a fundamental platform limitation. As a result, a few APIs that require runtime code generation (eg `System.Reflection.Emit`) do not work. This includes code that uses the `dynamic` keyword.
### WebAssembly is single-threaded
Currently, WebAssembly code in the browser executes on a single thread. This limitation is expected to be lifted in the future, but for now, code that expects additional threads to be available may not function as expected.
[This GitHub issue](https://github.com/unoplatform/uno/issues/2302) tracks support for multi-threading on WebAssembly in Uno Platform.
## Uno.Development.BestPractices
# Best practices for developing Uno Platform applications
This article covers some basic best practices when developing cross-platform applications with Uno Platform.
## Questions to ask
1. Which [platforms](#Uno.GettingStarted.Requirements) do I plan to target?
2. What framework features do I plan to use? Are they supported on all of my planned target platforms?
3. Which major third-party dependencies will I use? Are they supported on all of my planned target platforms?
## Development workflow
Testing and debugging your application is easier and more rapid on some platforms and trickier and more time-consuming on others. Depending on where you're at in your development cycle, it may make sense to test all platforms, or it may make sense to focus on the 'easiest' platform.
1. **At the beginning of the development cycle,** you should identify key features from the Uno Platform framework and 3rd-party dependencies that you plan to use. Check that the framework controls you plan to use [are implemented](implemented-views.md). Consider creating a simple proof-of-concept (POC) app covering the 'riskiest' features and testing it on all platforms you're targeting.
2. **In the middle of the development cycle,** once the major pieces are in place, when you're iterating on the UI and business logic of your application, most of your day-to-day development should focus on the easiest platform to develop on. Most of the time, this will be Windows, where you can take advantage of Microsoft's excellent tooling (Live Visual Tree, XAML Hot Reload, etc) and where build times are often shortest. For this reason, it's recommended to keep the Windows (WinUI 3) head project in your solution, even if you don't plan to publish your application to Windows.
3. **At the end of the development cycle,** as your attention shifts to testing and fixing bugs, you'll again distribute your time more equally across all of the platforms you plan to target, ensuring that the application looks and behaves consistently everywhere.
## Platform-specific code
It's likely that some part of your application's code, be it C# code or XAML markup, will be specific to only one platform - perhaps because you want to access platform-specific APIs, implement a feature using native third-party libraries, or simply customize the experience to be more idiomatic to that particular platform.
You can read more on the mechanics of platform-specific code [here for C#](#Uno.Development.PlatformSpecificCSharp) and [here for XAML](#Uno.Development.PlatformSpecificXaml). You should also make sure you understand [an Uno Platform App solution structure](#Uno.Development.AppStructure).
The main goals where platform-specific code is concerned are to:
* **Maximize maintainability by keeping as much code shared as possible.**
* **Maximize readability by organizing your code in a consistent, legible way.**
Here are some tips to achieve that:
* **Use [partial class](platform-specific-csharp.md#partial-class-definitions) definitions to mix shared code and platform-specific code in a single class.** Separating all platform-specific code into a dedicated partial definition is usually more readable than interleaving platform-specific `#if` blocks with shared code, particularly if the amount of platform-specific code is significant.
* **Give partial definition files a platform-specific suffix.** Eg, for a `FormHighlighter` class, the shared partial definition would go in `FormHighlighter.cs`, the iOS-specific partial definition would go in `FormHighlighter.iOS.cs`, etc.
* **(Optional) Consider putting platform-agnostic application layers in a separate .NET Standard project.** 'Thinking multi-platform' adds to the cognitive burden of reading and writing code, as well as the testing effort of verifying that it runs the same way on every platform. For this reason, some people prefer to split out platform-agnostic parts of the application into a separate .NET Standard project, eg 'pure' business logic which doesn't interact with the UI or with non-visual platform APIs. This project builds once as a single binary used on all platforms, giving a stronger guarantee that it will behave consistently everywhere. Enforcing that platform-agnostic separation does impose an architectural burden too, so it's a matter of personal preference.
## Application architecture
You have a lot of choice when choosing an architecture for an Uno Platform application. Since it uses the WinUI contract, Uno Platform supports several features which lend themselves to a [model/view/view-model (MVVM) approach](https://learn.microsoft.com/windows/uwp/data-binding/data-binding-and-mvvm), like data binding and dependency properties; but you're perfectly free to use any approach you like best.
Sometimes so much freedom can be paralyzing. To help you get started, we've created several reference applications especially for Uno Platform. These are working, real-world applications utilizing simple but effective architectural patterns for cross-platform development.
* [**Ch9**](https://github.com/unoplatform/Uno.Ch9): browse content from Microsoft's publicly-available Channel 9 video feed.
* [**UADO**](https://github.com/unoplatform/uado): Universal Azure DevOps Organizer
## Performance
See a checklist of performance-related best practices [here](Uno-UI-Performance.md).
## Uno.UI.CommonIssues
# Troubleshooting
The Uno Platform features and support are constantly evolving, yet you may encounter some of the issues while building your application, for which answers and details are available below.
> [!TIP]
> Take a look at our [common issues list](xref:Uno.UI.CommonIssues) and [health status](https://aka.platform.uno/health-status) if you're having any troubles.
>
> If you are experiencing issues with Uno Platform, please visit our [GitHub Discussions](https://github.com/unoplatform/uno/discussions) or [Discord Server](https://www.platform.uno/discord) - where our engineering team and community will be able to help you.
>
A better resource for high-level questions about Uno Platform is the [general FAQ](#Uno.Development.FAQ).
## Hot Reload
When using Hot Reload, ensure you first review the [supported features](#Uno.Features.HotReload), [supported features per OS](#Uno.Features.HotReload), and [supported features per platform](#Uno.Features.HotReload).
If issues persist, additional troubleshooting information is available in [this section](#Uno.Features.HotReload).
## Development Environments
- [All Development Environments](#Uno.UI.CommonIssues.AllIDEs)
- [Visual Studio 2022/2026 for Windows](#Uno.UI.CommonIssues.vs2022)
- [VS Code](#Uno.UI.CommonIssues.vscode)
- [Rider](#Uno.UI.CommonIssues.rider)
- [AI Agents](#Uno.UI.CommonIssues.AIAgents)
## Platforms
- [Common issues on WebAssembly](#Uno.UI.CommonIssues.Wasm)
- [Common issues on Skia (X11/macOS/Framebuffer/Windows)](#Uno.UI.CommonIssues.Skia)
- [Common issues on iOS](#Uno.UI.CommonIssues.Ios)
- [Common issues on Android](#Uno.UI.CommonIssues.Android)
## Build Errors
- [Troubleshooting build errors](#Uno.Development.Troubleshooting)
- [Build error codes](#Build.Solution.error-codes)
## Next Steps
Learn more about:
- You can head to [How-tos and tutorials](#Uno.Tutorials.Intro) on how to work on your Uno Platform app.
- [List of views implemented in Uno](implemented-views.md) for the set of available controls and their properties.
## Uno.UI.CommonIssues.AIAgents
# Issues related to AI Agents
## dnx is not a valid command
The getting started for Claude, Codex and Copilot CLI use the `dnx` command, which is only available on .NET 10.
If you want to use the App MCP with .NET 9 projects, you'll need to change `dnx` to `uno-devserver` and install it using `dotnet tool install -g uno.devserver`.
## The App MCP turns red in Visual Studio 2022/2026
In Visual Studio, the App MCP might turn red in some occasions. To fix this issue, click on the three dots on the right and select `Reload`.
## The uno-app MCP failed to start
The Uno Platform App MCP may fail to start in Claude/Codex/Copilot CLI when it is started in a folder that does not contain an Uno Platform project.
To fix this issue, change directories to a folder that contains the `.sln` or `.slnx` file of your project.
## Uno.UI.CommonIssues.AllIDEs
# Issues related to all development environments
## Could not resolve SDK "Uno.Sdk"
This error may happen for multiple reasons:
- Make sure to update your [Uno Platform extension](https://aka.platform.uno/vs-extension-marketplace) in VS 2022 to 5.3.x or later. Earlier versions may automatically update to an incorrect version of the Uno.SDK.
- Make sure to [re-run Uno.Check](#UnoCheck.UsingUnoCheck) to get all the latest dependencies.
- Ensure that all [NuGet feeds are authenticated properly](https://learn.microsoft.com/nuget/consume-packages/consuming-packages-authenticated-feeds). When building on the command line, some enterprise NuGet feeds may not be authenticated properly.
- Ensure that no global package mappings are interfering with nuget restore. To validate that no package mappings are set, on Windows for Visual Studio:
- Make a backup copy of `%AppData%\NuGet\NuGet.Config`
- Open a visual studio instance that does not have any solution opened
- Go to **Tools**, **Options**, **NuGet Package Manager**, then **Package Source Mappings**
- If there are entries in the list, click then click **Remove All**
- Delete the `Uno.Sdk` folder in your development environment's Nuget packages `global-packages` folder:
- Windows: `%userprofile%\.nuget\packages`
- Mac/Linux: `~/.nuget/packages`
[This folder may be overridden](https://learn.microsoft.com/en-us/nuget/consume-packages/managing-the-global-packages-and-cache-folders) using the `NUGET_PACKAGES` environment variable, the `globalPackagesFolder` or `repositoryPath` configuration settings (when using PackageReference and `packages.config`, respectively), or the `RestorePackagesPath` MSBuild property (MSBuild only). The environment variable takes precedence over the configuration setting.
Try building your project again.
## Runtime error `No parameterless constructor defined for XXXX`
This error is generally caused by some missing [IL Linker](https://github.com/dotnet/runtime/tree/main/src/tools/illink) configuration on WebAssembly. You may need to add some of your application assemblies in the LinkerConfig.xml file of your project. You can find [additional information in the documentation](#uno.articles.features.illinker).
Similar error messages using various libraries:
- `Don't know how to detect when XXX is activated/deactivated, you may need to implement IActivationForViewFetcher` (ReactiveUI)
## `Layout cycle detected` exception
Layout cycle means that the measuring of a specific part of the visual tree couldn't get stabilized. For example, during an element `Arrange` pass, its measure was invalidated, then it's measured again then arranged, and the app will fall into a layout cycle.
Uno Platform and WinUI run this loop for 250 iterations. If the loop hasn't stabilized, the app will fail with an exception with the message `Layout cycle detected`. For more information, see also [LayoutCycleTracingLevel in Microsoft Docs](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.debugsettings.layoutcycletracinglevel). Note that what Uno Platform logs may be quite different from what WinUI logs.
This error is sometimes tricky to debug. To get more information, in your `App.OnLaunched` method, you can call `DebugSettings.LayoutCycleTracingLevel = Microsoft.UI.Xaml.LayoutCycleTracingLevel.High` in order to get additional troubleshooting information printed out in the app's logs. You will also need to update your logging to `.SetMinimumLevel(LogLevel.Trace)`, as well as add `builder.AddFilter("Microsoft.UI.Xaml.UIElement", LogLevel.Trace);` if you set the log level to high and want to get stack trace information.
When the last 10 iterations out of 150 are reached, we will start logging some information as warnings. Those logs are prefixed with `[LayoutCycleTracing]` and include information such as when an element is measured or arranged, and when measure or arrange is invalidated.
One possible cause of layout cycle is incorrect usage of `LayoutUpdated` event. This event isn't really tied to a specific `FrameworkElement` and is fired whenever any element changes its layout in the visual tree. So, using this event to add or remove an element to the visual tree can lead to layout cycle. The simplest example is having XAML similar to the following
```xaml
```
and code behind:
```csharp
private void sp_LayoutUpdated(object sender, object e)
{
sp.Children.Add(new Button() { Content = "Button" });
}
```
In this case, when `LayoutUpdated` is first fired, you add a new child to the `StackPanel` which will cause visual tree root to have its measure invalidated, then `LayoutUpdated` gets fired again, causing visual tree root to have its measured invalidated again, and so on. This ends up causing a layout cycle.
## Cannot build with both Uno.WinUI and Uno.UI NuGet packages referenced
This issue generally happens when referencing an Uno.UI (using WinUI APIs) NuGet package in an application that uses Uno.WinUI (Using WinAppSDK APIs).
For instance, if your application has ` `Uno.WinUI`
## Abnormally long build times when using Roslyn analyzers
It is a good practice to use Roslyn analyzers to validate your code during compilation, but some generators may have difficulty handling the source generated by the Uno Platform (one notable example is [GCop](https://github.com/Geeksltd/GCop)). You may need to disable those for Uno projects or get an update from the analyzer's vendor.
## Build errors with .NET workloads
If you encounter errors such as: `error MSB4022: The result "" of evaluating the value "$(MonoTargetsTasksAssemblyPath)" of the "AssemblyFile" attribute in element is not valid.`, this usually indicates a problem with your .NET workloads installation. If `uno-check` does not report issues but your project still fails to build, try running:
```dotnetcli
dotnet workload repair
```
This command can repair missing or misconfigured workload components.
## Uno.UI.CommonIssues.Android
# Issues related to Android projects
## Insets not working when using WebView
There is a known issue on Android with the [Edge-to-Edge](https://developer.android.com/develop/ui/views/layout/edge-to-edge) feature, where the bottom Insets do not function correctly when using a WebView. This flaw prevents the inputs from being shifted upward, which results in the keyboard covering them.
> [!IMPORTANT]
> Edge-to-Edge is enforced on devices running Android 15 with a Target SDK of 35 or higher.
A workaround for this issue is to navigate to the `MainActivity.Android.cs` file in your Uno Platform application, override the `OnCreate` method, and call `WindowCompat.SetDecorFitsSystemWindows()`, setting the second parameter, decorFitsSystemWindows, to true.
Your code should be structured as follows:
```csharp
public class MainActivity : Microsoft.UI.Xaml.ApplicationActivity
{
protected override void OnCreate(Bundle bundle)
{
base.OnCreate(bundle);
WindowCompat.SetDecorFitsSystemWindows(Window, true);
}
}
```
Learn more about this issue [on Google's issues tracker](https://issuetracker.google.com/issues/311256305?pli=1) website.
> [!IMPORTANT]
> Using the workaround mentioned above will deactivate some benefits of the Edge-To-Edge feature. For instance, your top navigation bar will no longer be "invisible," which removes the immersive appearance associated with edge-to-edge design.
## ADB0020 - The package does not support the CPU architecture of this device
This error may occur when deploying an application to a physical device with ARM architecture. To resolve this issue, you will need to add the following to your csproj anywhere inside the `` tag:
```xml
android-arm;android-arm64;android-x86;android-x64
```
## Deploying an Android app takes a long time
Android deployment requires a few considerations:
- Android physical device
- Make sure to have a good cable (USB 3 or C) to have a good connection
- Avoid debugging through wifi
- Android Emulators
- Use an Android x86_64 emulator. If not, [create a new one](https://learn.microsoft.com/dotnet/maui/android/emulator/device-manager).
- Ensure that you have either Hyper-V or AEHD enabled. (See [Microsoft's documentation](https://learn.microsoft.com/dotnet/maui/android/emulator/hardware-acceleration))
- Try disabling `Fast Deployment` in your app configuration
1. Open your project properties
1. In the Android section, search for `Fast Deployment`
1. Uncheck all target platforms
- Try setting `false` in the debug configuration of your `.csproj`.
## Android Warning XA4218
When building for Android, the following messages may happen:
```text
obj\Debug\net8.0-android\android\AndroidManifest.xml : warning XA4218: Unable to find //manifest/application/uses-library at path: C:\Program Files (x86)\Android\android-sdk\platforms\android-34\optional\androidx.window.extensions.jar
obj\Debug\net8.0-android\android\AndroidManifest.xml : warning XA4218: Unable to find //manifest/application/uses-library at path: C:\Program Files (x86)\Android\android-sdk\platforms\android-34\optional\androidx.window.sidecar.jar
```
Those messages are from a [known .NET for Android issue](https://github.com/xamarin/xamarin-android/issues/6809) and can be ignored as they are not impacting the build output.
## Additional troubleshooting
You can get additional build [troubleshooting information here](#Uno.Development.Troubleshooting).
## Uno.UI.CommonIssues.Ios
# Issues related to iOS projects
## Developing on older Mac hardware
The latest macOS release and Xcode version are required to develop with Uno Platform for iOS. However, if you have an older Mac that does not support the latest macOS release, you can use a third-party tool to upgrade it, such as [OpenCore Legacy Patcher](https://dortania.github.io/OpenCore-Legacy-Patcher/). While not ideal, this can extend the use of older hardware by installing the latest macOS release on it. Please note that this method is not required when developing for other targets such as Android, Skia, WebAssembly, or Windows.
## `Don't know how to marshal a return value of type 'System.IntPtr'`
[This issue](https://github.com/unoplatform/uno/issues/9430) may happen for Uno.UI 4.4.20 and later, when deploying an application using the iOS Simulator, when the application contains a `TextBox`.
In order to fix this, add the following to your `.csproj`:
```xml
$(MtouchExtraArgs) --registrar=static
```
## Error while retrieving iOS device in VS code
When switching to an iOS debugging target in VS Code, you might encounter an error stating that the iOS device could not be retrieved. The error message may appear as follows:
```error
[Info]: Project reload forced to switch to net8.0-ios | Debug
[Error] Could not retrieve ios devices within 10 seconds. Aborting...
```
To resolve this issue, download [Xcodes](https://www.xcodes.app). Inside Xcodes.app, select the correct version of Xcode and click the **Make Active** button to make it the default Xcode for your Mac. After completing this step, you can speed up the process and use the new default Xcode for simulators. On VS Code, open the Command Palette and select `Developer: Reload Window`. This should resolve the error when switching to an iOS debugging target in VS Code.
## Build stops with `Verification of iOS environment is running. Please try again in a moment`
When building for an iOS physical device, the following error may happen in your build `Verification of iOS environment is running. Please try again in a moment.`. If this happens and your Visual Studio is connected to your Mac, you may need to ensure that you have selected a provisioning profile.
Make sure to [configure your Apple account](https://learn.microsoft.com/en-us/dotnet/maui/ios/device-provisioning/automatic-provisioning?view=net-maui-9.0#enable-automatic-provisioning), or in some cases, selecting the development team and provisioning profile is required.
## Debugging takes a long time when connecting from a Windows machine
In case your debugging experience is slow when connecting from a Windows VS environment to a Mac machine, make sure that you're not connected through Wifi on either end. Try pinging your Mac from your Windows machine and ensure it's lower than 5ms.
## Additional troubleshooting
You can get additional build [troubleshooting information here](uno-builds-troubleshooting.md).
## Uno.UI.CommonIssues.MobileDebugging
# Android & iOS emulators: setup & troubleshooting
If Android or iOS emulators are missing or fail to start in JetBrains Rider, Visual Studio, or Visual Studio Code on macOS or Windows, use the checklists and setup paths below.
## Quick-fix checklist (do this first)
- **Start the emulator manually** once, then reopen your IDE.
- **Update tools & images** (Android Emulator, Platform-Tools, system images).
- **Use one Android SDK location** across tools; avoid cloud-synced folders.
- **Windows:** ensure virtualization is enabled (see “Windows virtualization”).
- **ADB refresh:** `adb kill-server && adb start-server`, then `adb devices`.
- **AVD reset:** Cold Boot or Wipe Data for a flaky AVD.
- **macOS/iOS:** open the iOS Simulator from Xcode once to initialize it.
- After changing SDKs, emulator images, or virtualization settings, **restart your IDE** so it refreshes its device list.
## Android emulator setup
There are several common ways to manage Android Virtual Devices (AVDs):
### Option 1 — Android Studio (works with all IDEs)
1. Install the latest Android Studio.
2. **Tools → SDK Manager → SDK Tools**: update **Android Emulator** and **Android SDK Platform-Tools**.
3. **Tools → Device Manager (AVD Manager)**: create/update an AVD with a recent system image.
4. Launch the emulator, then run your Uno Platform app from your IDE.
### Option 2 — Visual Studio
1. Install Visual Studio 2022/2026 with the **Multi-Platform App UI development with .NET** workload.
2. Open **Tools → Android → Android Device Manager**.
3. Create/update an AVD and start it before you deploy from your IDE.
### Option 3 — JetBrains Rider
1. Install **Rider** and the **Android Support** plugin via **Preferences/Settings → Plugins → Marketplace**.
2. From Rider’s Device/AVD Manager, create/update an AVD (you can reuse AVDs made in Android Studio).
3. If Rider doesn’t list it immediately, start the AVD manually and restart Rider.
### Option 4 — Visual Studio Code
> VS Code doesn’t include a built-in AVD manager. It **uses AVDs created by Android Studio, Rider, or Visual Studio** and can start them via extensions or the terminal.
1. **Install/verify Android SDK & tools**
- Create AVDs in **Android Studio** (recommended) or another IDE.
- Ensure command-line tools are available in your `PATH` (e.g., `/platform-tools` and `/emulator`).
- Optional: confirm the .NET Android workload is present: `dotnet workload list` (look for `android`).
2. **Start an emulator**
- Use an extension (e.g., an “Android/iOS Emulator” helper) to start/stop AVDs from the Command Palette, **or**
- Use the terminal:
```bash
emulator -list-avds
emulator -avd
adb devices
```
3. **Make VS Code see the device**
- **Reload Window** after the emulator starts, or restart VS Code.
- If the emulator isn’t listed, verify `adb devices` shows it, then relaunch the debugger.
4. **Troubleshooting in VS Code**
- Ensure `ANDROID_SDK_ROOT` (or `ANDROID_HOME`) points to the correct SDK.
- Keep only **one** SDK location across tools to avoid a mismatch.
- If an extension can’t find the emulator, set the SDK/emulator path in its settings.
---
## Windows virtualization (required for fast Android emulation)
Enable **Windows Hypervisor Platform** (and **Hyper-V** on supported editions), then **reboot**. Avoid conflicts with other hypervisors (e.g., VirtualBox in non-Hyper-V mode).
## iOS simulator setup (macOS only)
1. Install the latest **Xcode** from the App Store and launch it once to accept the license.
2. Verify the Simulator runs: **Xcode → Window → Devices and Simulators**.
3. If your IDE can’t find the Simulator, **start it manually** or **reboot**.
4. Inspect available simulators:
```bash
xcrun simctl list devices
```
## SDK location
- Keep your **Android SDK** and **AVD** directories **outside** cloud-sync folders (OneDrive/iCloud/Dropbox) to avoid file-locking and partial syncs.
- Verify or change the SDK path in **Android Studio**:
- **macOS:** *Preferences → Appearance & Behavior → System Settings → Android SDK*
- **Windows/Linux:** *File → Settings → Appearance & Behavior → System Settings → Android SDK*
- Use a **single SDK location** across all tools (Android Studio, Rider, VS/VS Code).
- Set environment variables so CLIs and IDEs agree:
- **`ANDROID_SDK_ROOT`** (recommended) or **`ANDROID_HOME`** (legacy).
- Typical locations:
- **macOS:** `~/Library/Android/sdk`
- **Windows:** `%LOCALAPPDATA%\Android\Sdk` (or a custom `C:\Android\Sdk`)
- **Linux:** `~/Android/Sdk`
- **AVDs:** `~/.android/avd` (macOS/Linux) or `%USERPROFILE%\.android\avd` (Windows)
- After moving or changing SDKs/AVDs, **restart your IDE** so it refreshes device lists.
## Uno.UI.CommonIssues.rider
# Issues related to Rider
You can view the [list of known issues in Rider's bug tracker](https://github.com/unoplatform/uno/issues/15226).
## Uno.UI.CommonIssues.Skia
# Issues related to Skia-based projects
## System.DllNotFoundException: Gtk: libgtk-3-0.dll
When running the Skia.GTK project head, the following error may happen:
```console
Unhandled exception. System.TypeInitializationException: The type initializer for 'Gtk.Application' threw an exception.
---> System.DllNotFoundException: Gtk: libgtk-3-0.dll, libgtk-3.so.0, libgtk-3.0.dylib, gtk-3.dll
```
## Linux
## [**Ubuntu 20.04/22.04**](#tab/ubuntu2004)
- Install the required dependencies:
```bash
sudo apt update
sudo apt install mesa-utils libgl1-mesa-glx ttf-mscorefonts-installer dbus libfontconfig1 libxrandr2 libxi-dev
```
## [**ArchLinux 5.8.14 or later / Manjaro**](#tab/archlinux2004)
- Update system and packages
```bash
pacman -Syu
```
- Install the necessary dependencies
```bash
sudo pacman -S dotnet-targeting-pack dotnet-sdk dotnet-host dotnet-runtime python ninja gn aspnet-runtime dbus libxrandr libxi
```
---
You may also need to [install the Microsoft fonts](https://wiki.archlinux.org/title/Microsoft_fonts) manually.
If you are using Windows Subsystem for Linux (WSL), you can find specific instructions in the following video:
> [!Video https://www.youtube-nocookie.com/embed/GGszH8PDf-w]
## Additional troubleshooting
You can get additional build [troubleshooting information here](uno-builds-troubleshooting.md).
## Uno.UI.CommonIssues.vs2022
# Issues related to Visual Studio 2022/2026
## Unable to select the `MyApp (Unpackaged WinAppSDK)` profile
A [Visual Studio issue](https://developercommunity.visualstudio.com/t/WinAppSDK-Unpackaged-profile-cannot-be-s/10643735) is preventing the Unpackaged profile if iOS/Android target frameworks are present in the project. In order for the unpackaged profile to be selected, you'll need to edit the `Properties/launchSettings.json` file to remove the `MyApp (Packaged WinAppSDK)` entry. Once it is removed, select the `MyApp (Unpackaged WinAppSDK)` then start the debugging of your app.
## An iOS fails to run with `No class inheriting from a valid Application Delegate found`
When using iOS Hot Restart on Visual Studio 2022/2026, a [limitation of the environment](https://developercommunity.visualstudio.com/t/iOS-Hot-Restart-does-not-work-for-non-MA/10714660) prevents an Uno Platform app from starting properly when MAUI Embedding is referenced.
A workaround is to disable MAUI Embedding in the [`UnoFeatures` of your project](#Uno.Features.Uno.Sdk).
## App builds in Visual Studio 2022/2026 are taking a long time
Take a [look at our article](#Build.Solution.TargetFramework-override) in order to ensure that your solution is building and showing intellisense as fast as possible, and to avoid [this Visual Studio issue](https://developercommunity.visualstudio.com/t/Building-a-cross-targeted-project-with-m/651372?space=8&q=building-a-cross-targeted-project-with-many-target) (help the community by upvoting it!) where multi-targeted project libraries always build their full set of targets.
## My app is not running as fast as I want
There could be many reasons for being in this situation, but we've built a list of performance tips in [this article](#Uno.Development.Performance) that you can apply to your app. If you haven't found your answer, open a [discussion](https://github.com/unoplatform/uno/discussions) to tell us about it!
## C# Hot Reload troubleshooting
C# Hot Reload is provided by Visual Studio 2022/2026, and there may be occasions where updates are not applied, or the modified code is incorrectly reported as not compiling.
If that is the case:
- Make sure that the top left selector in the C# editor is showing the project head being debugged. For instance, if debugging with `net9.0-desktop`, select the `net9.0-desktop` project.
- Try recompiling the application completely (with the `Rebuild` command)
More troubleshooting information is available [in this section](#Uno.Features.HotReload).
## error NETSDK1148: A referenced assembly was compiled using a newer version of Microsoft.Windows.SDK.NET.dll
See [this article](features/winapp-sdk-specifics.md#adjusting-windows-sdk-references) to solve this issue.
### My application does not start under WSL
Your application may fail to run under WSL for multiple reasons:
- Your app is in a path that contains spaces and/or characters such as `[` or `]`
- [WSLg](#Uno.GetStarted.vs2022) has not been installed
- [X11 dependencies](#Uno.GetStarted.vs2022) have not been installed
### New Projects in Existing Solutions
Creating a new Uno Platform project inside an existing solution that wasn’t originally created with “Place solution and project in the same directory” is not supported by the `unoapp` templates. You can work around this by following the guide: [Adding Platforms to an Existing Project](#Uno.Guides.AddAdditionalPlatforms).
## Legacy issues
### The XAML editor shows `The type 'page' does not support direct content` message
This issue has been fixed in Visual Studio 17.8 and later.
If you're using an earlier version, XAML Intellisense [is not working properly](https://developercommunity.visualstudio.com/content/problem/587980/xaml-intellisense-does-not-use-contentpropertyattr.html) in Visual Studio when the active target framework is not the WinAppSDK one.
To work around this issue, close all XAML editors, open a C# file and select the '[MyApp].Windows' in the top-left drop-down list of the text editor sector. Once selected, re-open the XAML file.
### `InitializeComponent` or `x:Name` variable is not available in code-behind
This issue has been fixed in Visual Studio 17.8 and later.
If you're using an earlier version, Visual Studio [does not refresh the intellisense cache](https://developercommunity.visualstudio.com/content/problem/588021/the-compile-itemgroup-intellisense-cache-is-not-re.html) properly, causing variables to be incorrectly defined.
To fix this issue, build your project once, close the solution and reopen it.
It is also important to note that Uno Platform uses a multi-project structure, for which each project has to be build individually for errors to disappear from the **Error List** window (notice the **Project** column values).
In order to clear the **Error List** window, build the whole solution completely once. Thereafter, build a specific project and prefer the use of the **Output** tool window (in the menu **View** -> **Output**), taking build messages by order of appearance.
### Event handler cannot be added automatically
Event handlers [cannot be automatically](https://github.com/unoplatform/uno/issues/1348#issuecomment-520300471) added using the XAML editor.
A workaround is to use the [`x:Bind` to events feature](features/windows-ui-xaml-xbind.md#examples). This feature allows to use a simpler syntax like `` and declare a simple method `private void MyClick() { }` in the code-behind.
### WebAssembly: Hot Reload fails to start with Mixed Content: The page at XXX was loaded over HTTPS, but attempted to connect to the insecure WebSocket endpoint
This issue is caused by visual studio enforcing https connections for local content. You can work around this by either:
- Removing the https endpoint in the `Properties/launchSettings.json` file
- Unchecking the `Use SSL` option in the project's Debug launch profiles
- Selecting the project name instead of IISExpress in the toolbar debug icon drop down list
### Error MSB3030: Could not copy the file "MyProject.Shared\MainPage.xbf" because it was not found
This issue is present in Visual Studio 17.2 and 17.3, and can be addressed by [taking a look at this issue](https://github.com/unoplatform/uno/discussions/5007#discussioncomment-2583741).
## Uno.UI.CommonIssues.vscode
# Issues related to VS Code
## Known limitations for VS Code support
- C# Debugging is not supported when running in a remote Linux Container, Codespaces.
- Calls to `InitializeComponent()` may show intellisense errors until the Windows head has been built once.
## Troubleshooting Uno Platform VS Code issues
For assistance configuring or running Android or iOS emulators, see the [Android & iOS emulator troubleshooting guide](#Uno.UI.CommonIssues.MobileDebugging).
If you're not sure whether your environment is correctly configured for Uno Platform development, running the [`uno-check` command-line tool](external/uno.check/doc/using-uno-check.md) should be your first step.
The Uno Platform extension provides multiple output windows to troubleshoot its activities:
- **Uno Platform**, which indicates general messages about the extension
- **Uno Platform - Debugger**, which provides activity messages about the debugger feature
- **Uno Platform - Hot Reload**, which provides activity messages about the Hot Reload feature
- **Uno Platform - XAML**, which provides activity messages about the XAML Code Completion feature
They are also accessible using the status bar Uno logo: hover your mouse pointer over the logo, and the extension status will be shown along with links to the related outputs.
If the extension is not behaving properly, try using the `Developer: Reload Window` (or `Ctrl+R`) command in the palette.
## Reporting issues
You can report issues directly from VS Code by either:
- using the Uno logo status bar (see screenshot above); or
- pressing `F1` and selecting `Uno Platform: Report Issue...`
The form is already pre-filled with some useful information to help diagnose issues.
Follow the comments to complete the report.
## Uno.UI.CommonIssues.Wasm
# Issues related to WebAssembly projects
## WebAssembly: DllImport unable to load library 'libSkiaSharp'
If you're getting the following message in the browser debugger:
```text
[MONO] DllImport unable to load library 'libSkiaSharp'.
```
Here are a few ways to fix this:
- Make sure that you've run [`uno-check`](#UnoCheck.UsingUnoCheck) and that the `dotnet workload list` shows the `wasm-tools` workload. If you're using Visual Studio, make sure to restart it if you've installed workloads.
- If you've run `dotnet publish`, make sure to use the `bin\Release\netX.0-browserwasm\publish\wwwroot` folder to serve your app. Make sure to visit [our publishing docs](#uno.publishing.overview) for more information.
## Mixed Content, this request has been blocked
When running a webassembly app under WebAssembly with HTTPS the following error may happen:
```text
Mixed Content: The page at 'https://localhost:5002' was loaded over HTTPS, but attempted to
connect to the insecure WebSocket endpoint 'ws://XXXX:59867/rc'. This request has been blocked;
this endpoint must be available over WSS.
```
In order to fix this issue, you may need to apply the [HTTPS fixes](#Uno.Guides.UsingTheServerProject) mentioned in the server project documentation.
## WebAssembly: Access to fetch at 'https://XXXX' from origin 'http://XXXX' has been blocked by CORS policy
This is a security restriction from the JavaScript `fetch` API, where the endpoint you're calling needs to provide [CORS headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) to work properly.
If you control the API, you'll need to use the features from your framework to enable CORS, and if you don't you'll need to ask the maintainers of the endpoint to enable CORS.
To test if CORS is really the issue, you can use [CORS Anywhere](https://cors-anywhere.herokuapp.com/) to proxy the queries.
### Build error `Failed to generate AOT layout`
When building for WebAssembly with AOT mode enabled, the following error may appear:
```console
Failed to generate AOT layout (More details are available in diagnostics mode or using the MSBuild /bl switch)
```
To troubleshoot this error, you can change the text output log level:
- Go to **Tools**, **Options**, **Projects and Solution**, then **Build and Run**
- Set **MSBuild project build output verbosity** to **Normal** or **Detailed**
- Build your project again and take a look at the additional output next to the `Failed to generate AOT layout` error
You can get additional build [troubleshooting information here](uno-builds-troubleshooting.md).
## Uno.Development.Composition
# Composition API
Composition Visuals make up the visual tree structure which all other features of the composition API use and build on.
The API allows developers to define and create one or many visual objects each representing a single node in a visual tree.
To get more info, you can refer to [Microsoft's documentation](https://learn.microsoft.com/windows/uwp/composition/composition-visual-tree).
Uno Platform currently supports a small number of the APIs in the [`Windows.UI.Composition` namespace](https://learn.microsoft.com/uwp/api/windows.ui.composition?view=winrt).
The rest of this article details Uno-specific considerations regarding Composition API.
**On Android, most composition features are functional only for Android 10 (API 29) and above.**
## Compositor Thread [Android]
On Android, the composition refers to the [`Draw`](https://developer.android.com/reference/android/view/View#draw(android.graphics.Canvas)) and [`OnDraw`](https://developer.android.com/reference/android/view/View#onDraw(android.graphics.Canvas)) methods.
To get more info about custom drawing on Android, you can refer to the [Android's documentation](https://developer.android.com/training/custom-views/custom-drawing).
By default, those methods are invoked on the UI Thread.
With Uno, you can request to run those methods on a dedicated thread by setting in your Android application's constructor:
```csharp
Uno.CompositionConfiguration.Configuration = Uno.CompositionConfiguration.Options.Enabled;
```
This thread will also be used for [independent animations](https://learn.microsoft.com/windows/uwp/design/motion/storyboarded-animations#dependent-and-independent-animations).
**When overriding the `[On]Draw` methods, it is very important not to access any state that can be edited from the UI Thread, including any `DependencyProperty`.**
**Instead, you should capture the state of your control into a `RenderNode` during the `ArrangeOverride` and render it on the provided `Canvas`.**
_There are a few known issues associated with the used of the compositor thread, [make sure to read the section below](#known-issues)._
## Brush Anti-aliasing [Skia Backends]
On Skia Desktop targets (X11, Framebuffer, macOS, and Windows), anti-aliasing is disabled by default for brushes, You can request it to be anti-aliased by setting this in your application's constructor:
```csharp
#if HAS_UNO
Uno.CompositionConfiguration.Configuration |= Uno.CompositionConfiguration.Options.UseBrushAntialiasing;
#endif
```
Or alternatively, if you want to enable all available Composition capabilities:
```csharp
#if HAS_UNO
Uno.CompositionConfiguration.Configuration = Uno.CompositionConfiguration.Options.Enabled;
#endif
```
## Implemented APIs [Skia Backends]
### Windows.UI.Composition
- [CompositionAnimation](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositionanimation)
- [CompositionBackdropBrush](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositionbackdropbrush)
- [CompositionBrush](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositionbrush)
- [CompositionCapabilities](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositioncapabilities)
- [CompositionClip](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositionclip)
- [CompositionColorBrush](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositioncolorbrush)
- [CompositionEffectBrush](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositioneffectbrush)
- [CompositionEffectFactory](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositioneffectfactory)
- [CompositionEffectSourceParameter](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositioneffectsourceparameter)
- [CompositionEllipseGeometry](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositionellipsegeometry)
- [CompositionGeometricClip](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositiongeometricclip)
- [CompositionGeometry](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositiongeometry)
- [CompositionGradientBrush](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositiongradientbrush)
- [CompositionLinearGradientBrush](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositionlineargradientbrush)
- [CompositionLineGeometry](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositionlinegeometry)
- [CompositionMaskBrush](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositionmaskbrush)
- [CompositionNineGridBrush](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositionninegridbrush)
- [CompositionObject](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositionobject)
- [CompositionPath](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositionpath)
- [CompositionPathGeometry](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositionpathgeometry)
- [CompositionPropertySet](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositionpropertyset)
- [CompositionRadialGradientBrush](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositionradialgradientbrush)
- [CompositionRectangleGeometry](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositionrectanglegeometry)
- [CompositionRoundedRectangleGeometry](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositionroundedrectanglegeometry)
- [CompositionShape](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositionshape)
- [CompositionShapeCollection](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositionshapecollection)
- [CompositionSpriteShape](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositionspriteshape)
- [CompositionSurfaceBrush](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositionsurfacebrush)
- [CompositionViewBox](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositionviewbox)
- [CompositionVisualSurface](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositionvisualsurface)
- [Compositor](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositor)
- [ContainerVisual](https://learn.microsoft.com/uwp/api/windows.ui.composition.containervisual)
- [ExpressionAnimation](https://learn.microsoft.com/uwp/api/windows.ui.composition.expressionanimation)
- [InsetClip](https://learn.microsoft.com/uwp/api/windows.ui.composition.insetclip)
- [IVisualElement](https://learn.microsoft.com/uwp/api/windows.ui.composition.ivisualelement)
- [IVisualElement2](https://learn.microsoft.com/uwp/api/windows.ui.composition.ivisualelement2)
- [RectangleClip](https://learn.microsoft.com/uwp/api/windows.ui.composition.rectangleclip)
- [RedirectVisual](https://learn.microsoft.com/uwp/api/windows.ui.composition.redirectvisual)
- [ShapeVisual](https://learn.microsoft.com/uwp/api/windows.ui.composition.shapevisual)
- [SpriteVisual](https://learn.microsoft.com/uwp/api/windows.ui.composition.spritevisual)
- [Visual](https://learn.microsoft.com/uwp/api/windows.ui.composition.visual)
- [VisualCollection](https://learn.microsoft.com/uwp/api/windows.ui.composition.visualcollection)
### Windows.UI.Composition.Interactions
- [InteractionTracker](https://learn.microsoft.com/uwp/api/windows.ui.composition.interactions.interactiontracker)
- [VisualInteractionSource](https://learn.microsoft.com/uwp/api/windows.ui.composition.interactions.visualinteractionsource)
### Windows.Graphics.Effects
- [IGraphicsEffectSource](https://learn.microsoft.com/uwp/api/windows.graphics.effects.igraphicseffectsource)
### Windows.Graphics.Effects.Interop
- [IGraphicsEffectD2D1Interop](https://learn.microsoft.com/en-us/windows/win32/api/windows.graphics.effects.interop/nn-windows-graphics-effects-interop-igraphicseffectd2d1interop)
### Microsoft.Graphics.Canvas.Effects (Win2D/Composition Effects)
- [AlphaMaskEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_AlphaMaskEffect.htm)
- [ArithmeticCompositeEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_ArithmeticCompositeEffect.htm)
- [BlendEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_BlendEffect.htm)
- [BorderEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_BorderEffect.htm)
- [ColorMatrixEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_ColorMatrixEffect.htm)
- [ColorSourceEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_ColorSourceEffect.htm)
- [CompositeEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_CompositeEffect.htm)
- [ContrastEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_ContrastEffect.htm)
- [CrossFadeEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_CrossFadeEffect.htm)
- [DistantDiffuseEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_DistantDiffuseEffect.htm)
- [DistantSpecularEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_DistantSpecularEffect.htm)
- [ExposureEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_ExposureEffect.htm)
- [GammaTransferEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_GammaTransferEffect.htm)
- [GaussianBlurEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_GaussianBlurEffect.htm)
- [GrayscaleEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_GrayscaleEffect.htm)
- [HueRotationEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_HueRotationEffect.htm)
- [InvertEffectEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_InvertEffect.htm)
- [LinearTransferEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_LinearTransferEffect.htm)
- [LuminanceToAlphaEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_LuminanceToAlphaEffect.htm)
- [Matrix5x4](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_Matrix5x4.htm)
- [OpacityEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_OpacityEffect.htm)
- [PointDiffuseEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_PointDiffuseEffect.htm)
- [PointSpecularEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_PointSpecularEffect.htm)
- [SaturationEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_SaturationEffect.htm)
- [SepiaEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_SepiaEffect.htm)
- [SpotDiffuseEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_SpotDiffuseEffect.htm)
- [SpotSpecularEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_SpotSpecularEffect.htm)
- [TemperatureAndTintEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_TemperatureAndTintEffect.htm)
- [TintEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_TintEffect.htm)
- [Transform2DEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_Transform2DEffect.htm)
Note that while Uno Platform implements these effects and [their Win2D wrappers](https://github.com/unoplatform/uno/tree/master/src/Uno.UI.Composition/Win2D/Microsoft/Graphics/Canvas/Effects), the Win2D wrappers are still internal and not exposed to users, but the effects can still be used by temporary implementing the [IGraphicsEffectD2D1Interop](https://learn.microsoft.com/en-us/windows/win32/api/windows.graphics.effects.interop/nn-windows-graphics-effects-interop-igraphicseffectd2d1interop) interface manually until the Win2D wrappers become public, like for example the [GaussianBlurEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_GaussianBlurEffect.htm) can be implemented like this:
```csharp
#nullable enable
using System;
using Windows.Graphics.Effects;
using Windows.Graphics.Effects.Interop;
internal class GaussianBlurEffect : IGraphicsEffect, IGraphicsEffectSource, IGraphicsEffectD2D1Interop
{
private string _name = "GaussianBlurEffect";
private Guid _id = new Guid("1FEB6D69-2FE6-4AC9-8C58-1D7F93E7A6A5");
public string Name
{
get => _name;
set => _name = value;
}
public IGraphicsEffectSource? Source { get; set; }
public float BlurAmount { get; set; } = 3.0f;
public Guid GetEffectId() => _id;
public void GetNamedPropertyMapping(string name, out uint index, out GraphicsEffectPropertyMapping mapping)
{
switch (name)
{
case nameof(BlurAmount):
{
index = 0;
mapping = GraphicsEffectPropertyMapping.Direct;
break;
}
default:
{
index = 0xFF;
mapping = (GraphicsEffectPropertyMapping)0xFF;
break;
}
}
}
public object? GetProperty(uint index)
{
switch (index)
{
case 0:
return BlurAmount;
default:
return null;
}
}
public uint GetPropertyCount() => 1;
public IGraphicsEffectSource? GetSource(uint index) => Source;
public uint GetSourceCount() => 1;
}
```
The GUID used in the example above is the Effect CLSID of the [Direct2D Gaussian Blur Effect](https://learn.microsoft.com/windows/win32/direct2d/gaussian-blur). For a list of built-in Direct2D effects and their corresponding CLSIDs, see [Direct2D Built-in Effects](https://learn.microsoft.com/windows/win32/direct2d/built-in-effects).
## Known issues
- [Android] When using the compositor thread, the native ripple effect of Android (used in native buttons) does not work.
- [Skia Backends] Some Composition effects don't render properly (or at all) on software rendering (CPU), to check if Uno is running on the software rendering (CPU) or the hardware rendering (GPU), you can call `CompositionCapabilities.GetForCurrentView().AreEffectsFast()`.
## Uno.Overview.Philosophy
# Philosophy of Uno Platform
This document outlines the philosophy of Uno Platform. It guides the development of past and future major architectural decisions.
## Leverage existing tools
We stand on the shoulders of giants, Microsoft's tooling is a treat to work with:
- [Edit and Continue](https://learn.microsoft.com/visualstudio/debugger/edit-and-continue)
- [Live Visual Tree](https://learn.microsoft.com/visualstudio/debugger/inspect-xaml-properties-while-debugging)
- [XAML Hot Reload](https://learn.microsoft.com/visualstudio/debugger/xaml-hot-reload?view=vs-2019)
The promise of the Uno Platform is to enable building your app with those tools and then deploying it to WebAssembly, iOS, Android, macOS, and Linux.
## Create pixel-perfect, rich, and responsive UIs
Developers shouldn't sacrifice application looks for personal productivity. You can have both. Strong support for animations, templating, and custom visual effects is a must. When phones come in all sizes and manufacturers are [gouging holes out of the screen area](https://www.cnet.com/pictures/phones-with-notches/), your application's layout better be responsive and pixel-perfect or today's users, be it in corporate or private setting will not use it.
## Let views do views
Separation of model, view, and presentation keeps your code loosely coupled and easy to maintain. Features like data binding and attached properties let you write clean, elegant MVVM-style code.
## Native inter-compatibility (leave an escape hatch)
100% code reuse is the ideal, but it must also be easy to access functionality specific to a single platform in case it is a must. Also, a platform must make it easy to incorporate native third-party libraries. Uno Platform is architected to make this possible.
## Performance is a feature
The slow antelope gets eaten, and the slow app gets 1-star ratings. We've done a lot of optimization on the basis of profiling in real-world use cases, and we'll continue to do so.
## Uno.Overview.WhyUno
# Why use Uno Platform for your project?
Thank you for considering Uno Platform for your next project. While we always recommend trying out any stack before deciding on your next project, here are some tips you can use for your in-depth evaluation.
## It's a platform, not just a UI framework
Uno Platform is a developer productivity **platform** and much **more than a UI framework**, for building single codebase, native, mobile, web, desktop, and embedded apps with .NET.
At the core is a cross-platform .NET UI framework, that allows apps to run everywhere with a single codebase.
However, built on top of this foundation is also a rich platform which includes libraries, extensions, and tools that accelerate the design, development, and testing of cross-platform applications.
## Hot Design - The only Visual Designer for cross-platform .NET Applications
Uno Platform offers Hot Design, industry's first and only runtime Visual Designer for cross-platform .NET Applications. It transforms your running app into a Designer from any IDE on any OS. This offers unprecedented productivity gains. Learn more about [Hot Design](https://platform.uno/hot-design/)
## True Single Project across Mobile, Web, Desktop, and Embedded
Our Single Project approach is .NET ecosystem’s first and only true Single Project solution, empowering developers with a unified approach, spanning mobile, web, desktop, and embedded apps. This genuine Single Project approach simplifies development, accelerates build times, and facilitates platform-specific development, enhancing your productivity and efficiency.
## It's Free and Open-Source
Uno Platform is free and open source under Apache 2.0.
It is well funded and has a [sustainability model](https://platform.uno/blog/sustaining-the-open-source-uno-platform/) built in so that the project is sustainable in the long term. In addition, it is fueled by support from a thriving community of users who regularly send feedback and contribute.
## A single codebase that runs everywhere natively
Uno Platform apps run as a single codebase for native mobile, web, desktop, and embedded apps, utilizing the full breadth and reach of .NET. Uno Platform ships its releases in lock step with the latest .NET releases. So, you can always benefit from the latest and greatest advancements in the .NET world.
## Keep using your favorite IDE
Need we say more? Use the IDE that works for you – Visual Studio, VS Code, Rider as well as GitHub Codespaces. Wherever you are, Uno Platform is with you.
## Work from your favorite OS
Remain on the operating system that you are on. A detailed list of target platforms for which you can develop from Windows, macOS, or Linux is available. Our docs are designed to be OS agnostic, so every tutorial step works regardless of the system you develop on.
## Use either XAML or C# Markup for your app UI
With Uno Platform, you have a choice of building polished cross-platform UI with concise declarative UI markup using a modern XAML-centric syntax or declarative-style C# Markup. Both approaches are supported right out of the box. Our C# Markup approach works with both 1st party and 3rd party controls and application-level libraries, mapping directly to the underlying object model. All thanks to real-time C# source generators doing the heavy lifting for you.
## Hot Reload that just works
Our Hot Reload offers the most comprehensive solution for fast development loop – make a change and see it live everywhere is running in real-time without recompiling. Uno Platform Hot Reload works on:
- Visual Studio and Visual Studio Code
- All target platforms
- XAML, C# Markup, and C#
- Bindings & x:Bind, Resources, Data Templates, and Styles
- 1st party or 3rd party controls
- Devices and Emulators
For more information, see [Hot Reload](#Uno.Features.HotReload).
## Stop typing markup and use Figma code generation
Design handoff is one of the biggest time traps, as design envisioned by the designer needs to be manually translated to markup. With our plugin\*, this process is automatic, and the result is well structured, performant XAML or C#.
For more information, see [Design and Build Uno Platform Applications with Figma](#Uno.Figma.Overview.GetStarted).
\*_Note this plugin is optional_
## Quickly create a project using the Templates Wizard
Our [Uno Platform Template Wizard](https://platform.uno/blog/the-new-uno-platform-solution-template-wizard/) and its [live version](https://new.platform.uno/) allow you to get to a working project quickly. You can select your preferred version of .NET, choose the target platforms you want to develop for, pick a design system that suits your app the best, pick from the MVVM or MVUX architectural pattern, and throw in any mix of the rich set of Uno Extensions as starting building blocks. Additionally, you can include support for PWA, first-party API server, UI tests, and even generate initial build scripts for GitHub Actions or Azure DevOps, alleviating the hassle of figuring out the complex, cross-platform YAML specifics.
## Your apps will be pixel-perfect across all platforms
Uno Platform allows you to control each pixel of your UI elements to match the experience you envision. This concept of lookless-controls is very similar to what is named "[headless controls](https://martinfowler.com/articles/headless-component.html)" in the React world. Each built-in and third-party control defines its fundamental logic (e.g. how it responds to interactions, handles data, or behaves once a property value is set) independently of a visual style and template. This approach means you can tailor the appearance of any control to fit a special use case, or to match your brand identity. Changes to control styling can even be performed at runtime. Uno Platform leverages this to offer multiple built-in design systems influenced by guidance from popular platforms.
Under the hood, your app can use either a Native or Skia-based approach for rendering.
The Native rendering approach uses the built-in native UI primitives on each target, for iOS, Android, and WebAssembly. These build up a native view hierarchy and draw the visuals using native OS capabilities. That way, you still get all the benefits of the native world, such as localization and accessibility, but without giving up the rich control of pixel-level details in your app experience.
The [Skia-based](#uno.features.renderer.skia) rendering approach uses a Skia-based canvas for fast and rich rendering across platforms and gets the exact same behavior across all platforms. You can also use the Composition API to get advanced rendering and animations across platforms.
All of the above remains possible without needing to replicate the same design for each target platform.
## Multiple design systems included with support for dark mode
Uno Platform controls come pre-built with the Fluent design system, so your app looks the same across all platforms. The [Uno Themes](#Uno.Themes.Overview) library is available to provide alternative styles for your controls and help with adapting them to the other design systems Material Design or Cupertino. All three design implementations take advantage of [theme resources](https://learn.microsoft.com/windows/apps/design/style/xaml-theme-resources), enabling out-of-the-box support for light and dark color modes.
## Move forward gradually with Uno Islands
We recognize that many developers have existing WPF applications they want to modernize, and offer such a path via [Uno Islands](#Uno.Tutorials.UnoIslands), which allows you to host modern Uno Platform content within WPF UI. This means you can start modernizing your application and bringing it cross-platform step by step, not just all at once!
The _islands_ of hosted content enable any app to take advantage of modern WinUI controls, but preserve compatibility with its existing WPF experience. For example, an app using the list-details pattern can keep its robust, WPF-built details view while upgrading the list control to a WinUI `ListView`. Support for DataBinding between both contexts allows a seamless transition between the two.
## Native performance, never stuck
Uno Platform-built apps are **native apps**. As a developer, you can take advantage of each platform's capabilities and features while enjoying the flexibility to adapt and optimize as needed.
Uno Platform provides access to the **original APIs** provided by the target platform, both for UI and non-UI functionalities. You will be able to use the UI controls that come directly from the respective target platform's native SDK. This ensures that your app seamlessly incorporates the _familiar_ look and feel of the platform it's running on.
This versatility allows for a broader reach with compatibility across all supported platforms and devices.
Uno Platform provides "escape hatches" when needed. This means that you have the flexibility to utilize platform-specific features or optimizations when required, should that functionality not be provided by Uno Platform itself.
Uno Platform simply reuses default behaviors that come from the respective platform itself. This includes features like Input Method Editor (IME), spell checking, password manager integration, autofill, magnifier features (long press on textbox), accessibility features, voice-over, support for TTY (Teletypewriter) and native back swipe gestures.
The resulting app provides a consistent, native user experience your end-users expect.
## Breadth of UI controls – over 500 controls available
Uno Platform gives you automatic access to all controls coming from Microsoft and its 3rd party ecosystem. All controls from WinUI, Windows Community Toolkit, or open-source projects developed for WinUI 2/3 or UWP will work with Uno Platform.
## Controls from Windows Community Toolkit (WCT)
The Windows Community Toolkit (WCT) is a collection of helper functions, controls, and services designed to simplify and enhance Windows app development for developers. You can take those WCT features such as the `DataGrid` or `Expander` controls cross-platform when your project uses Uno Platform.
## More UI controls with MAUI Embedding
Uno Platform allows for embedding .NET MAUI-specific controls from all leading 3rd party vendors like Syncfusion, Grial Kit, Telerik, DevExpress, Esri, Grape City, and the .NET MAUI Community Toolkit. Keep in mind that this cross-platform approach works only for target platforms .NET MAUI reaches – iOS, Android, macOS, and Windows. [We have 6 sample apps](#Uno.Extensions.Maui.Overview) showing how to work with MAUI embedding by all leading 3rd party vendors.
> [!NOTE]
> Uno Platform is not built on top of .NET MAUI.
## Uno Toolkit
In addition to hundreds of UI controls available from 3rd party UI vendors as described above, we offer our own set of [higher-level UI Controls](https://platform.uno/uno-toolkit/) designed specifically for multi-platform, responsive applications.
## Consistent shadow effect everywhere
Displaying consistent shadows in cross-platform apps was always a problem. We are confident that we have solved it! Our [ShadowContainer control](#Toolkit.Controls.ShadowContainer) will allow you to easily display highly customizable inner and outer shadows in your apps. And if you fancy [neumorphism](#Toolkit.Controls.ShadowContainer) depth effects, we have control styles for that too!
## Maps
Uno Platform offers charting components via integration with [Maps UI](https://github.com/Mapsui/Mapsui) (Open Source) on all targets.
Also, for targeting just mobile, you can use [Esri ArcGIS Maps SDK for .NET](#Uno.Extensions.Maui.ThirdParty.EsriMaps) via our .NET MAUI embedding feature.
In addition, we are looking into integrating the new WinUI [MapControl](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.mapcontrol?view=windows-app-sdk-1.5) into our core offering.
## Charts
Uno Platform offers charting components via integration with [Live Charts](https://livecharts.dev/) (Open Source) and OxyPlot on all targets.
## DataGrid
Uno Platform offers DataGrid control via our support for Windows Community Toolkit (WCT). You can see the DataGrid implemented by going to [nuget.info](https://nuget.info/), which is the web implementation of the popular NuGet Package Explorer. Furthermore, you can see an implementation of it at [Uno Gallery](https://gallery.platform.uno/), then navigating to "Windows Community Toolkit" tab. Do note that you have options to [performance-tune your Uno Platform web apps](https://platform.uno/blog/optimizing-uno-platform-webassembly-applications-for-peak-performance/).
We will support Windows Community Toolkit [DataTable](https://github.com/CommunityToolkit/Labs-Windows/discussions/415) once it reaches RTM.
## Non-UI APIs
It is a common misconception that Uno Platform is just a UI framework. Nothing could be further from the truth, however! Uno Platform comes with [many non-UI APIs built in](#Uno.Features.Accelerometer) – ranging from various ways to retrieve device-related information, through access to user and application preferences, all the way to a range of sensors including GPS, compass, or even Accelerometer! All these APIs are fully cross-platform, so you just write once and run everywhere. For those who have a musical instrument, we even have MIDI!
How's _that_ for music to your ears?
## Our set of extensions for common app needs
[Uno.Extensions](https://platform.uno/uno-extensions/) is built on top of **Microsoft.Extensions** to setup and create a host for your application. The host allows access to a multitude of services for many app features including Configuration, Logging, Serialization, and HTTP. You can even register your own custom services using the same pattern.
## Navigation
As part of Uno.Extensions, Navigation provides a consistent abstraction for navigating within an application. Whether it is navigating to a new page, switching tabs, or opening a dialog, navigation can be initiated from code-behind, XAML, or from within a ViewModel.
## Authentication
Uno.Extensions Authentication is a provider-based authentication service that can be used to authenticate users of an application. It has built-in support for Microsoft Entra ID (formerly Azure AD), OpenIDConnect, Web, and Custom.
## Skia drawing
The Uno Platform provides access to SkiaSharp as a render canvas for your app, enabling rich support for fine-grained drawing primitives. Uno Platform also uses SkiaSharp to render the UI for X11, FrameBuffer, macOS, and Windows 7+ apps. Starting from Uno Platform 6.0, Skia rendering is also available for iOS, Android, and WebAssembly.
## Animations: Beyond storyboards, access to Lottie and Rive
Based on SkiaSharp support, Uno Platform provides AnimatedVisualPlayer to give the ability to render rich [Lottie files](https://airbnb.io/lottie/#/) directly in your app, for all target platforms.
## Performance and app size with AOT/Jiterpreter
Uno Platform allows to use .NET 9+ features such as Profiled AOT (Ahead Of Time compilation) and the Jiterpreter, to get better performance for your apps and balanced size. Profiled AOT is a powerful feature that allows to continue using the interpreter for code that is not often used, thus keeping your app's size down.
## Comprehensive App Packaging for All Platforms
Uno Platform offers comprehensive [app packaging solutions](#uno.publishing.overview), allowing you to build, package, and deploy your applications with ease across all supported platforms. Whether you're targeting mobile app stores, desktop environments, or web hosting, our built-in packaging support streamlines your release process. The platform handles all the platform-specific packaging requirements, enabling you to focus on your application logic instead of deployment complexities.
## Accessibility included
Uno Platform comes with built-in support for accessible apps, such as font scaling and support for screen readers. Support is provided for Windows Narrator, Android TalkBack, Apple VoiceOver, and browser-specific narrators when targeting the web. In addition, Uno Platform provides programmatic access to most UI elements, enabling assistive technology products.
## Localization included
Uno Platform supports localization from the `x:Uid` feature in XAML, as well as using resource files from `ResourceManager` in plain C# code. Localization is done once for all your target platforms.
## XAML and Resources Trimming
[XAML and Resources Trimming](#Uno.Features.ResourcesTrimming) is a feature that allows for trimming the size of WebAssembly, Desktop and iOS apps down by removing XAML styles and that are not used in your app, helping to bring down the size of your application.
## Lightweight styling
Lightweight styling is a way to customize the appearance of XAML controls by overriding their default brushes, fonts, and numeric properties. Lightweight styles are changed by providing alternate resources with the same key. All Uno Material styles support the capability to be customized through resource overrides without the need to redefine the style.
Overriding resources from Uno Material can be done at the app, page, or even control level.
## Easily manage and scale image assets
[Resizetizer](#Uno.Resizetizer.GettingStarted) is a set of MSBuild tasks designed to manage an application's assets. With this package, there is no need to worry about creating and maintaining various image sizes or setting up a splash screen. Simply provide an SVG file, and the tool will handle everything else.
## Support for SVG
Today's apps run on such a wide range of displays, it is sometimes hard to make sure your icons always look crisp and sharp. To counter this, Uno Platform has a built-in support for the vector-based SVG format!
## Progressive Web Apps (PWAs)
Your Uno Platform WebAssembly app can run as a Progressive Web App. This means users can install it and run as a normal application on their device. In addition, this gives you even more customization options and additional PWA-specific APIs like badge notifications. You can install the [NuGet Package Explorer](https://nuget.info/) PWA like a local app!
## WebView across platforms
When you need to display web content within your cross-platform apps, you can use our `WebView2` control across all Uno Platform targets, at no additional cost. Not only will it easily handle rendering of both remote and in-app HTML content, but it will also allow you to implement bi-directional JavaScript communication without any hassle. We are working on an implementation for the remaining Skia targets.
## Media Player across platforms
Uno Platform provides - at no additional cost - the `MediaPlayerElement` control, which allows your app to play media files back in your app. It is supported on Linux through libVLC.
## Monaco Editor on WebAssembly
For all your in-app text and code editing needs, you can use our port of the Monaco Editor – the same one that is used by Visual Studio Code. With full support for syntax highlighting, you could even build your own WebAssembly IDE!
## Mix and match XAML controls with native components
Because Uno Platform apps are native mobile apps, you can embed any native control on a per platform basis into an Uno Platform app.
Uno Platform views inherit from the base native view defined in .NET binding or the native framework itself, you can incorporate native views into your app's visual tree. For more information, see [UnoConf 2021 - Using Native Controls in Uno Platform Apps](https://www.youtube.com/watch?v=4Cwzk8dDHs0).
Your app's powerful visual tree can also render native components through embedding in Skia targets.
## Choice of presentation framework
With Uno Platform, you get a choice of your favorite presentation framework – MVVM, Prism, or Uno Platform in-box MVUX/Reactive.
## Support for SQLite
Uno Platform supports SQLite for all platforms, including WebAssembly, to allow for your app to use offline or local caching techniques.
## Proven migration path for Xamarin.Forms
In addition to providing 3rd party control MAUI Embedding, Uno Platform is a proven modernization path for Xamarin.Forms apps. We've collated numerous [docs](https://platform.uno/xamarin.forms) to aid you in the migration. Big brands such as **TOYOTA** have already migrated some of their apps to Uno Platform.
> [!NOTE]
> Uno Platform is not built on top of .NET MAUI.
Watch TOYOTA's [video testimonial](https://youtu.be/TeA6zEq5MGk?t=1449).
## Standing on the shoulders of giants
Uno Platform was designed to be source compatible with the APIs of WinUI. This gives us the great advantage of being able to port existing code for even the most complex controls directly from Microsoft, preserving all their feature richness. And, because WinUI sources are now publicly available, everyone from the community can help!
## Developed by App Builders, for App Builders
We are first and foremost app builders who have built hundreds of applications for consumer brands via our sister company – nventive. We use our platform and tooling daily (dog fooding) and understand the pains of app development first-hand.
## Used to build countless apps for over a decade
Uno Platform started as an internal project at Nventive over 10 years ago, which we have used to develop [countless apps for top worldwide-recognized brands](https://nventive.com/en/our-work). In addition, many Fortune 500 companies use Uno Platform for their internal, line of business applications. Some of those can be found on the [Uno Platform case studies](https://platform.uno/case-studies/) page.
## Support: Community and Paid
We are well known for a friendly and welcoming community which is always willing to help. If you need support time directly from the core team, there are also paid plans available which is how we sustain Uno Platform, a process explained in the [Sustaining the Open-Source Uno Platform blog post](https://platform.uno/blog/sustaining-the-open-source-uno-platform/).
To see your free & paid support options, see our official [support page](https://platform.uno/support/).
## Workshops
Getting started is easy with our workshops that will give you all the necessary intro into cross-platform app development. And the fact that we have multiple workshops means you can pick and choose based on the time you have available and the level of difficulty! Give our [Simple Calculator](https://platform.uno/simple-calc/) or [Tube Player](https://platform.uno/tube-player/) workshop a go.
## Books/Content
XAML for UI is a mature & well documented technology – you'll always find an example suiting your needs. In addition, there are [dozens of training courses and books](https://platform.uno/blog/uno-platform-learning-resources-2023-update/) written to help you learn Uno Platform.
## Fast ship cadence
Uno Platform ships official releases 6-8 times per year, and dozens of dev builds in between. This flexibility has traditionally allowed us to ship on day-0 alongside .NET, WinUI, and Windows App SDK.
## Amazing team behind it
As Uno Platform grows, the team behind it grows as well. The product is in good hands, with a group of focused and highly motivated experts in many areas. The project thrives because of this, as new features and improvements are added daily.
## Integrates with any .NET Library
In addition to the UI components mentioned above, Uno Platform apps also integrate perfectly with your existing .NET libraries. This includes both .NET Standard 2.0 and libraries targeting .NET 6, up to the latest .NET version. Because of this, your Uno Platform app has compatibility with packages like Json.NET, LiteDB, SQLite, and SkiaSharp.
## The Community
Welcoming, tight, and helpful community on GitHub discussions and Discord, with over 300 contributors to the project. Popular with over 60,000,000 NuGet downloads of its various packages and is used among the [biggest companies](https://platform.uno/case-studies/). Our core team is always ready to help!
## Wealth of Samples
To show Uno Platform's versatility, we tinker around with technology and share with you our full-blown apps and code samples that you can learn from.
Check out: [Cross-Platform Sample Apps with XAML and C# - Uno Platform](https://platform.uno/code-samples/)
## Uno.Contributing.Artifacts
# Build artifacts
- Uno publishes a new [pre-release build to NuGet](https://www.nuget.org/packages/Uno.WinUI) after every merge to master.
## Uno.Contributing.BreakingChanges
# Guidelines for breaking changes
## Overview
Uno uses a [Package Diff tool](https://github.com/unoplatform/uno.PackageDiff) to ensure that [binary breaking changes](https://learn.microsoft.com/dotnet/standard/library-guidance/breaking-changes#binary-breaking-change) do not
go unnoticed. As [part of our continuous integration process](https://github.com/unoplatform/uno/blob/b1a6eddcad3bcca6d9756b0a57ff6cf458321048/build/Uno.UI.Build.csproj#L529), the PackageDiffTool consumes the last published non-experimental package available on nuget.org, and compares it with the current PR.
This process only diffs against previous versions of Uno, not against the WinUI assemblies, so it doesn't pick up all forms of mismatches. There are [some inconsistencies](https://github.com/unoplatform/uno/pull/1300) dating from before SyncGenerator was added. At some point it might be a good idea to extend SyncGenerator tool to try to report them all (or even automatically fix them)
Breaking changes must be marked as such when committed using the [Conventional Commits formatting](../../uno-development/git-conventional-commits.md).
## When are binary breaking changes acceptable?
### Breaking cross-platform compatibility - not ok
Changes that break compatibility with the public API surface of WinUI are generally never acceptable, because they not only break existing code but break cross-platform compatibility as well.
### Restoring cross-platform compatibility - ok, but discuss with core team
In some cases, Uno's existing API is close to WinUI, but not identical. (Hypothetical example: a property with type `DependencyObject[]` on Uno, but type `IList` on WinUI.) This is mostly the case for older code that was written before the use of [generated `NotImplemented` stubs](../../uno-development/uno-internals-overview.md#generated-notimplemented-stubs) and the `PackageDiff` tool, which act in combination to prevent these kinds of errors when implementing new features.
In these cases, we do want to align Uno with WinUI, even at the expense of a breaking change. However, we tend to be more careful with when we merge these changes, compared to other bugfixes. We prefer to 'batch' many such breaking changes into a single stable release cycle, rather than wear out consumers' patience with a steady trickle of breaking changes each release.
The best way to proceed is to create an issue if one doesn't exist already, and open a discussion with the core team about the change in question, so we can jointly work out how best to manage it.
Note that some cases may be sufficiently benign that the breaking change is acceptable in a normal release cycle. (For example, removing a public constructor for an obscure `EventArgs` subclass that would presumably never be created from user code anyway.)
### Breaking changes to Uno-only APIs - it depends
The diff tool guards against all changes to Uno's public API surface, including functionality that has no equivalent in WinUI's API surface.
In the cases where these Uno-only APIs are exposed intentionally (example: the [`VisibleBoundsPadding` behavior](../../features/VisibleBoundsPadding.md)), we would usually reject breaking changes, unless there were a very compelling reason for them.
In other cases, this might be functionality that's inadvertently exposed - in other words, functionality that was made public when it should really have been internal. Here the validity of the breaking change should be considered on a case-by-case basis, taking into account the risk of breaking existing Uno app code (and conversely, the possibility for the Uno-only APIs to collide with 'brownfield' WinUI code). Again, the principle of 'batching' breaking changes applies.
## Adding breaking changes to the allow list
Where a breaking change is acceptable according to the above criteria, and after discussion with the core team where appropriate, it can be marked as such using the [build/PackageDiffIgnore.xml](https://github.com/unoplatform/uno/blob/master/build/PackageDiffIgnore.xml) file.
Please refer to the documentation of the [Uno.PackageDiff tool](https://github.com/unoplatform/uno.PackageDiff) for more information.
## Example report
Below is a comparison report for Uno.UI **1.45.0** with Uno.UI **1.46.0-PullRequest1300.2330** as part of [this pull-request](https://github.com/unoplatform/uno/pull/1300).
You can find the report within the `NuGetPackages.zip` archive on the build server and attached to the pull-request job. The report uses this convention: `ApiDiff.1.46.0-PullRequest1300.2330.md`
Key things to pay attention to:
- the report is for each TFM and the assemblies for that TFM.
- breaking changes which have been blessed have been ~~struck out~~.
- `Windows.UI.Xaml.ResourceDictionary::MergedDictionaries()` is the breaking change which has not been blessed and thus the process failed the build.
```md
## MonoAndroid80 Platform
#### Uno.dll
##### 0 missing types:
##### 8 missing or changed method in existing types:
- `Windows.Phone.Devices.Notification.VibrationDevice`
* ~~``System.Void Windows.Phone.Devices.Notification.VibrationDevice..ctor()``~~
- `Windows.Devices.Sensors.Accelerometer`
* ~~``System.Void Windows.Devices.Sensors.Accelerometer..ctor()``~~
- `Windows.Devices.Sensors.AccelerometerReading`
* ~~``System.Void Windows.Devices.Sensors.AccelerometerReading..ctor()``~~
- `Windows.Devices.Sensors.AccelerometerReadingChangedEventArgs`
* ~~``System.Void Windows.Devices.Sensors.AccelerometerReadingChangedEventArgs..ctor()``~~
- `Windows.Devices.Sensors.AccelerometerShakenEventArgs`
* ~~``System.Void Windows.Devices.Sensors.AccelerometerShakenEventArgs..ctor()``~~
- `Windows.Devices.Sensors.Barometer`
* ~~``System.Void Windows.Devices.Sensors.Barometer..ctor()``~~
- `Windows.Devices.Sensors.BarometerReading`
* ~~``System.Void Windows.Devices.Sensors.BarometerReading..ctor()``~~
- `Windows.Devices.Sensors.BarometerReadingChangedEventArgs`
* ~~``System.Void Windows.Devices.Sensors.BarometerReadingChangedEventArgs..ctor()``~~
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 0 missing or changed properties in existing types:
#### Uno.Foundation.dll
##### 0 missing types:
##### 0 missing or changed method in existing types:
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 0 missing or changed properties in existing types:
#### Uno.UI.BindingHelper.Android.dll
##### 0 missing types:
##### 0 missing or changed method in existing types:
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 0 missing or changed properties in existing types:
#### Uno.UI.dll
##### 0 missing types:
##### 15 missing or changed method in existing types:
- `Windows.UI.Xaml.Controls.ComboBoxItem`
* ~~``Windows.UI.Xaml.Controls.Popup Windows.UI.Xaml.Controls.ComboBoxItem.GetPopupControl()``~~
- `Windows.UI.Xaml.Controls.ContentDialogButtonClickDeferral`
* ~~``System.Void Windows.UI.Xaml.Controls.ContentDialogButtonClickDeferral..ctor()``~~
- `Windows.UI.Xaml.Controls.ContentDialogButtonClickEventArgs`
* ~~``System.Void Windows.UI.Xaml.Controls.ContentDialogButtonClickEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.ContentDialogClosedEventArgs`
* ~~``System.Void Windows.UI.Xaml.Controls.ContentDialogClosedEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.ContentDialogClosingDeferral`
* ~~``System.Void Windows.UI.Xaml.Controls.ContentDialogClosingDeferral..ctor()``~~
- `Windows.UI.Xaml.Controls.ContentDialogClosingEventArgs`
* ~~``System.Void Windows.UI.Xaml.Controls.ContentDialogClosingEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.TextBoxBeforeTextChangingEventArgs`
* ~~``System.Void Windows.UI.Xaml.Controls.TextBoxBeforeTextChangingEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.TextBoxTextChangingEventArgs`
* ~~``System.Void Windows.UI.Xaml.Controls.TextBoxTextChangingEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.TextChangedEventArgs`
* ~~``System.Void Windows.UI.Xaml.Controls.TextChangedEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.Popup`
* ~~``Android.Views.View Windows.UI.Xaml.Controls.Popup.get_Anchor()``~~
* ~~``System.Void Windows.UI.Xaml.Controls.Popup.set_Anchor(Android.Views.View value)``~~
- `Windows.UI.Xaml.Controls.TextBoxView`
* ~~``System.Void Windows.UI.Xaml.Controls.TextBoxView..ctor()``~~
* ~~``System.String Windows.UI.Xaml.Controls.TextBoxView.get_BindableText()``~~
* ~~``System.Void Windows.UI.Xaml.Controls.TextBoxView.set_BindableText(System.String value)``~~
* ~~``System.Void Windows.UI.Xaml.Controls.TextBoxView.NotifyTextChanged()``~~
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 3 missing or changed properties in existing types:
- `Windows.UI.Xaml.ResourceDictionary`
* ``Windows.UI.Xaml.ResourceDictionary[] Windows.UI.Xaml.ResourceDictionary::MergedDictionaries()``
- `Windows.UI.Xaml.Controls.Popup`
* ~~``Android.Views.View Windows.UI.Xaml.Controls.Popup::Anchor()``~~
- `Windows.UI.Xaml.Controls.TextBoxView`
* ~~``System.String Windows.UI.Xaml.Controls.TextBoxView::BindableText()``~~
#### Uno.UI.Toolkit.dll
##### 0 missing types:
##### 0 missing or changed method in existing types:
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 0 missing or changed properties in existing types:
#### Uno.Xaml.dll
##### 0 missing types:
##### 0 missing or changed method in existing types:
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 0 missing or changed properties in existing types:
## MonoAndroid90 Platform
#### Uno.dll
##### 0 missing types:
##### 8 missing or changed method in existing types:
- `Windows.Phone.Devices.Notification.VibrationDevice`
* ~~``System.Void Windows.Phone.Devices.Notification.VibrationDevice..ctor()``~~
- `Windows.Devices.Sensors.Accelerometer`
* ~~``System.Void Windows.Devices.Sensors.Accelerometer..ctor()``~~
- `Windows.Devices.Sensors.AccelerometerReading`
* ~~``System.Void Windows.Devices.Sensors.AccelerometerReading..ctor()``~~
- `Windows.Devices.Sensors.AccelerometerReadingChangedEventArgs`
* ~~``System.Void Windows.Devices.Sensors.AccelerometerReadingChangedEventArgs..ctor()``~~
- `Windows.Devices.Sensors.AccelerometerShakenEventArgs`
* ~~``System.Void Windows.Devices.Sensors.AccelerometerShakenEventArgs..ctor()``~~
- `Windows.Devices.Sensors.Barometer`
* ~~``System.Void Windows.Devices.Sensors.Barometer..ctor()``~~
- `Windows.Devices.Sensors.BarometerReading`
* ~~``System.Void Windows.Devices.Sensors.BarometerReading..ctor()``~~
- `Windows.Devices.Sensors.BarometerReadingChangedEventArgs`
* ~~``System.Void Windows.Devices.Sensors.BarometerReadingChangedEventArgs..ctor()``~~
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 0 missing or changed properties in existing types:
#### Uno.Foundation.dll
##### 0 missing types:
##### 0 missing or changed method in existing types:
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 0 missing or changed properties in existing types:
#### Uno.UI.BindingHelper.Android.dll
##### 0 missing types:
##### 0 missing or changed method in existing types:
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 0 missing or changed properties in existing types:
#### Uno.UI.dll
##### 0 missing types:
##### 15 missing or changed method in existing types:
- `Windows.UI.Xaml.Controls.ComboBoxItem`
* ~~``Windows.UI.Xaml.Controls.Popup Windows.UI.Xaml.Controls.ComboBoxItem.GetPopupControl()``~~
- `Windows.UI.Xaml.Controls.ContentDialogButtonClickDeferral`
* ~~``System.Void Windows.UI.Xaml.Controls.ContentDialogButtonClickDeferral..ctor()``~~
- `Windows.UI.Xaml.Controls.ContentDialogButtonClickEventArgs`
* ~~``System.Void Windows.UI.Xaml.Controls.ContentDialogButtonClickEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.ContentDialogClosedEventArgs`
* ~~``System.Void Windows.UI.Xaml.Controls.ContentDialogClosedEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.ContentDialogClosingDeferral`
* ~~``System.Void Windows.UI.Xaml.Controls.ContentDialogClosingDeferral..ctor()``~~
- `Windows.UI.Xaml.Controls.ContentDialogClosingEventArgs`
* ~~``System.Void Windows.UI.Xaml.Controls.ContentDialogClosingEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.TextBoxBeforeTextChangingEventArgs`
* ~~``System.Void Windows.UI.Xaml.Controls.TextBoxBeforeTextChangingEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.TextBoxTextChangingEventArgs`
* ~~``System.Void Windows.UI.Xaml.Controls.TextBoxTextChangingEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.TextChangedEventArgs`
* ~~``System.Void Windows.UI.Xaml.Controls.TextChangedEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.Popup`
* ~~``Android.Views.View Windows.UI.Xaml.Controls.Popup.get_Anchor()``~~
* ~~``System.Void Windows.UI.Xaml.Controls.Popup.set_Anchor(Android.Views.View value)``~~
- `Windows.UI.Xaml.Controls.TextBoxView`
* ~~``System.Void Windows.UI.Xaml.Controls.TextBoxView..ctor()``~~
* ~~``System.String Windows.UI.Xaml.Controls.TextBoxView.get_BindableText()``~~
* ~~``System.Void Windows.UI.Xaml.Controls.TextBoxView.set_BindableText(System.String value)``~~
* ~~``System.Void Windows.UI.Xaml.Controls.TextBoxView.NotifyTextChanged()``~~
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 3 missing or changed properties in existing types:
- `Windows.UI.Xaml.ResourceDictionary`
* ``Windows.UI.Xaml.ResourceDictionary[] Windows.UI.Xaml.ResourceDictionary::MergedDictionaries()``
- `Windows.UI.Xaml.Controls.Popup`
* ~~``Android.Views.View Windows.UI.Xaml.Controls.Popup::Anchor()``~~
- `Windows.UI.Xaml.Controls.TextBoxView`
* ~~``System.String Windows.UI.Xaml.Controls.TextBoxView::BindableText()``~~
#### Uno.UI.Toolkit.dll
##### 0 missing types:
##### 0 missing or changed method in existing types:
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 0 missing or changed properties in existing types:
#### Uno.Xaml.dll
##### 0 missing types:
##### 0 missing or changed method in existing types:
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 0 missing or changed properties in existing types:
## netstandard2.0 Platform
#### Uno.dll
##### 0 missing types:
##### 7 missing or changed method in existing types:
- `Windows.Phone.Devices.Notification.VibrationDevice`
* ~~``System.Void Windows.Phone.Devices.Notification.VibrationDevice..ctor()``~~
- `Windows.Devices.Sensors.Accelerometer`
* ~~``System.Void Windows.Devices.Sensors.Accelerometer..ctor()``~~
- `Windows.Devices.Sensors.AccelerometerReading`
* ~~``System.Void Windows.Devices.Sensors.AccelerometerReading..ctor()``~~
- `Windows.Devices.Sensors.AccelerometerReadingChangedEventArgs`
* ~~``System.Void Windows.Devices.Sensors.AccelerometerReadingChangedEventArgs..ctor()``~~
- `Windows.Devices.Sensors.AccelerometerShakenEventArgs`
* ~~``System.Void Windows.Devices.Sensors.AccelerometerShakenEventArgs..ctor()``~~
- `Windows.Devices.Sensors.BarometerReading`
* ~~``System.Void Windows.Devices.Sensors.BarometerReading..ctor()``~~
- `Windows.Devices.Sensors.BarometerReadingChangedEventArgs`
* ~~``System.Void Windows.Devices.Sensors.BarometerReadingChangedEventArgs..ctor()``~~
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 0 missing or changed properties in existing types:
#### Uno.Foundation.dll
##### 0 missing types:
##### 0 missing or changed method in existing types:
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 0 missing or changed properties in existing types:
#### Uno.UI.dll
##### 0 missing types:
##### 9 missing or changed method in existing types:
- `Windows.UI.Xaml.Controls.ComboBoxItem`
* ~~``Windows.UI.Xaml.Controls.Popup Windows.UI.Xaml.Controls.ComboBoxItem.GetPopupControl()``~~
- `Windows.UI.Xaml.Controls.ContentDialogButtonClickDeferral`
* ~~``System.Void Windows.UI.Xaml.Controls.ContentDialogButtonClickDeferral..ctor()``~~
- `Windows.UI.Xaml.Controls.ContentDialogButtonClickEventArgs`
* ~~``System.Void Windows.UI.Xaml.Controls.ContentDialogButtonClickEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.ContentDialogClosedEventArgs`
* ~~``System.Void Windows.UI.Xaml.Controls.ContentDialogClosedEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.ContentDialogClosingDeferral`
* ~~``System.Void Windows.UI.Xaml.Controls.ContentDialogClosingDeferral..ctor()``~~
- `Windows.UI.Xaml.Controls.ContentDialogClosingEventArgs`
* ~~``System.Void Windows.UI.Xaml.Controls.ContentDialogClosingEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.TextBoxBeforeTextChangingEventArgs`
* ~~``System.Void Windows.UI.Xaml.Controls.TextBoxBeforeTextChangingEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.TextBoxTextChangingEventArgs`
* ~~``System.Void Windows.UI.Xaml.Controls.TextBoxTextChangingEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.TextChangedEventArgs`
* ~~``System.Void Windows.UI.Xaml.Controls.TextChangedEventArgs..ctor()``~~
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 1 missing or changed properties in existing types:
- `Windows.UI.Xaml.ResourceDictionary`
* ``Windows.UI.Xaml.ResourceDictionary[] Windows.UI.Xaml.ResourceDictionary::MergedDictionaries()``
#### Uno.UI.Toolkit.dll
##### 0 missing types:
##### 0 missing or changed method in existing types:
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 0 missing or changed properties in existing types:
#### Uno.UI.Wasm.dll
##### 0 missing types:
##### 0 missing or changed method in existing types:
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 0 missing or changed properties in existing types:
#### Uno.Xaml.dll
##### 0 missing types:
##### 0 missing or changed method in existing types:
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 0 missing or changed properties in existing types:
## UAP Platform
#### Uno.UI.Toolkit.dll
##### 0 missing types:
##### 0 missing or changed method in existing types:
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 0 missing or changed properties in existing types:
## xamarinios10 Platform
#### Uno.dll
##### 0 missing types:
##### 8 missing or changed method in existing types:
- `Windows.Phone.Devices.Notification.VibrationDevice`
* ~~``System.Void Windows.Phone.Devices.Notification.VibrationDevice..ctor()``~~
- `Windows.Devices.Sensors.Accelerometer`
* ~~``System.Void Windows.Devices.Sensors.Accelerometer..ctor()``~~
- `Windows.Devices.Sensors.AccelerometerReading`
* ~~``System.Void Windows.Devices.Sensors.AccelerometerReading..ctor()``~~
- `Windows.Devices.Sensors.AccelerometerReadingChangedEventArgs`
* ~~``System.Void Windows.Devices.Sensors.AccelerometerReadingChangedEventArgs..ctor()``~~
- `Windows.Devices.Sensors.AccelerometerShakenEventArgs`
* ~~``System.Void Windows.Devices.Sensors.AccelerometerShakenEventArgs..ctor()``~~
- `Windows.Devices.Sensors.Barometer`
* ~~``System.Void Windows.Devices.Sensors.Barometer..ctor()``~~
- `Windows.Devices.Sensors.BarometerReading`
* ~~``System.Void Windows.Devices.Sensors.BarometerReading..ctor()``~~
- `Windows.Devices.Sensors.BarometerReadingChangedEventArgs`
* ~~``System.Void Windows.Devices.Sensors.BarometerReadingChangedEventArgs..ctor()``~~
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 0 missing or changed properties in existing types:
#### Uno.Foundation.dll
##### 0 missing types:
##### 0 missing or changed method in existing types:
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 0 missing or changed properties in existing types:
#### Uno.UI.dll
##### 0 missing types:
##### 10 missing or changed method in existing types:
- `Windows.UI.Xaml.Controls.ComboBoxItem`
* ~~``Windows.UI.Xaml.Controls.Popup Windows.UI.Xaml.Controls.ComboBoxItem.GetPopupControl()``~~
- `Windows.UI.Xaml.Controls.ContentDialogButtonClickDeferral`
* ~~``System.Void Windows.UI.Xaml.Controls.ContentDialogButtonClickDeferral..ctor()``~~
- `Windows.UI.Xaml.Controls.ContentDialogButtonClickEventArgs`
* ~~``System.Void Windows.UI.Xaml.Controls.ContentDialogButtonClickEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.ContentDialogClosedEventArgs`
* ~~``System.Void Windows.UI.Xaml.Controls.ContentDialogClosedEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.ContentDialogClosingDeferral`
* ~~``System.Void Windows.UI.Xaml.Controls.ContentDialogClosingDeferral..ctor()``~~
- `Windows.UI.Xaml.Controls.ContentDialogClosingEventArgs`
* ~~``System.Void Windows.UI.Xaml.Controls.ContentDialogClosingEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.TextBoxBeforeTextChangingEventArgs`
* ~~``System.Void Windows.UI.Xaml.Controls.TextBoxBeforeTextChangingEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.TextBoxTextChangingEventArgs`
* ~~``System.Void Windows.UI.Xaml.Controls.TextBoxTextChangingEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.TextChangedEventArgs`
* ~~``System.Void Windows.UI.Xaml.Controls.TextChangedEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.VirtualizingPanelLayout`
* ~~``System.Void Windows.UI.Xaml.Controls.VirtualizingPanelLayout.UpdateLayoutAttributesForItem(UIKit.UICollectionViewLayoutAttributes layoutAttributes)``~~
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 1 missing or changed properties in existing types:
- `Windows.UI.Xaml.ResourceDictionary`
* ``Windows.UI.Xaml.ResourceDictionary[] Windows.UI.Xaml.ResourceDictionary::MergedDictionaries()``
#### Uno.UI.Toolkit.dll
##### 0 missing types:
##### 0 missing or changed method in existing types:
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 0 missing or changed properties in existing types:
#### Uno.Xaml.dll
##### 0 missing types:
##### 0 missing or changed method in existing types:
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 0 missing or changed properties in existing types:
## xamarinmac20 Platform
#### Uno.dll
##### 0 missing types:
##### 2 missing or changed method in existing types:
- `Windows.Devices.Sensors.BarometerReading`
* ~~``System.Void Windows.Devices.Sensors.BarometerReading..ctor()``~~
- `Windows.Devices.Sensors.BarometerReadingChangedEventArgs`
* ~~``System.Void Windows.Devices.Sensors.BarometerReadingChangedEventArgs..ctor()``~~
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 0 missing or changed properties in existing types:
#### Uno.Foundation.dll
##### 0 missing types:
##### 0 missing or changed method in existing types:
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 0 missing or changed properties in existing types:
#### Uno.UI.dll
##### 0 missing types:
##### 9 missing or changed method in existing types:
- `Windows.UI.Xaml.Controls.ComboBoxItem`
* ~~``Windows.UI.Xaml.Controls.Popup Windows.UI.Xaml.Controls.ComboBoxItem.GetPopupControl()``~~
- `Windows.UI.Xaml.Controls.ContentDialogButtonClickDeferral`
* ~~``System.Void Windows.UI.Xaml.Controls.ContentDialogButtonClickDeferral..ctor()``~~
- `Windows.UI.Xaml.Controls.ContentDialogButtonClickEventArgs`
* ~~``System.Void Windows.UI.Xaml.Controls.ContentDialogButtonClickEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.ContentDialogClosedEventArgs`
* ~~``System.Void Windows.UI.Xaml.Controls.ContentDialogClosedEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.ContentDialogClosingDeferral`
* ~~``System.Void Windows.UI.Xaml.Controls.ContentDialogClosingDeferral..ctor()``~~
- `Windows.UI.Xaml.Controls.ContentDialogClosingEventArgs`
* ~~``System.Void Windows.UI.Xaml.Controls.ContentDialogClosingEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.TextBoxBeforeTextChangingEventArgs`
* ~~``System.Void Windows.UI.Xaml.Controls.TextBoxBeforeTextChangingEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.TextBoxTextChangingEventArgs`
* ~~``System.Void Windows.UI.Xaml.Controls.TextBoxTextChangingEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.TextChangedEventArgs`
* ~~``System.Void Windows.UI.Xaml.Controls.TextChangedEventArgs..ctor()``~~
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 1 missing or changed properties in existing types:
- `Windows.UI.Xaml.ResourceDictionary`
* ``Windows.UI.Xaml.ResourceDictionary[] Windows.UI.Xaml.ResourceDictionary::MergedDictionaries()``
#### Uno.Xaml.dll
##### 0 missing types:
##### 0 missing or changed method in existing types:
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 0 missing or changed properties in existing types:
```
## Uno.Contributing.CodeStyle
# Guidelines for Code style
Uno uses EditorConfig ([here's our configuration](https://github.com/unoplatform/uno/blob/master/.editorconfig)) to maintain consistent coding styles and settings in our codebase, such as indent style, tab width, end of line characters, encoding, and more. Most IDEs should respect the `EditorConfig` settings by default when applying formatting. We typically observe the [Microsoft C# Coding Conventions](https://learn.microsoft.com/dotnet/csharp/programming-guide/inside-a-program/coding-conventions) with one notable exception - Uno uses Tabs. If you install this [Visual Studio plugin](https://marketplace.visualstudio.com/items?itemName=mynkow.FormatdocumentonSave) it will automatically format your contributions upon file save.
## Refactoring
Pure refactoring for its own sake should generally be done in a separate, refactoring-only pull request, and you should generally open an issue to initiate discussion with the core team before you start such a refactoring, to determine if it's really appropriate. See [this blog post on Open Source Contribution Etiquette](https://tirania.org/blog/archive/2010/Dec-31.html) for some explanation of the reasons why. Consistently-observed conventions are essential to the long-term health of the codebase.
Within a bugfix or enhancement PR, refactoring should be restricted to the relevant files, and it should respect the conventions of existing Uno code.
## Patterns
This section describes some recurring patterns and practices you'll see in Uno code.
### Partial classes
[Partial class definitions](https://learn.microsoft.com/dotnet/csharp/programming-guide/classes-and-structs/partial-classes-and-methods) are used extensively in Uno. The two main use cases for partial classes are [platform-specific code](../../platform-specific-csharp.md) and [generated code](../../uno-development/uno-internals-overview.md#generated-notimplemented-stubs).
However, in some cases where it makes sense, partial class files are also used for logical separation of code. If you're implementing a type that owns a lot of dependency properties, consider putting these in a separate partial, to avoid cluttering up the file where the actual business logic is with DP boilerplate. Another use case for a partial is a nested class with a large definition.
### Disposables
Uno uses lightweight `IDisposables` widely for robust lifetime management. The most commonly used types for this purpose are `SerialDisposable`, `CompositeDisposable`, `CancellationDisposable`, and `DisposableAction`.
If you've used the `Reactive Extensions` framework, these names [might be familiar](https://learn.microsoft.com/previous-versions/dotnet/reactive-extensions/hh229090(v=vs.103)), and in fact these disposables behave identically to their Rx equivalents. However, they've been transplanted into [Uno](https://github.com/unoplatform/uno/tree/master/src/Uno.Foundation/Uno.Core.Extensions/Uno.Core.Extensions.Disposables/Disposables), to avoid having to take a dependency on `System.Reactive`.
### Extension methods
[Extension methods](https://learn.microsoft.com/dotnet/csharp/programming-guide/classes-and-structs/extension-methods) are used throughout the Uno Platform codebase to add reusable functionality to existing types, particularly types coming from the Xamarin bindings. Extension methods should be defined in a dedicated class, with the naming convention `[TypeName]Extensions.cs`, where `TypeName` is the name of the type either being returned or passed as the `this` parameter.
A number of extensions to the standard .NET types already exists in [Uno.Foundation](https://github.com/unoplatform/uno/tree/master/src/Uno.Foundation/Uno.Core.Extensions). So, you should check those first to see if they do what you need.
When adding a new extension method class, it should typically be marked `internal`, to avoid naming clashes with existing consumer code.
## Conventions
### Braces
```csharp
if (condition)
{
// do something
}
else
{
// use braces even for single line conditions
}
```
## Integration Tests (UI Tests)
```csharp
[ActivePlatforms(Platform.Android, Platform.Browser, Platform.iOS)]
[TestFixture]
public class LocalSettings_Tests : SampleControlUITestBase
{
[Test]
[AutoRetry]
public void ClearAddContainsRemove()
{
// Navigate to this x:Class control name
Run("UITests.Shared.Windows_Storage_ApplicationData.LocalSettings");
// Define elements that will be interacted with at the start of the test
var containerName = _app.Marked("ContainerName");
var clearButton = _app.Marked("ClearButton");
var addButton = _app.Marked("AddButton");
var containsButton = _app.Marked("ContainsButton");
var removeButton = _app.Marked("RemoveButton");
var output = _app.Marked("Output");
// Specify what user interface element to wait on before starting test execution
_app.WaitForElement(clearButton);
// Take an initial screenshot
TakeScreenshot("Initial State");
// Assert initial state
Assert.AreEqual("Local", containerName.GetDependencyPropertyValue("Text")?.ToString());
Assert.AreEqual(string.Empty, output.GetDependencyPropertyValue("Text")?.ToString());
{
_app.Tap(clearButton);
_app.WaitForDependencyPropertyValue(output, "Text", 0);
TakeScreenshot("Clear Button");
}
{
_app.Tap(addButton);
_app.WaitForDependencyPropertyValue(output, "Text", 1);
TakeScreenshot("Add Button");
}
{
_app.Tap(containsButton);
_app.WaitForDependencyPropertyValue(output, "Text", "True");
TakeScreenshot("Contains Button");
}
{
_app.Tap(removeButton);
_app.WaitForDependencyPropertyValue(output, "Text", 0);
TakeScreenshot("Remove Button");
}
}
}
```
## Uno.Contributing.CreatingTests
# Guidelines for creating tests
Good test coverage is essential to maintaining Uno stable and free of regressions. Appropriate tests are generally a requirement for bugfix and new feature PRs.
There's no 'one size fits all' strategy to testing UI. Simple in-process unit tests have the traditional advantages of speed and simplicity, but more complex out-of-process testing harnesses are necessary for simulating user interaction and verifying actual screen input. Consequently Uno internally incorporates several different types of tests. These different test strategies complement each other and work together to provide the widest possible coverage.
This guide offers an overview of the various types of tests used within Uno, and shows you how to decide which one is appropriate for testing a given behavior.
The 'TLDR' rule of thumb for adding tests is:
- if you're testing platform-independent functionality, like the dependency property system, [use Uno.UI.Tests](../../uno-development/creating-mocked-tests.md);
- if you're testing platform-dependent functionality that can be verified programmatically in-process, like checking that a control is measured and arranged properly, [use Uno.UI.RuntimeTests](../../uno-development/creating-runtime-tests.md);
- if your test needs to simulate user interaction or check that the final screen output is correct, [use SamplesApp.UITests](../../uno-development/creating-ui-tests.md).
## Types of tests
These are the main types of tests in Uno:
Test type | Location
--------------------------- | ---------------------------------------------------------------------------------
UI tests |
Unit tests |
Platform runtime unit tests |
XAML code generation tests |
UI snapshot tests |
All these tests are run on each CI build, and all tests must pass before a PR can be merged.
### UI tests
Uno's UI tests use the [Uno.UITest](https://github.com/unoplatform/Uno.UITest) testing harness, which mimics the [`Xamarin.UITest` API](https://learn.microsoft.com/appcenter/test-cloud/uitest/) and extends it to WebAssembly. These tests run out-of-process and interact with a running app (the [SamplesApp](https://github.com/unoplatform/uno/tree/master/src/SamplesApp/UITests.Shared)) to confirm that it behaves correctly on each supported platform.
UI tests can mimic the actions of a user:
- tapping buttons and other UI elements
- entering keyboard input
- scrolling, swiping, and other gestures
They can verify assertions about the state of the app:
- text labels
- any DependencyProperty value
- onscreen bounds of a view element
- comparing screenshots at different stages of the app, and asserting equality or inequality
A complete set of instructions for authoring UI tests is available in [Using the SamplesApp documentation](../../uno-development/working-with-the-samples-apps.md).
Although only a subset of the samples in the SamplesApp are covered by automated UI tests, _all_ samples are screen-shotted on every build, and a reporting tool (runs on Skia, Wasm, Android, and iOS) reports any screenshots that differ from the previous build. Currently, the build isn't gated on these checks, but this may be adjusted in the future.
> [!NOTE]
> Platform runtime tests are generally preferred to UI tests as their execution performance is generally faster than UI Tests.
### Unit tests (`Uno.UI.Tests`)
These are 'classic' unit tests which are built against a mocked version of the `Uno.UI` assembly.
These tests are ideal for testing platform-agnostic parts of the code, such as the dependency property system. They [have access to](https://github.com/unoplatform/uno/blob/b1a6eddcad3bcca6d9756b0a57ff6cf458321048/src/Uno.UI/AssemblyInfo.cs#L7) internal Uno.UI members, and the mocking layer allows values to be read or written which can't be accessed via the 'real' API.
### Platform runtime tests (`Uno.UI.RuntimeTests`)
Again these are 'classic' unit tests, but they are run 'in-process' on the actual target platform, using the 'real' Uno.UI assemblies. They can be run locally through the [Unit Tests Runner](https://github.com/unoplatform/uno/blob/master/src/SamplesApp/SamplesApp.Shared/Samples/UnitTests/UnitTestsPage.xaml) sample in the SamplesApp.
These tests are useful for testing behavior which can run synchronously, or on the UI Thread and where correctness can be asserted programmatically. Relative to the unit tests, they have the advantage that platform-dependent behavior can be tested, and also that the same test can easily be run on WinUI by compiling and running the Windows head of the SamplesApp, giving confidence that the test is verifying the correct behavior.
The platform runtime tests also have access to internal Uno.UI members if need be, but when possible they should be restricted to the public API, since this allows them to be run on WinUI as just mentioned.
### XAML code generation tests (`XamlGenerationTests`)
These specifically target [the parser](https://github.com/unoplatform/uno/tree/master/src/SourceGenerators/Uno.UI.SourceGenerators/XamlGenerator) which generates C# code from XAML files. They are 'tests' in a simple sense that if the parser throws an error, or if it generates invalid C# code, they will fail the CI build.
If you want to actually test that generated XAML produces correct behavior, which will be the case most of the time, you should use one of the other test types.
### Source generator tests
These can be used to assert that a given input to a given source generator produces specific expected diagnostics. The infrastructure for the tests easily allows to test the generator output exactly, but you should avoid that kind of assertion if you can. These tests exist in [`Uno.UI.SourceGenerators.Tests`](https://github.com/unoplatform/uno/tree/master/src/SourceGenerators/Uno.UI.SourceGenerators.Tests).
### UI snapshot tests
These are 'semi-automated' tests that takes a screenshot of each sample in the [SamplesApp](https://github.com/unoplatform/uno/tree/master/src/SamplesApp/UITests.Shared).
On Android, iOS, and Wasm, a minimal UI test is [generated](https://github.com/unoplatform/uno/blob/master/src/SamplesApp/SamplesApp.UITests.Generator/SnapShotTestGenerator.cs) which simply runs the sample (which automatically takes a screenshot of the loaded sample).
On Skia and macOS, we [loop over the samples and load them](https://github.com/unoplatform/uno/blob/b1a6eddcad3bcca6d9756b0a57ff6cf458321048/src/SamplesApp/SamplesApp.UnitTests.Shared/Controls/UITests/Presentation/SampleChooserViewModel.cs#L364-L427), then [save a screenshot](https://github.com/unoplatform/uno/blob/b1a6eddcad3bcca6d9756b0a57ff6cf458321048/src/SamplesApp/SamplesApp.UnitTests.Shared/Controls/UITests/Presentation/SampleChooserViewModel.cs#L1221-L1244) of each sample using `RenderTargetBitmap` and `BitmapEncoder`. This is generally faster than relying on UI tests.
The screenshots from each sample, as well as all screenshots generated by the main UI tests (using the `TakeScreenshot()` method), are [compared](https://github.com/unoplatform/uno/tree/master/src/Uno.UI.TestComparer) with the same sample from the most recent merged CI build.
**Failed** comparisons will not fail the build (for one thing, it's possible the differences are expected or even desired). Instead, a report is generated, with a summary added to the PR as a comment listing all samples that changed. The onus is on the PR author to manually review these changes to ensure that no regressions have been introduced.
Screenshots can be viewed by going to the CI build (from the main PR summary, press the 'Details' link for the build), opening the **Tests** tab, and opening **Attachments** for individual tests. For failed comparisons, one attachment will be a per-pixel XOR with the screenshot from the previous build, which will give some insight into why the comparison failed. Attached screenshots also contain multiple versions of the same screenshot from previous successful builds of the target branch (e.g. master or main). The file name for those screenshots contains a leading number for which the highest is from your current build.
Note: there may be 'false positives' in the comparison results due to inherently 'noisy' samples: ones with animated content, ones that show a timestamp, etc. It's possible to exclude screenshots for specific samples and/or UI tests.
### Excluding snapshots from comparison
Skip screenshot for static sample:
```csharp
namespace Uno.UI.Samples.Content.UITests.ButtonTestsControl;
[SampleControlInfo(ignoreInSnapshotTests: true)]
public sealed partial class CheckBox_Button_With_CanExecute_Changing : UserControl
{
...
}
```
Skip screenshot comparison for UI tests:
```csharp
[Test]
[AutoRetry]
public void TimePicker_Flyout()
{
Run("UITests.Shared.Windows_UI_Xaml_Controls.TimePicker.TimePicker_Flyout_Automated", skipInitialScreenshot: true);
...
TakeScreenshot("TimePicker - Flyout", ignoreInSnapshotCompare: true);
}
```
## Which type of test should I create?
The UI tests are in some sense the most powerful means of testing behavior, since they can simulate real user input and verify the state of the running app. However they're also typically more time-consuming to author, and take several orders of magnitude longer to run , which affects both your own personal development loop and also very importantly the running time of the CI build. Sometimes, a UI test is a sledgehammer where you only need... some... smaller hammer.
As a rule of thumb, if the behavior you're testing can be verified by a unit test (in `Uno.UI.Tests`) or a runtime test (in `Uno.UI.RuntimeTests`), you should write it as such.
If you're fixing a bug that can be verified by a static sample, create a SamplesApp sample that can be monitored by the snapshot comparer.
If you're fixing a bug that involves user interaction or multiple asynchronous UI operations, or you want a hard verification of the onscreen visual state, then create a UI test.
## What can't be tested?
Some UI behaviors are difficult to test in an automated fashion, such as transient animations.
Some non-UI APIs may not be testable in the emulated environment on the CI build.
If you're working on something that falls under one of these descriptions, you should add a [sample](https://github.com/unoplatform/uno/tree/master/src/SamplesApp/UITests.Shared) that covers the bug or feature you're working on, and verify that the existing samples in the same feature category aren't negatively affected by your changes. Also, you should mark such sample as a manual test. For more information about manual tests, see [Adding a manual test sample section in Using the SamplesApp documentation](../../uno-development/working-with-the-samples-apps.md#adding-a-manual-test-sample).
## Uno.Contributing.ImplementWinUIWinRTAPI
# Guidelines for implementing a new WinUI/WinRT API
Implementing a new WinUI/WinRT API generally requires:
- Finding the generated API source file (e.g. `src\Uno.UWP\Generated\3.0.0.0\Windows.Data.Pdf\PdfDocument.cs`).
- Copying the file to the non-generated location (e.g. `src\Uno.UWP\Data.Pdf\PdfDocument.cs`).
- Keeping only the members that need to be implemented in the non-generated location.
- Removing (completely or partially depending on the platforms) the implemented members in the generated file.
If your API implementation is for a specific platform:
- You can use a platform suffix in the source file name (`PdfDocument.Android.cs`) so the file is built only for this platform.
- Remove the parts that relate to your platform in the `NotImplemented` attribute:
```csharp
#if __ANDROID__ || __IOS__ || __TVOS__ || IS_UNIT_TESTS || __WASM__ || __SKIA__ || __NETSTD_REFERENCE__
[global::Uno.NotImplemented("__ANDROID__", "__IOS__", "__TVOS__", "IS_UNIT_TESTS", "__WASM__", "__SKIA__", "__NETSTD_REFERENCE__")]
public global::Windows.Data.Pdf.PdfPageDimensions Dimensions
{
#endif
```
becomes
```csharp
#if false || __IOS__ || __TVOS__ || IS_UNIT_TESTS || __WASM__ || __SKIA__ || __NETSTD_REFERENCE__
[global::Uno.NotImplemented("__IOS__", "__TVOS__", "IS_UNIT_TESTS", "__WASM__", "__SKIA__", "__NETSTD_REFERENCE__")]
public global::Windows.Data.Pdf.PdfPageDimensions Dimensions
{
#endif
```
when implemented for Android only.
When implementing a feature, try to place as much code as possible in a common source file (a non-suffixed file), so that it is reused across platforms. Make sure to follow [partial classes coding guidelines](code-style.md).
Note that the generated files may be overridden at any point, and placing custom code (aside from changing the `NotImplemented` values) will be overwritten.
## Uno.Contributing.IssueTriage
# Guidelines for issue triage
## Purpose
Speed up issue management.
The detailed list of labels can be found at .
While working on triaging issues, you may not have the privilege to assign a specific label and in that case add a comment in the issue with your findings.
Here are a few predetermined searches on issues for convenience:
* [Longest un-triaged issues](https://github.com/unoplatform/uno/issues?q=is%3Aissue+is%3Aopen+sort%3Acreated-asc) (sorted by age)
* [Newest incoming issues](https://github.com/unoplatform/uno/issues?q=is%3Aopen+is%3Aissue)
* [Busy un-triaged issues](https://github.com/unoplatform/uno/issues?q=is%3Aissue+is%3Aopen+sort%3Acomments-desc) (sorted by number of comments)
* [Issues that need more attention](https://github.com/unoplatform/uno/issues?q=is%3Aissue+is%3Aopen+sort%3Acomments-asc)
## Scope
These guidelines serves as a primary document for triaging incoming issues to Uno. Maintainers and contributors are encouraged to either use these guidelines, or use this as a starting point if necessary.
## Security
Security-related matters should be disclosed in private as per [our policy on GitHub](https://github.com/unoplatform/uno/security/policy). If a security matter is raised as an issue, please capture the relevant information, [delete the GitHub issue](https://docs.github.com/issues/tracking-your-work-with-issues/deleting-an-issue), and follow up via email. This [tool can be used to find](https://emailaddress.github.io/) (almost) any GitHub user's email address.
## Support requests
These issues should be directed to our support structures (see below) and then closed _but_ before doing so consider why the support request was raised.
Is something unclear? Do we need to improve our documentation or samples?
Community support requests should be directed to:
* Our [documentation](https://platform.uno/docs/) and [troubleshooting guide](#Uno.UI.CommonIssues).
* [GitHub Discussions](https://github.com/unoplatform/uno/discussions)
* The [Discord Server](https://platform.uno/discord)
* On [X/Twitter using the #unoplatform](https://x.com/search?q=%23unoplatform) hashtag.
Organizations that want a deeper level of support beyond community support should be directed to [contact Uno Platform](https://platform.uno/contact/) to discuss obtaining professional support.
## Validate if the issue is a bug
Confirm if the problem is a bug by reproducing it. If a test case has not been supplied, ask the reporter to supply one. You may need to contact the issue reporter in the following cases:
* Do a quick duplicate search to see if the issue has been reported already. If a duplicate is found, let the issue reporter know it by marking it duplicate. Label such issues as `triage/duplicate`.
* If you can not reproduce the issue, label it as a `triage/not-reproducible`. Contact the issue reporter with your findings and close the issue if both the parties agree that it could not be reproduced.
* If you need more information to further work on the issue, let the reporter know it by adding an issue comment followed by label `triage/needs-information`.
In all cases, if you do not get a response in 20 days, then close the issue with an appropriate comment.
## Closing issues
Issues that are identified as a support request, duplicate, not-reproducible, or lacks enough information from reporter should be closed using the following guidelines explained in this file. Also, any issues that can not be resolved because of any particular reason should be closed. These issues should have one or more of following self-readable labels:
* `triage/duplicate`: Indicates an issue is a duplicate of other open issue.
* `triage/not-reproducible`: Indicates an issue can not be reproduced as described.
* `triage/needs-information`: Indicates an issue needs more information in order to work on it.
## Help Wanted issues
We use two labels [help wanted](https://github.com/unoplatform/uno/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22+sort%3Aupdated-desc) and [good first issue](https://github.com/unoplatform/uno/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22+sort%3Aupdated-desc) to identify issues that have been specially curated for new contributors.
The `good first issue` label is a subset of `help wanted` label, indicating that members have committed to providing extra assistance for new contributors. All `good first issue` items also have the `help wanted` label.
Items marked with the `good first issue` label are intended for _first-time
contributors_. It indicates that members will keep an eye out for these pull
requests and shepherd them through our processes.
**New contributors should not be left to find an approver, ping for reviews, or identify that their build failed due to a flake.**
This makes new contributors feel welcome, valued, and assures them that they will have an extra level of help with their first contribution.
After a contributor has successfully completed 1-2 `good first issue`'s, they should be ready to move on to `help wanted` items, saving remaining `good first issue`'s for other new contributors.
These items need to ensure that they follow the guidelines for `help wanted` labels (above) in addition to meeting the following criteria:
* **No Barrier to Entry**
The task is something that a new contributor can tackle without advanced setup, or domain knowledge.
* **Solution Explained**
The recommended solution is clearly described in the issue.
* **Provides Context**
If background knowledge is required, this should be explicitly mentioned and a list of suggested readings included.
* **Gives Examples**
Link to examples of similar implementations so new contributors have a reference guide for their changes.
* **Identifies Relevant Code**
The relevant code and tests to be changed should be linked in the issue.
* **Ready to Test**
There should be existing tests that can be modified, or existing test cases fit to be copied. If the area of code doesn't have tests, before labelling the issue, add a test fixture. This prep often makes a great `help wanted` task!
## Quick Replies
When commenting on an issue or pull request, there's a [feature in GitHub](https://help.github.com/en/articles/using-saved-replies) where you can add a saved reply that you've already set up. The saved reply can be the entire comment or if you want to customize it, you can add or delete content. Below you'll find some suggestions that maintainers and contributors can use as a starting point.
### already fixed
> Thanks for reporting this!
>
> This has already been fixed in [INSERT URL OF PR HERE]. It should be available in version [VERSION NUMBER HERE].
### closing inactive
> Closing this out due to inactivity. @[NAME] if you're able to provide the requested information we're happy to revisit the issue.
### duplicate
> Thanks for taking the time to contribute!
>
> We noticed that this is a duplicate of [ISSUE URL]. Please follow that issue for further updates.
### future proposal
> Thanks for the suggestion!
>
> This idea is interesting for the future, but this is beyond the scope of our current roadmap.
>
> We will keep it open until there's more evidence. If you believe this to be incorrectly prioritized, please do let us know and we will evaluate your counter-proposal. If you want to contribute the implementation, please tell the maintainers that you are willing to send in a pull-request and we'll do everything we can to bring you up to speed with becoming a contributor.
### needs information or reproduction (Android)
> Thanks for the report!
>
> Specific things I'd like to learn about are what Android API level you are using and if you are testing in a simulator or on a device.
>
> Could you please provide a test case that reproduces the issue and provide [logs from `logcat`](https://learn.microsoft.com/xamarin/android/deploy-test/debugging/android-debug-log?tabs=windows)?
### needs template
> Thanks for reaching out!
>
> We require the template to be filled out when submitting all issues. We do this so that we can be certain we have all the information we need to address your submission efficiently. This allows the maintainers to spend more time fixing bugs, implementing enhancements, and reviewing and merging pull requests.
>
> Thanks for understanding and meeting us halfway!
### no response
> Thank you for your issue!
>
> We haven't gotten a response to our questions in our comment [insert URL here]. With only the information that is currently in the issue, we don't have enough information to take action. I'm going to close this but don't hesitate to reach out if you have or find the answers we need, we'll be happy to reopen the issue.
### not a priority
> Thanks for the suggestion @[NAME]!
>
> This would be good to have, but we may not have anyone available to work on it right now or in the immediate future.
>
> I've added the `help wanted` label to this issue and community contributions would be most welcome in the meantime. If you want to contribute the implementation, please tell the maintainers that you are willing to send in a pull-request and we'll do everything we can to bring you up to speed with becoming a contributor.
### open a new issue
> @[NAME] please open a new issue and fill out the issue template so that we're better able to help you.
### send in a pull-request
> This would be good to have and we'd love it if you or someone from the community could contribute the implementation. Please let us know if you want to send in the PR and we'll do everything we can to bring you up to speed with becoming a contributor.
## Acknowledgements
* This document was based off the [Kubernetes community sig guidelines](https://github.com/kubernetes/community/blob/e4eabb7c3c26ce4463f1ab89e0ad94a7a7671b08/contributors/guide/issue-triage.md).
## Uno.Contributing.PullRequests
# Guidelines for pull-requests
If you don't know what a pull request is, read the [About pull requests documentation from GitHub](https://docs.github.com/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests).
## Creating a PR
If you are an outside contributor, please fork the Uno Platform repository you would like to contribute to your account. See the GitHub documentation for [forking a repo](https://help.github.com/articles/fork-a-repo/) if you have any questions about this.
Make sure the repository can build and all tests pass, as well as follow the current [coding guidelines](code-style.md).
Pull requests should all be made to the **master** branch.
### Updating your branch on top of the latest of the default branch
Make sure to rebase your work on the latest default branch of the Uno repository, when working on a fork:
- Add the official uno repository to your remotes:
```bash
git remote add uno-origin https://github.com/unoplatform/uno
```
- Fetch the official repository
```bash
git fetch uno-origin
```
- Rebase your work on the default branch
```bash
git rebase uno-origin/master
```
- Then push your branch to your fork:
```bash
git push -f
```
**Commit/Pull Request Format**
All commits **must** be in the [Conventional Commits format](../../uno-development/git-conventional-commits.md), otherwise the build will fail.
We use this convention to automatically generate release notes for new releases, and means that your commit messages will appear untouched in the release notes.
Make sure that:
- You create only the least possible commits, where each commit details a specific added feature or bug fix.
- Try using the category feature as frequently as possible. (e.g. `feat(NavigationView): Updated the main panel`, or `fix(ProgressRing): Fix visibility`)
- Squash your commits, using interactive rebase:
```bash
git fetch uno-origin
git rebase uno-origin/master -i # Rebase your branch on top of the latest master, squash using fixups
git push -f
```
- If you're fixing a regression introduced by a PR that has not been released in a stable version yet, use the `reg` category. Example: `fix(reg): Fixing issue of previous PR`.
When opening a PR, you'll see the description is filled by a template. Make sure to read through the template and fill the missing parts in it.
If you haven't [added tests](creating-tests.md) appropriate to your changes, the reviewers will probably ask you to add some.
## Reviewing
Maintainers, contributors, and the community can participate in reviewing pull-requests. We require `two approvals` before the pull-request can be merged. Please apply the appropriate labels to the pull-request when reviewing. If the pull-request requires minor touch ups, consider doing them in the GitHub editor rather than asking the initiator of the pull-request to do them for you.
The history should be squashed to meaningful commits, and the branch should be rebased to a recent commit.
## Merging
Once a PR is reviewed and approved. One of the team members will merge it when it passes CI and is ready to merge.
If the branch is within the `unoplatform/uno` repository then the branch will be automatically deleted after merging by the [delete-merged-branch](https://github.com/apps/delete-merged-branch) robot.
## Uno.Contributing.UpdatingDependencies
# Guidelines for updating dependencies
We use Dependabot to notify the team of any updates to dependencies. Once a week, the robot will scan our dependencies and raise a pull-request if a new version is found. If an existing open pull-request is found for a dependency, it will be closed and replaced with a new pull-request..
## Internal dependencies
The following dependencies don't change the public API surface and are typically safe to merge and we could potentially [configure mergify to automatically merge them if CI passes](https://docs.mergify.com/workflow/automerge/):
- BenchmarkDotNet
- [FluentAssertions](https://github.com/unoplatform/uno/pull/1196)
- [NUnit3TestAdapter](https://github.com/unoplatform/uno/pull/1455)
- [NUnit.Runners](https://github.com/unoplatform/uno/pull/1122)
- [Microsoft.AppCenter](https://github.com/unoplatform/uno/pull/1175)
- [Microsoft.SourceLink.GitHub](https://github.com/unoplatform/uno/pull/1204)
- [Microsoft.NET.Test.Sdk](https://github.com/unoplatform/uno/pull/1203)
- [MSTest.TestAdapter](https://github.com/unoplatform/uno/pull/1126)
- [MSTest.TestFramework](https://github.com/unoplatform/uno/pull/1128)
- Moq
The following dependencies require manual adjustments before merging:
- [docfx.console](https://github.com/unoplatform/Uno/pull/1082/commits/c222caf8c23b35e19f6b33cd624cbfa714250bfe)
- `Microsoft.CodeAnalysis.*`. Those dependencies need to be aligned with the source generation task package, for which the dependency cannot be be explicitly provided.
- `Xamarin.GooglePlayServices.*`. Those dependencies are added per TargetFramework (Android SDK version), not updated.
## Public dependencies
Updating public dependencies will require consumers to upgrade their dependencies and as such need consideration on a case by case basis is required before merging.
## additional care required
The following dependencies require care and human testing:
- [Microsoft.CodeAnalysis.*](https://github.com/unoplatform/uno/pull/1169) children packages needs to be aligned with the other `Microsoft.CodeAnalysis` packages.
- [Microsoft.Build.*](https://github.com/unoplatform/uno/pull/1169) children packages needs to be aligned with the other `Microsoft.Build` packages.
- [Microsoft.Extensions.Logging.*](https://github.com/unoplatform/uno/pull/1108/files#r300432589) child packages needs to be aligned with the other `Microsoft.Extensions.Logging` packages. Currently can't be upgraded because most recent versions are using thread, which are not supported on Wasm.
- [Microsoft.UI.Xaml](https://github.com/unoplatform/uno/pull/1503): This dependency is needs to be aligned with the currently supported API set found in Uno.
- [Microsoft.Extensions.Logging.Console](https://github.com/unoplatform/Uno/pull/894#issuecomment-495046929): Compatibility of this dependency should be confirmed against WebAssembly.
## chatops
You can trigger Dependabot actions by commenting on the pull-request:
```text
@dependabot recreate will recreate this PR, overwriting any edits that have been made to it
@dependabot ignore this [patch|minor|major] version will close this PR and stop Dependabot creating any more for this minor/major version (unless you reopen the PR or upgrade to it yourself)
@dependabot ignore this dependency will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)
```
Please do not use any of the `rebase|merge|squash and merge` chatops commands as they bypass our merging pull-request guidelines and `ready-to-merge` workflow.
## Uno.Controls.ComboBox
# ComboBox
The `ComboBox` is designed to select a value in a set of items. For more information about its usage, see [Combo box and list box Microsoft documentation](https://learn.microsoft.com/windows/apps/design/controls/combo-box).
## Customize the placement of the Drop-Down (UNO-only feature)
By default, when opening a `ComboBox`, WinUI aligns its drop-down to keep the selected item at the same location. This means that, if the currently selected value is the last one in the list, the drop-down will appear above the `ComboBox`.
If there isn't any selected item, the drop-down will appear centered over the `ComboBox`.
On Uno, you can change this behavior using `DefaultDropDownPreferredPlacement` or `DropDownPreferredPlacement`.
### Change the default value for all the `ComboBox` in your application
The default placement for all `ComboBox` instances can be changed by setting the feature flag in the startup of your app (`App.cs` or `App.xaml.cs`):
```csharp
Uno.UI.FeatureConfiguration.ComboBox.DefaultDropDownPreferredPlacement = DropDownPlacement.Below;
```
### Change only for a specific `ComboBox`
```xml
```
## Uno.Controls.CommandBar
# CommandBar
The `CommandBar` in **Uno** is designed to be used the same way you would use the `CommandBar` on **WinUI**. In most cases, you should refer to the [official `CommandBar` documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.commandbar).
This document exists to highlight some of the differences you might encounter when working with the native mode of `CommandBar` on either **iOS** or **Android**.
## Modes
The `CommandBar` supports 2 different modes:
| Mode | Style |
|---------|--------------------------|
| Windows | `XamlDefaultCommandBar` |
| Native | `NativeDefaultCommandBar`|
### Windows
This mode replicates **WinUI**'s `CommandBar`. It is templatable and supports a template that's almost identical to **WinUI**'s default `CommandBar`.
#### Usage Example
```csharp
```
#### Remarks
- This mode hasn't been extensively tested.
- We usually avoid using this mode, and prefer to use the Native one instead.
### Native
This mode is the preferred one and is enabled by default. It uses platform-specific controls to ensure a more native user experience.
| Platform | Native control | Benefits |
|----------|---------------------|-------------------------------------------------------|
| Android | `Toolbar` | Native pressed states (ripple), native overflow menu. |
| iOS | `UINavigationBar` | Transitions when navigating between pages. |
The rest of this document will exclusively cover this mode.
#### Usage Example
```csharp
```
#### Remarks
In this mode, the `CommandBar` can't be fully customized like other templatable controls would. Additionally, you can't customize the visual states of either the `CommandBar` or its `AppBarButton`s.
### Padding
You must use `VisibleBoundsPadding.PaddingMask="Top"` on `CommandBar` to properly support the notch or punch-holes on iOS/Native and Android/Native.
On Skia-based renderers, you'll need to set the `VisibleBoundsPadding` or `SafeArea` on the parent control of the `CommandBar`.
#### Back button
An important difference with this mode is the presence of a back button. Whenever the `CommandBar` is part of a `Page` whose `Frame` has a non-empty back stack, the back button will be displayed.
On **Android**, tapping the back button triggers `SystemNavigationManager.BackRequested`. It's the responsibility of the application's navigation controller to eventually call `Frame.GoBack()`.
On **iOS**, tapping the back button automatically triggers a back navigation on the native `UINavigationController` (which is part of the native `Frame` implementation). The `Frame` will raise the `Navigated` event, and its state will automatically be updated to reflect the navigation. The navigation can't be intercepted or canceled. To intercept back navigation, you must replace the native back button with your own custom button using `NavigationCommand` (see below).
## Properties
| Property | Windows | iOS | Android | Comments |
|---------------------------------------|:-------:|:---:|:-------:|------------------------------------------------------ |
| Background | x | x | x | |
| Content | x | x | x | |
| Foreground | x | x | x | |
| Height | x | - | - | **iOS** and **Android**: Fixed and can't be changed. |
| HorizontalAlignment | x | - | x | **iOS**: Always use `HorizontalAlignment.Stretch`. |
| Opacity | x | x | x | |
| Padding | x | x | x | **iOS**, **Android** and **Skia**: Please refer to the `Padding` section. |
| PrimaryCommands | x | x | x | |
| SecondaryCommands | x | - | x | **iOS**: Not supported. |
| VerticalAlignment | x | - | x | **iOS**: Always use `VerticalAlignment.Top`. |
| Visibility | x | x | x | |
| Width | x | - | x | **iOS**: Always use `double.NaN`. |
| HorizontalContentAlignment | x | - | x | **Android**: Stretch and Left are supported. **Windows**: Set `IsDynamicOverflowEnabled="False"` for proper behavior. |
| VerticalContentAlignment | x | - | - | Only supported on Windows. **Android**: Alignment needs to be done through the content itself. |
*If it's not listed, assume it's not supported.*
### Background
Gets or sets a brush that describes the background of a control.
#### Remarks
- Only supports `SolidColorBrush`.
- Changing the opacity through `SolidColorBrush.Opacity` is supported.
### Content
Gets or sets the content of a `ContentControl`.
#### Remarks
The `Content` is processed differently whether it's of type `string` or `FrameworkElement`.
When `Content` is a `string`, it's displayed using the platform's default font family, font size, font style and text alignment. Only the foreground color can be changed, using `Foreground`.
| Platform | FontFamily | FontSize | HorizontalAlignment |
|----------|---------------|----------|---------------------|
| iOS | `San Francisco` | 17 | Center |
| Android | `Roboto` | 20 | Left |
When `Content` is a `FrameworkElement`, it's displayed within the available area:
| Platform | Available height |
|----------|:----------------:|
| iOS | 30px |
| Android | 48px |
Please note that:
- `HorizontalContentAlignment` and `VerticalContentAlignment` are ignored.
- On **iOS**, the Content is automatically centered horizontally unless `HorizontalAlignment.Stretch` is used.
### Foreground
Gets or sets a brush that describes the foreground color.
#### Remarks
- This is typically used to change the Content`'s text color.
- Only supports `SolidColorBrush`.
- Setting this property will not affect any of the `CommandBar's` `AppBarButton` tint Color. If you need to change the `AppBarButton` tint, this is possible by setting the `ShowAsMonochrome` property to true as well as setting the Foreground`SolidColorBrush`on the`BitmapIcon`.
- On`Android`, you can also enable a feature that will allow that the`SolidColorBrush`set on your `CommandBar` `Foreground` to update your`AppBarButton`s Tint. To enable this, set on your `App.xml.cs` the `FeatureConfiguration.AppBarButton.EnableBitmapIconTint` to **true**.
### PrimaryCommands
Gets the collection of primary command elements for the `CommandBar`.
#### Remarks
- Only supports `AppBarButton`. `AppBarToggleButton` and `AppBarSeparator` are not supported.
- Refer to the `AppBarButton` section for details.
### SecondaryCommands
Gets the collection of secondary command elements for the `CommandBar`.
#### Remarks
- Only supported on **Android**.
### Height
Gets or sets the suggested height of a `FrameworkElement`.
#### Remarks
The height is fixed and cannot be changed.
| Platform | Form factor | Portrait | Landscape |
|----------|-------------|:--------:|:---------:|
| iOS | Phone | 44pt | 44pt |
| iOS | Tablet | 44pt | 44pt |
| Android | Phone | 48dp | 56dp |
| Android | Tablet | 64dp | 64dp |
[Source (Android)](https://material.io/guidelines/layout/structure.html#structure-app-bar)
## Extensions
Extensions are attached properties that extend the **WinUI** APIs to provide platform-specific features.
They can be found in the `Uno.UI.Toolkit` namespace.
Extensions to extend the functionality of `CommandBar` can be found in the `CommandBarExtensions` class.
| Attached Property | Windows | iOS | Android | Comments |
|----------------------|:-------:|:---:|:-------:|----------|
| BackButtonForeground | - | x | x | |
| BackButtonIcon | - | x | x | |
| BackButtonTitle | - | x | x | |
| NavigationCommand | - | x | x | |
| Subtitle | - | - | x | |
### BackButtonForeground
Gets or sets the back button foreground for the `CommandBar`.
#### Remarks
- Only supports `SolidColorBrush`.
### BackButtonIcon
Gets or sets the back button icon for the `CommandBar`.
#### Remarks
- Only supports `BitmapIcon`.
### BackButtonTitle
Gets or sets the back button title for the `CommandBar`.
#### Remarks
Only supported on **iOS**.
On **iOS**, the back button displays the title of the previous page (which we usually set as `string` on `Content`). When the title of the previous page is too long (over 140px wide on iPhone 5) or isn't set (for example, if we set `FrameworkElement` instead of `string` on `Content`), "Back" will be displayed instead.
To explicitly provide a value to be used by the back button of the next page, use `BackButtonTitle`.
To remove the back button title from all pages (and only leave the back arrow), set `BackButtonTitle` to `""` in the default `CommandBar` style.
**WARNING:** The name of this property can be misleading, and doesn't actually let you change the title of the back button displayed on the given `CommandBar`. Read above for recommended usage.
### Elevation
Gets or sets the elevation of the `UIElement`.
#### Remarks
- This is usually only used on **Android**.
- According to [Google's Material Design Guidelines](https://material.io/guidelines/material-design/elevation-shadows.html), the recommended elevation for `CommandBar` is **8**.
### NavigationCommand
Gets or sets the navigation command for the `CommandBar`.
#### Remarks
Unlike the `PrimaryCommands` or `SecondaryCommands`, which appear to the right of the `CommandBar`, the `NavigationCommand` appears to the left of the `CommandBar`.
This is typically used for burger menus.
On **iOS**, the back gesture can be enabled or disabled using this property.
- When a `CommandBar` (visible or collapsed) is in the visual tree, the back gesture is **enabled**.
- When a `CommandBar` has a `NavigationCommand`, the back gesture is **disabled**.
On **Android**, only icons are supported (`AppBarButton.Icon`). This is due to a platform limitation, which can be explained by the fact that `CommandBar.Content` is left-aligned.
### Subtitle (**Android**)
Gets or sets the subtitle for the `CommandBar`.
#### Remarks
- The subtitle is displayed below the native title (`Content` of type `string`).
- The color of the subtitle currently can't be changed.
## Placement
On **iOS**, the same `UINavigationBar` instance is shared throughout all pages. When navigating between two pages, you can see that the `UINavigationBar` doesn't move, and only its content and the pages have a transition. To get the same effect while still letting you use `CommandBar` as you would on **WinUI** (as part of the `Page`), we have to do some magic. Namely, the `CommandBar` you define inside your `Page` is never actually rendered there, and only serves as a placeholder from which to read the information we need to pass to the shared `UINavigationBar` instance.
To ensure everything works properly, you must follow a few rules:
- The `CommandBar` must stretch horizontally and be aligned with the top of your `Page`.
- The `CommandBar` can't move (i.e., don't put it inside a `ScrollViewer`)
- The `CommandBar` must be accessible as soon as the page is being navigated to (i.e., don't put it inside a `DataTemplate` or an `AsyncValuePresenter`).
- There can only be one `CommandBar` per page.
## Extensibility
The `CommandBar` it automatically managed by the `Frame` control, however you can still use the "native" mode of the `CommandBar` with your own navigation mechanism.
On **iOS** a `CommandBarHelper` is available for this purpose, you only have to invoke each of the provided method in your own `UIViewController` implementation.
# AppBarButton
The `AppBarButton` in **Uno** is designed to be used the same way you would use the `AppBarButton` on **WinUI**. In most cases, you should refer to the [official `CommandBar` documentation](https://learn.microsoft.com/uwp/api/windows.ui.xaml.controls.appbarbutton).
When `AppBarButton` is used within a native `CommandBar`, its control template is completely ignored and can't be customized.
## Events
| Event | Windows | iOS | Android | Comments |
|---------|:-------:|:---:|:-------:|----------|
| Clicked | x | x | x | |
## Properties
| Property | Windows | iOS | Android | Comments |
|-----------------|:-------:|:---:|:-------:|--------------------------------------------|
| Command | x | x | x | |
| Content | x | x* | x* | Supports `string` and `FrameworkElement`. |
| Foreground | x | x | x* | **Android**: See details below. |
| Icon | x | x* | x* | Only supports `BitmapIcon`. |
| IsEnabled | x | x | x* | **Android**: Not supported with `Content`. |
| Label | x | x* | x* | See details below. |
| Opacity | x | x | x | |
| Visibility | x | x | x | |
*If it's not listed, assume it's not supported.*
### Foreground
Gets or sets a brush that describes the foreground color.
#### Remarks
- This changes the color of the `Content` (text) or `Icon`.
- Only supports `SolidColorBrush`.
- On **Android**, this only affects the color of `Icon`, not `Content` (text).
- On **iOS**, the default value is blue.
### Content
Gets or sets the content of a `ContentControl`.
#### Remarks
- When given a `string`, its text will be displayed instead of the icon.
- When given a `FrameworkElement`:
- it will be displayed instead of the icon
- the native pressed state and tooltip (Android only) won't work
- Make sure to set `Icon` to null, as it takes priority over `Content`.
### Icon
Gets or sets the graphic content of the app bar button.
#### Remarks
- Only supports `BitmapIcon` (with PNG).
#### Recommended icon sizes (by scale)
| Platform | 100% | 150% | 200% | 300% | 400% |
|----------|:-----:|:-----:|:-----:|:-----:|:-------:|
| iOS | 25x25 | - | 50x50 | 75x75 | - |
| Android | 24x24 | 36x36 | 48x48 | 72x72 | 96x96 |
| Windows | 32x32 | 48x48 | 64x64 | 96x96 | 128x128 |
### Label
Gets or sets the text description displayed on the app bar button.
#### Remarks
Unlike on **WinUI**, the `Label` will not be displayed below the `Icon`.
It is only displayed on **Android** when the `AppBarButton` is displayed from the overflow (when part of `SecondaryCommands`)
It is highly recommended to set and localize `Label` on all `AppBarButton`s, if only for accessibility.
### IsEnabled
Gets or sets a value indicating whether the user can interact with the control.
#### Remarks
- When set to **false**, buttons are disabled and grayed out (semi-transparent).
- You can't customize the disabled visual state of buttons.
- On **Android**, the disabled visual state only works with `Icon` and not with `Content` (text).
# Known issues
## iOS
- Can't have multiple CommandBars in the same page (e.g., Master/Details, bottom CommandBar).
- Can't change the title of the back button if the previous page doesn't have a CommandBar.
- You must define the title of the back button of the current page's CommandBar in the CommandBar of the previous page.
- Can't have a smooth transition between pages with different CommandBar backgrounds.
- Can't have a smooth transition between pages with and without a CommandBar.
- Can't change the position and size of the CommandBar (always top-aligned, horizontally-stretched, height of 44).
- Can't remove the 1px underline/shadow without making the CommandBar's background transparent.
- Can't change the height of the CommandBar.
- Can't use the back gesture on pages without a CommandBar.
- Can't disable the back gesture without using workarounds (fake back buttons).
- Can't change the Visibility of a CommandBar.
- Can't change the Opacity of a CommandBar.
- Can't superpose views over a CommandBar.
- Can't animate/translate the CommandBar (i.e., when hiding/showing it based on scroll offset).
- Can't put your CommandBar inside a ScrollViewer and make it scroll.
- Can't put your CommandBar inside templates (i.e., AVP).
- Can't cancel a back navigation using BackRequestedEventArgs.Handled.
# FAQ: CommandBar
- > Why is my content underneath the `CommandBar` for iOS and the `CommandBar` underneath the StatusBar/Notch for Android ?
You must use `VisibleBoundsPadding.PaddingMask="Top"` on `CommandBar` to properly support the notch or punch-holes on iOS and Android.
```xml
xmlns:toolkit="using:Uno.UI.Toolkit"
...
```
- > How can I remove the back button title from all pages on iOS?
```xml
xmlns:toolkit="using:Uno.UI.Toolkit"
...
```
- > How can I change the back button icon/arrow/chevron in my app?
```xml
xmlns:toolkit="using:Uno.UI.Toolkit"
...
```
- > How can I change the color of the back button?
```xml
xmlns:toolkit="using:Uno.UI.Toolkit"
...
```
- > Why does my back button display "Back" on iOS?
The back button will display "Back" if:
- The previous page doesn't have a `CommandBar`.
- The previous page's `CommandBar` doesn't have a `Content` of type `string`.
- The previous page's `CommandBar` doesn't have a `CommandBarExtensions.BackButtonTitle`.
- The previous page's `CommandBar` has a title that's too long (more than 140pt).
- > Why can't I overlap content over the CommandBar on iOS?
The `CommandBar` is not actually part of the `Page` on **iOS**, and you can't overlap content over it like you would on **WinUI** or **Android**. Please refer to the **Placement** section for details.
- > Why is my CommandBar going into the status bar on iOS/Android?
You must use `VisibleBoundsPadding.PaddingMask="Top"` on the parent control of `CommandBar` to properly support the notch or punch-holes on iOS and Android.
```xml
xmlns:toolkit="using:Uno.UI.Toolkit"
...
...
```
- > Why doesn't my CommandBar show a back button?
For a `CommandBar` to show a back button, it must first be resolved by `Frame` as soon as it navigates to a `Page`. To ensure that `CommandBar` is available as soon as the navigation starts, make sure it's directly part of a page, and not part of a `DataTemplate` or `ControlTemplate`.
- > Why don't my AppBarButton visual states work?
You can't customize the `ControlTemplate` of `AppBarButton` when using `CommandBar` in native mode.
- > How can I change the foreground of the CommandBarExtensions.Subtitle on Android?
You can't currently customize the foreground of the `CommandBarExtensions.Subtitle` on **Android**.
- > Why doesn't CommandBarExtensions.Subtitle work on iOS?
`CommandBarExtensions.Subtitle` is not currently implemented on iOS.
You can replicate the same effect by setting a custom `Content` on `CommandBar`:
```xml
```
- > How can I add a badge to an AppBarButton?
You can implement your own badge by setting a custom content on `AppBarButton`:
```xml
```
- > How can I set custom content to an AppBarButton?
You can set a custom content to an `AppBarButton` like this:
```xml
```
- > Why does my CommandBar always appear at the top of the page on iOS?
You can't place your `CommandBar` anywhere other than at the top of the `Page` on **iOS**. See the **Placement** section for details.
- > How can I change the height of my CommandBar?
You can't currently change the height of the `CommandBar`.
- > How can I remove the 1px line displayed below the CommandBar on iOS?
To hide the native 1px *shadow* that's displayed below the `CommandBar` on **iOS**, make its background transparent:
```xml
```
- > How can I add an elevation shadow to the CommandBar on Android?
```xml
xmlns:toolkit="using:Uno.UI.Toolkit"
...
```
- > How can I use a Path for the AppBarButton Icon?
`AppBarButton` doesn't currently support `PathIcon`. Only `BitmapIcon` with PNGs is supported. Please refer to the **Icon** section.
- > Why doesn't CommandBarExtensions.BackButtonTitle change the title of my back button?
`CommandBarExtensions.BackButtonTitle` must be set on the page to which the back button navigates to. Please refer to the **BackButtonTitle** section.
- > Why doesn't my CommandBarExtensions.NavigationCommand display anything on Android?
`CommandBarExtensions.NavigationCommand` only supports `AppBarButton` with `Icon` (not `Content`). Please refer to the **NavigationCommand** section.
- > How can I localize CommandBarExtensions.BackButtonTitle?
*For attached properties, you need a special syntax in the Name column of a `.resw` file.* Ref: [Microsoft documentation](https://learn.microsoft.com/windows/uwp/app-resources/localize-strings-ui-manifest#refer-to-a-string-resource-identifier-from-xaml).
More specifically :
```xml
...
```
And in the `.resw` file, the name would be: `MyCommandBar.[using:Uno.UI.Toolkit]CommandBarExtensions.BackButtonTitle`
- > How can I put a ComboBox in my CommandBar?
```xml
```
- > How can I customize the pressed/disabled visual states of my AppBarButton?
You can't currently customize the visual states of `AppBarButton` when using `CommandBar` in native mode.
- > Why doesn't the disabled state work on my AppBarButton on Android?
`AppBarButton` doesn't currently support the disabled state when used with `Content` (of `string`) on **Android**. You can use an `Icon` instead.
- > How can I disable the back swipe/gesture on iOS?
To disable the back swipe/gesture on **iOS**, you must remove the `CommandBar` or replace the back button with a custom one:
```xml
```
- > How can I display two CommandBars side by side on iOS (i.e., master-detail)
`Page` only supports a single `CommandBar` at a time. To display two `CommandBar`s side by side (i.e., master-detail), you should place two `Frame`s side by side and put a `CommandBar` in the `Page` of each `Frame`.
- > How can I add a burger menu to the left of my CommandBar?
```xml
```
- > Why doesn't Flyout work on my AppBarButton?
`AppBarButton` doesn't currently support `Flyout` when using `CommandBar` in native mode. You can use `MenuFlyout` instead.
- > Why can't I change the Foreground of my AppBarButton on Android?
`AppBarButton` doesn't currently support `Foreground` when displaying text (using `Content` of `string`).
However, you can change the color of all textual `AppBarButton`s globally using **Android** styles:
**Colors.xml**
```xml
#FFFF0000
```
**Styles.xml**
```xml
@color/red@color/red
```
If you need the button to display a different color to reflect being in a disabled state, you can add a selector in its own file, under res/color, like so:
**PrimaryTextColorSelector.xml**
```xml
```
**Styles.xml**
```xml
@color/PrimaryTextColorSelector@color/PrimaryTextColorSelector
```
- > How can I customize the font of the CommandBar title/content?
You can't currently customize the font of the native `CommandBar` title (set with a `string` on `Content`). Only the color can be changed, using the `Foreground` property.
To customize the font of the `CommandBar`'s title, you must set a custom `FrameworkElement` as the `Content` of your `CommandBar`:
```xml
```
- > Why doesn't my CommandBar scroll when placed inside a ScrollViewer on iOS?
`CommandBar` can't be placed inside a `ScrollViewer`. It must be anchored to the top of your `Page` at all time. Please refer to the **Placement** section for details.
- > How can I change the color of the ripple effect when pressing on AppBarButtons on Android?
You can change the color of the ripple effect globally using Android styles:
**Colors.xml**
```xml
#20444444#20ffffff
```
**Styles.xml**
```xml
@color/ripple_material_dark
```
- > Why doesn't my AppBarToggleButton work?
`AppBarToggleButton` is not currently supported.
To implement a similar effect, you can bind your `AppBarButton`'s icon to a state using a converter:
```xml
```
- > How can I show an image under my CommandBar?
You can show an image under a `CommandBar` by making its background transparent and superposing it over an `Image`:
```xml
```
- > What size should my AppBarButton icons be?
Please refer to the **Icon** section for details.
- > Why does my back button icon change when swiping back on iOS?
This can happen when navigating between two pages with `CommandBar`s using different `CommandBarExtensions.BackButtonIcon`s.
To avoid this issue, please make sure that all `CommandBar`s use the same `CommandBarExtensions.BackButtonIcon` by using a style:
```xml
```
If the issue still occurs, make sure that both pages have a `CommandBar`. If you don't want your page to display a `CommandBar`, you can simply collapse it:
```xml
```
## Uno.Controls.DatePicker
# DatePicker
## Summary
`DatePicker` is used to select a specific date.
## Managed vs. native implementation
On iOS and Android the `DatePicker` by default displays using the native time picker UI. If you prefer consistent UI across all targets, you can switch to the managed implementation by setting the `UseNativeStyle` property:
```xml
```
To include the `not_win` XAML namespace on your page follow the instructions for [Platform-specific XAML](../platform-specific-xaml.md).
## Uno.Controls.Flyout
# Flyout
If you want to show a dimmed overlay underneath the flyout, set the `Flyout.LightDismissOverlayMode` property to `On`.
If you wish to customize the overlay color, add the following to your top-level `App.Resources`:
```xml
```
## Uno.Controls.Frame
# Frame
> [!TIP]
> This article covers Uno-specific information for the `Frame` class. For a full description of the feature and instructions on using it, see [Frame class](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.frame)
* Displays Page instances, supports navigation to new pages, and maintains a navigation history to support forward and backward navigation.
## Using Frame with Uno
To improve performance during navigation, `Frame` on Android, iOS, and WebAssembly targets operates in different way than in WinUI. Whereas WinUI follows `NavigationCacheMode` property on individual `Page` instances, on iOS and Android we keep the individual page instances in the back stack in memory by default. This way they can be quickly surfaced back to the user during back navigation. This behavior can be controlled using the `FeatureConfiguration.Frame.UseWinUIBehavior` property. This defaults to `true` on Skia targets and to `false` on Android, iOS and WebAssembly.
If you set `UseWinUIBehavior` to `true` on Android and iOS, you also need to override the default style for the control. You can do this by explicitly setting the `Style` to `XamlDefaultFrame`:
```xml
```
Or by creating an implicit style based on `XamlDefaultFrame`:
```xml
```
## Uno.Controls.GLCanvasElement
# GLCanvasElement
> [!IMPORTANT]
> This functionality is only available on WinAppSDK and Skia Desktop (`netX.0-desktop`) targets that are running on platforms with support for hardware acceleration. On Windows and Linux, OpenGL 3.0+ is used directly and on macOS, Metal is used through the [ANGLE](https://en.wikipedia.org/wiki/ANGLE_(software)) library.
`GLCanvasElement` is a control for drawing 3D graphics with OpenGL. It can be enabled by adding the [`GLCanvas` UnoFeature](#Uno.Features.Uno.Sdk). The OpenGL APIs provided are provided by [Silk.NET](https://dotnet.github.io/Silk.NET/).
## Using the GLCanvasElement
To use `GLCanvasElement`, create a subclass of `GLCanvasElement` and override the abstract methods `Init`, `RenderOverride` and `OnDestroy`.
```csharp
protected GLCanvasElement(Func getWindowFunc);
protected abstract void Init(GL gl);
protected abstract void RenderOverride(GL gl);
protected abstract void OnDestroy(GL gl);
```
These three abstract methods take a `Silk.NET.OpenGL.GL` parameter that can be used to make OpenGL calls.
### The GLCanvasElement constructor
The protected constructor requires a `Func` argument that fetches the `Microsoft.UI.Xaml.Window` object that the `GLCanvasElement` belongs to. This function is required because WinUI doesn't yet provide a way to get the `Window` of a `FrameworkElement`. This parameter is ignored on Uno Platform and can be set to null. This function is only called while the `GLCanvasElement` is still in the visual tree.
### The `Init` method
The `Init` method is a regular OpenGL setup method that you can use to set up the needed OpenGL objects, like textures, Vertex Array Buffers (VAOs), Element Array Buffers (EBOs), etc. The `OnDestroy` method is the complement of `Init` and is used to clean up any allocated resources. `Init` and `OnDestroy` might be called multiple times alternatingly. In other words, 2 `OnDestroy` calls are guaranteed to have an `Init` call in between and vice versa.
### The `RenderOverride` method
The `RenderOverride` is the main render-loop function. When adding your drawing logic in `RenderOverride`, you can assume that the OpenGL viewport rectangle is already set and its dimensions are equal to the `RenderSize` of the `GLCanvasElement`.
### macOS Specifics
On MacOS, since OpenGL support is not natively present, we use [ANGLE](https://en.wikipedia.org/wiki/ANGLE_(software)) to provide OpenGL ES support. This means that we're actually using OpenGL ES 3.00, not OpenGL. Due to the similarity between desktop OpenGL and OpenGL ES, (almost) all the OpenGL ES functions are present in the `Silk.NET.OpenGL.GL` API surface and therefore we can use the same class to represent both the OpenGL and OpenGL ES APIs. To run the same `GLCanvasElement` subclasses on all supported platforms, make sure to use a subset of functions that are present in both APIs (which is almost all of OpenGL ES).
## Invalidating the canvas
Additionally, `GLCanvasElement` has an `Invalidate` method that requests a redrawing of the `GLCanvasElement`, calling `RenderOverride` in the process. Note that `RenderOverride` will only be called once per `Invalidate` call and the output will be saved to be used in future frames. To update the output, you must call `Invalidate`. If you need to continuously update the output (e.g. in an animation), you can add an `Invalidate` call inside `RenderOverride`.
## Detecting errors
To detect errors in initializing the OpenGL environment, `GLCanvasElement` exposes an `IsGLInitializedProperty` dependency property that shows whether or nor the loading of the element and its OpenGL setup were successful. This property is only valid when the element is loaded, i.e. its `IsLoaded` property is true. When the element is not loaded, the value of `IsGLInitialized` will be null. `GLCanvasElement` implements `INotifyPropertyChanged`, so you can use this property in a data bindings, for example to set the visibility of a control as a fallback. Attempting to change this property is illegal.
## How to use Silk.NET
To learn more about using [Silk.NET](https://www.nuget.org/packages/Silk.NET.OpenGL/) as a C# binding for OpenGL, see the examples in the Silk.NET repository [here](https://github.com/dotnet/Silk.NET/tree/main/examples/CSharp). Note that the windowing and inputs APIs in Silk.NET are not relevant to `GLCanvasElement`, since we only use Silk.NET as an OpenGL binding library, not a windowing library.
## Full example
To see this in action, here's a complete sample that uses `GLCanvasElement` to draw a triangle. Note how you have to be careful with surrounding all the OpenGL-related logic in platform-specific guards. This is the case for both the [XAML](platform-specific-xaml) and the [code-behind](platform-specific-csharp). For complete C# projects, visit our [GLCanvasElement Samples in the Uno.Samples repository](https://aka.platform.uno/glcanvaselement-sample).
XAML:
```xaml
```
Code-behind:
```csharp
// GLCanvasElementExample.xaml.cs
public partial class GLCanvasElementExample : UserControl
{
public GLCanvasElementExample()
{
this.InitializeComponent();
}
}
```
```csharp
// GLTriangleElement.cs
#if DESKTOP || WINDOWS
// https://learnopengl.com/Getting-started/Hello-Triangle
public class SimpleTriangleGlCanvasElement()
// Assuming that App.xaml.cs has a static property named MainWindow
: GLCanvasElement(() => App.MainWindow)
{
private uint _vao;
private uint _vbo;
private uint _program;
unsafe protected override void Init(GL gl)
{
_vao = gl.GenVertexArray();
gl.BindVertexArray(_vao);
float[] vertices =
{
0.5f, -0.5f, 0.0f, // bottom right
-0.5f, -0.5f, 0.0f, // bottom left
0.0f, 0.5f, 0.0f // top
};
_vbo = gl.GenBuffer();
gl.BindBuffer(BufferTargetARB.ArrayBuffer, _vbo);
gl.BufferData(BufferTargetARB.ArrayBuffer, new ReadOnlySpan(vertices), BufferUsageARB.StaticDraw);
gl.VertexAttribPointer(0, 3, GLEnum.Float, false, 3 * sizeof(float), (void*)0);
gl.EnableVertexAttribArray(0);
var slVersion = gl.GetStringS(StringName.ShadingLanguageVersion);
var versionDef = slVersion.Contains("OpenGL ES", StringComparison.InvariantCultureIgnoreCase)
? "#version 300 es"
: "#version 330";
var vertexCode =
$$"""
{{versionDef}}
precision highp float; // for OpenGL ES compatibility
layout (location = 0) in vec3 aPosition;
out vec4 vertexColor;
void main()
{
gl_Position = vec4(aPosition, 1.0);
vertexColor = vec4(aPosition.x + 0.5, aPosition.y + 0.5, aPosition.z + 0.5, 1.0);
}
""";
var fragmentCode =
$$"""
{{versionDef}}
precision highp float; // for OpenGL ES compatibility
out vec4 out_color;
in vec4 vertexColor;
void main()
{
out_color = vertexColor;
}
""";
uint vertexShader = gl.CreateShader(ShaderType.VertexShader);
gl.ShaderSource(vertexShader, vertexCode);
gl.CompileShader(vertexShader);
gl.GetShader(vertexShader, ShaderParameterName.CompileStatus, out int vStatus);
if (vStatus != (int)GLEnum.True)
{
throw new Exception("Vertex shader failed to compile: " + gl.GetShaderInfoLog(vertexShader));
}
uint fragmentShader = gl.CreateShader(ShaderType.FragmentShader);
gl.ShaderSource(fragmentShader, fragmentCode);
gl.CompileShader(fragmentShader);
gl.GetShader(fragmentShader, ShaderParameterName.CompileStatus, out int fStatus);
if (fStatus != (int)GLEnum.True)
{
throw new Exception("Fragment shader failed to compile: " + gl.GetShaderInfoLog(fragmentShader));
}
_program = gl.CreateProgram();
gl.AttachShader(_program, vertexShader);
gl.AttachShader(_program, fragmentShader);
gl.LinkProgram(_program);
gl.GetProgram(_program, ProgramPropertyARB.LinkStatus, out int lStatus);
if (lStatus != (int)GLEnum.True)
{
throw new Exception("Program failed to link: " + gl.GetProgramInfoLog(_program));
}
gl.DetachShader(_program, vertexShader);
gl.DetachShader(_program, fragmentShader);
gl.DeleteShader(vertexShader);
gl.DeleteShader(fragmentShader);
}
protected override void OnDestroy(GL gl)
{
gl.DeleteVertexArray(_vao);
gl.DeleteBuffer(_vbo);
gl.DeleteProgram(_program);
}
protected override void RenderOverride(GL gl)
{
gl.ClearColor(Color.Black);
gl.Clear(ClearBufferMask.ColorBufferBit);
gl.UseProgram(_program);
gl.BindVertexArray(_vao);
gl.DrawArrays(PrimitiveType.Triangles, 0, 3);
}
}
#endif
```
## Uno.Controls.ListViewBase
# ListViewBase in Uno Platform
Uno Platform's implementation of ListViewBase supports shared styling and template use with WinUI apps, whilst internally delegating to the native list view on Android and iOS for high performance. This document explains how Uno's implementation differs in some details from Windows.
For contributors, see in-depth documentation on [the internals of ListView](../uno-development/listviewbase-internals.md).
## Style reuse
This is a stripped-down view of the default style for ListView in Uno:
```xml
```
As on Windows, the `ItemsPanelTemplate` can be set; `ItemsStackPanel` and `ItemsWrapGrid` are the supported panels, and each of these supports most of the same properties as on Windows.
In fact there is only one difference from the Windows style, which is a custom Style on the `ScrollViewer` element. Below is the custom `ScrollViewer` style in its entirety:
```xml
```
This style replaces the internal `ScrollPresenter` with a `ListViewBaseScrollContentPresenter`, for reasons explained below. Custom ListView/GridView styles should modify the ScrollViewer template part's style to the one shown above.
## Performance tips
### Observable collections
If you use a collection type like an array or a `List` as an `ItemsSource`, then whenever you change the `ItemsSource`, all the item views will be removed and recreated. Often it's preferable to support incremental changes to your source collection.
`ListViewBase` implicitly supports incremental collection changes whenever the ItemsSource is a collection which implements the `INotifyCollectionChanged` interface. The `ObservableCollection` class in the standard library is one such collection. Whenever an item is added, removed, or replaced in the collection, the corresponding `CollectionChanged` event is raised. `ListViewBase` listens to this event and only visually modifies the items that have actually changed, using platform-specific animations. The list also maintains the scroll position if possible and maintains the current selected item (unless it's removed).
Using `ObservableCollection` (or another `INotifyCollectionChanged` implementation) has performance benefits in certain situations:
1. When only modifying one or two items.
2. When modifying items out of view.
3. When fetching 'new' data that hasn't actually changed (e.g. auto refresh).
It also has UX benefits in certain situations:
1. When only adding/removing a couple of items (esp. in response to user action).
2. When modifying the items source shouldn't affect the scroll position.
3. When modifying the items source shouldn't change the user's selection.
4. When item changes should be visually highlighted.
A good use case might be, for instance, a list of reminders that the user can remove by swiping them out of view.
Note that using an observable collection adds complexity and there are some cases when it can even be anti-performant. For example, consider a list of items that can be filtered by a search term. Modifying the search term by one character (i.e., when the user types in a `TextBox`) might remove or add hundreds of items from the filtered source. Particularly on iOS, and to a lesser extent on Android, the list tries to do preprocessing on each change to determine what animations it needs, etc. The result is a noticeable lag, where changing the `ItemsSource` completely would have been nearly instantaneous.
So consider using a non-observable collection, or use the Uno-only `RefreshOnCollectionChanged` flag (which causes the native list to refresh without animations when any `CollectionChanged` event is raised), if your scenario matches the following:
1. Large numbers of items may change at once, and
2. Changes are not particularly 'meaningful' to the user.
## Internal implementation
Internally Uno's implementation differs from WinUI's. On WinUI the ScrollViewer handles scrolling, while the ItemsStackPanel or ItemsWrapGrid handles virtualization (reuse of item views). On Uno, both scrolling and virtualization are handled by NativeListViewBase, an internal panel which inherits from the native list class on each platform. ItemsStackPanel/ItemsWrapGrid exist only as logical elements of ListView/GridView, they aren't in the visual tree. Their properties are redirected to ItemsStackPanelLayout/ItemsWrapGridLayout, non-visual classes which instruct NativeListViewBase on how to lay out its views.
Since NativeListViewBase class handles scrolling, the ScrollViewer contains a ListViewBaseScrollContentPresenter which is essentially a placeholder with no functionality.
Note that this only applies when ItemsStackPanel/ItemsWrapGrid are used. When any other panel is used, ListViewBase will use an ordinary ScrollViewer + ScrollContentPresenter.
### Difference in the visual tree
```schema
WinUI Uno
+--ListView------------------------------------------+ +--ListView------------------------------------------+
| | | |
| +--ScrollViewer----------------------------------+ | | +--ScrollViewer----------------------------------+ |
| | | | | | | |
| | +--ScrollContentPresenter--------------------+ | | | | +--ListViewBaseScrollContentPresenter--------+ | |
| | | | | | | | | | | |
| | | +--ItemsPresenter------------------------+ | | | | | | +--ItemsPresenter------------------------+ | | |
| | | | | | | | | | | | | | | |
| | | | +--Header----------------------------+ | | | | | | | | +--NativeListViewBase----------------+ | | | |
| | | | | | | | | | | | | | | | | | | |
| | | | +------------------------------------+ | | | | | | | | | +--Header------------------------+ | | | | |
| | | | | | | | | | | | | | | | | | | |
| | | | +--ItemsStackPanel-------------------+ | | | | | | | | | +--------------------------------+ | | | | |
| | | | | | | | | | | | | | | | | | | |
| | | | | +--ListViewItem------------------+ | | | | | | | | | | +--ListViewItem------------------+ | | | | |
| | | | | | | | | | | | | | | | | | | | | | | |
| | | | | +--------------------------------+ | | | | | | | | | | +--------------------------------+ | | | | |
| | | | | | | | | | | | | | | | | | | |
| | | | | +--ListViewItem------------------+ | | | | | | | | | | +--ListViewItem------------------+ | | | | |
| | | | | | | | | | | | | | | | | | | | | | | |
| | | | | +--------------------------------+ | | | | | | | | | | +--------------------------------+ | | | | |
| | | | | | | | | | | | | | | | | | | |
| | | | | | | | | | | | | | | +--Footer------------------------+ | | | | |
| | | | | | | | | | | | | | | | | | | | | |
| | | | | | | | | | | | | | | +--------------------------------+ | | | | |
| | | | +------------------------------------+ | | | | | | | | | | | | | |
| | | | | | | | | | | | | | | | | |
| | | | +--Footer----------------------------+ | | | | | | | | | | | | | |
| | | | | | | | | | | | | | | | | | | |
| | | | +------------------------------------+ | | | | | | | | +------------------------------------+ | | | |
| | | | | | | | | | | | | | | |
| | | +----------------------------------------+ | | | | | | +----------------------------------------+ | | |
| | | | | | | | | | | |
| | +--------------------------------------------+ | | | | +--------------------------------------------+ | |
| | | | | | | |
| +------------------------------------------------+ | | +------------------------------------------------+ |
| | | |
+----------------------------------------------------+ +----------------------------------------------------+
```
### Other differences from WinUI
* The ListView doesn't use XAML animations (`AddDeleteThemeTransition`, etc) for collection modifications, instead, it uses the animations provided by the native collection class. On iOS, these can be disabled by setting the `ListViewBase.UseCollectionAnimations` flag to `false`.
## Uno.Controls.MapControl
# MapControl
The `MapControl` is a control that allows you to display maps in your app. Currently, Uno supports `MapControl` on iOS and Android.
## Architecture
Although `MapControl` is defined in `Uno.UI`, to function, it requires an additional package to be installed, `Uno.UI.Maps`, which supplies the actual implementation. This is done to avoid imposing an unnecessary dependency on applications that don't use maps, and also to allow alternative map providers (eg, Google Maps on iOS) to be easily supported in the future.
The current implementation uses the native UIKit Map for iOS and the Google Play Services Map control for Android.
## How to use MapControl in an Uno Platform app
1. Install the [Uno.WinUI.Maps NuGet package](https://www.nuget.org/packages/Uno.WinUI.Maps/) in the Android and/or iOS head projects of your app.
1. Add the `MapResources` resource dictionary to `Application.Resources` in your `App.xaml` file:
```xml
```
1. (Windows and Android) Obtain an API key for your app, following the instructions below.
1. (Android) Configure permissions in the manifest, following the instructions below.
1. Add `MapControl` to your app (``).
## Sample XAML
Here's a complete sample:
```xml
```
The above code will display Page with a Map Control and a slider that will be used to change the ZoomLevel.
## Platform support
| Feature | Android | iOS | Wasm |
| ------------------------------------------|:-------:|:---:|:----:|
| Display a map | X | X | |
| Display a path | | X | |
| Customize pushpins with icon | | | |
| Fully template pushpins | | | |
| Show user's location on map | | | |
| Toggle native Locate-Me button visibility | | | |
| Toggle native Compass button visibility | | | |
## Usage
## Get API key for the map component
To use the map component, you will need an API key for Windows and Android. Here are the steps to retrieve it.
### Windows
For the detailed procedure for Windows, see [Request a maps authentication key
](https://learn.microsoft.com/windows/uwp/maps-and-location/authentication-key) documentation.
+ Go to
+ Login to your account or register if you don't have one
+ Go to MyAccount -> Keys
+ Click on create a new key
+ Enter the following information:
+ Application name
+ Application URL (optional)
+ Key type
+ Application type
+ Hit *Create* and get the key
The key will be set as the value for the parameter *MapServiceToken* for the MapControl object.
### Android
+ Create a project in the Google Developers Console.
+ Enable Map Service. In case this is your first time using the Google Maps API you will need to enable it before using it.
1. Go to
2. Login with a Google account
3. Click on "Enable APIs and Services"
4. Select "Maps SDK for Android" and click on Enable
+ Generate an API key.
1. If you are coming from step-2 just navigate back until you are again in the dashboard, otherwise, go to and login with a Google account.
2. Go to the Credentials section on the left-hand side menu
3. Click on "Create Credentials", then "API key"
4. Copy the key generated as this will be the one we will use later in the application
**Note:** For apps in production we suggest restricting the keys to be used only by your Android app. This is possible by using the SHA-1 fingerprint of your app.
*For a detailed procedure on how to retrieve the SHA-1 fingerprint for your Android application, please follow this link: *
## Configure your application
+ For **Android**
1. Add the following to AndroidManifest.xml:
```xml
```
2. Add the API key to `AssemblyInfo.cs`.
```csharp
[assembly: MetaData("com.google.android.maps.v2.API_KEY", Value = "YOUR_API_KEY")]
```
Replace the text YOUR_API_KEY with the key generated in previous step.
Note: Since this key might vary depending on the platform and environment we suggest using a constant class where the key could be retrieved from.
3. Add the relevant permissions to `AssemblyInfo.cs`. For example, if you wish to access the user location
```csharp
[assembly: UsesPermission(Android.Manifest.Permission.AccessFineLocation)]
[assembly: UsesPermission("com.myapp.permission.MAPS_RECEIVE")]
[assembly: Permission(Name = "com.myapp.permission.MAPS_RECEIVE", ProtectionLevel = Android.Content.PM.Protection.Signature)]
```
## Uno.Controls.MediaPlayerElement
# MediaPlayerElement
See [Microsoft API reference for MediaPlayerElement](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.mediaplayerelement).
## Media formats
| Supported Formats | iOS | Android | Wasm | Skia Desktop | Remarks |
|----------------------------|:----:|:---------:|:------:|:---------:|------------------------------------------------------------------------------|
| Local/Remote MP3 Support | ✅ | ✅ | ✅ | ✅ | |
| Local/Remote MPEG4 Support | ✅ | ✅ | ✅ | ✅ | |
| HLSv3 Support | ✅ | ✅ | ✅ | ✅ | |
| HLSv4 Support | ✅ | ✅ | ✅ | ✅ | |
| 3GP Support | ✅ | ✅ | ✅ | ✅ |3GP with AMR Narrow Band (SAMR) audio codec does not work on iOS (See notes) |
| FLV Support | - | ✅ | ✅ | ✅ | |
| MOV Support | ✅ | - | - | - | |
| MKV Support | - | ✅ | ✅ | ✅ | |
| AVI Support | - | ✅ | ✅ | ✅ | |
| OGG Support | - | - | ✅ | ✅ | |
| MPEG-Dash Support | - | - | - | - | |
| Smooth Streaming Support | - | - | - | - | |
### Notes
- Uno's MediaPlayerElement relies on AVPlayer for iOS and AndroidMediaPlayer for Android. Please, refer to those native players documentation for more information about supported audio and video formats.
- Uno's MediaPlayerElement relies on VLC and libvlc on Linux. please follow [these instructions](https://github.com/videolan/libvlcsharp/blob/3.x/docs/linux-setup.md) to get the necessary dependencies.
- If you need to set source programmatically (i.e., using `_mediaPlayerElement.Source = [source]`), please note that only sources created with `MediaSource.CreateFromUri()` are currently supported.
## Features
| Section | Feature | iOS & Android (native) | Wasm (native) | Skia | Remarks |
| ------------------ | ---------------------------------------------- | :--------------------: | :-----------: | :--: | --------------------------------------------- |
| MediaPlayerElement | AutoPlay | ✅ | ✅ | ✅ | |
| | Poster image | ✅ | ✅ | ✅ | Does not show when playing music |
| | Enable/Disable MediaTransportControls | ✅ | ✅ | ✅ | |
| | Stretch | ✅ | ✅ | ✅ | Stretch.None behaves like Stretch.Fill on iOS |
| | Pause media when headphones unplugged | ✅ | - | - | |
| TransportControls | Transport controls custom style | ✅ | ✅ | ✅ | |
| | Play/Pause | ✅ | ✅ | ✅ | |
| | Stop | ✅ | ✅ | ✅ | |
| | Seek | ✅ | ✅ | ✅ | |
| | Volume change | ✅ | ✅ | ✅ | |
| | Mute | ✅ | ✅ | ✅ | |
| | Show elapsed time | ✅ | ✅ | ✅ | |
| | Show remaining time | ✅ | ✅ | ✅ | |
| | Show/Hide MediaTransportControls automatically | ✅ | ✅ | ✅ | |
| | MediaTransportControls compact mode | ✅ | ✅ | ✅ | |
| | Show/Hide MediaTransportControls commands | ✅ | ✅ | ✅ | |
| | Enable/Disable MediaTransportControls commands | ✅ | ✅ | ✅ | |
| | Skip forward | ✅ | ✅ | ✅ | |
| | Skip backward | ✅ | ✅ | ✅ | |
| | Show buffering progress | ✅ | ✅ | ✅ | |
| | Zoom mode | ✅ | ✅ | ✅ | |
| | Full-screen mode | ✅ | ✅ | - | |
| | Playlists support | ✅ | - | - | |
| | Change playback rate | - | ✅ | ✅ | |
| | Player controls on locked screen support | - | - | - | |
| | Subtitles support | - | - | - | |
| | Languages support | - | - | - | |
## Getting Started
To add video playback functionality, include the following XAML snippet:
```xml
```
Make sure to enable the required feature in your `UnoFeatures` to include the necessary packages. Add `MediaPlayerElement;` as shown below:
```diff
+ MediaPlayerElement;
```
### iOS
Add the following to your info.plist:
```xml
NSAppTransportSecurityNSAllowsArbitraryLoadsNSExceptionMinimumTLSVersionTLSv1.2
```
__Note:__ Don't just copy/paste, but properly setup `NSAppTransportSecurity` as required by your project
### Android
Add the following to your AndroidManifest.xml
```xml
```
### Skia
On some weaker devices, the first load of a `MediaPlayerElement` instance is extremely slow. To attempt to preload media playback resources on app startup, enable the `PreloadMediaPlayer` option in the host builder where supported.
```csharp
var host = UnoPlatformHostBuilder.Create()
.App(() => new App())
.UseX11(hostBuilder => hostBuilder.PreloadMediaPlayer(true))
.UseWin32(hostBuilder => hostBuilder.PreloadMediaPlayer(true))
.Build();
```
## Future improvement
- React to audio focus changes (pause/stop playback or reduce audio volume)
- Subtitles support
- Languages support
- Buffering of next playlist element when using MediaPlaybackList
- Cast to device
- Playlist for Wasm
- Download option
## Known issues
- `[iOS]` Volume flyout does not display (Uno issue)
- `[All]` Dynamic width/height not supported when playing audio
- `[All]` Sometimes flickers during resizing when using dynamic width/height
## Uno.Controls.MenuFlyout
# MenuFlyout
MenuFlyout is implemented to provide support for `ContextMenu` and `MenuBar` features.
## Platform-specific behavior
On iOS and Android, the flyout can either be displayed using native popup, or Uno managed popups.
The default behavior of the MenuFlyout is to follow the value `FeatureConfiguration.Style.UseUWPDefaultStyles`, but this can be changed per MenuFlyout using the `FlyoutBase.UseNativePopup` property.
### iOS (native)
#### Destructive action
> If an alert button results in a destructive action, such as deleting content, set the button’s style to Destructive so that it gets appropriate formatting by the system.
```xml
xmlns:toolkit="using:Uno.UI.Toolkit"
```
#### Cancel button text
```xml
xmlns:toolkit="using:Uno.UI.Toolkit"
```
## Uno.Controls.NavigationView
# NavigationView
The `NavigationView` control provides top-level navigation for your app. It adapts to a variety of screen sizes and supports both top and left navigation styles. For more information about its usage, see [NavigationView Microsoft documentation](https://learn.microsoft.com/windows/apps/design/controls/navigationview).
## Back button visibility
The `IsBackButtonVisible` property is by default set to `Auto`. This means the system chooses whether or not to display the back button. As per the design guidelines on Android, this means it is not shown by default and the [**hardware back button**](#Uno.Features.HardwareBackButton) should be used instead. If you prefer to always display the back button, set the `IsBackButtonVisible` property to `Visible`.
## Uno.Controls.Pivot
# Pivot in Uno Platform
## Pivot WinUI Default Style
Uno provides a full support of the Pivot WinUI style.
The Pivot with the default style looks the same on all platforms, both statically and in motion.
If you need to have a custom design, you can just update the Pivot WinUI default style for your needs.
## Pivot Native Default Style
With the `NativeDefaultPivot` style on Android and iOS, the Pivot uses the native implementations of each platform.
Of course, you can still bind to its properties in XAML as you normally would.
This is another powerful option to have: for some apps it makes sense to look as 'native' as possible, for others it's desirable to have a rich, customized UI.
You may even want to mix and match different approaches for different screens in your app.
### Native Pivot Style for Android and iOS
If you want to use the native Pivot style for either Android or iOS, you'll need to specify the following `Pivot` style as well as a `NativePivotPresenter` style.
```xml
```
#### NativePivotPresenter Android Style
Note that this one is written in C# rather than XAML because of the `SlidingTabLayout` object.
```csharp
var style = new Style(typeof(NativePivotPresenter))
{
Setters =
{
new Setter("Template", pb => pb
.Template = new ControlTemplate(() =>
new Grid
{
RowDefinitions =
{
new RowDefinition(){ Height = GridLength.Auto},
new RowDefinition(){ Height = new GridLength(1, GridUnitType.Star)},
},
Children =
{
// Header
new Border
{
Child = new Uno.UI.Controls.SlidingTabLayout(ContextHelper.Current)
{
LayoutParameters = new Android.Views.ViewGroup.LayoutParams(Android.Views.ViewGroup.LayoutParams.MatchParent, Android.Views.ViewGroup.LayoutParams.WrapContent),
},
BorderThickness = new Thickness(0,0,0,1),
}
.Apply(b => b.SetBinding("Background", new Binding { Path = "Background", RelativeSource = RelativeSource.TemplatedParent }))
.Apply(b => b.SetBinding("BorderBrush", new Binding { Path = "BorderBrush", RelativeSource = RelativeSource.TemplatedParent })),
// Content
new ExtendedViewPager(ContextHelper.Current)
{
OffscreenPageLimit = 1,
PageMargin = (int)TypedValue.ApplyDimension(ComplexUnitType.Dip, 4, ContextHelper.Current.Resources.DisplayMetrics),
SwipeEnabled = true,
}
.Apply(v => Grid.SetRow(v, 1))
}
})
)
}
};
Style.RegisterDefaultStyleForType(typeof(NativePivotPresenter), style);
```
#### NativePivotPresenter iOS Style
```xml
```
## Uno.Controls.Popup
# Popup
## Customizing light-dismiss overlay
If you want to show a dimmed overlay underneath the popup, set the `Popup.LightDismissOverlayMode` property to `On`.
If you wish to customize the overlay color, add the following to your top-level `App.Resources`:
```xml
```
## Uno.Controls.RefreshContainer
# RefreshContainer (Pull to Refresh)
## Summary
`RefreshContainer` is used to provide the pull-to-refresh UI functionality primarily for scrollable content.
The touch-based pull capability is currently available only on Android, iOS and Windows (via WinUI). However, on the other targets you can still manually call the `RequestRefresh()` method to display the refresh UI.
To handle the refresh, subscribe to the `RefreshRequested` event. You can perform any kind of work in the handler. To use `async/await`, make the method `async`, get the deferral in the beginning of the method, and complete it after all required work is finished:
```csharp
refreshContainer.RefreshRequested += OnRefreshRequested;
private async void OnRefreshRequested(
object sender,
RefreshRequestedEventArgs e)
{
var deferral = e.GetDeferral();
await Task.Delay(3000); // Do some asynchronous work
deferral.Complete();
}
```
## Android and iOS specifics
On Android and iOS `RefreshContainer` requires a scrollable element as the child of the control. This can be either a `ScrollViewer` or a list-based control like `ListView`:
```xml
```
## Uno.Controls.ScrollViewer
# ScrollViewer in Uno Platform
The `ScrollViewer` represents a scrollable area that can contain other visible elements. For more information about its usage, see [Microsoft API reference for ScrollViewer](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.scrollviewer).
## ScrollViewer visual diagram
The `ScrollViewer` is a more intricate control and it's not always easy to have a good overview/understanding of some of its properties.
So, here is a more visual diagram to better understand how some of the main ScrollViewer properties are supposed to behave.
## Uno.Controls.SKCanvasElement
# SKCanvasElement
When creating an Uno Platform application, developers might want to create elaborate 2D graphics using a library such as [Skia](https://skia.org) or [Cairo](https://www.cairographics.org), rather than using, for example, a simple [Canvas](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.canvas). To support this use case, SkiaSharp comes with an [SKXamlCanvas](https://learn.microsoft.com/dotnet/api/skiasharp.views.windows.skxamlcanvas) element that allows for drawing in an area using SkiaSharp.
On Uno Platform targets with Skia rendering, we can utilize the pre-existing internal Skia canvas used to render the application window instead of creating additional Skia surfaces. Unlike `SKXamlCanvas` which doesn't support hardware acceleration on Skia targets yet, hardware acceleration comes out of the box if the Uno application is already using OpenGL to render. Moreover, `SKXamlCanvas` has to make additional buffer copying, which can be skipped with this implementation.
> [!IMPORTANT]
> . The `Uno.WinUI.Graphics2DSK` package which provides the `SKCanvasElement` class is referenced for you by Uno.Sdk automatically when the `Skia` or `SkiaRenderer` features are present, and is always referenced on the netX.0-desktop target. However, the class is only supported (i.e. `SKCanvasElement.IsSupportedOnCurrentPlatform` returns true) on the netX.0-desktop target and on other targets that use skia rendering, for example netX.0-android with the `SkiaRenderer` feature.
`SKCanvasElement` is an abstract `FrameworkElement` for 2D drawing with Skia. To use `SKCanvasElement`, create a subclass of `SKCanvasElement` and override the `RenderOverride` method, which takes the canvas that will be drawn on and the clipping area inside the canvas.
```csharp
protected abstract void RenderOverride(SKCanvas canvas, Size area);
```
When adding your drawing logic in `RenderOverride` on the provided canvas, you can assume that the origin is already translated so that `0,0` is the origin of the element, not the entire window. Drawing outside this area will be clipped.
Additionally, `SKCanvasElement` has an `Invalidate` method that invalidates the `SKCanvasElement` and triggers a redraw. The drawing of the `SKCanvasElement` is often cached and will not be updated unless `Invalidate` is called.
Since `SKCanvasElement` is just a FrameworkElement, controlling the dimensions of the drawing area is done by manipulating the layout of the element, e.g. by overriding MeasureOverride and ArrangeOverride.
Finally, since `SKCanvasElement` makes use of the Skia-based rendering infrastructure and is therefore only supported when skia rendering is used, there's a static method that provides a check at runtime for whether `SKCanvasElement` can function on the current platform.
```csharp
public static bool IsSupportedOnCurrentPlatform();
```
Attempting to create an `SKCanvasElement` instance when `IsSupportedOnCurrentPlatform` returns false throws an exception.
## Full example
For a complete example that showcases how to work with `SKCanvasElement`, see [this sample](https://github.com/unoplatform/Uno.Samples/tree/master/UI/SKCanvasElementShowcase) in the Uno.Samples repository
## WinAppSDK Specifics
When using the SKCanvasElement and running on WinAppSDK, make sure to create an `x64` or `ARM64` configuration:
- In the Visual Studio configuration manager, create an `x64` or `ARM64` solution configuration
- Assign it to the Uno Platform project
- Debug your application using the configuration relevant to your current environment
## Uno.Controls.TextBox
# TextBox
## InputScopes Mapping Table
| Value | Description | Android | iOS |
|-------------------------|-------------------------------------------------------------------------------------------------------------------------------------------|:------------------------------------------------------------:|:------------------------------------:|
| AlphanumericFullWidth | Input scope is intended for alphanumeric full-width characters. | | |
| AlphanumericHalfWidth | Input scope is intended for alphanumeric half-width characters. | | |
| AlphanumericPin | Expected input is an alphanumeric PIN. | | |
| Chat | Input scope is intended for chat strings. | | |
| ChatWithoutEmoji | Expected input does not include emoji. Advises input processors to not show the emoji key. | | |
| ChineseFullWidth | Input scope is intended for Chinese full-width characters. | | |
| ChineseHalfWidth | Input scope is intended for Chinese half-width characters. | | |
| CurrencyAmount | Input scope is intended for working with a currency amount (no currency symbol). | InputTypes.ClassNumber OR InputTypes.NumberFlagDecimal | UIKeyboardType.DecimalPad |
| CurrencyAmountAndSymbol | Input scope is intended for working with amount and symbol of currency. | | |
| DateDayNumber | Input scope is intended for working with a numeric day of the month. | | |
| DateMonthNumber | Input scope is intended for working with a numeric month of the year. | | |
| DateYear | Input scope is intended for working with a numeric year. | | |
| Default | No input scope is applied. | InputTypes.ClassText | UIKeyboardType.Default |
| Digits | Input scope is intended for working with a collection of numbers. | | |
| EmailNameOrAddress | Input scope is intended for working with an email name or full email address. | InputTypes.ClassText OR InputTypes.TextVariationEmailAddress | UIKeyboardType.EmailAddress |
| EmailSmtpAddress | Input scope is intended for working with a Simple Mail Transport Protocol (SMTP) form e-mail address (accountname@host). | InputTypes.ClassText OR InputTypes.TextVariationEmailAddress | UIKeyboardType.EmailAddress |
| Formula | Input scope is intended for spreadsheet formula strings. | | |
| FormulaNumber | Expected input is a mathematical formula. Advises input processors to show the number page. | | |
| HangulFullWidth | Input scope is intended for Hangul full-width characters. | | |
| HangulHalfWidth | Input scope is intended for Hangul half-width characters. | | |
| Hanja | Input scope is intended for Hanja characters. | | |
| Hiragana | Input scope is intended for Hiragana characters. | | |
| KatakanaFullWidth | Input scope is intended for Katakana full-width characters. | | |
| KatakanaHalfWidth | Input scope is intended for Katakana half-width characters. | | |
| Maps | Input scope is intended for working with a map location. | | |
| NameOrPhoneNumber | Input scope is intended for working with a name or telephone number. | | |
| NativeScript | Input scope is intended for native script. | | |
| Number | Input scope is intended for working with digits 0-9. | InputTypes.ClassNumber | UIKeyboardType.NumberPad |
| NumberFullWidth | Input scope is intended for full-width number characters. | InputTypes.ClassPhone(*) | UIKeyboardType.NumbersAndPunctuation |
| NumericPassword | Expected input is a numeric password, or PIN. | | |
| NumericPin | Expected input is a numeric PIN. | InputTypes.ClassNumber | UIKeyboardType.NumbersAndPunctuation |
| Password | Input scope is intended for working with an alphanumeric password, including other symbols, such as punctuation and mathematical symbols. | | |
| PersonalFullName | Input scope is intended for working with a complete personal name. | | |
| Search | Input scope is intended for search strings. | InputTypes.ClassText | UIKeyboardType.Default |
| SearchIncremental | Input scope is intended for search boxes where incremental results are displayed as the user types. | | |
| TelephoneAreaCode | Input scope is intended for working with a numeric telephone area code. | | |
| TelephoneCountryCode | Input scope is intended for working with a numeric telephone country code. | | |
| TelephoneLocalNumber | Input scope is intended for working with a local telephone number. | | |
| TelephoneNumber | Input scope is intended for working with telephone numbers. | InputTypes.ClassPhone | UIKeyboardType.PhonePad |
| Text | Input scope is intended for working with text. | | |
| TimeHour | Input scope is intended for working with a numeric hour of the day. | | |
| TimeMinutesOrSeconds | Input scope is intended for working with a numeric minute of the hour, or second of the minute. | | |
| Url | Indicates a Uniform Resource Identifier (URI). This can include URL, File, or File Transfer Protocol (FTP) formats. | InputTypes.ClassText OR InputTypes.TextVariationUri | UIKeyboardType.Url |
\[\*: Workaround]
## Controlling the Keyboard on iOS
If a view needs to keep the keyboard opened when tapping on it, use the `Uno.UI.Controls.Window.SetNeedsKeyboard` attached property.
## Paste event
Support for capturing and handling the `Paste` event is implemented on all targets except for macOS.
In the case of Android, it is currently limited to the pastes that are triggered by the native context menu (e.g. after long-pressing the `TextBox`). It cannot detect paste triggered by the virtual keyboard or via a hardware keyboard shortcut.
## Pointer capture on WebAssembly
In addition to focus, `TextBox` control also captures pointers, so that manipulations like scrolling through contents are possible. However, on WASM setting the programmatic capture will prevent the native scrolling behavior of the underlying ``. For that reason, we avoid performing the pointer capture in this case. If you still want to capture the pointer, you can do so by setting the `IsPointerCaptureRequired` attached property to `true`:
In C#:
```csharp
#if __WASM__
myTextBox.IsPointerCaptureRequired = true;
#endif
```
Or in XAML:
```xml
```
> Follow [Platform-specific XAML guide](#Uno.Development.PlatformSpecificXaml) to add the `wasm` namespace.
The value only affects WebAssembly, all other targets capture by default.
## Customizing the Enter key appearance
On mobile targets you can customize the visual appearance of the Enter key on the virtual keyboard. This can be done using the `TextBoxExtensions.InputReturnType` attached property:
```csharp
Uno.UI.Xaml.Controls.TextBoxExtensions.SetInputReturnType(myTextBox, Uno.UI.Xaml.Controls.InputReturnType.Search);
```
These are the supported input return type values:
- **Enter**: Typically indicating inserting a new line.
- **Done**: There is nothing more to input, and the input method editor (IME) will be closed.
- **Go**: Typically meaning to take the user to the target of the text they typed.
- **Next**: Typically taking the user to the next field that will accept text.
- **Previous**: Typically taking the user to the previous field that will accept text.
- **Search**: Typically taking the user to the results of searching for the text they have typed.
- **Send**: Typically delivering the text to its target.
- **Default**: System default.
## Uno.Controls.TimePicker
# TimePicker
## Summary
`TimePicker` is used to select a specific time of the day in hour and minute (AM/PM).
Button showing time open the time picker popup.
Bind to the `Time` property of the control to set initial time.
days, seconds and milliseconds of input timespan are ignored
By default minute increment is set to 1
if you assign a negative value or 0, it will use 1 minute increment
if you assign a value over 30, it will use 30 minute increment
While all increments under 30 minutes are valid, we recommend using 1,2,5,10,15,20,25,30 minute increment.
If bound time is 2h03 and time increment is 5 than time picker initial pickable time will be 2h05
If bound time is 2h08 and time increment is 15 than time picker initial pickable time will be 2h15
Cancel button cancel the new time selection. You can also click outside the time picker to do the same.
Done/OK button save the new selected time.
## Managed vs. native implementation
On iOS and Android the `TimePicker` by default displays using the native time picker UI. If you prefer consistent UI across all targets, you can switch to the managed implementation by setting the `UseNativeStyle` property:
```xml
```
To include the `not_win` XAML namespace on your page follow the instructions for [Platform-specific XAML](../platform-specific-xaml.md).
### Styles
Time button style: `TimePickerFlyoutButtonStyle`
Time picker flyout popup style: default generic `TimePickerFlyoutPresenterStyle`
`TimePickerSelector` is a platform specific wrapper for IOS/Android time pickers
### Device-specific implementation quirks
There might be differences in the time picker on different platform since it wraps platform specific ios/android time picker
#### Android
- Native time picker is wrapped in the flyout.
- `TimePicker` flyout appear centered to screen.
- You can change the flyout button by copying and modifying TimePickerFlyoutButtonStyle.
- You can change the flyout button by copying and modifying TimePickerFlyoutPresenterStyle.
- If 'MinuteIncrement` is more than 1, `TimePicker` will show in "spinner mode"
- In case clock mode still appear for some reason picked value will be rounded to minute increment intervals..
#### iOS
- Native time picker is wrapped in the flyout.
- Set 'ios:FlyoutPlacement' property to change flyout docking placement
- Default 'ios:FlyoutPlacement' is 'Full' and will dock of the flyout at the bottom of the screen
- You can change the flyout button by copying and modifying TimePickerFlyoutButtonStyle.
- You can change the flyout button by copying and modifying TimePickerFlyoutPresenterStyle.
Some `ColorBrushes` are specific to **iOS** and could be changed by copying and redoing the new style so they use your own color brushes:
```resources
IOSTimePickerAcceptButtonForegroundBrush Color="#055bb7"
IOSTimePickerDismissButtonForegroundBrush Color="#055bb7"
IOSTimePickerHeaderBackgroundBrush Color="{ThemeResource SystemListLowColor}"
```
If you want to show a dimmed overlay underneath the picker, set the `TimePicker.LightDismissOverlayMode` property to `On`.
If you wish to customize the overlay color, add the following to your top-level `App.Resources`:
```xml
```
Since **iOS14** the native `TimePicker` changed the way it's presented. By default iOS14 devices will display this new style. You can still force the previous style (the one found in iOS13 or earlier) by adding the following at your `App.cs` or `App.xaml.cs` class:
```csharp
Uno.UI.FeatureConfiguration.TimePicker.UseLegacyStyle = true;
```
> [!IMPORTANT]
> This feature flag is required and will only affect iOS 14 devices. As of **iOS 15**, the preferred style for the DatePicker is again the one found in iOS13 and earlier.
## Uno.Controls.ToggleSwitch
# ToggleSwitch in Uno Platform
`ToggleSwitch` represents a switch that can be toggled between two states.
## ToggleSwitch WinUI Default Style
Uno provides a full support of the ToggleSwitch WinUI style.
The ToggleSwitch with the default style looks the same on all platforms, both statically and in motion.
If you need to have a custom design, you can just update the ToggleSwitch WinUI default style for your needs.
## ToggleSwitch Native Default Style
With the `NativeDefaultToggleSwitch` style on Android and iOS, the ToggleSwitch uses the native toggle control of each platform.
Of course, you can still bind to its properties in XAML as you normally would.
This is another powerful option to have: for some apps it makes sense to look as 'native' as possible, for others its desirable to have a rich, customized UI.
You may even want to mix and match different approaches for different screens in your app.
### Native Android ToggleSwitch
The Native Style for ToggleSwitch on Android is based on `SwitchCompat`, a Material Design version of the Switch widget supported by API 7 and above.
It does not make any attempt to use the platform provided widget on those devices which it is available normally.
This ensures the same behavior on all system versions.
#### Platform support
| Property | `BindableSwitchCompat` |
|----------------------|:----------------------:|
| Checked | X |
| Enabled | X |
| Text | X |
| TextColor | X |
| TextOff | |
| TextOn | |
| ShowText | |
| SplitTrack | |
| SwitchMinWidth | |
| SwitchPadding | |
| SwitchTextAppearance | |
| Thumb | |
| ThumbTextPadding | |
| ThumbTint | X |
| ThumbTintMode | |
| Track | |
| TrackTint | X |
| TrackTintMode | |
#### Native Android ToggleSwitch Style
If you need the simple native style :
```xml
```
If you need the native style but you want to change the Text, ThumbTint and TrackTint colors:
```xml
```
### Native iOS ToggleSwitch
Based on the UISwitch.
#### Platform support
| Property | BindableUISwitch |
| ------------------------------------------ |:----------------:|
| IsOn | X |
| Enabled | X |
| OnTintColorBrush | X |
| TintColorBrush | X |
| ThumbTintColorBrush | X |
| OnImage | |
| OffImage | |
#### Native iOS ToggleSwitch Style
If you need the simple native style:
```xml
```
If you need the native style but you want to change the Tint, OnTinT and ThumbTint colors:
```xml
```
## Uno.Controls.WebView2
# `WebView2` (`WebView`)
> Uno Platform supports two `WebView` controls - the `WebView2` control and the legacy `WebView`. For new development, we strongly recommend `WebView2` as it will get further improvements in the future.
`WebView2` is supported on all Uno Platform targets.
## Basic usage
You can include the `WebView2` control anywhere in XAML:
```xaml
```
To manipulate the control from C#, first ensure that you call its `EnsureCoreWebView2Async` method:
```csharp
await MyWebView.EnsureCoreWebView2Async();
```
Afterward, you can perform actions such as navigating to an HTML string:
```csharp
MyWebView.NavigateToString("
Hello world!
");
```
## Desktop support
To enable `WebView` on the `-desktop` target, add the `WebView` Uno Feature in your `.csproj`:
```diff
+ WebView;
```
> [!IMPORTANT]
> If your project's desktop builder in `Platforms/Desktop/Program.cs` uses `.UseWindows()`, you'll also need to add the `true` property for the integration to work. However, it is recommended to [migrate to `.UseWin32()`](#Uno.Development.MigratingToUno6) for better performance and reliability.
## WebAssembly support
In case of WebAssembly, the control is supported via a native `