From 953c973a0ab7b17f8e86ce4efc06ff2aff3c46b0 Mon Sep 17 00:00:00 2001 From: Qiutong Shen Date: Thu, 23 Apr 2026 11:14:01 +0800 Subject: [PATCH 1/3] Migrate input docs from UWP to WinUI 3 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - respond-to-the-presence-of-the-touch-keyboard.md: - Update AutomationPeer/AutomationControlType links to WinUI 3 API - Update C# namespaces: Windows.UI.Xaml.* → Microsoft.UI.Xaml.* - Update C++/WinRT namespaces: Windows::UI::Xaml::* → Microsoft::UI::Xaml::* - Update prerequisite link to WinUI 3 getting started guide - Replace obsolete MSDN archive samples with WinUI Gallery reference - guidelines-for-visualfeedback.md: - Update UserControl link to WinUI 3 API - Fix Thickness link (was WPF System.Windows, now WinUI 3) - Add notes about UWP sample repository Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../input/guidelines-for-visualfeedback.md | 7 ++++-- ...d-to-the-presence-of-the-touch-keyboard.md | 24 +++++++++---------- 2 files changed, 17 insertions(+), 14 deletions(-) diff --git a/hub/apps/develop/input/guidelines-for-visualfeedback.md b/hub/apps/develop/input/guidelines-for-visualfeedback.md index 6b2fe5c776..9fbdcca046 100644 --- a/hub/apps/develop/input/guidelines-for-visualfeedback.md +++ b/hub/apps/develop/input/guidelines-for-visualfeedback.md @@ -21,8 +21,8 @@ Use visual feedback to show users when their interactions are detected, interpre - Try to limit modifications of a control template to those directly related to your design intent, as extensive changes can impact the performance and accessibility of both the control and your application. - See [XAML styles](../platform/xaml/xaml-styles.md) for more info on customizing the properties of a control, including visual state properties. - - See the [UserControl Class](/uwp/api/windows.ui.xaml.controls.usercontrol) for details on making changes to a control template - - Consider creating your own custom templated control if you need to make significant changes to a control template. For an example of a custom templated control, see the [Custom Edit Control sample](https://github.com/Microsoft/Windows-universal-samples/tree/master/Samples/CustomEditControl). + - See the [UserControl Class](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.usercontrol) for details on making changes to a control template + - Consider creating your own custom templated control if you need to make significant changes to a control template. For an example of a custom templated control, see the [Custom Edit Control sample](https://github.com/Microsoft/Windows-universal-samples/tree/master/Samples/CustomEditControl) (UWP sample). - Don't use touch visualizations in situations where they might interfere with the use of the app. For more info, see [**ShowGestureFeedback**](/uwp/api/windows.ui.input.gesturerecognizer.showgesturefeedback). - Don't display feedback unless it is absolutely necessary. Keep the UI clean and uncluttered by not showing visual feedback unless you are adding value that is not available elsewhere. - Try not to dramatically customize the visual feedback behaviors of the built-in Windows gestures, as this can create an inconsistent and confusing user experience. @@ -120,6 +120,9 @@ To change the colors on a per-control basis, just edit the focus visual properti - [User interaction mode sample](https://github.com/Microsoft/Windows-universal-samples/tree/master/Samples/UserInteractionMode) - [Focus visuals sample](https://github.com/Microsoft/Windows-universal-samples/tree/master/Samples/XamlFocusVisuals) +> [!NOTE] +> The samples above are from the UWP Windows-universal-samples repository. For WinUI 3 examples, see the [WinUI Gallery](https://github.com/microsoft/WinUI-Gallery). + ### Archive samples - [Input: XAML user input events sample](https://github.com/microsoftarchive/msdn-code-gallery-microsoft/tree/411c271e537727d737a53fa2cbe99eaecac00cc0/Official%20Windows%20Platform%20Sample/Input%20XAML%20user%20input%20events%20sample) diff --git a/hub/apps/develop/input/respond-to-the-presence-of-the-touch-keyboard.md b/hub/apps/develop/input/respond-to-the-presence-of-the-touch-keyboard.md index 060b6ab244..6bc90b51a7 100644 --- a/hub/apps/develop/input/respond-to-the-presence-of-the-touch-keyboard.md +++ b/hub/apps/develop/input/respond-to-the-presence-of-the-touch-keyboard.md @@ -16,7 +16,7 @@ Learn how to tailor the UI of your app when showing or hiding the touch keyboard ### Important APIs -- [AutomationPeer](/uwp/api/Windows.UI.Xaml.Automation.Peers.AutomationPeer) +- [AutomationPeer](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.automation.peers.automationpeer) - [InputPane](/uwp/api/Windows.UI.ViewManagement.InputPane) :::image type="content" source="images/keyboard/default.png" alt-text="The touch keyboard in default layout mode."::: @@ -25,7 +25,7 @@ Learn how to tailor the UI of your app when showing or hiding the touch keyboard The touch keyboard enables text entry for devices that support touch. Windows app text input controls invoke the touch keyboard by default when a user taps on an editable input field. The touch keyboard typically remains visible while the user navigates between controls in a form, but this behavior can vary based on the other control types within the form. -To support corresponding touch keyboard behavior in a custom text input control that does not derive from a standard text input control, you must use the AutomationPeer class to expose your controls to Microsoft UI Automation and implement the correct UI Automation control patterns. See [Keyboard accessibility](../../design/accessibility/keyboard-accessibility.md) and [Custom automation peers](../../design/accessibility/custom-automation-peers.md). +To support corresponding touch keyboard behavior in a custom text input control that does not derive from a standard text input control, you must use the [AutomationPeer](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.automation.peers.automationpeer) class to expose your controls to Microsoft UI Automation and implement the correct UI Automation control patterns. See [Keyboard accessibility](../../design/accessibility/keyboard-accessibility.md) and [Custom automation peers](../../design/accessibility/custom-automation-peers.md). Once this support has been added to your custom control, you can respond appropriately to the presence of the touch keyboard. @@ -37,7 +37,7 @@ You should have a basic understanding of standard keyboard interactions, handlin If you're new to developing Windows apps, have a look through these topics to get familiar with the technologies discussed here. -- [Create your first app](/windows/uwp/get-started/your-first-app) +- [Create your first WinUI 3 app](/windows/apps/get-started/start-here) - Learn about events with [Events and routed events overview](/windows/apps/develop/platform/xaml/events-and-routed-events-overview) **User experience guidelines:** @@ -50,7 +50,7 @@ Here are a few basic recommendations for custom text input controls. - Display the touch keyboard throughout the entire interaction with your form. -- Ensure that your custom controls have the appropriate UI Automation [AutomationControlType](/uwp/api/Windows.UI.Xaml.Automation.Peers.AutomationControlType) for the keyboard to persist when focus moves from a text input field while in the context of text entry. For example, if you have a menu that's opened in the middle of a text-entry scenario, and you want the keyboard to persist, the menu must have the **AutomationControlType** of Menu. +- Ensure that your custom controls have the appropriate UI Automation [AutomationControlType](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.automation.peers.automationcontroltype) for the keyboard to persist when focus moves from a text input field while in the context of text entry. For example, if you have a menu that's opened in the middle of a text-entry scenario, and you want the keyboard to persist, the menu must have the **AutomationControlType** of Menu. - Don't manipulate UI Automation properties to control the touch keyboard. Other accessibility tools rely on the accuracy of UI Automation properties. @@ -72,10 +72,10 @@ Here's an example of attaching event handlers for the [Showing](/uwp/api/windows ```csharp using Windows.UI.ViewManagement; -using Windows.UI.Xaml.Controls; -using Windows.UI.Xaml.Media; +using Microsoft.UI.Xaml.Controls; +using Microsoft.UI.Xaml.Media; using Windows.Foundation; -using Windows.UI.Xaml.Navigation; +using Microsoft.UI.Xaml.Navigation; namespace SDKTemplate { @@ -131,7 +131,7 @@ Scenario2_ShowHideEvents::Scenario2_ShowHideEvents() InitializeComponent(); } -void Scenario2_ShowHideEvents::OnNavigatedTo(Windows::UI::Xaml::Navigation::NavigationEventArgs const& e) +void Scenario2_ShowHideEvents::OnNavigatedTo(Microsoft::UI::Xaml::Navigation::NavigationEventArgs const& e) { auto inputPane{ Windows::UI::ViewManagement::InputPane::GetForCurrentView() }; // Subscribe to Showing/Hiding events @@ -139,7 +139,7 @@ void Scenario2_ShowHideEvents::OnNavigatedTo(Windows::UI::Xaml::Navigation::Navi m_hidingEventToken = inputPane.Hiding({ this, &Scenario2_ShowHideEvents::OnHiding }); } -void Scenario2_ShowHideEvents::OnNavigatedFrom(Windows::UI::Xaml::Navigation::NavigationEventArgs const& e) +void Scenario2_ShowHideEvents::OnNavigatedFrom(Microsoft::UI::Xaml::Navigation::NavigationEventArgs const& e) { auto inputPane{ Windows::UI::ViewManagement::InputPane::GetForCurrentView() }; // Unsubscribe from Showing/Hiding events @@ -166,9 +166,9 @@ using namespace SDKTemplate; using namespace Platform; using namespace Windows::Foundation; using namespace Windows::UI::ViewManagement; -using namespace Windows::UI::Xaml; -using namespace Windows::UI::Xaml::Controls; -using namespace Windows::UI::Xaml::Navigation; +using namespace Microsoft::UI::Xaml; +using namespace Microsoft::UI::Xaml::Controls; +using namespace Microsoft::UI::Xaml::Navigation; Scenario2_ShowHideEvents::Scenario2_ShowHideEvents() { From 2fe40d86032d5971e9e6a3d447d1dffe44f7530f Mon Sep 17 00:00:00 2001 From: Qiutong Shen Date: Thu, 23 Apr 2026 14:47:57 +0800 Subject: [PATCH 2/3] Fix Thickness link - WPF to WinUI 3 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- hub/apps/develop/input/guidelines-for-visualfeedback.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hub/apps/develop/input/guidelines-for-visualfeedback.md b/hub/apps/develop/input/guidelines-for-visualfeedback.md index 9fbdcca046..43525a1f7b 100644 --- a/hub/apps/develop/input/guidelines-for-visualfeedback.md +++ b/hub/apps/develop/input/guidelines-for-visualfeedback.md @@ -69,7 +69,7 @@ To change the thickness of either border type (primary or secondary) use the **F ``` ![High visibility focus visual margin thicknesses](images/focus-margin.png) -The margin is a property of type [**Thickness**](/dotnet/api/system.windows.thickness), and therefore the margin can be customized to appear only on certain sides of the control. See below: +The margin is a property of type [**Thickness**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.thickness), and therefore the margin can be customized to appear only on certain sides of the control. See below: ![High visibility focus visual margin thickness bottom only](images/focus-thickness-side.png) The margin is the space between the control's visual bounds and the start of the focus visuals *secondary border*. The default margin is **1px** away from the control bounds. You can edit this margin on a per-control basis, by changing the **FocusVisualMargin** property: From 7d8475c2eeb5505a95ed204dff89dda399c07a3b Mon Sep 17 00:00:00 2001 From: Qiutong Shen Date: Thu, 23 Apr 2026 14:55:04 +0800 Subject: [PATCH 3/3] Complete WinUI 3 migration for input docs guidelines-for-visualfeedback.md: - Add note about Windows SDK vs WinUI 3 input APIs (Issue 1) - UserControl link already fixed (Issue 2) - UWP sample note already added (Issue 3) - Thickness link already fixed (Issue 4) respond-to-the-presence-of-the-touch-keyboard.md: - AutomationPeer link already fixed (Issue 1) - C# namespaces already updated (Issue 2) - C++/WinRT namespaces already updated (Issue 3) - Add note about InputPane.GetForCurrentView() for WinUI 3 (Issue 4) - Prerequisites link already fixed (Issue 5) - Add note about archive samples being legacy (Issue 6) - Add WinUI Gallery sample link Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- hub/apps/develop/input/guidelines-for-visualfeedback.md | 3 +++ .../respond-to-the-presence-of-the-touch-keyboard.md | 9 ++++++++- 2 files changed, 11 insertions(+), 1 deletion(-) diff --git a/hub/apps/develop/input/guidelines-for-visualfeedback.md b/hub/apps/develop/input/guidelines-for-visualfeedback.md index 43525a1f7b..0887997651 100644 --- a/hub/apps/develop/input/guidelines-for-visualfeedback.md +++ b/hub/apps/develop/input/guidelines-for-visualfeedback.md @@ -16,6 +16,9 @@ ms.localizationpriority: medium Use visual feedback to show users when their interactions are detected, interpreted, and handled. Visual feedback can help users by encouraging interaction. It indicates the success of an interaction, which improves the user's sense of control. It also relays system status and reduces errors. > **Important APIs**: [**Windows.Devices.Input**](/uwp/api/Windows.Devices.Input), [**Windows.UI.Input**](/uwp/api/Windows.UI.Input), [**Windows.UI.Core**](/uwp/api/Windows.UI.Core) +> +> [!NOTE] +> The `Windows.Devices.Input` and `Windows.UI.Input` APIs are Windows SDK (WinRT) APIs that work in both UWP and WinUI 3 apps. For WinUI 3-specific input APIs, see [Microsoft.UI.Input](/windows/windows-app-sdk/api/winrt/microsoft.ui.input). ## Recommendations diff --git a/hub/apps/develop/input/respond-to-the-presence-of-the-touch-keyboard.md b/hub/apps/develop/input/respond-to-the-presence-of-the-touch-keyboard.md index 6bc90b51a7..d601a99362 100644 --- a/hub/apps/develop/input/respond-to-the-presence-of-the-touch-keyboard.md +++ b/hub/apps/develop/input/respond-to-the-presence-of-the-touch-keyboard.md @@ -70,6 +70,9 @@ Here are a few basic recommendations for custom text input controls. Here's an example of attaching event handlers for the [Showing](/uwp/api/windows.ui.viewmanagement.inputpane.showing) and [Hiding](/uwp/api/windows.ui.viewmanagement.inputpane.hiding) events of the touch keyboard. +> [!NOTE] +> The code samples use `InputPane.GetForCurrentView()`, which is a UWP-era API. For WinUI 3 desktop apps, consider using [InputPane.GetForWindow](/uwp/api/windows.ui.viewmanagement.inputpane.getforwindow) with your window's HWND instead. + ```csharp using Windows.UI.ViewManagement; using Microsoft.UI.Xaml.Controls; @@ -212,10 +215,14 @@ void Scenario2_ShowHideEvents::OnHiding(InputPane^ /*sender*/, InputPaneVisibili ### Samples -- [Touch keyboard sample](https://github.com/Microsoft/Windows-universal-samples/tree/master/Samples/TouchKeyboard) +- [Touch keyboard sample](https://github.com/Microsoft/Windows-universal-samples/tree/master/Samples/TouchKeyboard) (UWP) +- [WinUI Gallery](https://github.com/microsoft/WinUI-Gallery) - For WinUI 3 control examples ### Archive samples +> [!NOTE] +> The following samples are from archived repositories and target Windows 8 or early UWP. They may not compile in modern WinUI 3 projects. + - [Input: Touch keyboard sample](https://github.com/Microsoft/Windows-universal-samples/tree/master/Samples/TouchKeyboard) - [Responding to the appearance of the on-screen keyboard sample](https://github.com/microsoftarchive/msdn-code-gallery-microsoft/tree/411c271e537727d737a53fa2cbe99eaecac00cc0/Official%20Windows%20Platform%20Sample/Responding%20to%20the%20appearance%20of%20the%20on-screen%20keyboard%20sample) - [XAML text editing sample](https://github.com/microsoftarchive/msdn-code-gallery-microsoft/tree/411c271e537727d737a53fa2cbe99eaecac00cc0/Official%20Windows%20Platform%20Sample/Windows%208%20app%20samples/%5BVB%5D-Windows%208%20app%20samples/VB/Windows%208%20app%20samples/XAML%20text%20editing%20sample%20(Windows%208))