From 8384ef1f6e225f59be65f17e0ec657da839d795c Mon Sep 17 00:00:00 2001 From: Qiutong Shen Date: Thu, 21 May 2026 13:40:26 +0800 Subject: [PATCH] =?UTF-8?q?fix(develop):=20UWP=E2=86=92WinAppSDK=20link=20?= =?UTF-8?q?migration=20=E2=80=94=20input?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../input/focus-navigation-programmatic.md | 68 +++++++------- hub/apps/develop/input/focus-navigation.md | 48 +++++----- .../input/guidelines-for-optical-zoom.md | 4 +- .../input/guidelines-for-visualfeedback.md | 4 +- .../develop/input/handle-pointer-input.md | 94 +++++++++---------- .../develop/input/identify-input-devices.md | 8 +- .../develop/input/keyboard-accelerators.md | 46 ++++----- hub/apps/develop/input/keyboard-events.md | 86 ++++++++--------- hub/apps/develop/input/mouse-interactions.md | 80 ++++++++-------- hub/apps/develop/input/text-scaling.md | 6 +- .../develop/input/touch-developer-guide.md | 84 ++++++++--------- .../develop/input/touchpad-interactions.md | 2 +- ...nput-scope-to-change-the-touch-keyboard.md | 36 +++---- 13 files changed, 283 insertions(+), 283 deletions(-) diff --git a/hub/apps/develop/input/focus-navigation-programmatic.md b/hub/apps/develop/input/focus-navigation-programmatic.md index 0ea0679a0b..3a7a8a2d7b 100644 --- a/hub/apps/develop/input/focus-navigation-programmatic.md +++ b/hub/apps/develop/input/focus-navigation-programmatic.md @@ -15,18 +15,18 @@ ms.localizationpriority: medium ![Keyboard, remote, and D-pad](images/dpad-remote/dpad-remote-keyboard.png) -To move focus programmatically in your Windows application, you can use either the [FocusManager.TryMoveFocus](/uwp/api/windows.ui.xaml.input.focusmanager#Windows_UI_Xaml_Input_FocusManager_TryMoveFocus_Windows_UI_Xaml_Input_FocusNavigationDirection_) method or the [FindNextElement](/uwp/api/windows.ui.xaml.input.focusmanager#Windows_UI_Xaml_Input_FocusManager_FindNextElement_Windows_UI_Xaml_Input_FocusNavigationDirection_) method. +To move focus programmatically in your Windows application, you can use either the [FocusManager.TryMoveFocus](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.focusmanager) method or the [FindNextElement](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.focusmanager) method. -[TryMoveFocus](/uwp/api/windows.ui.xaml.input.focusmanager#Windows_UI_Xaml_Input_FocusManager_TryMoveFocus_Windows_UI_Xaml_Input_FocusNavigationDirection_) attempts to change focus from the element with focus to the next focusable element in the specified direction, while [FindNextElement](/uwp/api/windows.ui.xaml.input.focusmanager#Windows_UI_Xaml_Input_FocusManager_FindNextElement_Windows_UI_Xaml_Input_FocusNavigationDirection_) retrieves the element (as a [DependencyObject](/uwp/api/windows.ui.xaml.dependencyobject)) that will receive focus based on the specified navigation direction (directional navigation only, cannot be used to emulate tab navigation). +[TryMoveFocus](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.focusmanager) attempts to change focus from the element with focus to the next focusable element in the specified direction, while [FindNextElement](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.focusmanager) retrieves the element (as a [DependencyObject](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.dependencyobject)) that will receive focus based on the specified navigation direction (directional navigation only, cannot be used to emulate tab navigation). > [!NOTE] -> We recommend using the [FindNextElement](/uwp/api/windows.ui.xaml.input.focusmanager#Windows_UI_Xaml_Input_FocusManager_FindNextElement_Windows_UI_Xaml_Input_FocusNavigationDirection_) method instead of [FindNextFocusableElement](/uwp/api/windows.ui.xaml.input.focusmanager#Windows_UI_Xaml_Input_FocusManager_FindNextFocusableElement_Windows_UI_Xaml_Input_FocusNavigationDirection_) because FindNextFocusableElement retrieves a UIElement, which returns null if the next focusable element is not a UIElement (such as a Hyperlink object). +> We recommend using the [FindNextElement](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.focusmanager) method instead of [FindNextFocusableElement](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.focusmanager) because FindNextFocusableElement retrieves a UIElement, which returns null if the next focusable element is not a UIElement (such as a Hyperlink object). ## Find a focus candidate within a scope -You can customize the focus navigation behavior for both [TryMoveFocus](/uwp/api/windows.ui.xaml.input.focusmanager#Windows_UI_Xaml_Input_FocusManager_TryMoveFocus_Windows_UI_Xaml_Input_FocusNavigationDirection_) and [FindNextElement](/uwp/api/windows.ui.xaml.input.focusmanager#Windows_UI_Xaml_Input_FocusManager_FindNextElement_Windows_UI_Xaml_Input_FocusNavigationDirection_), including searching for the next focus candidate within a specific UI tree or excluding specific elements from consideration. +You can customize the focus navigation behavior for both [TryMoveFocus](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.focusmanager) and [FindNextElement](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.focusmanager), including searching for the next focus candidate within a specific UI tree or excluding specific elements from consideration. -This example uses a TicTacToe game to demonstrate the [TryMoveFocus](/uwp/api/windows.ui.xaml.input.focusmanager#Windows_UI_Xaml_Input_FocusManager_TryMoveFocus_Windows_UI_Xaml_Input_FocusNavigationDirection_) and [FindNextElement](/uwp/api/windows.ui.xaml.input.focusmanager#Windows_UI_Xaml_Input_FocusManager_FindNextElement_Windows_UI_Xaml_Input_FocusNavigationDirection_) methods. +This example uses a TicTacToe game to demonstrate the [TryMoveFocus](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.focusmanager) and [FindNextElement](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.focusmanager) methods. ```xaml [!Important] > If one or more transforms are applied to the descendants of **SearchRoot** that place them outside of the directional area, these elements are still considered candidates. -- [ExclusionRect](/uwp/api/windows.ui.xaml.input.findnextelementoptions#Windows_UI_Xaml_Input_FindNextElementOptions_ExclusionRect) - Focus navigation candidates are identified using a "fictitious" bounding rectangle where all overlapping objects are excluded from navigation focus. This rectangle is used only for calculations and is never added to the visual tree. -- [HintRect](/uwp/api/windows.ui.xaml.input.findnextelementoptions#Windows_UI_Xaml_Input_FindNextElementOptions_HintRect) - Focus navigation candidates are identified using a "fictitious" bounding rectangle that identifies the elements most likely to receive focus. This rectangle is used only for calculations and is never added to the visual tree. -- [XYFocusNavigationStrategyOverride](/uwp/api/windows.ui.xaml.input.findnextelementoptions#Windows_UI_Xaml_Input_FindNextElementOptions_XYFocusNavigationStrategyOverride) - The focus navigation strategy used to identify the best candidate element to receive focus. +- [ExclusionRect](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.findnextelementoptions) - Focus navigation candidates are identified using a "fictitious" bounding rectangle where all overlapping objects are excluded from navigation focus. This rectangle is used only for calculations and is never added to the visual tree. +- [HintRect](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.findnextelementoptions) - Focus navigation candidates are identified using a "fictitious" bounding rectangle that identifies the elements most likely to receive focus. This rectangle is used only for calculations and is never added to the visual tree. +- [XYFocusNavigationStrategyOverride](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.findnextelementoptions) - The focus navigation strategy used to identify the best candidate element to receive focus. The following image illustrates some of these concepts. When element B has focus, FindNextElement identifies I as the focus candidate when navigating to the right. The reasons for this are: -- Because of the [HintRect](/uwp/api/windows.ui.xaml.input.findnextelementoptions#Windows_UI_Xaml_Input_FindNextElementOptions_HintRect) on A, the starting reference is A, not B -- C is not a candidate because MyPanel has been specified as the [SearchRoot](/uwp/api/windows.ui.xaml.input.findnextelementoptions#Windows_UI_Xaml_Input_FindNextElementOptions_SearchRoot) -- F is not a candidate because the [ExclusionRect](/uwp/api/windows.ui.xaml.input.findnextelementoptions#Windows_UI_Xaml_Input_FindNextElementOptions_ExclusionRect) overlaps it +- Because of the [HintRect](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.findnextelementoptions) on A, the starting reference is A, not B +- C is not a candidate because MyPanel has been specified as the [SearchRoot](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.findnextelementoptions) +- F is not a candidate because the [ExclusionRect](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.findnextelementoptions) overlaps it ![Custom focus navigation behavior using navigation hints](images/keyboard/navigation-hints.png) @@ -143,13 +143,13 @@ When element B has focus, FindNextElement identifies I as the focus candidate wh ### NoFocusCandidateFound event -The [UIElement.NoFocusCandidateFound](/uwp/api/windows.ui.xaml.uielement#Windows_UI_Xaml_UIElement_NoFocusCandidateFound) event is fired when the tab or arrow keys are pressed and there is no focus candidate in the specified direction. This event is not fired for [TryMoveFocus](/uwp/api/windows.ui.xaml.input.focusmanager#Windows_UI_Xaml_Input_FocusManager_TryMoveFocus_Windows_UI_Xaml_Input_FocusNavigationDirection_). +The [UIElement.NoFocusCandidateFound](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement#Microsoft_UI_Xaml_UIElement_NoFocusCandidateFound) event is fired when the tab or arrow keys are pressed and there is no focus candidate in the specified direction. This event is not fired for [TryMoveFocus](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.focusmanager#Microsoft_UI_Xaml_Input_FocusManager_TryMoveFocus_Microsoft_UI_Xaml_Input_FocusNavigationDirection_). Because this is a routed event, it bubbles from the focused element up through successive parent objects to the root of the object tree. This lets you handle the event wherever appropriate. -Here, we show how a Grid opens a [SplitView](/uwp/api/windows.ui.xaml.controls.splitview) when the user attempts to move focus to the left of the left-most focusable control (see [Designing for Xbox and TV](../../design/devices/designing-for-tv.md#navigation-pane)). +Here, we show how a Grid opens a [SplitView](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.splitview) when the user attempts to move focus to the left of the left-most focusable control (see [Designing for Xbox and TV](../../design/devices/designing-for-tv.md#navigation-pane)). ```xaml @@ -174,39 +174,39 @@ private void OnNoFocusCandidateFound ( ``` ### GotFocus and LostFocus events -The [UIElement.GotFocus](/uwp/api/Windows.UI.Xaml.UIElement#Windows_UI_Xaml_UIElement_GotFocus) -and [UIElement.LostFocus](/uwp/api/Windows.UI.Xaml.UIElement#Windows_UI_Xaml_UIElement_LostFocus) events are fired when an element gets focus or loses focus, respectively. This event is not fired for [TryMoveFocus](/uwp/api/windows.ui.xaml.input.focusmanager#Windows_UI_Xaml_Input_FocusManager_TryMoveFocus_Windows_UI_Xaml_Input_FocusNavigationDirection_). +The [UIElement.GotFocus](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.UIElement#Microsoft_UI_Xaml_UIElement_GotFocus) +and [UIElement.LostFocus](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.UIElement#Microsoft_UI_Xaml_UIElement_LostFocus) events are fired when an element gets focus or loses focus, respectively. This event is not fired for [TryMoveFocus](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.focusmanager#Microsoft_UI_Xaml_Input_FocusManager_TryMoveFocus_Microsoft_UI_Xaml_Input_FocusNavigationDirection_). Because these are routed events, they bubble from the focused element up through successive parent objects to the root of the object tree. This lets you handle the event wherever appropriate. ### GettingFocus and LosingFocus events -The [UIElement.GettingFocus](/uwp/api/Windows.UI.Xaml.UIElement#Windows_UI_Xaml_UIElement_GettingFocus) and [UIElement.LosingFocus](/uwp/api/Windows.UI.Xaml.UIElement#Windows_UI_Xaml_UIElement_LosingFocus) events fire before the respective [UIElement.GotFocus](/uwp/api/Windows.UI.Xaml.UIElement#Windows_UI_Xaml_UIElement_GotFocus) -and [UIElement.LostFocus](/uwp/api/Windows.UI.Xaml.UIElement#Windows_UI_Xaml_UIElement_LostFocus) events. +The [UIElement.GettingFocus](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.UIElement#Microsoft_UI_Xaml_UIElement_GettingFocus) and [UIElement.LosingFocus](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.UIElement#Microsoft_UI_Xaml_UIElement_LosingFocus) events fire before the respective [UIElement.GotFocus](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.UIElement#Microsoft_UI_Xaml_UIElement_GotFocus) +and [UIElement.LostFocus](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.UIElement#Microsoft_UI_Xaml_UIElement_LostFocus) events. Because these are routed events, they bubble from the focused element up through successive parent objects to the root of the object tree. As this happens before a focus change takes place, you can redirect or cancel the focus change. -[GettingFocus](/uwp/api/Windows.UI.Xaml.UIElement#Windows_UI_Xaml_UIElement_GettingFocus) and [LosingFocus](/uwp/api/Windows.UI.Xaml.UIElement#Windows_UI_Xaml_UIElement_LosingFocus) are synchronous events so focus won’t be -moved while these events are bubbling. However, [GotFocus](/uwp/api/Windows.UI.Xaml.UIElement#Windows_UI_Xaml_UIElement_GotFocus) -and [LostFocus](/uwp/api/Windows.UI.Xaml.UIElement#Windows_UI_Xaml_UIElement_LostFocus) are asynchronous events, which means there is no guarantee that focus won’t +[GettingFocus](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.UIElement#Microsoft_UI_Xaml_UIElement_GettingFocus) and [LosingFocus](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.UIElement#Microsoft_UI_Xaml_UIElement_LosingFocus) are synchronous events so focus won’t be +moved while these events are bubbling. However, [GotFocus](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.UIElement#Microsoft_UI_Xaml_UIElement_GotFocus) +and [LostFocus](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.UIElement#Microsoft_UI_Xaml_UIElement_LostFocus) are asynchronous events, which means there is no guarantee that focus won’t move again before the handler is executed. -If focus moves through a call to [Control.Focus](/uwp/api/windows.ui.xaml.controls.control#Windows_UI_Xaml_Controls_Control_Focus_Windows_UI_Xaml_FocusState_), [GettingFocus](/uwp/api/Windows.UI.Xaml.UIElement#Windows_UI_Xaml_UIElement_GettingFocus) is raised during the call, while [GotFocus](/uwp/api/Windows.UI.Xaml.UIElement#Windows_UI_Xaml_UIElement_GotFocus) is raised after the call. +If focus moves through a call to [Control.Focus](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.control#Microsoft_UI_Xaml_Controls_Control_Focus_Microsoft_UI_Xaml_FocusState_), [GettingFocus](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.UIElement#Microsoft_UI_Xaml_UIElement_GettingFocus) is raised during the call, while [GotFocus](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.UIElement#Microsoft_UI_Xaml_UIElement_GotFocus) is raised after the call. -The focus navigation target can be changed during the [GettingFocus](/uwp/api/Windows.UI.Xaml.UIElement#Windows_UI_Xaml_UIElement_GettingFocus) and [LosingFocus](/uwp/api/Windows.UI.Xaml.UIElement#Windows_UI_Xaml_UIElement_LosingFocus) events (before focus moves) through the [GettingFocusEventArgs.NewFocusedElement](/uwp/api/windows.ui.xaml.input.gettingfocuseventargs#Windows_UI_Xaml_Input_GettingFocusEventArgs_NewFocusedElement) property. Even if the target is changed, the event still bubbles and the target can be changed again. +The focus navigation target can be changed during the [GettingFocus](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.UIElement#Microsoft_UI_Xaml_UIElement_GettingFocus) and [LosingFocus](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.UIElement#Microsoft_UI_Xaml_UIElement_LosingFocus) events (before focus moves) through the [GettingFocusEventArgs.NewFocusedElement](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.gettingfocuseventargs#Microsoft_UI_Xaml_Input_GettingFocusEventArgs_NewFocusedElement) property. Even if the target is changed, the event still bubbles and the target can be changed again. -To avoid reentrancy issues, an exception is thrown if you try to move focus (using [TryMoveFocus](/uwp/api/windows.ui.xaml.input.focusmanager#Windows_UI_Xaml_Input_FocusManager_TryMoveFocus_Windows_UI_Xaml_Input_FocusNavigationDirection_) or [Control.Focus](/uwp/api/windows.ui.xaml.controls.control#Windows_UI_Xaml_Controls_Control_Focus_Windows_UI_Xaml_FocusState_)) while these events are bubbling. +To avoid reentrancy issues, an exception is thrown if you try to move focus (using [TryMoveFocus](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.focusmanager#Microsoft_UI_Xaml_Input_FocusManager_TryMoveFocus_Microsoft_UI_Xaml_Input_FocusNavigationDirection_) or [Control.Focus](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.control#Microsoft_UI_Xaml_Controls_Control_Focus_Microsoft_UI_Xaml_FocusState_)) while these events are bubbling. These events are fired regardless of the reason for the focus moving (including tab navigation, directional navigation, and programmatic navigation). Here is the order of execution for the focus events: -1. [LosingFocus](/uwp/api/Windows.UI.Xaml.UIElement#Windows_UI_Xaml_UIElement_LosingFocus) - If focus is reset back to the losing focus element or [TryCancel](/uwp/api/windows.ui.xaml.input.losingfocuseventargs#Windows_UI_Xaml_Input_LosingFocusEventArgs_TryCancel) is successful, no further events are fired. -2. [GettingFocus](/uwp/api/Windows.UI.Xaml.UIElement#Windows_UI_Xaml_UIElement_GettingFocus) - If focus is reset back to the losing focus element or [TryCancel](/uwp/api/windows.ui.xaml.input.gettingfocuseventargs#Windows_UI_Xaml_Input_GettingFocusEventArgs_TryCancel) is successful, no further events are fired. -3. [LostFocus](/uwp/api/Windows.UI.Xaml.UIElement#Windows_UI_Xaml_UIElement_LostFocus) -4. [GotFocus](/uwp/api/Windows.UI.Xaml.UIElement#Windows_UI_Xaml_UIElement_GotFocus) +1. [LosingFocus](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.UIElement#Microsoft_UI_Xaml_UIElement_LosingFocus) + If focus is reset back to the losing focus element or [TryCancel](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.losingfocuseventargs#Microsoft_UI_Xaml_Input_LosingFocusEventArgs_TryCancel) is successful, no further events are fired. +2. [GettingFocus](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.UIElement#Microsoft_UI_Xaml_UIElement_GettingFocus) + If focus is reset back to the losing focus element or [TryCancel](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.gettingfocuseventargs#Microsoft_UI_Xaml_Input_GettingFocusEventArgs_TryCancel) is successful, no further events are fired. +3. [LostFocus](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.UIElement#Microsoft_UI_Xaml_UIElement_LostFocus) +4. [GotFocus](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.UIElement#Microsoft_UI_Xaml_UIElement_GotFocus) The following image shows how, when moving to the right from A, the XYFocus chooses B4 as a candidate. B4 then fires the GettingFocus event where the ListView has the opportunity to reassign focus to B3. @@ -214,7 +214,7 @@ The following image shows how, when moving to the right from A, the XYFocus choo *Changing focus navigation target on GettingFocus event* -Here, we show how to handle the [GettingFocus](/uwp/api/Windows.UI.Xaml.UIElement#Windows_UI_Xaml_UIElement_GettingFocus) event and redirect focus. +Here, we show how to handle the [GettingFocus](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.UIElement#Microsoft_UI_Xaml_UIElement_GettingFocus) event and redirect focus. ```XAML @@ -251,7 +251,7 @@ private void OnGettingFocus(UIElement sender, GettingFocusEventArgs args) } ``` -Here, we show how to handle the [LosingFocus](/uwp/api/Windows.UI.Xaml.UIElement#Windows_UI_Xaml_UIElement_LosingFocus) event for a [CommandBar](/uwp/api/windows.ui.xaml.controls.commandbar) and set focus when the menu is closed. +Here, we show how to handle the [LosingFocus](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.UIElement#Microsoft_UI_Xaml_UIElement_LosingFocus) event for a [CommandBar](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.commandbar) and set focus when the menu is closed. ```XAML @@ -283,7 +283,7 @@ private void OnLosingFocus(UIElement sender, LosingFocusEventArgs args) ## Find the first and last focusable element -The [FocusManager.FindFirstFocusableElement](/uwp/api/windows.ui.xaml.input.focusmanager#Windows_UI_Xaml_Input_FocusManager_FindFirstFocusableElement_Windows_UI_Xaml_DependencyObject_) and [FocusManager.FindLastFocusableElement](/uwp/api/windows.ui.xaml.input.focusmanager#Windows_UI_Xaml_Input_FocusManager_FindLastFocusableElement_Windows_UI_Xaml_DependencyObject_) methods move focus to the first or last focusable element within the scope of an object (the element tree of a [UIElement](/uwp/api/windows.ui.xaml.uielement) or the text tree of a [TextElement](/uwp/api/windows.ui.xaml.documents.textelement)). The scope is specified in the call (if the argument is null, the scope is the current window). +The [FocusManager.FindFirstFocusableElement](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.focusmanager) and [FocusManager.FindLastFocusableElement](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.focusmanager) methods move focus to the first or last focusable element within the scope of an object (the element tree of a [UIElement](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement) or the text tree of a [TextElement](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.documents.textelement)). The scope is specified in the call (if the argument is null, the scope is the current window). If no focus candidates can be identified in the scope, null is returned. diff --git a/hub/apps/develop/input/focus-navigation.md b/hub/apps/develop/input/focus-navigation.md index bd0cc5b08c..fcc3caf2bb 100644 --- a/hub/apps/develop/input/focus-navigation.md +++ b/hub/apps/develop/input/focus-navigation.md @@ -53,23 +53,23 @@ The 2D inner navigation region of a control, or control group, is referred to as ![directional area](images/keyboard/directional-area-small.png) *2D Inner navigation region, or directional area, of a control group* -You can use the [XYFocusKeyboardNavigation](/uwp/api/windows.ui.xaml.uielement#Windows_UI_Xaml_UIElement_XYFocusKeyboardNavigation) property (which has possible values of [Auto](/uwp/api/windows.ui.xaml.input.xyfocuskeyboardnavigationmode), [Enabled](/uwp/api/windows.ui.xaml.input.xyfocuskeyboardnavigationmode), or [Disabled](/uwp/api/windows.ui.xaml.input.xyfocuskeyboardnavigationmode)) to manage 2D inner navigation with the keyboard arrow keys. +You can use the [XYFocusKeyboardNavigation](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement#Microsoft_UI_Xaml_UIElement_XYFocusKeyboardNavigation) property (which has possible values of [Auto](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.xyfocuskeyboardnavigationmode), [Enabled](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.xyfocuskeyboardnavigationmode), or [Disabled](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.xyfocuskeyboardnavigationmode)) to manage 2D inner navigation with the keyboard arrow keys. > [!NOTE] -> Tab order is not affected by this property. To avoid a confusing navigation experience, we recommend that child elements of a directional area *not* be explicitly specified in the tab navigation order of your application. See the [UIElement.TabFocusNavigation](/uwp/api/windows.ui.xaml.uielement#Windows_UI_Xaml_UIElement_TabFocusNavigation) and [TabIndex](/uwp/api/windows.ui.xaml.controls.control#Windows_UI_Xaml_Controls_Control_TabIndex) properties for more detail on tabbing behavior for an element. +> Tab order is not affected by this property. To avoid a confusing navigation experience, we recommend that child elements of a directional area *not* be explicitly specified in the tab navigation order of your application. See the [UIElement.TabFocusNavigation](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement#Microsoft_UI_Xaml_UIElement_TabFocusNavigation) and [TabIndex](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.control#Microsoft_UI_Xaml_Controls_Control_TabIndex) properties for more detail on tabbing behavior for an element. -### [Auto](/uwp/api/windows.ui.xaml.input.xyfocuskeyboardnavigationmode) (default behavior) +### [Auto](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.xyfocuskeyboardnavigationmode) (default behavior) When set to Auto, directional navigation behavior is determined by the element’s ancestry, or inheritance hierarchy. If all ancestors are in default mode (set to **Auto**), directional navigation with the keyboard is *not* supported. -### [Disabled](/uwp/api/windows.ui.xaml.input.xyfocuskeyboardnavigationmode) +### [Disabled](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.xyfocuskeyboardnavigationmode) Set **XYFocusKeyboardNavigation** to **Disabled** to block directional navigation to the control and its child elements. ![XYFocusKeyboardNavigation disabled behavior](images/keyboard/xyfocuskeyboardnav-disabled.gif) *XYFocusKeyboardNavigation disabled behavior* -In this example, the primary [StackPanel](/uwp/api/Windows.UI.Xaml.Controls.StackPanel) (ContainerPrimary) has **XYFocusKeyboardNavigation** set to **Enabled**. All child elements inherit this setting, and can be navigated to with the arrow keys. However, the B3 and B4 elements are in a secondary [StackPanel](/uwp/api/Windows.UI.Xaml.Controls.StackPanel) (ContainerSecondary) with **XYFocusKeyboardNavigation** set to **Disabled**, which overrides the primary container and disables arrow key navigation to itself and between its child elements. +In this example, the primary [StackPanel](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.stackpanel) (ContainerPrimary) has **XYFocusKeyboardNavigation** set to **Enabled**. All child elements inherit this setting, and can be navigated to with the arrow keys. However, the B3 and B4 elements are in a secondary [StackPanel](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.stackpanel) (ContainerSecondary) with **XYFocusKeyboardNavigation** set to **Disabled**, which overrides the primary container and disables arrow key navigation to itself and between its child elements. ```XAML ``` -### [Enabled](/uwp/api/windows.ui.xaml.input.xyfocuskeyboardnavigationmode) +### [Enabled](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.xyfocuskeyboardnavigationmode) -Set **XYFocusKeyboardNavigation** to **Enabled** to support 2D directional navigation to a control and each of its [UIElement](/uwp/api/Windows.UI.Xaml.UIElement) child objects. +Set **XYFocusKeyboardNavigation** to **Enabled** to support 2D directional navigation to a control and each of its [UIElement](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement) child objects. When set, navigation with the arrow keys is restricted to elements within the directional area. Tab navigation is not affected, as all controls remain accessible through their tab order hierarchy. ![XYFocusKeyboardNavigation enabled behavior](images/keyboard/xyfocuskeyboardnav-enabled.gif) *XYFocusKeyboardNavigation enabled behavior* -In this example, the primary [StackPanel](/uwp/api/Windows.UI.Xaml.Controls.StackPanel) (ContainerPrimary) has **XYFocusKeyboardNavigation** set to **Enabled**. All child elements inherit this setting, and can be navigated to with the arrow keys. The B3 and B4 elements are in a secondary [StackPanel](/uwp/api/Windows.UI.Xaml.Controls.StackPanel) (ContainerSecondary) where **XYFocusKeyboardNavigation** is not set, which then inherits the primary container setting. The B5 element is not within a declared directional area, and does not support arrow key navigation but does support standard tab navigation behavior. +In this example, the primary [StackPanel](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.stackpanel) (ContainerPrimary) has **XYFocusKeyboardNavigation** set to **Enabled**. All child elements inherit this setting, and can be navigated to with the arrow keys. The B3 and B4 elements are in a secondary [StackPanel](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.stackpanel) (ContainerSecondary) where **XYFocusKeyboardNavigation** is not set, which then inherits the primary container setting. The B5 element is not within a declared directional area, and does not support arrow key navigation but does support standard tab navigation behavior. ```xaml [!NOTE] -> Use this property instead of the [Control.TabNavigation](/uwp/api/windows.ui.xaml.controls.control#Windows_UI_Xaml_Controls_Control_TabNavigation) property for objects that do not use a [ControlTemplate](/uwp/api/windows.ui.xaml.controls.controltemplate) to define their appearance. +> Use this property instead of the [Control.TabNavigation](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.control#Microsoft_UI_Xaml_Controls_Control_TabNavigation) property for objects that do not use a [ControlTemplate](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.controltemplate) to define their appearance. -As we mentioned in the previous section, to avoid a confusing navigation experience, we recommend that child elements of a directional area *not* be explicitly specified in the tab navigation order of your application. See the [UIElement.TabFocusNavigation](/uwp/api/windows.ui.xaml.uielement#Windows_UI_Xaml_UIElement_TabFocusNavigation) and the [TabIndex](/uwp/api/windows.ui.xaml.controls.control#Windows_UI_Xaml_Controls_Control_TabIndex) properties for more detail on tabbing behavior for an element. -> For versions older than Windows 10 Creators Update (build 10.0.15063), tab settings were limited to [ControlTemplate](/uwp/api/windows.ui.xaml.controls.controltemplate) objects. For more info, see [Control.TabNavigation](/uwp/api/windows.ui.xaml.controls.control#Windows_UI_Xaml_Controls_Control_TabNavigation). +As we mentioned in the previous section, to avoid a confusing navigation experience, we recommend that child elements of a directional area *not* be explicitly specified in the tab navigation order of your application. See the [UIElement.TabFocusNavigation](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement#Microsoft_UI_Xaml_UIElement_TabFocusNavigation) and the [TabIndex](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.control#Microsoft_UI_Xaml_Controls_Control_TabIndex) properties for more detail on tabbing behavior for an element. +> For versions older than Windows 10 Creators Update (build 10.0.15063), tab settings were limited to [ControlTemplate](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.controltemplate) objects. For more info, see [Control.TabNavigation](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.control#Microsoft_UI_Xaml_Controls_Control_TabNavigation). -[TabFocusNavigation](/uwp/api/windows.ui.xaml.uielement#Windows_UI_Xaml_UIElement_TabFocusNavigation) -has a value of type [KeyboardNavigationMode](/uwp/api/windows.ui.xaml.input.keyboardnavigationmode) with the following possible values (note that these examples are not custom control groups and do not require inner navigation with the arrow keys): +[TabFocusNavigation](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement#Microsoft_UI_Xaml_UIElement_TabFocusNavigation) +has a value of type [KeyboardNavigationMode](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.keyboardnavigationmode) with the following possible values (note that these examples are not custom control groups and do not require inner navigation with the arrow keys): - **Local** (default) Tab indexes are recognized on the local subtree inside the container. For this example, the tab order is B1, B2, B3, B4, B5, B6, B7, B1. @@ -312,23 +312,23 @@ Here's the code for the preceding examples (with TabFocusNavigation ="Cycle"). ``` -### [TabIndex](/uwp/api/windows.ui.xaml.controls.control#Windows_UI_Xaml_Controls_Control_TabIndex) +### [TabIndex](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.control#Microsoft_UI_Xaml_Controls_Control_TabIndex) -Use [TabIndex](/uwp/api/windows.ui.xaml.controls.control#Windows_UI_Xaml_Controls_Control_TabIndex) to specify the order in which elements receive focus when the user navigates through controls using the Tab key. A control with a lower tab index receives focus before a control with a higher index. +Use [TabIndex](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.control#Microsoft_UI_Xaml_Controls_Control_TabIndex) to specify the order in which elements receive focus when the user navigates through controls using the Tab key. A control with a lower tab index receives focus before a control with a higher index. -When a control has no [TabIndex](/uwp/api/Windows.UI.Xaml.Controls.Control#Windows_UI_Xaml_Controls_Control_TabIndex) specified, it is assigned a higher index value than the current highest index value (and the lowest priority) of all interactive controls in the visual tree, based on scope. +When a control has no [TabIndex](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.Controls.Control#Microsoft_UI_Xaml_Controls_Control_TabIndex) specified, it is assigned a higher index value than the current highest index value (and the lowest priority) of all interactive controls in the visual tree, based on scope. All child elements of a control are considered a scope, and if one of these elements also has child elements, they are considered another scope. Any ambiguity is resolved by choosing the first element on the visual tree of the scope. -To exclude a control from the tab order, set the [IsTabStop](/uwp/api/Windows.UI.Xaml.Controls.Control#Windows_UI_Xaml_Controls_Control_IsTabStop) property to **false**. +To exclude a control from the tab order, set the [IsTabStop](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.Controls.Control#Microsoft_UI_Xaml_Controls_Control_IsTabStop) property to **false**. -Override the default tab order by setting the [TabIndex](/uwp/api/Windows.UI.Xaml.Controls.Control#Windows_UI_Xaml_Controls_Control_TabIndex) property. +Override the default tab order by setting the [TabIndex](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.Controls.Control#Microsoft_UI_Xaml_Controls_Control_TabIndex) property. > [!NOTE] -> [TabIndex](/uwp/api/Windows.UI.Xaml.Controls.Control#Windows_UI_Xaml_Controls_Control_TabIndex) works the same way with both [UIElement.TabFocusNavigation](/uwp/api/windows.ui.xaml.uielement#Windows_UI_Xaml_UIElement_TabFocusNavigation) and [Control.TabNavigation](/uwp/api/windows.ui.xaml.controls.control#Windows_UI_Xaml_Controls_Control_TabNavigation). +> [TabIndex](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.Controls.Control#Microsoft_UI_Xaml_Controls_Control_TabIndex) works the same way with both [UIElement.TabFocusNavigation](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement#Microsoft_UI_Xaml_UIElement_TabFocusNavigation) and [Control.TabNavigation](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.control#Microsoft_UI_Xaml_Controls_Control_TabNavigation). -Here, we show how focus navigation can be affected by the [TabIndex](/uwp/api/Windows.UI.Xaml.Controls.Control#Windows_UI_Xaml_Controls_Control_TabIndex) property on specific elements. +Here, we show how focus navigation can be affected by the [TabIndex](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.Controls.Control#Microsoft_UI_Xaml_Controls_Control_TabIndex) property on specific elements. !["Local" tab navigation with TabIndex behavior](images/keyboard/tabnav-tabindex.gif) @@ -432,7 +432,7 @@ The following navigation strategy properties let you influence which control rec - XYFocusLeftNavigationStrategy - XYFocusRightNavigationStrategy -These properties have possible values of [Auto](/uwp/api/windows.ui.xaml.input.xyfocusnavigationstrategy) (default), [NavigationDirectionDistance](/uwp/api/windows.ui.xaml.input.xyfocusnavigationstrategy), [Projection](/uwp/api/windows.ui.xaml.input.xyfocusnavigationstrategy), or [RectilinearDistance ](/uwp/api/windows.ui.xaml.input.xyfocusnavigationstrategy). +These properties have possible values of [Auto](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.xyfocusnavigationstrategy) (default), [NavigationDirectionDistance](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.xyfocusnavigationstrategy), [Projection](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.xyfocusnavigationstrategy), or [RectilinearDistance ](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.xyfocusnavigationstrategy). If set to **Auto**, the behavior of the element is based on the ancestors of the element. If all elements are set to **Auto**, **Projection** is used. diff --git a/hub/apps/develop/input/guidelines-for-optical-zoom.md b/hub/apps/develop/input/guidelines-for-optical-zoom.md index 9b90d4872d..443f505321 100644 --- a/hub/apps/develop/input/guidelines-for-optical-zoom.md +++ b/hub/apps/develop/input/guidelines-for-optical-zoom.md @@ -15,7 +15,7 @@ ms.localizationpriority: medium This article describes Windows zooming and resizing elements and provides user experience guidelines for using these interaction mechanisms in your apps. -> **Important APIs**: [**Windows.UI.Input**](/uwp/api/Windows.UI.Input), [**Input (XAML)**](/uwp/api/Windows.UI.Xaml.Input) +> **Important APIs**: [**Windows.UI.Input**](/uwp/api/Windows.UI.Input), [**Input (XAML)**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.Input) Optical zoom lets users magnify their view of the content within a content area (it is performed on the content area itself), whereas resizing enables users to change the relative size of one or more objects without changing the view of the content area (it is performed on the objects within the content area). @@ -44,7 +44,7 @@ Use the following guidelines for apps that support either resizing or optical zo - If maximum and minimum size constraints or boundaries are defined, use visual feedback to demonstrate when the user reaches or exceeds those boundaries. - Use snap points to influence zooming and resizing behavior by providing logical points at which to stop the manipulation and ensure a specific subset of content is displayed in the viewport. Provide snap points for common zoom levels or logical views to make it easier for a user to select those levels. For example, photo apps might provide a resizing snap point at 100% or, in the case of mapping apps, snap points might be useful at city, state, and country/region views. - Snap points enable users to be imprecise and still achieve their goals. If you're using XAML, see the snap points properties of [**ScrollViewer**](/uwp/api/Windows.UI.Xaml.Controls.ScrollViewer). + Snap points enable users to be imprecise and still achieve their goals. If you're using XAML, see the snap points properties of [**ScrollViewer**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.scrollviewer). There are two types of snap-points: diff --git a/hub/apps/develop/input/guidelines-for-visualfeedback.md b/hub/apps/develop/input/guidelines-for-visualfeedback.md index 0887997651..84950262f2 100644 --- a/hub/apps/develop/input/guidelines-for-visualfeedback.md +++ b/hub/apps/develop/input/guidelines-for-visualfeedback.md @@ -26,7 +26,7 @@ Use visual feedback to show users when their interactions are detected, interpre - 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](/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 use touch visualizations in situations where they might interfere with the use of the app. For more info, see [**ShowGestureFeedback**](/windows/windows-app-sdk/api/winrt/microsoft.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. @@ -43,7 +43,7 @@ Using the default XAML platform controls available ensures that your app works c Visual feedback is generally dependent on the input device (touch, touchpad, mouse, pen/stylus, keyboard, and so on). For example, the built-in feedback for a mouse usually involves moving and changing the cursor, while touch and pen require contact visualizations, and keyboard input and navigation uses focus rectangles and highlighting. -Use [**ShowGestureFeedback**](/uwp/api/windows.ui.input.gesturerecognizer.showgesturefeedback) to set feedback behavior for the platform gestures. +Use [**ShowGestureFeedback**](/windows/windows-app-sdk/api/winrt/microsoft.ui.input.gesturerecognizer.showgesturefeedback) to set feedback behavior for the platform gestures. If customizing feedback UI, ensure you provide feedback that supports, and is suitable for, all input modes. diff --git a/hub/apps/develop/input/handle-pointer-input.md b/hub/apps/develop/input/handle-pointer-input.md index a0416ee6cc..4f506b79ca 100644 --- a/hub/apps/develop/input/handle-pointer-input.md +++ b/hub/apps/develop/input/handle-pointer-input.md @@ -20,8 +20,8 @@ Receive, process, and manage input data from pointing devices (such as touch, mo ## Important APIs - [Windows.Devices.Input](/uwp/api/Windows.Devices.Input) -- [Windows.UI.Input](/uwp/api/Windows.UI.Core) -- [Windows.UI.Xaml.Input](/uwp/api/Windows.UI.Input) +- [Microsoft.UI.Input](/windows/windows-app-sdk/api/winrt/microsoft.ui.input) +- [Microsoft.UI.Xaml.Input](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input) ## Pointers Most interaction experiences typically involve the user identifying the object they want to interact with by pointing at it through input devices such as touch, mouse, pen/stylus, and touchpad. Because the raw Human Interface Device (HID) data provided by these input devices includes many common properties, the data is promoted and consolidated into a unified input stack and exposed as device-agnostic pointer data. Your Windows applications can then consume this data without worrying about the input device being used. @@ -29,7 +29,7 @@ Most interaction experiences typically involve the user identifying the object t > [!NOTE] > Device-specific info is also promoted from the raw HID data should your app require it. -Each input point (or contact) on the input stack is represented by a [**Pointer**](/uwp/api/Windows.UI.Xaml.Input.Pointer) object exposed through the [**PointerRoutedEventArgs**](/uwp/api/Windows.UI.Xaml.Input.PointerRoutedEventArgs) parameter in the various pointer event handlers. In the case of multi-pen or multi-touch input, each contact is treated as a unique input pointer. +Each input point (or contact) on the input stack is represented by a [**Pointer**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.pointer) object exposed through the [**PointerRoutedEventArgs**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.pointerroutedeventargs) parameter in the various pointer event handlers. In the case of multi-pen or multi-touch input, each contact is treated as a unique input pointer. ## Pointer events @@ -38,18 +38,18 @@ Pointer events expose basic info such as input device type and detection state ( Windows apps can listen for the following pointer events: > [!NOTE] -> Constrain pointer input to a specific UI element by calling [**CapturePointer**](/uwp/api/windows.ui.xaml.uielement.capturepointer) on that element within a pointer event handler. When a pointer is captured by an element, only that object receives pointer input events, even when the pointer moves outside the bounding area of the object. The [**IsInContact**](/uwp/api/windows.ui.xaml.input.pointer.isincontact) (mouse button pressed, touch or stylus in contact) must be true for **CapturePointer** to be successful. +> Constrain pointer input to a specific UI element by calling [**CapturePointer**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.capturepointer) on that element within a pointer event handler. When a pointer is captured by an element, only that object receives pointer input events, even when the pointer moves outside the bounding area of the object. The [**IsInContact**](/windows/windows-app-sdk/api/winrt/microsoft.ui.input.pointerpoint.isincontact) (mouse button pressed, touch or stylus in contact) must be true for **CapturePointer** to be successful. | Event | Description | |---|---| -| [**PointerCanceled**](/uwp/api/windows.ui.xaml.uielement.pointercanceled) | Occurs when a pointer is canceled by the platform. This can occur in the following circumstances:
• Touch pointers are canceled when a pen is detected within range of the input surface.
• An active contact is not detected for more than 100 ms.
• Monitor/display is changed (resolution, settings, multi-mon configuration).
• The desktop is locked or the user has logged off.
• The number of simultaneous contacts exceeded the number supported by the device. | -| [**PointerCaptureLost**](/uwp/api/windows.ui.xaml.uielement.pointercapturelost) | Occurs when another UI element captures the pointer, the pointer was released, or another pointer was programmatically captured.
**Note:** There is no corresponding pointer capture event. | -| [**PointerEntered**](/uwp/api/windows.ui.xaml.uielement.pointerentered) | Occurs when a pointer enters the bounding area of an element. This can happen in slightly different ways for touch, touchpad, mouse, and pen input.
• Touch requires a finger contact to fire this event, either from a direct touch down on the element or from moving into the bounding area of the element.
• Mouse and touchpad both have an on-screen cursor that is always visible and fires this event even if no mouse or touchpad button is pressed.
• Like touch, pen fires this event with a direct pen down on the element or from moving into the bounding area of the element. However, pen also has a hover state ([IsInRange](/uwp/api/windows.ui.xaml.input.pointer.isinrange)) that, when true, fires this event. | -| [**PointerExited**](/uwp/api/windows.ui.xaml.uielement.pointerexited) | Occurs when a pointer leaves the bounding area of an element. This can happen in slightly different ways for touch, touchpad, mouse, and pen input.
• Touch requires a finger contact and fires this event when the pointer moves out of the bounding area of the element.
• Mouse and touchpad both have an on-screen cursor that is always visible and fires this event even if no mouse or touchpad button is pressed.
• Like touch, pen fires this event when moving out of the bounding area of the element. However, pen also has a hover state ([IsInRange](/uwp/api/windows.ui.xaml.input.pointer.isinrange)) that fires this event when the state changes from true to false. | -| [**PointerMoved**](/uwp/api/windows.ui.xaml.uielement.pointermoved) | Occurs when a pointer changes coordinates, button state, pressure, tilt, or contact geometry (for example, width and height) within the bounding area of an element. This can happen in slightly different ways for touch, touchpad, mouse, and pen input.
• Touch requires a finger contact and fires this event only when in contact within the bounding area of the element.
• Mouse and touchpad both have an on-screen cursor that is always visible and fires this event even if no mouse or touchpad button is pressed.
• Like touch, pen fires this event when in contact within the bounding area of the element. However, pen also has a hover state ([IsInRange](/uwp/api/windows.ui.xaml.input.pointer.isinrange)) that, when true and within the bounding area of the element, fires this event. | -| [**PointerPressed**](/uwp/api/windows.ui.xaml.uielement.pointerpressed) | Occurs when the pointer indicates a press action (such as a touch down, mouse button down, pen down, or touchpad button down) within the bounding area of an element.
[CapturePointer](/uwp/api/windows.ui.xaml.uielement.capturepointer) must be called from the handler for this event. | -| [**PointerReleased**](/uwp/api/windows.ui.xaml.uielement.pointerreleased) | Occurs when the pointer indicates a release action (such as a touch up, mouse button up, pen up, or touchpad button up) within the bounding area of an element or, if the pointer is captured, outside the bounding area. | -| [**PointerWheelChanged**](/uwp/api/windows.ui.xaml.uielement.pointerwheelchanged) | Occurs when the mouse wheel is rotated.
Mouse input is associated with a single pointer assigned when mouse input is first detected. Clicking a mouse button (left, wheel, or right) creates a secondary association between the pointer and that button through the [PointerMoved](/uwp/api/windows.ui.xaml.uielement.pointermoved) event. |  +| [**PointerCanceled**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.pointercanceled) | Occurs when a pointer is canceled by the platform. This can occur in the following circumstances:
• Touch pointers are canceled when a pen is detected within range of the input surface.
• An active contact is not detected for more than 100 ms.
• Monitor/display is changed (resolution, settings, multi-mon configuration).
• The desktop is locked or the user has logged off.
• The number of simultaneous contacts exceeded the number supported by the device. | +| [**PointerCaptureLost**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.pointercapturelost) | Occurs when another UI element captures the pointer, the pointer was released, or another pointer was programmatically captured.
**Note:** There is no corresponding pointer capture event. | +| [**PointerEntered**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.pointerentered) | Occurs when a pointer enters the bounding area of an element. This can happen in slightly different ways for touch, touchpad, mouse, and pen input.
• Touch requires a finger contact to fire this event, either from a direct touch down on the element or from moving into the bounding area of the element.
• Mouse and touchpad both have an on-screen cursor that is always visible and fires this event even if no mouse or touchpad button is pressed.
• Like touch, pen fires this event with a direct pen down on the element or from moving into the bounding area of the element. However, pen also has a hover state ([IsInRange](/windows/windows-app-sdk/api/winrt/microsoft.ui.input.pointerpointproperties.isinrange)) that, when true, fires this event. | +| [**PointerExited**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.pointerexited) | Occurs when a pointer leaves the bounding area of an element. This can happen in slightly different ways for touch, touchpad, mouse, and pen input.
• Touch requires a finger contact and fires this event when the pointer moves out of the bounding area of the element.
• Mouse and touchpad both have an on-screen cursor that is always visible and fires this event even if no mouse or touchpad button is pressed.
• Like touch, pen fires this event when moving out of the bounding area of the element. However, pen also has a hover state ([IsInRange](/windows/windows-app-sdk/api/winrt/microsoft.ui.input.pointerpointproperties.isinrange)) that fires this event when the state changes from true to false. | +| [**PointerMoved**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.pointermoved) | Occurs when a pointer changes coordinates, button state, pressure, tilt, or contact geometry (for example, width and height) within the bounding area of an element. This can happen in slightly different ways for touch, touchpad, mouse, and pen input.
• Touch requires a finger contact and fires this event only when in contact within the bounding area of the element.
• Mouse and touchpad both have an on-screen cursor that is always visible and fires this event even if no mouse or touchpad button is pressed.
• Like touch, pen fires this event when in contact within the bounding area of the element. However, pen also has a hover state ([IsInRange](/windows/windows-app-sdk/api/winrt/microsoft.ui.input.pointerpointproperties.isinrange)) that, when true and within the bounding area of the element, fires this event. | +| [**PointerPressed**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.pointerpressed) | Occurs when the pointer indicates a press action (such as a touch down, mouse button down, pen down, or touchpad button down) within the bounding area of an element.
[CapturePointer](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.capturepointer) must be called from the handler for this event. | +| [**PointerReleased**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.pointerreleased) | Occurs when the pointer indicates a release action (such as a touch up, mouse button up, pen up, or touchpad button up) within the bounding area of an element or, if the pointer is captured, outside the bounding area. | +| [**PointerWheelChanged**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.pointerwheelchanged) | Occurs when the mouse wheel is rotated.
Mouse input is associated with a single pointer assigned when mouse input is first detected. Clicking a mouse button (left, wheel, or right) creates a secondary association between the pointer and that button through the [PointerMoved](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.pointermoved) event. |  ## Pointer event example @@ -61,9 +61,9 @@ Here are some code snippets from a basic pointer tracking app that show how to l ### Create the UI -For this example, we use a [Rectangle](/uwp/api/windows.ui.xaml.shapes.rectangle) (`Target`) as the object consuming pointer input. The color of the target changes when the pointer status changes. +For this example, we use a [Rectangle](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.shapes.rectangle) (`Target`) as the object consuming pointer input. The color of the target changes when the pointer status changes. -Details for each pointer are displayed in a floating [TextBlock](/uwp/api/Windows.UI.Xaml.Controls.TextBlock) that follows the pointer as it moves. The pointer events themselves are reported in the [RichTextBlock](/uwp/api/Windows.UI.Xaml.Controls.RichTextBlock) to the right of the rectangle. +Details for each pointer are displayed in a floating [TextBlock](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.textblock) that follows the pointer as it moves. The pointer events themselves are reported in the [RichTextBlock](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.richtextblock) to the right of the rectangle. This is the Extensible Application Markup Language (XAML) for the UI in this example. @@ -120,9 +120,9 @@ This is the Extensible Application Markup Language (XAML) for the UI in this exa ### Listen for pointer events -In most cases, we recommend that you get pointer info through the [**PointerRoutedEventArgs**](/uwp/api/Windows.UI.Xaml.Input.PointerRoutedEventArgs) of the event handler. +In most cases, we recommend that you get pointer info through the [**PointerRoutedEventArgs**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.pointerroutedeventargs) of the event handler. -If the event argument doesn't expose the pointer details required, you can get access to extended [**PointerPoint**](/uwp/api/Windows.UI.Input.PointerPoint) info exposed through the [**GetCurrentPoint**](/uwp/api/windows.ui.xaml.input.pointerroutedeventargs.getcurrentpoint) and [**GetIntermediatePoints**](/uwp/api/windows.ui.xaml.input.pointerroutedeventargs.getintermediatepoints) methods of [**PointerRoutedEventArgs**](/uwp/api/Windows.UI.Xaml.Input.PointerRoutedEventArgs). +If the event argument doesn't expose the pointer details required, you can get access to extended [**PointerPoint**](/windows/windows-app-sdk/api/winrt/microsoft.ui.input.pointerpoint) info exposed through the [**GetCurrentPoint**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.pointerroutedeventargs.getcurrentpoint) and [**GetIntermediatePoints**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.pointerroutedeventargs.getintermediatepoints) methods of [**PointerRoutedEventArgs**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.pointerroutedeventargs). The following code sets up the global dictionary object for tracking each active pointer, and identifies the various pointer event listeners for the target object. @@ -130,14 +130,14 @@ The following code sets up the global dictionary object for tracking each active // Dictionary to maintain information about each active pointer. // An entry is added during PointerPressed/PointerEntered events and removed // during PointerReleased/PointerCaptureLost/PointerCanceled/PointerExited events. -Dictionary pointers; +Dictionary pointers; public MainPage() { this.InitializeComponent(); // Initialize the dictionary. - pointers = new Dictionary(); + pointers = new Dictionary(); // Declare the pointer event handlers. Target.PointerPressed += @@ -166,10 +166,10 @@ public MainPage() Next, we use UI feedback to demonstrate basic pointer event handlers. -- This handler manages the [**PointerPressed**](/uwp/api/windows.ui.xaml.uielement.pointerpressed) event. We add the event to the event log, add the pointer to the active pointer dictionary, and display the pointer details. +- This handler manages the [**PointerPressed**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.pointerpressed) event. We add the event to the event log, add the pointer to the active pointer dictionary, and display the pointer details. > [!NOTE] - > [**PointerPressed**](/uwp/api/windows.ui.xaml.uielement.pointerpressed) and [**PointerReleased**](/uwp/api/windows.ui.xaml.uielement.pointerreleased) events do not always occur in pairs. Your app should listen for and handle any event that might conclude a pointer down (such as [**PointerExited**](/uwp/api/windows.ui.xaml.uielement.pointerexited), [**PointerCanceled**](/uwp/api/windows.ui.xaml.uielement.pointercanceled), and [**PointerCaptureLost**](/uwp/api/windows.ui.xaml.uielement.pointercapturelost)). + > [**PointerPressed**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.pointerpressed) and [**PointerReleased**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.pointerreleased) events do not always occur in pairs. Your app should listen for and handle any event that might conclude a pointer down (such as [**PointerExited**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.pointerexited), [**PointerCanceled**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.pointercanceled), and [**PointerCaptureLost**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.pointercapturelost)).   ```csharp @@ -205,14 +205,14 @@ void Target_PointerPressed(object sender, PointerRoutedEventArgs e) } // Change background color of target when pointer contact detected. - Target.Fill = new SolidColorBrush(Windows.UI.Colors.Green); + Target.Fill = new SolidColorBrush(Microsoft.UI.Colors.Green); // Display pointer details. CreateInfoPop(ptrPt); } ``` -- This handler manages the [**PointerEntered**](/uwp/api/windows.ui.xaml.uielement.pointerentered) event. We add the event to the event log, add the pointer to the pointer collection, and display the pointer details. +- This handler manages the [**PointerEntered**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.pointerentered) event. We add the event to the event log, add the pointer to the pointer collection, and display the pointer details. ```csharp /// @@ -241,7 +241,7 @@ private void Target_PointerEntered(object sender, PointerRoutedEventArgs e) if (pointers.Count == 0) { // Change background color of target when pointer contact detected. - Target.Fill = new SolidColorBrush(Windows.UI.Colors.Blue); + Target.Fill = new SolidColorBrush(Microsoft.UI.Colors.Blue); } // Display pointer details. @@ -249,10 +249,10 @@ private void Target_PointerEntered(object sender, PointerRoutedEventArgs e) } ``` -- This handler manages the [**PointerMoved**](/uwp/api/windows.ui.xaml.uielement.pointermoved) event. We add the event to the event log and update the pointer details. +- This handler manages the [**PointerMoved**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.pointermoved) event. We add the event to the event log and update the pointer details. > [!Important] - > Mouse input is associated with a single pointer assigned when mouse input is first detected. Clicking a mouse button (left, wheel, or right) creates a secondary association between the pointer and that button through the [**PointerPressed**](/uwp/api/windows.ui.xaml.uielement.pointerpressed) event. The [**PointerReleased**](/uwp/api/windows.ui.xaml.uielement.pointerreleased) event is fired only when that same mouse button is released (no other button can be associated with the pointer until this event is complete). Because of this exclusive association, other mouse button clicks are routed through the [**PointerMoved**](/uwp/api/windows.ui.xaml.uielement.pointermoved) event.   + > Mouse input is associated with a single pointer assigned when mouse input is first detected. Clicking a mouse button (left, wheel, or right) creates a secondary association between the pointer and that button through the [**PointerPressed**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.pointerpressed) event. The [**PointerReleased**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.pointerreleased) event is fired only when that same mouse button is released (no other button can be associated with the pointer until this event is complete). Because of this exclusive association, other mouse button clicks are routed through the [**PointerMoved**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.pointermoved) event.   ```csharp /// @@ -299,7 +299,7 @@ private void Target_PointerMoved(object sender, PointerRoutedEventArgs e) } ``` -- This handler manages the [**PointerWheelChanged**](/uwp/api/windows.ui.xaml.uielement.pointerwheelchanged) event. We add the event to the event log, add the pointer to the pointer array (if necessary), and display the pointer details. +- This handler manages the [**PointerWheelChanged**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.pointerwheelchanged) event. We add the event to the event log, add the pointer to the pointer array (if necessary), and display the pointer details. ```csharp /// @@ -329,7 +329,7 @@ private void Target_PointerWheelChanged(object sender, PointerRoutedEventArgs e) } ``` -- This handler manages the [**PointerReleased**](/uwp/api/windows.ui.xaml.uielement.pointerreleased) event where contact with the digitizer is terminated. We add the event to the event log, remove the pointer from the pointer collection, and update the pointer details. +- This handler manages the [**PointerReleased**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.pointerreleased) event where contact with the digitizer is terminated. We add the event to the event log, remove the pointer from the pointer collection, and update the pointer details. ```csharp /// @@ -357,7 +357,7 @@ void Target_PointerReleased(object sender, PointerRoutedEventArgs e) if (ptrPt.PointerDevice.PointerDeviceType != Windows.Devices.Input.PointerDeviceType.Mouse) { // Update target UI. - Target.Fill = new SolidColorBrush(Windows.UI.Colors.Red); + Target.Fill = new SolidColorBrush(Microsoft.UI.Colors.Red); DestroyInfoPop(ptrPt); @@ -376,12 +376,12 @@ void Target_PointerReleased(object sender, PointerRoutedEventArgs e) } else { - Target.Fill = new SolidColorBrush(Windows.UI.Colors.Blue); + Target.Fill = new SolidColorBrush(Microsoft.UI.Colors.Blue); } } ``` -- This handler manages the [**PointerExited**](/uwp/api/windows.ui.xaml.uielement.pointerexited) event (when contact with the digitizer is maintained). We add the event to the event log, remove the pointer from the pointer array, and update the pointer details. +- This handler manages the [**PointerExited**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.pointerexited) event (when contact with the digitizer is maintained). We add the event to the event log, remove the pointer from the pointer array, and update the pointer details. ```csharp /// @@ -408,7 +408,7 @@ private void Target_PointerExited(object sender, PointerRoutedEventArgs e) if (pointers.Count == 0) { - Target.Fill = new SolidColorBrush(Windows.UI.Colors.Red); + Target.Fill = new SolidColorBrush(Microsoft.UI.Colors.Red); } // Update the UI and pointer details. @@ -416,7 +416,7 @@ private void Target_PointerExited(object sender, PointerRoutedEventArgs e) } ``` -- This handler manages the [**PointerCanceled**](/uwp/api/windows.ui.xaml.uielement.pointercanceled) event. We add the event to the event log, remove the pointer from the pointer array, and update the pointer details. +- This handler manages the [**PointerCanceled**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.pointercanceled) event. We add the event to the event log, remove the pointer from the pointer array, and update the pointer details. ```csharp /// @@ -448,17 +448,17 @@ private void Target_PointerCanceled(object sender, PointerRoutedEventArgs e) if (pointers.Count == 0) { - Target.Fill = new SolidColorBrush(Windows.UI.Colors.Black); + Target.Fill = new SolidColorBrush(Microsoft.UI.Colors.Black); } DestroyInfoPop(ptrPt); } ``` -- This handler manages the [**PointerCaptureLost**](/uwp/api/windows.ui.xaml.uielement.pointercapturelost) event. We add the event to the event log, remove the pointer from the pointer array, and update the pointer details. +- This handler manages the [**PointerCaptureLost**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.pointercapturelost) event. We add the event to the event log, remove the pointer from the pointer array, and update the pointer details. > [!NOTE] - > [**PointerCaptureLost**](/uwp/api/windows.ui.xaml.uielement.pointercapturelost) can occur instead of [**PointerReleased**](/uwp/api/windows.ui.xaml.uielement.pointerreleased). Pointer capture can be lost for various reasons including user interaction, programmatic capture of another pointer, calling [**PointerReleased**](/uwp/api/windows.ui.xaml.uielement.pointerreleased).   + > [**PointerCaptureLost**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.pointercapturelost) can occur instead of [**PointerReleased**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.pointerreleased). Pointer capture can be lost for various reasons including user interaction, programmatic capture of another pointer, calling [**PointerReleased**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.pointerreleased).   ```csharp /// @@ -483,7 +483,7 @@ private void Target_PointerCaptureLost(object sender, PointerRoutedEventArgs e) if (pointers.Count == 0) { - Target.Fill = new SolidColorBrush(Windows.UI.Colors.Black); + Target.Fill = new SolidColorBrush(Microsoft.UI.Colors.Black); } // Remove contact from dictionary. @@ -499,9 +499,9 @@ private void Target_PointerCaptureLost(object sender, PointerRoutedEventArgs e) ### Get pointer properties -As stated earlier, you must get most extended pointer info from a [**Windows.UI.Input.PointerPoint**](/uwp/api/Windows.UI.Input.PointerPoint) object obtained through the [**GetCurrentPoint**](/uwp/api/windows.ui.xaml.input.pointerroutedeventargs.getcurrentpoint) and [**GetIntermediatePoints**](/uwp/api/windows.ui.xaml.input.pointerroutedeventargs.getintermediatepoints) methods of [**PointerRoutedEventArgs**](/uwp/api/Windows.UI.Xaml.Input.PointerRoutedEventArgs). The following code snippets show how. +As stated earlier, you must get most extended pointer info from a [**Microsoft.UI.Input.PointerPoint**](/windows/windows-app-sdk/api/winrt/microsoft.ui.input.pointerpoint) object obtained through the [**GetCurrentPoint**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.pointerroutedeventargs.getcurrentpoint) and [**GetIntermediatePoints**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.pointerroutedeventargs.getintermediatepoints) methods of [**PointerRoutedEventArgs**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.pointerroutedeventargs). The following code snippets show how. -- First, we create a new [**TextBlock**](/uwp/api/Windows.UI.Xaml.Controls.TextBlock) for each pointer. +- First, we create a new [**TextBlock**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.textblock) for each pointer. ```csharp /// @@ -512,7 +512,7 @@ void CreateInfoPop(PointerPoint ptrPt) { TextBlock pointerDetails = new TextBlock(); pointerDetails.Name = ptrPt.PointerId.ToString(); - pointerDetails.Foreground = new SolidColorBrush(Windows.UI.Colors.White); + pointerDetails.Foreground = new SolidColorBrush(Microsoft.UI.Colors.White); pointerDetails.Text = QueryPointer(ptrPt); TranslateTransform x = new TranslateTransform(); @@ -524,7 +524,7 @@ void CreateInfoPop(PointerPoint ptrPt) } ``` -- Then we provide a way to update the pointer info in an existing [**TextBlock**](/uwp/api/Windows.UI.Xaml.Controls.TextBlock) associated with that pointer. +- Then we provide a way to update the pointer info in an existing [**TextBlock**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.textblock) associated with that pointer. ```csharp /// @@ -535,7 +535,7 @@ void UpdateInfoPop(PointerPoint ptrPt) { foreach (var pointerDetails in Container.Children) { - if (pointerDetails.GetType().ToString() == "Windows.UI.Xaml.Controls.TextBlock") + if (pointerDetails.GetType().ToString() == "Microsoft.UI.Xaml.Controls.TextBlock") { TextBlock textBlock = (TextBlock)pointerDetails; if (textBlock.Name == ptrPt.PointerId.ToString()) @@ -608,7 +608,7 @@ String QueryPointer(PointerPoint ptrPt) ## Primary pointer Some input devices, such as a touch digitizer or touchpad, support more than the typical single pointer of a mouse or a pen (in most cases as the Surface Hub supports two pen inputs). -Use the read-only **[IsPrimary](/uwp/api/windows.ui.input.pointerpointproperties.IsPrimary)** property of the **[PointerPointerProperties](/uwp/api/windows.ui.input.pointerpointproperties)** class to identify and differentiate a single primary pointer (the primary pointer is always the first pointer detected during an input sequence). +Use the read-only **[IsPrimary](/windows/windows-app-sdk/api/winrt/microsoft.ui.input.pointerpointproperties.IsPrimary)** property of the **[PointerPointerProperties](/windows/windows-app-sdk/api/winrt/microsoft.ui.input.pointerpointproperties)** class to identify and differentiate a single primary pointer (the primary pointer is always the first pointer detected during an input sequence). By identifying the primary pointer, you can use it to emulate mouse or pen input, customize interactions, or provide some other specific functionality or UI. @@ -627,7 +627,7 @@ This particular app uses both color and animation to highlight the primary point ### Visual feedback -We define a **[UserControl](/uwp/api/windows.ui.xaml.controls.usercontrol)**, based on a XAML **[Ellipse](/uwp/api/windows.ui.xaml.shapes.ellipse)** object, that highlights where each pointer is on the canvas and uses a **[Storyboard](/uwp/api/windows.ui.xaml.media.animation.storyboard)** to animate the ellipse that corresponds to the primary pointer. +We define a **[UserControl](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.usercontrol)**, based on a XAML **[Ellipse](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.shapes.ellipse)** object, that highlights where each pointer is on the canvas and uses a **[Storyboard](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.animation.storyboard)** to animate the ellipse that corresponds to the primary pointer. **Here's the XAML:** @@ -702,9 +702,9 @@ We define a **[UserControl](/uwp/api/windows.ui.xaml.controls.usercontrol)**, ba And here's the code-behind: ```csharp using Windows.Foundation; -using Windows.UI.Xaml; -using Windows.UI.Xaml.Controls; -using Windows.UI.Xaml.Media; +using Microsoft.UI.Xaml; +using Microsoft.UI.Xaml.Controls; +using Microsoft.UI.Xaml.Media; // The User Control item template is documented at // https://go.microsoft.com/fwlink/?LinkId=234236 @@ -819,7 +819,7 @@ namespace UWP_Pointers ``` ### Create the UI -The UI in this example is limited to the input **[Canvas](/uwp/api/windows.ui.xaml.controls.canvas)** where we track any pointers and render the pointer indicators and primary pointer animation (if applicable), along with a header bar containing a pointer counter and a primary pointer identifier. +The UI in this example is limited to the input **[Canvas](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.canvas)** where we track any pointers and render the pointer indicators and primary pointer animation (if applicable), along with a header bar containing a pointer counter and a primary pointer identifier. Here's the MainPage.xaml: diff --git a/hub/apps/develop/input/identify-input-devices.md b/hub/apps/develop/input/identify-input-devices.md index 575cab7c5a..10b3c12869 100644 --- a/hub/apps/develop/input/identify-input-devices.md +++ b/hub/apps/develop/input/identify-input-devices.md @@ -16,7 +16,7 @@ ms.localizationpriority: medium Identify the input devices connected to a Windows app device and identify their capabilities and attributes. -> **Important APIs**: [**Windows.Devices.Input**](/uwp/api/Windows.Devices.Input), [**Windows.UI.Input**](/uwp/api/Windows.UI.Core), [**Windows.UI.Xaml.Input**](/uwp/api/Windows.UI.Input) +> **Important APIs**: [**Windows.Devices.Input**](/uwp/api/Windows.Devices.Input), [**Windows.UI.Input**](/uwp/api/Windows.UI.Input), [**Windows.UI.Xaml.Input**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.Input) ## Retrieve mouse properties @@ -27,7 +27,7 @@ The [**Windows.Devices.Input**](/uwp/api/Windows.Devices.Input) namespace contai   -The following code uses a series of [**TextBlock**](/uwp/api/Windows.UI.Xaml.Controls.TextBlock) elements to display the individual mouse properties and values. +The following code uses a series of [**TextBlock**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.Controls.TextBlock) elements to display the individual mouse properties and values. ```CSharp private void GetMouseProperties() @@ -46,7 +46,7 @@ private void GetMouseProperties() The [**Windows.Devices.Input**](/uwp/api/Windows.Devices.Input) namespace contains the [**KeyboardCapabilities**](/uwp/api/Windows.Devices.Input.KeyboardCapabilities) class used to retrieve whether a keyboard is connected. Just create a new **KeyboardCapabilities** object and get the [**KeyboardPresent**](/uwp/api/windows.devices.input.keyboardcapabilities.keyboardpresent) property. -The following code uses a [**TextBlock**](/uwp/api/Windows.UI.Xaml.Controls.TextBlock) element to display the keyboard property and value. +The following code uses a [**TextBlock**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.Controls.TextBlock) element to display the keyboard property and value. ```CSharp private void GetKeyboardProperties() @@ -65,7 +65,7 @@ The [**Windows.Devices.Input**](/uwp/api/Windows.Devices.Input) namespace contai   -The following code uses a series of [**TextBlock**](/uwp/api/Windows.UI.Xaml.Controls.TextBlock) elements to display the touch properties and values. +The following code uses a series of [**TextBlock**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.Controls.TextBlock) elements to display the touch properties and values. ```CSharp private void GetTouchProperties() diff --git a/hub/apps/develop/input/keyboard-accelerators.md b/hub/apps/develop/input/keyboard-accelerators.md index ca8595bf21..48df46830c 100644 --- a/hub/apps/develop/input/keyboard-accelerators.md +++ b/hub/apps/develop/input/keyboard-accelerators.md @@ -55,7 +55,7 @@ We recommend that you specify keyboard accelerators wherever appropriate in your ## Specify a keyboard accelerator -Use the [KeyboardAccelerator](/uwp/api/windows.ui.xaml.input.keyboardaccelerator.-ctor) APIs to create keyboard accelerators in Windows apps. With these APIs, you don't have to handle multiple KeyDown events to detect the key combination pressed, and you can localize accelerators in the app resources. +Use the [KeyboardAccelerator](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.keyboardaccelerator.-ctor) APIs to create keyboard accelerators in Windows apps. With these APIs, you don't have to handle multiple KeyDown events to detect the key combination pressed, and you can localize accelerators in the app resources. We recommend that you set keyboard accelerators for the most common actions in your app and document them using the menu item label or tooltip. In this example, we declare keyboard accelerators only for the Rename and Copy commands. @@ -130,11 +130,11 @@ We recommend that you set keyboard accelerators for the most common actions in y ![Screenshot of a keyboard accelerator in a tooltip.](images/accelerators/accelerators_tooltip.png) ***Keyboard accelerator described in a tooltip*** -The [UIElement](/uwp/api/windows.ui.xaml.uielement) object has a [KeyboardAccelerator](/uwp/api/windows.ui.xaml.input.keyboardaccelerator) collection, [KeyboardAccelerators](/uwp/api/windows.ui.xaml.uielement.KeyboardAccelerators), where you specify your custom KeyboardAccelerator objects and define the keystrokes for the keyboard accelerator: +The [UIElement](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement) object has a [KeyboardAccelerator](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.keyboardaccelerator) collection, [KeyboardAccelerators](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.keyboardaccelerators), where you specify your custom KeyboardAccelerator objects and define the keystrokes for the keyboard accelerator: -- **[Key](/uwp/api/windows.ui.xaml.input.keyboardaccelerator.Key)** - the [VirtualKey](/uwp/api/windows.system.virtualkey) used for the keyboard accelerator. +- **[Key](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.keyboardaccelerator.key)** - the [VirtualKey](/uwp/api/windows.system.virtualkey) used for the keyboard accelerator. -- **[Modifiers](/uwp/api/windows.ui.xaml.input.keyboardaccelerator.Modifiers)** – the [VirtualKeyModifiers](/uwp/api/windows.system.virtualkeymodifiers) used for the keyboard accelerator. If Modifiers is not set, the default value is None. +- **[Modifiers](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.keyboardaccelerator.modifiers)** – the [VirtualKeyModifiers](/uwp/api/windows.system.virtualkeymodifiers) used for the keyboard accelerator. If Modifiers is not set, the default value is None. > [!NOTE] > Single key (A, Delete, F2, Spacebar, Esc, Multimedia Key) accelerators and multi-key accelerators (Ctrl+Shift+M) are supported. However, Gamepad virtual keys are not supported. @@ -151,7 +151,7 @@ For example, Microsoft Outlook includes the following accelerators: Context menu actions affect only specific areas or elements, such as the selected characters in a text editor or a song in a playlist. For this reason, we recommend setting the scope of keyboard accelerators for context menu items to the parent of the context menu. -Use the [ScopeOwner](/uwp/api/windows.ui.xaml.input.keyboardaccelerator.ScopeOwner) property to specify the scope of the keyboard accelerator. This code demonstrates how to implement a context menu on a ListView with scoped keyboard accelerators: +Use the [ScopeOwner](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.keyboardaccelerator.scopeowner) property to specify the scope of the keyboard accelerator. This code demonstrates how to implement a context menu on a ListView with scoped keyboard accelerators: ``` xaml @@ -194,7 +194,7 @@ The ScopeOwner attribute of the MenuFlyoutItem.KeyboardAccelerators element mark ## Invoke a keyboard accelerator -The [KeyboardAccelerator](/uwp/api/windows.ui.xaml.input.keyboardaccelerator) object uses the [UI Automation (UIA) control pattern](/windows/desktop/WinAuto/uiauto-controlpatternsoverview) to take action when an accelerator is invoked. +The [KeyboardAccelerator](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.keyboardaccelerator) object uses the [UI Automation (UIA) control pattern](/windows/desktop/WinAuto/uiauto-controlpatternsoverview) to take action when an accelerator is invoked. The UIA [control patterns] expose common control functionality. For example, the Button control implements the [Invoke](/windows/desktop/WinAuto/uiauto-implementinginvoke) control pattern to support the Click event (typically a control is invoked by clicking, double-clicking, or pressing Enter, a predefined keyboard shortcut, or some other combination of keystrokes). When a keyboard accelerator is used to invoke a control, the XAML framework looks up whether the control implements the Invoke control pattern and, if so, activates it (it is not necessary to listen for the KeyboardAcceleratorInvoked event). @@ -218,11 +218,11 @@ If no match is identified, the accelerator is invalid and a debug message is pro ## Custom keyboard accelerator behavior -The Invoked event of the [KeyboardAccelerator](/uwp/api/windows.ui.xaml.input.keyboardaccelerator) object is fired when the accelerator is executed. The [KeyboardAcceleratorInvokedEventArgs](/uwp/api/windows.ui.xaml.input.keyboardacceleratorinvokedeventargs) event object includes the following properties: +The Invoked event of the [KeyboardAccelerator](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.keyboardaccelerator) object is fired when the accelerator is executed. The [KeyboardAcceleratorInvokedEventArgs](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.keyboardacceleratorinvokedeventargs) event object includes the following properties: -- [**Handled**](/uwp/api/windows.ui.xaml.input.keyboardacceleratorinvokedeventargs.handled) (Boolean): Setting this to true prevents the event triggering the control pattern and stops accelerator event bubbling. The default is false. -- [**Element**](/uwp/api/windows.ui.xaml.input.keyboardacceleratorinvokedeventargs.element) (DependencyObject): The object associated with the accelerator. -- [**KeyboardAccelerator**](/uwp/api/windows.ui.xaml.input.keyboardacceleratorinvokedeventargs.keyboardaccelerator): The keyboard accelerator used to raise the Invoked event. +- [**Handled**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.keyboardacceleratorinvokedeventargs.handled) (Boolean): Setting this to true prevents the event triggering the control pattern and stops accelerator event bubbling. The default is false. +- [**Element**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.keyboardacceleratorinvokedeventargs.element) (DependencyObject): The object associated with the accelerator. +- [**KeyboardAccelerator**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.keyboardacceleratorinvokedeventargs.keyboardaccelerator): The keyboard accelerator used to raise the Invoked event. Here we demonstrate how to define a collection of keyboard accelerators for items in a ListView, and how to handle the Invoked event for each accelerator. @@ -252,9 +252,9 @@ void RefreshInvoked(KeyboardAccelerator sender, KeyboardAcceleratorInvokedEventA ## Override default keyboard behavior -Some controls, when they have focus, support built-in keyboard accelerators that override any app-defined accelerator. For example, when a [TextBox](/uwp/api/windows.ui.xaml.controls.textbox) has focus, the Control+C accelerator only copies the currently selected text (app-defined accelerators are ignored and no other functionality is executed). +Some controls, when they have focus, support built-in keyboard accelerators that override any app-defined accelerator. For example, when a [TextBox](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.textbox) has focus, the Control+C accelerator only copies the currently selected text (app-defined accelerators are ignored and no other functionality is executed). -While we don't recommend overriding default control behaviors due to user familiarity and expectations, you can override a control's built-in keyboard accelerator. The following example shows how to override the Control+C keyboard accelerator for a [TextBox](/uwp/api/windows.ui.xaml.controls.textbox) through the [PreviewKeyDown](/uwp/api/windows.ui.xaml.uielement.previewkeydown) event handler: +While we don't recommend overriding default control behaviors due to user familiarity and expectations, you can override a control's built-in keyboard accelerator. The following example shows how to override the Control+C keyboard accelerator for a [TextBox](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.textbox) through the [PreviewKeyDown](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.previewkeydown) event handler: ``` csharp private void TextBlock_PreviewKeyDown(object sender, KeyRoutedEventArgs e) @@ -300,7 +300,7 @@ Parent and child controls can share the same accelerator. In this case, the pare ## Screen readers and keyboard accelerators -Screen readers such as Narrator can announce the keyboard accelerator key combination to users. By default, this is each modifier (in the VirtualModifiers enum order) followed by the key (and separated by "+" signs). You can customize this through the [AcceleratorKey](/uwp/api/windows.ui.xaml.automation.automationproperties.AcceleratorKeyProperty) AutomationProperties attached property. If more than one accelerator is specified, only the first is announced. +Screen readers such as Narrator can announce the keyboard accelerator key combination to users. By default, this is each modifier (in the VirtualModifiers enum order) followed by the key (and separated by "+" signs). You can customize this through the [AcceleratorKey](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.automation.automationproperties.acceleratorkeyproperty) AutomationProperties attached property. If more than one accelerator is specified, only the first is announced. In this example, the AutomationProperty.AcceleratorKey returns the string "Control+Shift+A": @@ -374,7 +374,7 @@ Notice that some of the combinations are not valid for localized versions of Win As keyboard accelerators are not typically described directly in the UI of your Windows application, you can improve discoverability through [tooltips](../../design/controls/tooltips.md), which display automatically when the user moves focus to, presses and holds, or hovers the mouse pointer over a control. The tooltip can identify whether a control has an associated keyboard accelerator and, if so, what the accelerator key combination is. -By default, when keyboard accelerators are declared, all controls (except [MenuFlyoutItem](/uwp/api/Windows.UI.Xaml.Controls.MenuFlyoutItem) and [ToggleMenuFlyoutItem](/uwp/api/windows.ui.xaml.controls.togglemenuflyoutitem)) present the corresponding key combinations in a tooltip. +By default, when keyboard accelerators are declared, all controls (except [MenuFlyoutItem](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.menuflyoutitem) and [ToggleMenuFlyoutItem](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.togglemenuflyoutitem)) present the corresponding key combinations in a tooltip. > [!NOTE] > If a control has more than one accelerator defined, only the first is presented. @@ -382,7 +382,7 @@ By default, when keyboard accelerators are declared, all controls (except [MenuF ![Screenshot of a Save button with a tool tip above it that indicates support for the Ctrl+S accelerator.](images/accelerators/accelerators_tooltip_savebutton_small.png)
*Accelerator key combo in tooltip* -For [Button](/uwp/api/windows.ui.xaml.controls.button), [AppBarButton](/uwp/api/windows.ui.xaml.controls.appbarbutton), and [AppBarToggleButton](/uwp/api/windows.ui.xaml.controls.appbartogglebutton) objects, the keyboard accelerator is appended to the control's default tooltip. For [MenuFlyoutItem](/uwp/api/windows.ui.xaml.controls.appbarbutton) and [ToggleMenuFlyoutItem](/uwp/api/windows.ui.xaml.controls.togglemenuflyoutitem) objects, the keyboard accelerator is displayed with the flyout text. +For [Button](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.button), [AppBarButton](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.appbarbutton), and [AppBarToggleButton](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.appbartogglebutton) objects, the keyboard accelerator is appended to the control's default tooltip. For [MenuFlyoutItem](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.menuflyoutitem) and [ToggleMenuFlyoutItem](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.togglemenuflyoutitem) objects, the keyboard accelerator is displayed with the flyout text. > [!NOTE] > Specifying a tooltip (see Button1 in the following example) overrides this behavior. @@ -455,7 +455,7 @@ For [Button](/uwp/api/windows.ui.xaml.controls.button), [AppBarButton](/uwp/api/ ![Screenshot of a Menu with MenuFlyoutItems that include accelerator key combos.](images/accelerators/accelerators-appbar-menuflyoutitem-small.png)
*Accelerator key combo appended to MenuFlyoutItem's text* -Control the presentation behavior by using the [KeyboardAcceleratorPlacementMode](/uwp/api/windows.ui.xaml.uielement.KeyboardAcceleratorPlacementMode) property, which accepts two values: [Auto](/uwp/api/windows.ui.xaml.input.keyboardacceleratorplacementmode) or [Hidden](/uwp/api/windows.ui.xaml.input.keyboardacceleratorplacementmode). +Control the presentation behavior by using the [KeyboardAcceleratorPlacementMode](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.keyboardacceleratorplacementmode) property, which accepts two values: [Auto](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.keyboardacceleratorplacementmode) or [Hidden](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.keyboardacceleratorplacementmode). ```xaml