From 5b12eb030784da687d8b5ba80e1cfacac2e7738d Mon Sep 17 00:00:00 2001 From: Qiutong Shen Date: Thu, 23 Apr 2026 11:07:32 +0800 Subject: [PATCH 1/2] Migrate XAML platform docs from UWP to WinUI 3 - xaml-resource-dictionary.md: - Update C++/WinRT code to use Microsoft::UI::Xaml namespace - Update C# code to use WinUI 3 window pattern (m_window instead of Window.Current) - Replace Windows.UI.Color.FromArgb with Microsoft.UI.Colors.Green - items-repeater.md: - Remove muxc: namespace prefix (WinUI 2 pattern, unnecessary in WinUI 3) - Remove ItemsRepeaterScrollHost comments (not needed in WinUI 3) - Fix inconsistent variable names (itemsSource -> MyItemsSource, loadingIndicator -> myLoadingIndicator) - Update data binding link to WinUI 3 docs - Fix image path to use local reference - events-and-routed-events-overview.md: - Update C++/WinRT namespaces to Microsoft::UI::Xaml - Fix incorrect MouseEventHandler -> PointerEventHandler - Remove duplicate PointerWheelChanged entry - Replace MediaElement/WebView with MediaPlayerElement/WebView2 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../xaml/events-and-routed-events-overview.md | 11 ++- .../platform/xaml/xaml-resource-dictionary.md | 21 ++--- .../develop/ui/controls/items-repeater.md | 78 +++++++++---------- 3 files changed, 52 insertions(+), 58 deletions(-) diff --git a/hub/apps/develop/platform/xaml/events-and-routed-events-overview.md b/hub/apps/develop/platform/xaml/events-and-routed-events-overview.md index 5b512fdf9f..de66ef0b8c 100644 --- a/hub/apps/develop/platform/xaml/events-and-routed-events-overview.md +++ b/hub/apps/develop/platform/xaml/events-and-routed-events-overview.md @@ -59,15 +59,15 @@ End Sub ``` ```cppwinrt -void winrt::MyNamespace::implementation::BlankPage::ShowUpdatesButton_Click(Windows::Foundation::IInspectable const& sender, Windows::UI::Xaml::RoutedEventArgs const& e) +void winrt::MyNamespace::implementation::BlankPage::ShowUpdatesButton_Click(Windows::Foundation::IInspectable const& sender, Microsoft::UI::Xaml::RoutedEventArgs const& e) { - auto b{ sender.as() }; + auto b{ sender.as() }; // More logic to do here. } ``` ```cpp -void MyNamespace::BlankPage::ShowUpdatesButton_Click(Platform::Object^ sender, Windows::UI::Xaml::RoutedEventArgs^ e) +void MyNamespace::BlankPage::ShowUpdatesButton_Click(Platform::Object^ sender, Microsoft::UI::Xaml::RoutedEventArgs^ e) { Button^ b = (Button^) sender; //more logic to do here... @@ -130,7 +130,7 @@ void LayoutRoot_Loaded(object sender, RoutedEventArgs e) void LayoutRoot_Loaded(object sender, RoutedEventArgs e) { textBlock1.PointerEntered += new PointerEventHandler(textBlock1_PointerEntered); - textBlock1.PointerExited += new MouseEventHandler(textBlock1_PointerExited); + textBlock1.PointerExited += new PointerEventHandler(textBlock1_PointerExited); } ``` @@ -228,7 +228,6 @@ The Windows Runtime supports the concept of a routed event for a set of events t - [**PointerWheelChanged**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.pointerwheelchanged) - [**PreviewKeyDown**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.previewkeydown) - [**PreviewKeyUp**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.previewkeyup) -- [**PointerWheelChanged**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.pointerwheelchanged) - [**RightTapped**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.righttapped) - [**Tapped**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.tapped) @@ -280,7 +279,7 @@ Determining whether and where in UI an element is visible to mouse, touch, and s - If the element is a control, its [**IsEnabled**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.control.isenabled) property value must be **true**. - The element must have actual dimensions in layout. An element where either [**ActualHeight**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.frameworkelement.actualheight) and [**ActualWidth**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.frameworkelement.actualwidth) are 0 won't fire input events. -Some controls have special rules for hit testing. For example, [**TextBlock**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.Controls.TextBlock) has no **Background** property, but is still hit testable within the entire region of its dimensions. [**Image**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.Controls.Image) and [**MediaElement**](/uwp/api/windows.ui.xaml.controls.mediaelement) controls are hit testable over their defined rectangle dimensions, regardless of transparent content such as alpha channel in the media source file being displayed. [**WebView**](/uwp/api/windows.ui.xaml.controls.webview) controls have special hit testing behavior because the input can be handled by the hosted HTML and fire script events. +Some controls have special rules for hit testing. For example, [**TextBlock**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.Controls.TextBlock) has no **Background** property, but is still hit testable within the entire region of its dimensions. [**Image**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.Controls.Image) and [**MediaPlayerElement**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.mediaplayerelement) controls are hit testable over their defined rectangle dimensions, regardless of transparent content such as alpha channel in the media source file being displayed. [**WebView2**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.webview2) controls have special hit testing behavior because the input can be handled by the hosted HTML and fire script events. Most [**Panel**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.Controls.Panel) classes and [**Border**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.Controls.Border) are not hit-testable in their own background, but can still handle the user input events that are routed from the elements that they contain. diff --git a/hub/apps/develop/platform/xaml/xaml-resource-dictionary.md b/hub/apps/develop/platform/xaml/xaml-resource-dictionary.md index 1f70560afb..f4a7efc612 100644 --- a/hub/apps/develop/platform/xaml/xaml-resource-dictionary.md +++ b/hub/apps/develop/platform/xaml/xaml-resource-dictionary.md @@ -142,7 +142,7 @@ This example shows how to retrieve the `redButtonStyle` resource out of a page's MainPage::MainPage() { InitializeComponent(); - Windows::UI::Xaml::Style style = Resources().TryLookup(winrt::box_value(L"redButtonStyle")).as(); + Microsoft::UI::Xaml::Style style = Resources().TryLookup(winrt::box_value(L"redButtonStyle")).as(); } ``` @@ -178,9 +178,9 @@ To look up app-wide resources from code, use **Application.Current.Resources** t MainPage::MainPage() { InitializeComponent(); - Windows::UI::Xaml::Style style = Application::Current().Resources() - .TryLookup(winrt::box_value(L"appButtonStyle")) - .as(); + Microsoft::UI::Xaml::Style style = Application::Current().Resources() + .TryLookup(winrt::box_value(L"appButtonStyle")) + .as(); } ``` @@ -200,14 +200,16 @@ sealed partial class App : Application { protected override void OnLaunched(LaunchActivatedEventArgs e) { - Frame rootFrame = Window.Current.Content as Frame; - if (rootFrame == null) + // In WinUI 3, use m_window (a field you create) instead of Window.Current + if (m_window.Content is not Frame rootFrame) { - SolidColorBrush brush = new SolidColorBrush(Windows.UI.Color.FromArgb(255, 0, 255, 0)); // green + SolidColorBrush brush = new SolidColorBrush(Microsoft.UI.Colors.Green); this.Resources["brush"] = brush; // … Other code that VS generates for you … } } + + private Window m_window; } ``` @@ -217,7 +219,8 @@ sealed partial class App : Application void App::OnLaunched(LaunchActivatedEventArgs const& e) { Frame rootFrame{ nullptr }; - auto content = Window::Current().Content(); + // In WinUI 3, use m_window (a member variable you create) instead of Window::Current() + auto content = m_window.Content(); if (content) { rootFrame = content.try_as(); @@ -227,7 +230,7 @@ void App::OnLaunched(LaunchActivatedEventArgs const& e) // just ensure that the window is active if (rootFrame == nullptr) { - Windows::UI::Xaml::Media::SolidColorBrush brush{ Windows::UI::ColorHelper::FromArgb(255, 0, 255, 0) }; + Microsoft::UI::Xaml::Media::SolidColorBrush brush{ Microsoft::UI::Colors::Green() }; Resources().Insert(winrt::box_value(L"brush"), winrt::box_value(brush)); // … Other code that VS generates for you … ``` diff --git a/hub/apps/develop/ui/controls/items-repeater.md b/hub/apps/develop/ui/controls/items-repeater.md index b55a7971f2..327915d5a3 100644 --- a/hub/apps/develop/ui/controls/items-repeater.md +++ b/hub/apps/develop/ui/controls/items-repeater.md @@ -56,7 +56,7 @@ ItemsRepeater itemsRepeater1 = new ItemsRepeater(); itemsRepeater1.ItemsSource = Items; ``` -You can also bind the **ItemsSource** property to a collection in XAML. For more info about data binding, see [Data binding overview](/windows/uwp/data-binding/data-binding-quickstart). +You can also bind the **ItemsSource** property to a collection in XAML. For more info about data binding, see [Data binding overview](/windows/apps/develop/data-binding/data-binding-overview). ```xaml @@ -209,14 +209,14 @@ private async void ScrollViewer_ViewChanged(object sender, ScrollViewerViewChang // trigger if within 2 viewports of the end if (distanceToEnd <= 2.0 * scroller.ViewportHeight - && MyItemsSource.HasMore && !itemsSource.Busy) + && MyItemsSource.HasMore && !MyItemsSource.Busy) { // show an indeterminate progress UI myLoadingIndicator.Visibility = Visibility.Visible; await MyItemsSource.LoadMoreItemsAsync(/*DataFetchSize*/); - loadingIndicator.Visibility = Visibility.Collapsed; + myLoadingIndicator.Visibility = Visibility.Collapsed; } } } @@ -237,12 +237,11 @@ You can set the [Spacing](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.c This example shows how to set the ItemsRepeater.Layout property to a StackLayout with horizontal orientation and spacing of 8 pixels. ```xaml - - - - - - + + + + + ``` ### UniformGridLayout @@ -295,15 +294,14 @@ This image shows the effect of the **ItemsStretch** values in a vertical layout This example shows how to set the **ItemsRepeater.Layout** property to a **UniformGridLayout**. ```xaml - - - - + - - + + ``` ## Lifecycle events @@ -322,16 +320,15 @@ In a virtualizing control, you cannot rely on Loaded/Unloaded events because the This example shows how you could use these events to attach a custom selection service to track item selection in a custom control that uses ItemsRepeater to display items. ```xaml - ... - - + ... @@ -537,7 +534,6 @@ You can use the [ItemsRepeater](/windows/windows-app-sdk/api/winrt/microsoft.ui. This example shows how to place an [ItemsRepeater](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.itemsrepeater) in the template of a custom control named _MediaCollectionView_ and expose its properties. ```xaml -