From 734057ab723259f88422d040c80f9055abc3c8af Mon Sep 17 00:00:00 2001 From: Qiutong Shen Date: Thu, 23 Apr 2026 11:25:48 +0800 Subject: [PATCH] Fix WinUI 3 migration issues in miscellaneous documentation pages visual-layer-in-desktop-apps.md: - Add note directing WinUI 3 readers to correct Visual layer docs - Update Win2D package reference (Microsoft.Graphics.Win2D for WinAppSDK) - Update composition API links (/windows/uwp/ to /windows/apps/develop/) scan-from-your-app.md: - Add note about Dispatcher pattern changes for WinUI 3 handle-uri-activation.md: - Fix missing semicolon in C# code sample - Fix Frame API links (/uwp/api/ to /windows/windows-app-sdk/api/winrt/) xaml-property-animations.md: - Fix Window.Current.Compositor to CompositionTarget.GetCompositorForCurrentThread() - Update Visual Layer links (/windows/uwp/ to /windows/apps/develop/) optimize-xaml-loading.md: - Fix x:Load, x:Key, x:Name attribute links to Windows App SDK paths - Fix DebugSettings.IsOverdrawHeatMapEnabled link to WinUI 3 API simple-photo-viewer-winui3.md: - Fix INotifyPropertyChanged link (now points to .NET docs) - Fix ListView/GridView optimization link - Fix Data binding in depth link Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../ui/visual-layer-in-desktop-apps.md | 23 +++++++++++-------- .../devices-sensors/scan-from-your-app.md | 3 +++ .../develop/launch/handle-uri-activation.md | 8 +++---- .../motion/xaml-property-animations.md | 6 ++--- .../performance/optimize-xaml-loading.md | 8 +++---- .../get-started/simple-photo-viewer-winui3.md | 6 ++--- 6 files changed, 30 insertions(+), 24 deletions(-) diff --git a/hub/apps/desktop/modernize/ui/visual-layer-in-desktop-apps.md b/hub/apps/desktop/modernize/ui/visual-layer-in-desktop-apps.md index fe2746cea6..0bb0a746dc 100644 --- a/hub/apps/desktop/modernize/ui/visual-layer-in-desktop-apps.md +++ b/hub/apps/desktop/modernize/ui/visual-layer-in-desktop-apps.md @@ -9,7 +9,10 @@ ms.localizationpriority: medium # Using the Visual layer in desktop apps -You can now use Windows Runtime APIs in non-UWP desktop applications to enhance the look, feel, and functionality of your WPF, Windows Forms, and C++ Win32 applications, and take advantage of the latest Windows UI features that are only available via UWP. +> [!IMPORTANT] +> This page describes the Windows SDK Visual layer (`Windows.UI.Composition`) for Win32 interop scenarios. For new WinUI 3 / Windows App SDK development, see [Visual layer overview](/windows/apps/develop/composition/visual-layer) which covers the `Microsoft.UI.Composition` namespace. + +You can now use Windows Runtime APIs in non-UWP desktop applications to enhance the look, feel, and functionality of your WPF, Windows Forms, and C++ Win32 applications, and take advantage of modern Windows UI features. For many scenarios, you can use [XAML islands](../xaml-islands/xaml-islands.md) to add modern XAML controls to your app. However, when you need to create custom experiences that go beyond the built-in controls, you can access the Visual layer APIs. @@ -29,7 +32,7 @@ You can use the Visual layer to give your application a unique look and feel, an ### Brushes -[Composition brushes](/windows/uwp/composition/composition-brushes) let you paint UI objects with solid colors, gradients, images, videos, complex effects, and more. +[Composition brushes](/windows/apps/develop/composition/composition-brushes) let you paint UI objects with solid colors, gradients, images, videos, complex effects, and more. ![An egg created with Material Creator](../images/visual-layer-interop/egg.gif) @@ -37,7 +40,7 @@ You can use the Visual layer to give your application a unique look and feel, an ### Effects -[Composition effects](/windows/uwp/composition/composition-effects) include light, shadow, and a list of filter effects. They can be animated, customized, and chained, then applied directly to visuals. The SceneLightingEffect can be combined with composition lighting to create atmosphere, depth and materials. +[Composition effects](/windows/apps/develop/composition/composition-effects) include light, shadow, and a list of filter effects. They can be animated, customized, and chained, then applied directly to visuals. The SceneLightingEffect can be combined with composition lighting to create atmosphere, depth and materials. ![Lights and material](../images/visual-layer-interop/light-interop.gif) @@ -45,7 +48,7 @@ You can use the Visual layer to give your application a unique look and feel, an ### Animations -[Composition animations](/windows/uwp/composition/composition-animation) run directly in the compositor process, independent of the UI thread. This ensures smoothness and scale, so you can run large numbers of concurrent, explicit animations. In addition to familiar KeyFrame animations to drive property changes over time, you can use expressions to set up mathematical relationships between different properties, including user input. Input driven animations let you create UI that dynamically and fluidly responds to user input, which can result in higher user engagement. +[Composition animations](/windows/apps/develop/composition/composition-animation) run directly in the compositor process, independent of the UI thread. This ensures smoothness and scale, so you can run large numbers of concurrent, explicit animations. In addition to familiar KeyFrame animations to drive property changes over time, you can use expressions to set up mathematical relationships between different properties, including user input. Input driven animations let you create UI that dynamically and fluidly responds to user input, which can result in higher user engagement. ![Short video of another user interface created with the visual layer.](../images/visual-layer-interop/swipe-scroller.gif) @@ -84,7 +87,7 @@ Learn how to use the Visual layer in your applications by experimenting with our While many Visual Layer features work the same when hosted in a desktop application as they do in a UWP app, some features do have limitations. Here are some of the limitations to be aware of: -- Effect chains rely on [Win2D](https://microsoft.github.io/Win2D/html/Introduction.htm) for the effect descriptions. The [Win2D NuGet package](https://www.nuget.org/packages/Win2D.uwp) is not supported in desktop applications, so you would need to recompile it from the [source code](https://github.com/Microsoft/Win2D). +- Effect chains rely on [Win2D](https://microsoft.github.io/Win2D/html/Introduction.htm) for the effect descriptions. For Windows App SDK apps, use the [Microsoft.Graphics.Win2D](https://www.nuget.org/packages/Microsoft.Graphics.Win2D) NuGet package. For UWP apps, use [Win2D.uwp](https://www.nuget.org/packages/Win2D.uwp). - To do hit testing, you need to do bounds calculations by walking the visual tree yourself. This is the same as the Visual Layer in UWP, except in this case there's no XAML element you can easily bind to for hit testing. - The Visual Layer does not have a primitive for rendering text. - When two different UI technologies are used together, such as WPF and the Visual Layer, they are each responsible for drawing their own pixels on the screen, and they can't share pixels. As a result, Visual Layer content is always rendered on top of other UI content. (This is known as the _airspace_ issue.) You might need to do extra coding and testing to ensure your Visual layer content resizes with the host UI and doesn't occlude other content. @@ -92,11 +95,11 @@ While many Visual Layer features work the same when hosted in a desktop applicat ## Additional Resources -- [Visual layer](/windows/uwp/composition/visual-layer) -- [Composition visual](/windows/uwp/composition/composition-visual-tree) -- [Composition brushes](/windows/uwp/composition/composition-brushes) -- [Composition effects](/windows/uwp/composition/composition-effects) -- [Composition animations](/windows/uwp/composition/composition-animation) +- [Visual layer](/windows/apps/develop/composition/visual-layer) +- [Composition visual](/windows/apps/develop/composition/composition-visual-tree) +- [Composition brushes](/windows/apps/develop/composition/composition-brushes) +- [Composition effects](/windows/apps/develop/composition/composition-effects) +- [Composition animations](/windows/apps/develop/composition/composition-animation) API reference diff --git a/hub/apps/develop/devices-sensors/scan-from-your-app.md b/hub/apps/develop/devices-sensors/scan-from-your-app.md index 1763f822db..53fdc68714 100644 --- a/hub/apps/develop/devices-sensors/scan-from-your-app.md +++ b/hub/apps/develop/devices-sensors/scan-from-your-app.md @@ -18,6 +18,9 @@ This topic describes how to scan content from your app by using a flatbed, feede - [**DeviceInformation**](/uwp/api/Windows.Devices.Enumeration.DeviceInformation) - [**DeviceClass**](/uwp/api/Windows.Devices.Enumeration.DeviceClass) +> [!NOTE] +> The code samples in this article use UWP patterns. For WinUI 3 / Windows App SDK apps, replace `Dispatcher.RunAsync` with `DispatcherQueue.TryEnqueue` and use `Microsoft.UI.Dispatching.DispatcherQueuePriority` instead of `Windows.UI.Core.CoreDispatcherPriority`. For detailed migration guidance and code examples, see [Threading functionality migration](/windows/apps/windows-app-sdk/migrate-to-windows-app-sdk/guides/threading). + To scan from your app, you must first list the available scanners by declaring a new [**DeviceInformation**](/uwp/api/Windows.Devices.Enumeration.DeviceInformation) object and getting the [**DeviceClass**](/uwp/api/Windows.Devices.Enumeration.DeviceClass) type. Only scanners that are installed locally with WIA drivers are listed and available to your app. After your app has listed available scanners, it can use the auto-configured scan settings based on the scanner type, or just scan using the available flatbed or feeder scan source. To use auto-configured settings, the scanner must be enabled for auto-configuration and must not be equipped with both a flatbed and a feeder scanner. For more info, see [Auto-Configured Scanning](/windows-hardware/drivers/image/auto-configured-scanning). diff --git a/hub/apps/develop/launch/handle-uri-activation.md b/hub/apps/develop/launch/handle-uri-activation.md index da286a5a5a..0f1b4140ba 100644 --- a/hub/apps/develop/launch/handle-uri-activation.md +++ b/hub/apps/develop/launch/handle-uri-activation.md @@ -131,12 +131,12 @@ The following code programmatically launches the app via its URI: ```csharp // Launch the URI var uri = new Uri("alsdk:"); - var success = await Windows.System.Launcher.LaunchUriAsync(uri) + var success = await Windows.System.Launcher.LaunchUriAsync(uri); ``` For more details about how to launch an app via a URI, see [Launch the default app for a URI](launch-default-app.md). -It is recommended that apps create a new XAML [Frame](/uwp/api/Windows.UI.Xaml.Controls.Frame) for each activation event that opens a new page. This way, the navigation backstack for the new XAML **Frame** will not contain any previous content that the app might have on the current window when suspended. Apps that decide to use a single XAML **Frame** for Launch and File Contracts should clear the pages on the **Frame** navigation journal before navigating to a new page. +It is recommended that apps create a new XAML [Frame](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.frame) for each activation event that opens a new page. This way, the navigation backstack for the new XAML **Frame** will not contain any previous content that the app might have on the current window when suspended. Apps that decide to use a single XAML **Frame** for Launch and File Contracts should clear the pages on the **Frame** navigation journal before navigating to a new page. When launched via Protocol activation, apps should consider including UI that allows the user to go back to the top page of the app. @@ -150,9 +150,9 @@ Any app or website can use your URI scheme name, including malicious ones. So an > [!NOTE] > When a UWP app is launched via Protocol Contract, make sure that Back button takes the user back to the screen that launched the app and not to the app's previous content. -We recommend that apps create a new XAML [**Frame**](/uwp/api/Windows.UI.Xaml.Controls.Frame) for each activation event that opens a new Uri target. This way, the navigation backstack for the new XAML **Frame** will not contain any previous content that the app might have on the current window when suspended. +We recommend that apps create a new XAML [**Frame**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.frame) for each activation event that opens a new Uri target. This way, the navigation backstack for the new XAML **Frame** will not contain any previous content that the app might have on the current window when suspended. -If you decide that you want your apps to use a single XAML [**Frame**](/uwp/api/Windows.UI.Xaml.Controls.Frame) for Launch and Protocol Contracts, clear the pages on the **Frame** navigation journal before navigating to a new page. When launched via Protocol Contract, consider including UI into your apps that allows the user to go back to the top of the app. +If you decide that you want your apps to use a single XAML [**Frame**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.frame) for Launch and Protocol Contracts, clear the pages on the **Frame** navigation journal before navigating to a new page. When launched via Protocol Contract, consider including UI into your apps that allows the user to go back to the top of the app. ## Related content diff --git a/hub/apps/develop/motion/xaml-property-animations.md b/hub/apps/develop/motion/xaml-property-animations.md index f9e949400d..f381e076f1 100644 --- a/hub/apps/develop/motion/xaml-property-animations.md +++ b/hub/apps/develop/motion/xaml-property-animations.md @@ -13,7 +13,7 @@ This article introduces properties that let you animate a XAML UIElement with th Typically, you use either XAML or Composition APIs to build animations in your Windows apps: - Use XAML constructs like [Storyboarded animations](storyboarded-animations.md), or the _*ThemeTransition_ and _*ThemeAnimation_ classes in the [Microsoft.UI.Xaml.Media.Animation](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.animation) namespace. -- Use composition animations as described in [Using the Visual Layer with XAML](/windows/uwp/composition/using-the-visual-layer-with-xaml). +- Use composition animations as described in [Using the Visual Layer with XAML](/windows/apps/develop/composition/visual-layer). Using the visual layer provides better performance than using the XAML constructs. But using [ElementCompositionPreview](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.Hosting.ElementCompositionPreview) to get the element's underlying composition [Visual](/windows/windows-app-sdk/api/winrt/microsoft.ui.composition.visual) object, and then animating the Visual with composition animations, is more complex to use. @@ -100,7 +100,7 @@ Use the [StartAnimation](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.ui This example shows how to animate the scale of a Button. ```csharp -var compositor = Window.Current.Compositor; +var compositor = CompositionTarget.GetCompositorForCurrentThread(); var animation = compositor.CreateVector3KeyFrameAnimation(); animation.InsertKeyFrame(1.0f, new Vector3(2.0f,2.0f,1.0f)); @@ -132,5 +132,5 @@ destinationButton.StartAnimation(animation); ## Related topics - [Storyboarded animations](storyboarded-animations.md) -- [Using the Visual Layer with XAML](/windows/uwp/composition/using-the-visual-layer-with-xaml) +- [Using the Visual Layer with XAML](/windows/apps/develop/composition/visual-layer) - [Transforms overview](../../develop/platform/xaml/transforms.md) diff --git a/hub/apps/develop/performance/optimize-xaml-loading.md b/hub/apps/develop/performance/optimize-xaml-loading.md index 270106fdb3..186a636d6f 100644 --- a/hub/apps/develop/performance/optimize-xaml-loading.md +++ b/hub/apps/develop/performance/optimize-xaml-loading.md @@ -27,10 +27,10 @@ Here, we look at some other ways you can reduce the number of elements your app If your XAML markup contains elements that you don't show right away, you can defer loading those elements until they are shown. For example, you can delay the creation of non-visible content such as a secondary tab in a tab-like UI. Or, you might show items in a grid view by default, but provide an option for the user to view the data in a list instead. You can delay loading the list until it's needed. -Use the [x:Load attribute](/windows/uwp/xaml-platform/x-load-attribute) instead of the [Visibility](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.visibility) property to control when an element is shown. When an element's visibility is set to **Collapsed**, then it is skipped during the render pass, but you still pay the object instance costs in memory. When you use x:Load instead, the framework does not create the object instance until it is needed, so the memory costs are even lower. The drawback is that you pay a small memory overhead (approximately 600 bytes) when the UI is not loaded. +Use the [x:Load attribute](/windows/apps/develop/platform/xaml/x-load-attribute) instead of the [Visibility](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.visibility) property to control when an element is shown. When an element's visibility is set to **Collapsed**, then it is skipped during the render pass, but you still pay the object instance costs in memory. When you use x:Load instead, the framework does not create the object instance until it is needed, so the memory costs are even lower. The drawback is that you pay a small memory overhead (approximately 600 bytes) when the UI is not loaded. > [!NOTE] -> In Windows App SDK, [x:Load](/windows/uwp/xaml-platform/x-load-attribute) is the recommended deferred-loading pattern for XAML content that is not needed immediately. +> In Windows App SDK, [x:Load](/windows/apps/develop/platform/xaml/x-load-attribute) is the recommended deferred-loading pattern for XAML content that is not needed immediately. The following examples show the difference in element count and memory use when different techniques are used to hide UI elements. A ListView and a GridView containing identical items are placed in a page's root Grid. The ListView is not visible, but the GridView is shown. The XAML in each of these examples produces the same UI on the screen. Use [tools for profiling and performance](/windows/apps/performance/choose-between-tools) to check element count and memory use in your app. @@ -146,7 +146,7 @@ In general, [ResourceDictionary](/windows/windows-app-sdk/api/winrt/microsoft.ui ### Resources with x:Name -Use the [x:Key attribute](/windows/uwp/xaml-platform/x-key-attribute) to reference your resources. Any resource with the [x:Name attribute](/windows/uwp/xaml-platform/x-name-attribute) won't benefit from the platform optimization; instead, it is instantiated as soon as the ResourceDictionary is created. This happens because x:Name tells the platform that your app needs field access to this resource, so the platform needs to create something to hold a reference to it. +Use the [x:Key attribute](/windows/apps/develop/platform/xaml/x-key-attribute) to reference your resources. Any resource with the [x:Name attribute](/windows/apps/develop/platform/xaml/x-name-attribute) won't benefit from the platform optimization; instead, it is instantiated as soon as the ResourceDictionary is created. This happens because x:Name tells the platform that your app needs field access to this resource, so the platform needs to create something to hold a reference to it. ### ResourceDictionary in a UserControl @@ -272,7 +272,7 @@ To fix the duplication, define the brush as a resource. If controls in other pag Overdrawing occurs where more than one object is drawn in the same screen pixels. Note that there is sometimes a tradeoff between this guidance and the desire to minimize element count. -Use [**DebugSettings.IsOverdrawHeatMapEnabled**](/uwp/api/windows.ui.xaml.debugsettings.isoverdrawheatmapenabled) as a visual diagnostic. You might find objects being drawn that you didn't know were in the scene. +Use [**DebugSettings.IsOverdrawHeatMapEnabled**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.debugsettings.isoverdrawheatmapenabled) as a visual diagnostic. You might find objects being drawn that you didn't know were in the scene. ### Transparent or hidden elements diff --git a/hub/apps/get-started/simple-photo-viewer-winui3.md b/hub/apps/get-started/simple-photo-viewer-winui3.md index 5ab3cd8cef..ff30bf2cf9 100644 --- a/hub/apps/get-started/simple-photo-viewer-winui3.md +++ b/hub/apps/get-started/simple-photo-viewer-winui3.md @@ -90,7 +90,7 @@ For background info about some of the types we've just mentioned, see [Layout pa A *model* (in the sense of models, views, and view models) is a class that to some degree represents a real-world object or concept (such as a bank account). It's an *abstraction* of that real-world thing. In this section we'll be adding to our project a new class called **ImageFileInfo**. **ImageFileInfo** will be a model of an image file, such as a photo. This section will take us a step closer to being able to display photos in the app's user interface (UI). > [!TIP] -> In preparation for the code example below, let's introduce the term *observable*. A property that can be dynamically bound to a XAML control (so that the UI updates each time the property value changes) is known as an *observable* property. This idea is based on the software design pattern known as the observer pattern. In the app that we build in this tutorial, the properties of our **ImageFileInfo** model won't change. But even so, we'll show how to make **ImageFileInfo** observable, by having it implement the [**INotifyPropertyChanged**](/uwp/api/windows.ui.xaml.data.inotifypropertychanged) interface. +> In preparation for the code example below, let's introduce the term *observable*. A property that can be dynamically bound to a XAML control (so that the UI updates each time the property value changes) is known as an *observable* property. This idea is based on the software design pattern known as the observer pattern. In the app that we build in this tutorial, the properties of our **ImageFileInfo** model won't change. But even so, we'll show how to make **ImageFileInfo** observable, by having it implement the [**INotifyPropertyChanged**](/dotnet/api/system.componentmodel.inotifypropertychanged) interface. ### [C#](#tab/cs/) @@ -785,7 +785,7 @@ When you build and run this time, and experiment with adjusting the width of the Now it's time to move our sketch to a higher level of fidelity; and that means replacing the placeholder image with the real ones, and replacing the "lorem ipsum"-style placeholder text with real data. Let's take care of the images first. > [!IMPORTANT] -> The technique we'll use to display the photos in the `Assets\Samples` folder involves updating the **GridView**'s items progressively. Specifically, that's the code in the **ImageGridView_ContainerContentChanging** and **ShowImage** methods in the code example below, including use of the **ContainerContentChangingEventArgs.InRecycleQueue** and **ContainerContentChangingEventArgs.Phase** properties. For more info, see [ListView and GridView UI optimization](/windows/uwp/debug-test-perf/optimize-gridview-and-listview). But in a nutshell, the **GridView** will let us know (by way of an event) when one of its item containers is ready to display its item. And then we'll keep track of which phase of its update lifecycle the item container is in so that we can determine when it's ready to display photo data. +> The technique we'll use to display the photos in the `Assets\Samples` folder involves updating the **GridView**'s items progressively. Specifically, that's the code in the **ImageGridView_ContainerContentChanging** and **ShowImage** methods in the code example below, including use of the **ContainerContentChangingEventArgs.InRecycleQueue** and **ContainerContentChangingEventArgs.Phase** properties. For more info, see [ListView and GridView UI optimization](/windows/apps/develop/ui/controls/optimize-listview-gridview). But in a nutshell, the **GridView** will let us know (by way of an event) when one of its item containers is ready to display its item. And then we'll keep track of which phase of its update lifecycle the item container is in so that we can determine when it's ready to display photo data. ### [C#](#tab/cs/) @@ -928,7 +928,7 @@ In this section we'll use one-time data-bindings. A one-time binding is great fo An `x:Bind` expression links the value of a UI property with the value of a **data-object** property. Of course, that depends on first setting `x:DataType` to the type of that **data-object** so that the tooling and the runtime know what properties are available to bind to. - For more info, see [{x:Bind} markup extension](/windows/apps/develop/platform/xaml/x-bind-markup-extension) and [Data binding in depth](/windows/uwp/data-binding/data-binding-in-depth). + For more info, see [{x:Bind} markup extension](/windows/apps/develop/platform/xaml/x-bind-markup-extension) and [Data binding in depth](/windows/apps/develop/data-binding/data-binding-in-depth). 1. In the same way, replace the values of the other **TextBlock**s and the **RatingControl**. Here's the result: