diff --git a/hub/apps/develop/input/guidelines-for-visualfeedback.md b/hub/apps/develop/input/guidelines-for-visualfeedback.md index 6b2fe5c776..0887997651 100644 --- a/hub/apps/develop/input/guidelines-for-visualfeedback.md +++ b/hub/apps/develop/input/guidelines-for-visualfeedback.md @@ -16,13 +16,16 @@ 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 - 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. @@ -69,7 +72,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: @@ -120,6 +123,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..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 @@ -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. @@ -70,12 +70,15 @@ 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 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 +134,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 +142,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 +169,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() { @@ -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))