From da7a7d0dafdcb5e2194cceb82fa26e3c4e2e7cc9 Mon Sep 17 00:00:00 2001 From: Qiutong Shen Date: Wed, 22 Apr 2026 13:48:35 +0800 Subject: [PATCH 1/3] fix: Update API reference links from UWP to WinUI 3 Updated 8 files with API link corrections: - /uwp/api/windows.ui.xaml.* -> /windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.* Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../accessibility/custom-automation-peers.md | 6 +- hub/apps/develop/data/drag-and-drop.md | 50 ++++++++-------- hub/apps/develop/input/focus-navigation.md | 48 +++++++-------- .../develop/input/handle-pointer-input.md | 60 +++++++++---------- hub/apps/develop/input/text-scaling.md | 6 +- .../platform/xaml/3-d-perspective-effects.md | 48 +++++++-------- .../develop/ui/controls/navigationview.md | 2 +- .../guides/winui3.md | 8 +-- 8 files changed, 114 insertions(+), 114 deletions(-) diff --git a/hub/apps/design/accessibility/custom-automation-peers.md b/hub/apps/design/accessibility/custom-automation-peers.md index 6cf6d02295..92d3885a82 100644 --- a/hub/apps/design/accessibility/custom-automation-peers.md +++ b/hub/apps/design/accessibility/custom-automation-peers.md @@ -461,6 +461,6 @@ More generally, be conservative with exceptions. Many clients cannot convert pro ## Related topics * [Accessibility overview](accessibility-overview.md) * [XAML accessibility sample](https://github.com/microsoftarchive/msdn-code-gallery-microsoft/tree/411c271e537727d737a53fa2cbe99eaecac00cc0/Official%20Windows%20Platform%20Sample/XAML%20accessibility%20sample) -* [**FrameworkElementAutomationPeer**](/uwp/api/Windows.UI.Xaml.Automation.Peers.FrameworkElementAutomationPeer) -* [**AutomationPeer**](/uwp/api/Windows.UI.Xaml.Automation.Peers.AutomationPeer) -* [**OnCreateAutomationPeer**](/uwp/api/windows.ui.xaml.uielement.oncreateautomationpeer) +* [**FrameworkElementAutomationPeer**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.Automation.Peers.FrameworkElementAutomationPeer) +* [**AutomationPeer**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.Automation.Peers.AutomationPeer) +* [**OnCreateAutomationPeer**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.oncreateautomationpeer) diff --git a/hub/apps/develop/data/drag-and-drop.md b/hub/apps/develop/data/drag-and-drop.md index 3d66a40297..ec0386e680 100644 --- a/hub/apps/develop/data/drag-and-drop.md +++ b/hub/apps/develop/data/drag-and-drop.md @@ -11,7 +11,7 @@ ms.localizationpriority: medium Drag and drop is an intuitive way to transfer data within an application or between applications on the Windows desktop. Drag and drop lets the user transfer data between applications or within an application using a standard gesture (press-hold-and-pan with the finger or press-and-pan with a mouse or a stylus). -> **Important APIs**: [CanDrag property](/uwp/api/windows.ui.xaml.uielement.candrag), [AllowDrop property](/uwp/api/windows.ui.xaml.uielement.allowdrop) +> **Important APIs**: [CanDrag property](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.candrag), [AllowDrop property](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.allowdrop) The drag source, which is the application or area where the drag gesture is triggered, provides the data to be transferred by filling a data package object that can contain standard data formats, including text, RTF, HTML, bitmaps, storage items or custom data formats. The source also indicates the kind of operations it supports: copy, move or link. When the pointer is released, drop occurs. The drop target, which is the application or area underneath the pointer, processes the data package and returns the type of operation it performed. @@ -22,7 +22,7 @@ Drag and drop allows data transfer between or within any kind of application, in Here's an overview of what you need to do to enable drag and drop in your app: 1. Enable dragging on an element by setting its **CanDrag** property to true. -2. Build the data package. The system handles images and text automatically, but for other content, you'll need to handle the [**DragStarting**](/uwp/api/windows.ui.xaml.uielement.dragstarting) and [**DropCompleted**](/uwp/api/windows.ui.xaml.uielement.dropcompleted) events and use them to construct your own data package. +2. Build the data package. The system handles images and text automatically, but for other content, you'll need to handle the [**DragStarting**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.dragstarting) and [**DropCompleted**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.dropcompleted) events and use them to construct your own data package. 3. Enable dropping by setting the **AllowDrop** property to **true** on all the elements that can receive dropped content. 4. Handle the **DragOver** event to let the system know what type of drag operations the element can receive. 5. Process the **Drop** event to receive the dropped content. @@ -31,11 +31,11 @@ Here's an overview of what you need to do to enable drag and drop in your app: ## Enable dragging -To enable dragging on an element, set its [**CanDrag**](/uwp/api/windows.ui.xaml.uielement.candrag) property to **true**. This make the element—and the elements it contains, in the case of collections like ListView—draggable. +To enable dragging on an element, set its [**CanDrag**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.candrag) property to **true**. This make the element—and the elements it contains, in the case of collections like ListView—draggable. Be specific about what's draggable. Users won't want to drag everything in your app, only certain items, such as images or text. -Here's how to set [**CanDrag**](/uwp/api/windows.ui.xaml.uielement.candrag). +Here's how to set [**CanDrag**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.candrag). ```xaml @@ -49,11 +49,11 @@ In most cases, the system will construct a data package for you. The system auto - Images - Text -For other content, you'll need to handle the [**DragStarting**](/uwp/api/windows.ui.xaml.uielement.dragstarting) and [**DropCompleted**](/uwp/api/windows.ui.xaml.uielement.dropcompleted) events and use them to construct your own [DataPackage](/uwp/api/windows.applicationmodel.datatransfer.datapackage). +For other content, you'll need to handle the [**DragStarting**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.dragstarting) and [**DropCompleted**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.dropcompleted) events and use them to construct your own [DataPackage](/uwp/api/windows.applicationmodel.datatransfer.datapackage). ## Enable dropping -The following markup shows how the [**AllowDrop**](/uwp/api/windows.ui.xaml.uielement.allowdrop) property can be used to specify that an area of the app is a valid drop target for a dragged item (the specified area must not have a null background, it must be able to receive pointer input, and the item cannot be dropped anywhere other than the specified area). +The following markup shows how the [**AllowDrop**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.allowdrop) property can be used to specify that an area of the app is a valid drop target for a dragged item (the specified area must not have a null background, it must be able to receive pointer input, and the item cannot be dropped anywhere other than the specified area). > [!NOTE] > Typically, a UI element has a null background by default. If you want users to be able to drop an item anywhere within your app, the app background cannot be null (set `Background="Transparent"` if the background should not be visible). @@ -67,7 +67,7 @@ The following markup shows how the [**AllowDrop**](/uwp/api/windows.ui.xaml.uiel ## Handle the DragOver event -The [**DragOver**](/uwp/api/windows.ui.xaml.uielement.dragover) event fires when a user has dragged an item over your app, but not yet dropped it. In this handler, you need to specify what kind of operations your app supports by using the [**AcceptedOperation**](/uwp/api/windows.ui.xaml.drageventargs.acceptedoperation) property. Copy is the most common. +The [**DragOver**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.dragover) event fires when a user has dragged an item over your app, but not yet dropped it. In this handler, you need to specify what kind of operations your app supports by using the [**AcceptedOperation**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.drageventargs.acceptedoperation) property. Copy is the most common. ```csharp private void Grid_DragOver(object sender, DragEventArgs e) @@ -78,7 +78,7 @@ private void Grid_DragOver(object sender, DragEventArgs e) ## Process the Drop event -The [**Drop**](/uwp/api/windows.ui.xaml.uielement.drop) event occurs when the user releases items in a valid drop area. Process them by using the [**DataView**](/uwp/api/windows.ui.xaml.drageventargs.dataview) property. +The [**Drop**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.drop) event occurs when the user releases items in a valid drop area. Process them by using the [**DataView**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.drageventargs.dataview) property. For simplicity in the example below, we'll assume the user dropped a single photo and access it directly. In reality, users can drop multiple items of varying formats simultaneously. Your app should handle this possibility by checking what types of files were dropped and how many there are, and process each accordingly. You should also consider notifying the user if they're trying to do something your app doesn't support. @@ -102,7 +102,7 @@ private async void Grid_Drop(object sender, DragEventArgs e) ## Customize the UI -The system provides a default UI for dragging and dropping. However, you can also choose to customize various parts of the UI by setting custom captions and glyphs, or by opting not to show a UI at all. To customize the UI, use the [**DragEventArgs.DragUIOverride**](/uwp/api/windows.ui.xaml.drageventargs.draguioverride) property. +The system provides a default UI for dragging and dropping. However, you can also choose to customize various parts of the UI by setting custom captions and glyphs, or by opting not to show a UI at all. To customize the UI, use the [**DragEventArgs.DragUIOverride**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.drageventargs.draguioverride) property. ```csharp private void Grid_DragOverCustomized(object sender, DragEventArgs e) @@ -121,7 +121,7 @@ private void Grid_DragOverCustomized(object sender, DragEventArgs e) ## Open a context menu on an item you can drag with touch -When using touch, dragging a [**UIElement**](/uwp/api/Windows.UI.Xaml.UIElement) and opening its context menu share similar touch gestures; each begins with a press and hold. Here's how the system disambiguates between the two actions for elements in your app that support both: +When using touch, dragging a [**UIElement**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.UIElement) and opening its context menu share similar touch gestures; each begins with a press and hold. Here's how the system disambiguates between the two actions for elements in your app that support both: - If a user presses and holds an item and begins dragging it within 500 milliseconds, the item is dragged and the context menu is not shown. - If the user presses and holds but does not drag within 500 milliseconds, the context menu is opened. @@ -129,19 +129,19 @@ When using touch, dragging a [**UIElement**](/uwp/api/Windows.UI.Xaml.UIElement) ## Designate an item in a ListView or GridView as a folder -You can specify a [**ListViewItem**](/uwp/api/Windows.UI.Xaml.Controls.ListViewItem) or [**GridViewItem**](/uwp/api/Windows.UI.Xaml.Controls.GridViewItem) as a folder. This is particularly useful for TreeView and File Explorer scenarios. To do so, explicitly set the [**AllowDrop**](/uwp/api/windows.ui.xaml.uielement.allowdrop) property to **True** on that item. +You can specify a [**ListViewItem**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.Controls.ListViewItem) or [**GridViewItem**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.Controls.GridViewItem) as a folder. This is particularly useful for TreeView and File Explorer scenarios. To do so, explicitly set the [**AllowDrop**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.allowdrop) property to **True** on that item. -The system will automatically show the appropriate animations for dropping into a folder versus a non-folder item. Your app code must continue to handle the [**Drop**](/uwp/api/windows.ui.xaml.uielement.drop) event on the folder item (as well as on the non-folder item) in order to update the data source and add the dropped item to the target folder. +The system will automatically show the appropriate animations for dropping into a folder versus a non-folder item. Your app code must continue to handle the [**Drop**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.drop) event on the folder item (as well as on the non-folder item) in order to update the data source and add the dropped item to the target folder. ## Enable drag and drop reordering within ListViews -[**ListView**](/uwp/api/Windows.UI.Xaml.Controls.ListView)s support drag-based reordering out of the box, using an API very similar to the **CanDrop** API described in this article. At minimum, you add the **AllowDrop** and **CanReorderItems** properties. +[**ListView**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.Controls.ListView)s support drag-based reordering out of the box, using an API very similar to the **CanDrop** API described in this article. At minimum, you add the **AllowDrop** and **CanReorderItems** properties. -See [**ListViewBase.CanReorderItems**](/uwp/api/windows.ui.xaml.controls.listviewbase.canreorderitems) for more information. +See [**ListViewBase.CanReorderItems**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.listviewbase.canreorderitems) for more information. ## Implementing custom drag and drop -The [UIElement](/uwp/api/windows.ui.xaml.uielement) class does most of the work of implementing drag-and-drop for you. But if you want, you can implement your own version by using the APIs below. +The [UIElement](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement) class does most of the work of implementing drag-and-drop for you. But if you want, you can implement your own version by using the APIs below. | Functionality | Windows App SDK
Microsoft.UI.Input.DragDrop namespace | | --- | --- | @@ -153,13 +153,13 @@ The [UIElement](/uwp/api/windows.ui.xaml.uielement) class does most of the work ## See also - [App-to-app communication](../../design/input/index.md) -- [AllowDrop](/uwp/api/windows.ui.xaml.uielement.allowdrop) -- [CanDrag](/uwp/api/windows.ui.xaml.uielement.candrag) -- [DragOver](/uwp/api/windows.ui.xaml.uielement.dragover) -- [AcceptedOperation](/uwp/api/windows.ui.xaml.drageventargs.acceptedoperation) -- [DataView](/uwp/api/windows.ui.xaml.drageventargs.dataview) -- [DragUIOverride](/uwp/api/windows.ui.xaml.drageventargs.draguioverride) -- [Drop](/uwp/api/windows.ui.xaml.uielement.drop) -- [IsDragSource](/uwp/api/windows.ui.xaml.controls.listviewbase.isdragsource) -- [**DragStarting**](/uwp/api/windows.ui.xaml.uielement.dragstarting) -- [**DropCompleted**](/uwp/api/windows.ui.xaml.uielement.dropcompleted) +- [AllowDrop](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.allowdrop) +- [CanDrag](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.candrag) +- [DragOver](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.dragover) +- [AcceptedOperation](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.drageventargs.acceptedoperation) +- [DataView](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.drageventargs.dataview) +- [DragUIOverride](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.drageventargs.draguioverride) +- [Drop](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.drop) +- [IsDragSource](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.listviewbase.isdragsource) +- [**DragStarting**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.dragstarting) +- [**DropCompleted**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.dropcompleted) diff --git a/hub/apps/develop/input/focus-navigation.md b/hub/apps/develop/input/focus-navigation.md index bd0cc5b08c..dc710848f4 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#Windows_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#Windows_UI_Xaml_UIElement_TabFocusNavigation) and [TabIndex](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.control#Windows_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#Windows_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#Windows_UI_Xaml_UIElement_TabFocusNavigation) and the [TabIndex](/windows/windows-app-sdk/api/winrt/microsoft.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](/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#Windows_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#Windows_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#Windows_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#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. -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#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. 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#Windows_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#Windows_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#Windows_UI_Xaml_Controls_Control_TabIndex) works the same way with both [UIElement.TabFocusNavigation](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement#Windows_UI_Xaml_UIElement_TabFocusNavigation) and [Control.TabNavigation](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.control#Windows_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#Windows_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/handle-pointer-input.md b/hub/apps/develop/input/handle-pointer-input.md index a0416ee6cc..2c4939b692 100644 --- a/hub/apps/develop/input/handle-pointer-input.md +++ b/hub/apps/develop/input/handle-pointer-input.md @@ -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.xaml.input.pointer.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.xaml.input.pointer.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.xaml.input.pointer.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.xaml.input.pointer.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**](/uwp/api/Windows.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. @@ -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 @@ -212,7 +212,7 @@ void Target_PointerPressed(object sender, PointerRoutedEventArgs e) } ``` -- 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 /// @@ -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 /// @@ -381,7 +381,7 @@ void Target_PointerReleased(object sender, PointerRoutedEventArgs e) } ``` -- 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 /// @@ -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 /// @@ -455,10 +455,10 @@ private void Target_PointerCanceled(object sender, PointerRoutedEventArgs e) } ``` -- 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 /// @@ -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 [**Windows.UI.Input.PointerPoint**](/uwp/api/Windows.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 /// @@ -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 /// @@ -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:** @@ -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/text-scaling.md b/hub/apps/develop/input/text-scaling.md index 75426249e6..fb7ccc5f67 100644 --- a/hub/apps/develop/input/text-scaling.md +++ b/hub/apps/develop/input/text-scaling.md @@ -127,7 +127,7 @@ If text wrapping is not the preferred behavior, most text controls let you eithe > [!NOTE] > If you need to clip your text, clip the end of the string, not the beginning. -In this example, we show how to clip text in a TextBlock using the [TextTrimming](/uwp/api/windows.ui.xaml.controls.textblock.texttrimming) property. +In this example, we show how to clip text in a TextBlock using the [TextTrimming](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.textblock.texttrimming) property. ``` xaml @@ -157,7 +157,7 @@ Here, we add a tooltip to a TextBlock that doesn't support text wrapping: When using font-based icons for emphasis or decoration, disable scaling on these characters. -Set the [IsTextScaleFactorEnabled](/uwp/api/windows.ui.xaml.controls.control.istextscalefactorenabled) property to `false` for most XAML controls. +Set the [IsTextScaleFactorEnabled](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.control.istextscalefactorenabled) property to `false` for most XAML controls. ### Support text scaling natively @@ -171,5 +171,5 @@ This topic provides an overview of text scaling support in Windows and includes ### API reference -- [IsTextScaleFactorEnabled](/uwp/api/windows.ui.xaml.controls.control.istextscalefactorenabled) +- [IsTextScaleFactorEnabled](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.control.istextscalefactorenabled) - [TextScaleFactorChanged](/uwp/api/windows.ui.viewmanagement.uisettings.textscalefactorchanged) diff --git a/hub/apps/develop/platform/xaml/3-d-perspective-effects.md b/hub/apps/develop/platform/xaml/3-d-perspective-effects.md index 213d2c6bfa..d1d5b6202d 100644 --- a/hub/apps/develop/platform/xaml/3-d-perspective-effects.md +++ b/hub/apps/develop/platform/xaml/3-d-perspective-effects.md @@ -20,7 +20,7 @@ Another common usage for perspective transforms is to arrange objects in relatio Besides creating static 3-D effects, you can animate the perspective transform properties to create moving 3-D effects. -You just saw perspective transforms applied to images, but you can apply these effects to any [**UIElement**](/uwp/api/Windows.UI.Xaml.UIElement), including controls. For example, you can apply a 3-D effect to an entire container of controls like this: +You just saw perspective transforms applied to images, but you can apply these effects to any [**UIElement**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.UIElement), including controls. For example, you can apply a 3-D effect to an entire container of controls like this: ![3-D effect applied to a container of elements](images/skewedstackpanel.png) @@ -37,11 +37,11 @@ Here is the XAML code used to create this sample: ``` -Here we focus on the properties of [**PlaneProjection**](/uwp/api/Windows.UI.Xaml.Media.PlaneProjection) which is used to rotate and move objects in 3-D space. The next sample allows you to experiment with these properties and see their effect on an object. +Here we focus on the properties of [**PlaneProjection**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.Media.PlaneProjection) which is used to rotate and move objects in 3-D space. The next sample allows you to experiment with these properties and see their effect on an object. ## PlaneProjection class -You can apply 3D effects can to any [**UIElement**](/uwp/api/Windows.UI.Xaml.UIElement), by setting the UIElement's [**Projection**](/uwp/api/windows.ui.xaml.uielement.projection) property using a [**PlaneProjection**](/uwp/api/Windows.UI.Xaml.Media.PlaneProjection). The **PlaneProjection** defines how the transform is rendered in space. The next example shows a simple case. +You can apply 3D effects can to any [**UIElement**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.UIElement), by setting the UIElement's [**Projection**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.projection) property using a [**PlaneProjection**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.Media.PlaneProjection). The **PlaneProjection** defines how the transform is rendered in space. The next example shows a simple case. ```xml @@ -51,11 +51,11 @@ You can apply 3D effects can to any [**UIElement**](/uwp/api/Windows.UI.Xaml.UIE ``` -This figure shows what the image renders as. The x-axis, y-axis, and z-axis are shown as red lines. The image is rotated backward 35 degrees around the x-axis using the [**RotationX**](/uwp/api/windows.ui.xaml.media.planeprojection.rotationx) property. +This figure shows what the image renders as. The x-axis, y-axis, and z-axis are shown as red lines. The image is rotated backward 35 degrees around the x-axis using the [**RotationX**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.planeprojection.rotationx) property. ![RotateX minus 35 degrees](images/3drotatexminus35.png) -The [**RotationY**](/uwp/api/windows.ui.xaml.media.planeprojection.rotationy) property rotates around the y-axis of the center of rotation. +The [**RotationY**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.planeprojection.rotationy) property rotates around the y-axis of the center of rotation. ```xml @@ -67,7 +67,7 @@ The [**RotationY**](/uwp/api/windows.ui.xaml.media.planeprojection.rotationy) pr ![RotateY minus 35 degrees](images/3drotateyminus35.png) -The [**RotationZ**](/uwp/api/windows.ui.xaml.media.planeprojection.rotationz) property rotates around the z-axis of the center of rotation (a line that is perpendicular to the plane of the object). +The [**RotationZ**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.planeprojection.rotationz) property rotates around the z-axis of the center of rotation (a line that is perpendicular to the plane of the object). ```xml @@ -81,9 +81,9 @@ The [**RotationZ**](/uwp/api/windows.ui.xaml.media.planeprojection.rotationz) pr The rotation properties can specify a positive or negative value to rotate in either direction. The absolute number can be greater than 360, which rotates the object more than one full rotation. -You can move the center of rotation by using the [**CenterOfRotationX**](/uwp/api/windows.ui.xaml.media.planeprojection.centerofrotationx), [**CenterOfRotationY**](/uwp/api/windows.ui.xaml.media.planeprojection.centerofrotationy), and [**CenterOfRotationZ**](/uwp/api/windows.ui.xaml.media.planeprojection.centerofrotationz) properties. By default, the axes of rotation run directly through the center of the object, causing the object to rotate around its center. But if you move the center of rotation to the outer edge of the object, it will rotate around that edge. The default values for **CenterOfRotationX** and **CenterOfRotationY** are 0.5, and the default value for **CenterOfRotationZ** is 0. For **CenterOfRotationX** and **CenterOfRotationY**, values between 0 and 1 set the pivot point at some location within the object. A value of 0 denotes one object edge and 1 denotes the opposite edge. Values outside of this range are allowed and will move the center of rotation accordingly. Because the z-axis of the center of rotation is drawn through the plane of the object, you can move the center of rotation behind the object using a negative number and in front of the object (toward you) using a positive number. +You can move the center of rotation by using the [**CenterOfRotationX**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.planeprojection.centerofrotationx), [**CenterOfRotationY**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.planeprojection.centerofrotationy), and [**CenterOfRotationZ**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.planeprojection.centerofrotationz) properties. By default, the axes of rotation run directly through the center of the object, causing the object to rotate around its center. But if you move the center of rotation to the outer edge of the object, it will rotate around that edge. The default values for **CenterOfRotationX** and **CenterOfRotationY** are 0.5, and the default value for **CenterOfRotationZ** is 0. For **CenterOfRotationX** and **CenterOfRotationY**, values between 0 and 1 set the pivot point at some location within the object. A value of 0 denotes one object edge and 1 denotes the opposite edge. Values outside of this range are allowed and will move the center of rotation accordingly. Because the z-axis of the center of rotation is drawn through the plane of the object, you can move the center of rotation behind the object using a negative number and in front of the object (toward you) using a positive number. -[**CenterOfRotationX**](/uwp/api/windows.ui.xaml.media.planeprojection.centerofrotationx) moves the center of rotation along the x-axis parallel to the object while [**CenterOfRotationY**](/uwp/api/windows.ui.xaml.media.planeprojection.centerofrotationy) moves the center or rotation along the y-axis of the object. The next illustrations demonstrate using different values for **CenterOfRotationY**. +[**CenterOfRotationX**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.planeprojection.centerofrotationx) moves the center of rotation along the x-axis parallel to the object while [**CenterOfRotationY**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.planeprojection.centerofrotationy) moves the center or rotation along the y-axis of the object. The next illustrations demonstrate using different values for **CenterOfRotationY**. ```xml @@ -108,7 +108,7 @@ You can move the center of rotation by using the [**CenterOfRotationX**](/uwp/ap ![CenterOfRotationY equals 0.1](images/3dcenterofrotationy0point1.png) -Notice how the image rotates around the center when the [**CenterOfRotationY**](/uwp/api/windows.ui.xaml.media.planeprojection.centerofrotationy) property is set to the default value of 0.5 and rotates near the upper edge when set to 0.1. You see similar behavior when changing the [**CenterOfRotationX**](/uwp/api/windows.ui.xaml.media.planeprojection.centerofrotationx) property to move where the [**RotationY**](/uwp/api/windows.ui.xaml.media.planeprojection.rotationy) property rotates the object. +Notice how the image rotates around the center when the [**CenterOfRotationY**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.planeprojection.centerofrotationy) property is set to the default value of 0.5 and rotates near the upper edge when set to 0.1. You see similar behavior when changing the [**CenterOfRotationX**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.planeprojection.centerofrotationx) property to move where the [**RotationY**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.planeprojection.rotationy) property rotates the object. ```xml @@ -133,39 +133,39 @@ Notice how the image rotates around the center when the [**CenterOfRotationY**]( ![CenterOfRotationX equals 0.9](images/3dcenterofrotationx0point9.png) -Use the [**CenterOfRotationZ**](/uwp/api/windows.ui.xaml.media.planeprojection.centerofrotationz) to place the center of rotation above or below the plane of the object. This way, you can rotate the object around the point analogous to a planet orbiting around a star. +Use the [**CenterOfRotationZ**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.planeprojection.centerofrotationz) to place the center of rotation above or below the plane of the object. This way, you can rotate the object around the point analogous to a planet orbiting around a star. ## Positioning an object So far, you learned how to rotate an object in space. You can position these rotated objects in space relative to one another by using these properties: -- [**LocalOffsetX**](/uwp/api/windows.ui.xaml.media.planeprojection.localoffsetx) moves an object along the x-axis of the plane of a rotated object. -- [**LocalOffsetY**](/uwp/api/windows.ui.xaml.media.planeprojection.localoffsety) moves an object along the y-axis of the plane of a rotated object. -- [**LocalOffsetZ**](/uwp/api/windows.ui.xaml.media.planeprojection.localoffsetz) moves an object along the z-axis of the plane of a rotated object. -- [**GlobalOffsetX**](/uwp/api/windows.ui.xaml.media.planeprojection.globaloffsetx) moves an object along the screen-aligned x-axis. -- [**GlobalOffsetY**](/uwp/api/windows.ui.xaml.media.planeprojection.globaloffsety) moves an object along the screen-aligned y-axis. -- [**GlobalOffsetZ**](/uwp/api/windows.ui.xaml.media.planeprojection.globaloffsetz) moves an object along the screen-aligned z-axis. +- [**LocalOffsetX**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.planeprojection.localoffsetx) moves an object along the x-axis of the plane of a rotated object. +- [**LocalOffsetY**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.planeprojection.localoffsety) moves an object along the y-axis of the plane of a rotated object. +- [**LocalOffsetZ**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.planeprojection.localoffsetz) moves an object along the z-axis of the plane of a rotated object. +- [**GlobalOffsetX**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.planeprojection.globaloffsetx) moves an object along the screen-aligned x-axis. +- [**GlobalOffsetY**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.planeprojection.globaloffsety) moves an object along the screen-aligned y-axis. +- [**GlobalOffsetZ**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.planeprojection.globaloffsetz) moves an object along the screen-aligned z-axis. **Local offset** -The [**LocalOffsetX**](/uwp/api/windows.ui.xaml.media.planeprojection.localoffsetx), [**LocalOffsetY**](/uwp/api/windows.ui.xaml.media.planeprojection.localoffsety), and [**LocalOffsetZ**](/uwp/api/windows.ui.xaml.media.planeprojection.localoffsetz) properties translate an object along the respective axis of the plane of the object after it has been rotated. Therefore, the rotation of the object determines the direction that the object is translated. To demonstrate this concept, the next sample animates **LocalOffsetX** from 0 to 400 and [**RotationY**](/uwp/api/windows.ui.xaml.media.planeprojection.rotationy) from 0 to 65 degrees. +The [**LocalOffsetX**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.planeprojection.localoffsetx), [**LocalOffsetY**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.planeprojection.localoffsety), and [**LocalOffsetZ**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.planeprojection.localoffsetz) properties translate an object along the respective axis of the plane of the object after it has been rotated. Therefore, the rotation of the object determines the direction that the object is translated. To demonstrate this concept, the next sample animates **LocalOffsetX** from 0 to 400 and [**RotationY**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.planeprojection.rotationy) from 0 to 65 degrees. -Notice in the preceding sample that the object is moving along its own x-axis. At the very beginning of the animation, when the [**RotationY**](/uwp/api/windows.ui.xaml.media.planeprojection.rotationy) value is near zero (parallel to the screen), the object moves along the screen in the x direction, but as the object rotates toward you, the object moves along the x-axis of the plane of the object toward you. On the other hand, if you animated the **RotationY** property to -65 degrees, the object would curve away from you. +Notice in the preceding sample that the object is moving along its own x-axis. At the very beginning of the animation, when the [**RotationY**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.planeprojection.rotationy) value is near zero (parallel to the screen), the object moves along the screen in the x direction, but as the object rotates toward you, the object moves along the x-axis of the plane of the object toward you. On the other hand, if you animated the **RotationY** property to -65 degrees, the object would curve away from you. -[**LocalOffsetY**](/uwp/api/windows.ui.xaml.media.planeprojection.localoffsety) works similarly to [**LocalOffsetX**](/uwp/api/windows.ui.xaml.media.planeprojection.localoffsetx), except that it moves along the vertical axis, so changing [**RotationX**](/uwp/api/windows.ui.xaml.media.planeprojection.rotationx) affects the direction **LocalOffsetY** moves the object. In the next sample, **LocalOffsetY** is animated from 0 to 400 and **RotationX** from 0 to 65 degrees. +[**LocalOffsetY**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.planeprojection.localoffsety) works similarly to [**LocalOffsetX**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.planeprojection.localoffsetx), except that it moves along the vertical axis, so changing [**RotationX**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.planeprojection.rotationx) affects the direction **LocalOffsetY** moves the object. In the next sample, **LocalOffsetY** is animated from 0 to 400 and **RotationX** from 0 to 65 degrees. -[**LocalOffsetZ**](/uwp/api/windows.ui.xaml.media.planeprojection.localoffsetz) translates the object perpendicular to the plane of the object as though a vector was drawn directly through the center from behind the object out toward you. To demonstrate how **LocalOffsetZ** works, the next sample animates **LocalOffsetZ** from 0 to 400 and [**RotationX**](/uwp/api/windows.ui.xaml.media.planeprojection.rotationx) from 0 to 65 degrees. +[**LocalOffsetZ**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.planeprojection.localoffsetz) translates the object perpendicular to the plane of the object as though a vector was drawn directly through the center from behind the object out toward you. To demonstrate how **LocalOffsetZ** works, the next sample animates **LocalOffsetZ** from 0 to 400 and [**RotationX**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.planeprojection.rotationx) from 0 to 65 degrees. -At the beginning of the animation, when the [**RotationX**](/uwp/api/windows.ui.xaml.media.planeprojection.rotationx) value is near zero (parallel to the screen), the object moves directly out toward you, but as the face of the object rotates down, the object moves down instead. +At the beginning of the animation, when the [**RotationX**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.planeprojection.rotationx) value is near zero (parallel to the screen), the object moves directly out toward you, but as the face of the object rotates down, the object moves down instead. **Global offset** -The [**GlobalOffsetX**](/uwp/api/windows.ui.xaml.media.planeprojection.globaloffsetx), [**GlobalOffsetY**](/uwp/api/windows.ui.xaml.media.planeprojection.globaloffsety), and [**GlobalOffsetZ**](/uwp/api/windows.ui.xaml.media.planeprojection.globaloffsetz) properties translate the object along axes relative to the screen. That is, unlike the local offset properties, the axis the object moves along is independent of any rotation applied to the object. These properties are useful when you want to simply move the object along the x-, y-, or z-axis of the screen without worrying about the rotation applied to the object. +The [**GlobalOffsetX**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.planeprojection.globaloffsetx), [**GlobalOffsetY**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.planeprojection.globaloffsety), and [**GlobalOffsetZ**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.planeprojection.globaloffsetz) properties translate the object along axes relative to the screen. That is, unlike the local offset properties, the axis the object moves along is independent of any rotation applied to the object. These properties are useful when you want to simply move the object along the x-, y-, or z-axis of the screen without worrying about the rotation applied to the object. -The next sample animates [**GlobalOffsetX**](/uwp/api/windows.ui.xaml.media.planeprojection.globaloffsetx) from 0 to 400 and [**RotationY**](/uwp/api/windows.ui.xaml.media.planeprojection.rotationy) from 0 to 65 degrees. +The next sample animates [**GlobalOffsetX**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.planeprojection.globaloffsetx) from 0 to 400 and [**RotationY**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.planeprojection.rotationy) from 0 to 65 degrees. Notice in this sample that the object does not change course as it rotates. That is because the object is being moved along the x-axis of the screen without regard to its rotation. ## More complex semi-3D scenarios -You can use the [**Matrix3DProjection**](/uwp/api/Windows.UI.Xaml.Media.Matrix3DProjection) and [**Matrix3D**](/uwp/api/Windows.UI.Xaml.Media.Media3D.Matrix3D) types for more complex semi-3D scenarios than are possible with the [**PlaneProjection**](/uwp/api/Windows.UI.Xaml.Media.PlaneProjection). **Matrix3DProjection** provides you with a complete 3D transform matrix to apply to any [**UIElement**](/uwp/api/Windows.UI.Xaml.UIElement), so that you can apply arbitrary model transformation matrices and perspective matrices to elements. Keep in mind that these API are minimal and therefore if you use them, you will need to write the code that correctly creates the 3D transform matrices. Because of this, it is easier to use **PlaneProjection** for simple 3D scenarios. +You can use the [**Matrix3DProjection**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.Media.Matrix3DProjection) and [**Matrix3D**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.Media.Media3D.Matrix3D) types for more complex semi-3D scenarios than are possible with the [**PlaneProjection**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.Media.PlaneProjection). **Matrix3DProjection** provides you with a complete 3D transform matrix to apply to any [**UIElement**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.UIElement), so that you can apply arbitrary model transformation matrices and perspective matrices to elements. Keep in mind that these API are minimal and therefore if you use them, you will need to write the code that correctly creates the 3D transform matrices. Because of this, it is easier to use **PlaneProjection** for simple 3D scenarios. diff --git a/hub/apps/develop/ui/controls/navigationview.md b/hub/apps/develop/ui/controls/navigationview.md index 8481ff7b6b..248fc11a02 100644 --- a/hub/apps/develop/ui/controls/navigationview.md +++ b/hub/apps/develop/ui/controls/navigationview.md @@ -403,7 +403,7 @@ You can hide or disable the back button by setting these properties: This example shows how you can use NavigationView with both a top navigation pane on large window sizes and a left navigation pane on small window sizes. It can be adapted to left-only navigation by removing the *top* navigation settings in the VisualStateManager. -The example demonstrates a common way to set up navigation data that will work for many scenarios. In this example, you first store (in the tag of the [NavigationViewItem](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.navigationviewitem)) the full type name of the page to which you want to navigate. In the event handler, you unbox that value, turn it into a [Type]()(C#) or [**Windows::UI::Xaml::Interop::TypeName**](/uwp/api/windows.ui.xaml.interop.typename)(C++/WinRT) object, and use that to navigate to the destination page. This lets you create unit tests to confirm that the values inside your tags are of a valid type. (Also see [Boxing and unboxing values to IInspectable with C++/WinRT](/windows/uwp/cpp-and-winrt-apis/boxing)). It also demonstrates how to implement backwards navigation with NavigationView's back button. +The example demonstrates a common way to set up navigation data that will work for many scenarios. In this example, you first store (in the tag of the [NavigationViewItem](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.navigationviewitem)) the full type name of the page to which you want to navigate. In the event handler, you unbox that value, turn it into a [Type]()(C#) or [**Windows::UI::Xaml::Interop::TypeName**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.interop.typename)(C++/WinRT) object, and use that to navigate to the destination page. This lets you create unit tests to confirm that the values inside your tags are of a valid type. (Also see [Boxing and unboxing values to IInspectable with C++/WinRT](/windows/uwp/cpp-and-winrt-apis/boxing)). It also demonstrates how to implement backwards navigation with NavigationView's back button. This code assumes that your app contains pages with the following names to navigate to: *HomePage*, *AppsPage*, *GamesPage*, *MusicPage*, *MyContentPage*, and *SettingsPage*. Code for these pages is not shown. diff --git a/hub/apps/windows-app-sdk/migrate-to-windows-app-sdk/guides/winui3.md b/hub/apps/windows-app-sdk/migrate-to-windows-app-sdk/guides/winui3.md index ede9b53a82..106be65c47 100644 --- a/hub/apps/windows-app-sdk/migrate-to-windows-app-sdk/guides/winui3.md +++ b/hub/apps/windows-app-sdk/migrate-to-windows-app-sdk/guides/winui3.md @@ -30,7 +30,7 @@ In the Windows App SDK, the [**AcrylicBrush**](/windows/windows-app-sdk/api/winr ## Change Windows.UI.Xaml.Window.Current to App.Window -This section applies if you're using the [**Windows.UI.Xaml.Window.Current**](/uwp/api/windows.ui.xaml.window.current) property in your UWP app. That property isn't supported in the Windows App SDK, so this section describes how to port UWP code that uses **Window.Current**. +This section applies if you're using the [**Windows.UI.Xaml.Window.Current**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.window.current) property in your UWP app. That property isn't supported in the Windows App SDK, so this section describes how to port UWP code that uses **Window.Current**. ```csharp // MainPage.xaml.cs in a UWP app @@ -93,7 +93,7 @@ In your UWP app, if you use certain types from the [**Windows.UI.Popups**](/uwp/ The steps that you have to follow in a desktop app are described in [Display WinRT UI objects that depend on CoreWindow](../../../develop/ui-input/display-ui-objects.md). > [!NOTE] -> For new apps, we recommend using the [**ContentDialog**](/uwp/api/windows.ui.xaml.controls.contentdialog) control instead of [**MessageDialog**](/uwp/api/windows.ui.popups.messagedialog). For more info, see the [ContentDialog, and Popup](#contentdialog-and-popup) section below. +> For new apps, we recommend using the [**ContentDialog**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.contentdialog) control instead of [**MessageDialog**](/uwp/api/windows.ui.popups.messagedialog). For more info, see the [ContentDialog, and Popup](#contentdialog-and-popup) section below. Here's some typical UWP code to display a [**MessageDialog**](/uwp/api/windows.ui.popups.messagedialog). @@ -181,7 +181,7 @@ To use **DataTransferManager.ShowShareUI** in your Windows App SDK app, you need ## ContentDialog, and Popup -If in your UWP app you're using the [**Windows.UI.Xaml.Controls.ContentDialog**](/uwp/api/windows.ui.xaml.controls.contentdialog) or [**Windows.UI.Xaml.Controls.Primitives.Popup**](/uwp/api/windows.ui.xaml.controls.primitives.popup) classes, then this section contains info to help you migrate that code. The code examples below use **ContentDialog**, but you can apply exactly the same techniques to displaying a **Popup** object. +If in your UWP app you're using the [**Windows.UI.Xaml.Controls.ContentDialog**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.contentdialog) or [**Windows.UI.Xaml.Controls.Primitives.Popup**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.primitives.popup) classes, then this section contains info to help you migrate that code. The code examples below use **ContentDialog**, but you can apply exactly the same techniques to displaying a **Popup** object. Here's some typical UWP code to display a **ContentDialog**. @@ -249,7 +249,7 @@ In addition, you won't be able to copy a `` element over to **Ma ## AcrylicBrush.BackgroundSource property -The [**AcrylicBrush.BackgroundSource**](/uwp/api/windows.ui.xaml.media.acrylicbrush.backgroundsource) property exists in UWP, but not in the Windows App SDK. In the Windows App SDK, the [**AcrylicBrush**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.acrylicbrush) always samples from the app content. +The [**AcrylicBrush.BackgroundSource**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.acrylicbrush.backgroundsource) property exists in UWP, but not in the Windows App SDK. In the Windows App SDK, the [**AcrylicBrush**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.acrylicbrush) always samples from the app content. So if you're accessing the **AcrylicBrush.BackgroundSource** property in the source code of your UWP app (whether that's in XAML markup or in imperative code), then remove that code when migrating your app to the Windows App SDK. Instead, use the [DesktopAcrylicController](/windows/windows-app-sdk/api/winrt/microsoft.ui.composition.systembackdrops.desktopacryliccontroller) class. From 8baf67982bc38a2703ace8131714806366011e72 Mon Sep 17 00:00:00 2001 From: Qiutong Shen Date: Wed, 22 Apr 2026 15:59:28 +0800 Subject: [PATCH 2/3] fix uwp api --- ...djust-layout-and-fonts--and-support-rtl.md | 4 +- .../layout/boxpanel-example-custom-panel.md | 54 ++++++------- .../develop/camera/basic-photo-capture.md | 2 +- .../develop/input/handle-pointer-input.md | 28 +++---- .../develop/input/keyboard-accelerators.md | 44 +++++------ .../develop/input/keyboard-interactions.md | 10 +-- hub/apps/develop/input/mouse-interactions.md | 76 +++++++++--------- .../develop/input/touch-developer-guide.md | 78 +++++++++---------- .../develop/input/touchpad-interactions.md | 2 +- ...nput-scope-to-change-the-touch-keyboard.md | 36 ++++----- .../develop/ui/controls/navigationview.md | 14 ++-- .../develop/ui/controls/person-picture.md | 6 +- hub/apps/develop/ui/display-ui-objects.md | 2 +- .../navigation/navigate-between-two-pages.md | 4 +- ...gation-history-and-backwards-navigation.md | 2 +- 15 files changed, 181 insertions(+), 181 deletions(-) diff --git a/hub/apps/design/globalizing/adjust-layout-and-fonts--and-support-rtl.md b/hub/apps/design/globalizing/adjust-layout-and-fonts--and-support-rtl.md index 18bb5dda34..156d3929bb 100644 --- a/hub/apps/design/globalizing/adjust-layout-and-fonts--and-support-rtl.md +++ b/hub/apps/design/globalizing/adjust-layout-and-fonts--and-support-rtl.md @@ -59,11 +59,11 @@ this.languageTag = Windows.Globalization.ApplicationLanguages.Languages[0]; var flowDirectionSetting = Windows.ApplicationModel.Resources.Core.ResourceContext.GetForCurrentView().QualifierValues["LayoutDirection"]; if (flowDirectionSetting == "LTR") { - this.layoutRoot.FlowDirection = Windows.UI.Xaml.FlowDirection.LeftToRight; + this.layoutRoot.FlowDirection = Microsoft.UI.Xaml.FlowDirection.LeftToRight; } else { - this.layoutRoot.FlowDirection = Windows.UI.Xaml.FlowDirection.RightToLeft; + this.layoutRoot.FlowDirection = Microsoft.UI.Xaml.FlowDirection.RightToLeft; } ``` diff --git a/hub/apps/design/layout/boxpanel-example-custom-panel.md b/hub/apps/design/layout/boxpanel-example-custom-panel.md index 9283395139..76ec72a18e 100644 --- a/hub/apps/design/layout/boxpanel-example-custom-panel.md +++ b/hub/apps/design/layout/boxpanel-example-custom-panel.md @@ -15,13 +15,13 @@ ms.localizationpriority: medium --- # "Tutorial: Create a custom panel -Learn to write code for a custom [**Panel**](/uwp/api/Windows.UI.Xaml.Controls.Panel) class, implementing [**ArrangeOverride**](/uwp/api/windows.ui.xaml.frameworkelement.arrangeoverride) and [**MeasureOverride**](/uwp/api/windows.ui.xaml.frameworkelement.measureoverride) methods, and using the [**Children**](/uwp/api/windows.ui.xaml.controls.panel.children) property. +Learn to write code for a custom [**Panel**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.Controls.Panel) class, implementing [**ArrangeOverride**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.frameworkelement.arrangeoverride) and [**MeasureOverride**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.frameworkelement.measureoverride) methods, and using the [**Children**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.panel.children) property. -> **Important APIs**: [**Panel**](/uwp/api/Windows.UI.Xaml.Controls.Panel), [**ArrangeOverride**](/uwp/api/windows.ui.xaml.frameworkelement.arrangeoverride),[**MeasureOverride**](/uwp/api/windows.ui.xaml.frameworkelement.measureoverride) +> **Important APIs**: [**Panel**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.Controls.Panel), [**ArrangeOverride**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.frameworkelement.arrangeoverride),[**MeasureOverride**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.frameworkelement.measureoverride) The example code shows a custom panel implementation, but we don't devote a lot of time explaining the layout concepts that influence how you can customize a panel for different layout scenarios. If you want more info about these layout concepts and how they might apply to your particular layout scenario, see [XAML custom panels overview](custom-panels-overview.md). -A *panel* is an object that provides a layout behavior for child elements it contains, when the XAML layout system runs and your app UI is rendered. You can define custom panels for XAML layout by deriving a custom class from the [**Panel**](/uwp/api/Windows.UI.Xaml.Controls.Panel) class. You provide behavior for your panel by overriding the [**ArrangeOverride**](/uwp/api/windows.ui.xaml.frameworkelement.arrangeoverride) and [**MeasureOverride**](/uwp/api/windows.ui.xaml.frameworkelement.measureoverride) methods, supplying logic that measures and arranges the child elements. This example derives from **Panel**. When you start from **Panel**, **ArrangeOverride** and **MeasureOverride** methods don't have a starting behavior. Your code is providing the gateway by which child elements become known to the XAML layout system and get rendered in the UI. So, it's really important that your code accounts for all child elements and follows the patterns the layout system expects. +A *panel* is an object that provides a layout behavior for child elements it contains, when the XAML layout system runs and your app UI is rendered. You can define custom panels for XAML layout by deriving a custom class from the [**Panel**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.Controls.Panel) class. You provide behavior for your panel by overriding the [**ArrangeOverride**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.frameworkelement.arrangeoverride) and [**MeasureOverride**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.frameworkelement.measureoverride) methods, supplying logic that measures and arranges the child elements. This example derives from **Panel**. When you start from **Panel**, **ArrangeOverride** and **MeasureOverride** methods don't have a starting behavior. Your code is providing the gateway by which child elements become known to the XAML layout system and get rendered in the UI. So, it's really important that your code accounts for all child elements and follows the patterns the layout system expects. ## Your layout scenario @@ -37,7 +37,7 @@ With that in mind, the `BoxPanel` shown here is for a particular scenario. In th ## Start by deriving from **Panel** -Start by deriving a custom class from [**Panel**](/uwp/api/Windows.UI.Xaml.Controls.Panel). Probably the easiest way to do this is to define a separate code file for this class, using the **Add** | **New Item** | **Class** context menu options for a project from the **Solution Explorer** in Microsoft Visual Studio. Name the class (and file) `BoxPanel`. +Start by deriving a custom class from [**Panel**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.Controls.Panel). Probably the easiest way to do this is to define a separate code file for this class, using the **Add** | **New Item** | **Class** context menu options for a project from the **Solution Explorer** in Microsoft Visual Studio. Name the class (and file) `BoxPanel`. The template file for a class doesn't start with many **using** statements because it's not specifically for Windows apps. So first, add **using** statements. The template file also starts with a few **using** statements that you probably don't need, and can be deleted. Here's a suggested list of **using** statements that can resolve types you'll need for typical custom panel code: @@ -45,12 +45,12 @@ The template file for a class doesn't start with many **using** statements becau using System; using System.Collections.Generic; // if you need to cast IEnumerable for iteration, or define your own collection properties using Windows.Foundation; // Point, Size, and Rect -using Windows.UI.Xaml; // DependencyObject, UIElement, and FrameworkElement -using Windows.UI.Xaml.Controls; // Panel -using Windows.UI.Xaml.Media; // if you need Brushes or other utilities +using Microsoft.UI.Xaml; // DependencyObject, UIElement, and FrameworkElement +using Microsoft.UI.Xaml.Controls; // Panel +using Microsoft.UI.Xaml.Media; // if you need Brushes or other utilities ``` -Now that you can resolve [**Panel**](/uwp/api/Windows.UI.Xaml.Controls.Panel), make it the base class of `BoxPanel`. Also, make `BoxPanel` public: +Now that you can resolve [**Panel**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.Controls.Panel), make it the base class of `BoxPanel`. Also, make `BoxPanel` public: ```CSharp public class BoxPanel : Panel @@ -66,9 +66,9 @@ After you've done this, the complete code file looks like this (removing comment using System; using System.Collections.Generic; 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; public class BoxPanel : Panel { @@ -115,18 +115,18 @@ protected override Size MeasureOverride(Size availableSize) } ``` -The necessary pattern of a [**MeasureOverride**](/uwp/api/windows.ui.xaml.frameworkelement.measureoverride) implementation is the loop through each element in [**Panel.Children**](/uwp/api/windows.ui.xaml.controls.panel.children). Always call the [**Measure**](/uwp/api/windows.ui.xaml.uielement.measure) method on each of these elements. **Measure** has a parameter of type [**Size**](/uwp/api/Windows.Foundation.Size). What you're passing here is the size that your panel is committing to have available for that particular child element. So, before you can do the loop and start calling **Measure**, you need to know how much space each cell can devote. From the **MeasureOverride** method itself, you have the *availableSize* value. That is the size that the panel's parent used when it called **Measure**, which was the trigger for this **MeasureOverride** being called in the first place. So a typical logic is to devise a scheme whereby each child element divides the space of the panel's overall *availableSize*. You then pass each division of size to **Measure** of each child element. +The necessary pattern of a [**MeasureOverride**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.frameworkelement.measureoverride) implementation is the loop through each element in [**Panel.Children**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.panel.children). Always call the [**Measure**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.measure) method on each of these elements. **Measure** has a parameter of type [**Size**](/uwp/api/Windows.Foundation.Size). What you're passing here is the size that your panel is committing to have available for that particular child element. So, before you can do the loop and start calling **Measure**, you need to know how much space each cell can devote. From the **MeasureOverride** method itself, you have the *availableSize* value. That is the size that the panel's parent used when it called **Measure**, which was the trigger for this **MeasureOverride** being called in the first place. So a typical logic is to devise a scheme whereby each child element divides the space of the panel's overall *availableSize*. You then pass each division of size to **Measure** of each child element. How `BoxPanel` divides size is fairly simple: it divides its space into a number of boxes that's largely controlled by the number of items. Boxes are sized based on row and column count and the available size. Sometimes one row or column from a square isn't needed, so it's dropped and the panel becomes a rectangle rather than square in terms of its row : column ratio. For more info about how this logic was arrived at, skip ahead to ["The scenario for BoxPanel"](#the-scenario-for-boxpanel). -So what does the measure pass do? It sets a value for the read-only [**DesiredSize**](/uwp/api/windows.ui.xaml.uielement.desiredsize) property on each element where [**Measure**](/uwp/api/windows.ui.xaml.uielement.measure) was called. Having a **DesiredSize** value is possibly important once you get to the arrange pass, because the **DesiredSize** communicates what the size can or should be when arranging and in the final rendering. Even if you don't use **DesiredSize** in your own logic, the system still needs it. +So what does the measure pass do? It sets a value for the read-only [**DesiredSize**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.desiredsize) property on each element where [**Measure**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.measure) was called. Having a **DesiredSize** value is possibly important once you get to the arrange pass, because the **DesiredSize** communicates what the size can or should be when arranging and in the final rendering. Even if you don't use **DesiredSize** in your own logic, the system still needs it. -It's possible for this panel to be used when the height component of *availableSize* is unbounded. If that's true, the panel doesn't have a known height to divide. In this case, the logic for the measure pass informs each child that it doesn't have a bounded height, yet. It does so by passing a [**Size**](/uwp/api/Windows.Foundation.Size) to the [**Measure**](/uwp/api/windows.ui.xaml.uielement.measure) call for children where [**Size.Height**](/uwp/api/windows.foundation.size.height) is infinite. That's legal. When **Measure** is called, the logic is that the [**DesiredSize**](/uwp/api/windows.ui.xaml.uielement.desiredsize) is set as the minimum of these: what was passed to **Measure**, or that element's natural size from factors such as explicitly-set [**Height**](/uwp/api/Windows.UI.Xaml.FrameworkElement.Height) and [**Width**](/uwp/api/Windows.UI.Xaml.FrameworkElement.Width). +It's possible for this panel to be used when the height component of *availableSize* is unbounded. If that's true, the panel doesn't have a known height to divide. In this case, the logic for the measure pass informs each child that it doesn't have a bounded height, yet. It does so by passing a [**Size**](/uwp/api/Windows.Foundation.Size) to the [**Measure**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.measure) call for children where [**Size.Height**](/uwp/api/windows.foundation.size.height) is infinite. That's legal. When **Measure** is called, the logic is that the [**DesiredSize**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.desiredsize) is set as the minimum of these: what was passed to **Measure**, or that element's natural size from factors such as explicitly-set [**Height**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.FrameworkElement.Height) and [**Width**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.FrameworkElement.Width). > [!NOTE] -> The internal logic of [**StackPanel**](/uwp/api/Windows.UI.Xaml.Controls.StackPanel) also has this behavior: **StackPanel** passes an infinite dimension value to [**Measure**](/uwp/api/windows.ui.xaml.uielement.measure) on children, indicating that there is no constraint on children in the orientation dimension. **StackPanel** typically sizes itself dynamically, to accommodate all children in a stack that grows in that dimension. +> The internal logic of [**StackPanel**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.Controls.StackPanel) also has this behavior: **StackPanel** passes an infinite dimension value to [**Measure**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.measure) on children, indicating that there is no constraint on children in the orientation dimension. **StackPanel** typically sizes itself dynamically, to accommodate all children in a stack that grows in that dimension. -However, the panel itself can't return a [**Size**](/uwp/api/Windows.Foundation.Size) with an infinite value from [**MeasureOverride**](/uwp/api/windows.ui.xaml.frameworkelement.measureoverride); that throws an exception during layout. So, part of the logic is to find out the maximum height that any child requests, and use that height as the cell height in case that isn't coming from the panel's own size constraints already. Here's the helper function `LimitUnboundedSize` that was referenced in previous code, which then takes that maximum cell height and uses it to give the panel a finite height to return, as well as assuring that `cellheight` is a finite number before the arrange pass is initiated: +However, the panel itself can't return a [**Size**](/uwp/api/Windows.Foundation.Size) with an infinite value from [**MeasureOverride**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.frameworkelement.measureoverride); that throws an exception during layout. So, part of the logic is to find out the maximum height that any child requests, and use that height as the cell height in case that isn't coming from the panel's own size constraints already. Here's the helper function `LimitUnboundedSize` that was referenced in previous code, which then takes that maximum cell height and uses it to give the panel a finite height to return, as well as assuring that `cellheight` is a finite number before the arrange pass is initiated: ```CSharp // This method limits the panel height when no limit is imposed by the panel's parent. @@ -163,17 +163,17 @@ protected override Size ArrangeOverride(Size finalSize) } ``` -The necessary pattern of an [**ArrangeOverride**](/uwp/api/windows.ui.xaml.frameworkelement.arrangeoverride) implementation is the loop through each element in [**Panel.Children**](/uwp/api/windows.ui.xaml.controls.panel.children). Always call the [**Arrange**](/uwp/api/windows.ui.xaml.uielement.arrange) method on each of these elements. +The necessary pattern of an [**ArrangeOverride**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.frameworkelement.arrangeoverride) implementation is the loop through each element in [**Panel.Children**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.panel.children). Always call the [**Arrange**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.arrange) method on each of these elements. -Note how there aren't as many calculations as in [**MeasureOverride**](/uwp/api/windows.ui.xaml.frameworkelement.measureoverride); that's typical. The size of children is already known from the panel's own **MeasureOverride** logic, or from the [**DesiredSize**](/uwp/api/windows.ui.xaml.uielement.desiredsize) value of each child set during the measure pass. However, we still need to decide the location within the panel where each child will appear. In a typical panel, each child should render at a different position. A panel that creates overlapping elements isn't desirable for typical scenarios (although it's not out of the question to create panels that have purposeful overlaps, if that's really your intended scenario). +Note how there aren't as many calculations as in [**MeasureOverride**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.frameworkelement.measureoverride); that's typical. The size of children is already known from the panel's own **MeasureOverride** logic, or from the [**DesiredSize**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.desiredsize) value of each child set during the measure pass. However, we still need to decide the location within the panel where each child will appear. In a typical panel, each child should render at a different position. A panel that creates overlapping elements isn't desirable for typical scenarios (although it's not out of the question to create panels that have purposeful overlaps, if that's really your intended scenario). -This panel arranges by the concept of rows and columns. The number of rows and columns was already calculated (it was necessary for measurement). So now the shape of the rows and columns plus the known sizes of each cell contribute to the logic of defining a rendering position (the `anchorPoint`) for each element that this panel contains. That [**Point**](/uwp/api/Windows.Foundation.Point), along with the [**Size**](/uwp/api/Windows.Foundation.Size) already known from measure, are used as the two components that construct a [**Rect**](/uwp/api/Windows.Foundation.Rect). **Rect** is the input type for [**Arrange**](/uwp/api/windows.ui.xaml.uielement.arrange). +This panel arranges by the concept of rows and columns. The number of rows and columns was already calculated (it was necessary for measurement). So now the shape of the rows and columns plus the known sizes of each cell contribute to the logic of defining a rendering position (the `anchorPoint`) for each element that this panel contains. That [**Point**](/uwp/api/Windows.Foundation.Point), along with the [**Size**](/uwp/api/Windows.Foundation.Size) already known from measure, are used as the two components that construct a [**Rect**](/uwp/api/Windows.Foundation.Rect). **Rect** is the input type for [**Arrange**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.arrange). -Panels sometimes need to clip their content. If they do, the clipped size is the size that's present in [**DesiredSize**](/uwp/api/windows.ui.xaml.uielement.desiredsize), because the [**Measure**](/uwp/api/windows.ui.xaml.uielement.measure) logic sets it as the minimum of what was passed to **Measure**, or other natural size factors. So you don't typically need to specifically check for clipping during [**Arrange**](/uwp/api/windows.ui.xaml.uielement.arrange); the clipping just happens based on passing the **DesiredSize** through to each **Arrange** call. +Panels sometimes need to clip their content. If they do, the clipped size is the size that's present in [**DesiredSize**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.desiredsize), because the [**Measure**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.measure) logic sets it as the minimum of what was passed to **Measure**, or other natural size factors. So you don't typically need to specifically check for clipping during [**Arrange**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.arrange); the clipping just happens based on passing the **DesiredSize** through to each **Arrange** call. -You don't always need a count while going through the loop if all the info you need for defining the rendering position is known by other means. For example, in [**Canvas**](/uwp/api/Windows.UI.Xaml.Controls.Canvas) layout logic, the position in the [**Children**](/uwp/api/windows.ui.xaml.controls.panel.children) collection doesn't matter. All the info needed to position each element in a **Canvas** is known by reading [**Canvas.Left**](/dotnet/api/system.windows.controls.canvas.left) and [**Canvas.Top**](/dotnet/api/system.windows.controls.canvas.top) values of children as part of the arrange logic. The `BoxPanel` logic happens to need a count to compare to the *colcount* so it's known when to begin a new row and offset the *y* value. +You don't always need a count while going through the loop if all the info you need for defining the rendering position is known by other means. For example, in [**Canvas**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.Controls.Canvas) layout logic, the position in the [**Children**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.panel.children) collection doesn't matter. All the info needed to position each element in a **Canvas** is known by reading [**Canvas.Left**](/dotnet/api/system.windows.controls.canvas.left) and [**Canvas.Top**](/dotnet/api/system.windows.controls.canvas.top) values of children as part of the arrange logic. The `BoxPanel` logic happens to need a count to compare to the *colcount* so it's known when to begin a new row and offset the *y* value. -It's typical that the input *finalSize* and the [**Size**](/uwp/api/Windows.Foundation.Size) you return from a [**ArrangeOverride**](/uwp/api/windows.ui.xaml.frameworkelement.arrangeoverride) implementation are the same. For more info about why, see "**ArrangeOverride**" section of [XAML custom panels overview](custom-panels-overview.md). +It's typical that the input *finalSize* and the [**Size**](/uwp/api/Windows.Foundation.Size) you return from a [**ArrangeOverride**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.frameworkelement.arrangeoverride) implementation are the same. For more info about why, see "**ArrangeOverride**" section of [XAML custom panels overview](custom-panels-overview.md). ## A refinement: controlling the row vs. column count @@ -213,13 +213,13 @@ if (Orientation == Orientation.Vertical) { aspectratio = 1 / aspectratio; } ## The scenario for BoxPanel -The particular scenario for `BoxPanel` is that it's a panel where one of the main determinants of how to divide space is by knowing the number of child items, and dividing the known available space for the panel. Panels are innately rectangle shapes. Many panels operate by dividing that rectangle space into further rectangles; that's what [**Grid**](/uwp/api/Windows.UI.Xaml.Controls.Grid) does for its cells. In **Grid**'s case, the size of the cells is set by [**ColumnDefinition**](/uwp/api/Windows.UI.Xaml.Controls.ColumnDefinition) and [**RowDefinition**](/uwp/api/Windows.UI.Xaml.Controls.RowDefinition) values, and elements declare the exact cell they go into with [**Grid.Row**](/dotnet/api/system.windows.controls.grid.row) and [**Grid.Column**](/dotnet/api/system.windows.controls.grid.column) attached properties. Getting good layout from a **Grid** usually requires knowing the number of child elements beforehand, so that there are enough cells and each child element sets its attached properties to fit into its own cell. +The particular scenario for `BoxPanel` is that it's a panel where one of the main determinants of how to divide space is by knowing the number of child items, and dividing the known available space for the panel. Panels are innately rectangle shapes. Many panels operate by dividing that rectangle space into further rectangles; that's what [**Grid**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.Controls.Grid) does for its cells. In **Grid**'s case, the size of the cells is set by [**ColumnDefinition**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.Controls.ColumnDefinition) and [**RowDefinition**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.Controls.RowDefinition) values, and elements declare the exact cell they go into with [**Grid.Row**](/dotnet/api/system.windows.controls.grid.row) and [**Grid.Column**](/dotnet/api/system.windows.controls.grid.column) attached properties. Getting good layout from a **Grid** usually requires knowing the number of child elements beforehand, so that there are enough cells and each child element sets its attached properties to fit into its own cell. But what if the number of children is dynamic? That's certainly possible; your app code can add items to collections, in response to any dynamic run-time condition you consider to be important enough to be worth updating your UI. If you're using data binding to backing collections/business objects, getting such updates and updating the UI is handled automatically, so that's often the preferred technique (see [Data binding in depth](/windows/uwp/data-binding/data-binding-in-depth)). But not all app scenarios lend themselves to data binding. Sometimes, you need to create new UI elements at runtime and make them visible. `BoxPanel` is for this scenario. A changing number of child items is no problem for `BoxPanel` because it's using the child count in calculations, and adjusts both the existing and new child elements into a new layout so they all fit. -An advanced scenario for extending `BoxPanel` further (not shown here) could both accommodate dynamic children and use a child's [**DesiredSize**](/uwp/api/windows.ui.xaml.uielement.desiredsize) as a stronger factor for the sizing of individual cells. This scenario might use varying row or column sizes or non-grid shapes so that there's less "wasted" space. This requires a strategy for how multiple rectangles of various sizes and aspect ratios can all fit into a containing rectangle both for aesthetics and smallest size. `BoxPanel` doesn't do that; it's using a simpler technique for dividing space. `BoxPanel`'s technique is to determine the least square number that's greater than the child count. For example, 9 items would fit in a 3x3 square. 10 items require a 4x4 square. However, you can often fit items while still removing one row or column of the starting square, to save space. In the count=10 example, that fits in a 4x3 or 3x4 rectangle. +An advanced scenario for extending `BoxPanel` further (not shown here) could both accommodate dynamic children and use a child's [**DesiredSize**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.desiredsize) as a stronger factor for the sizing of individual cells. This scenario might use varying row or column sizes or non-grid shapes so that there's less "wasted" space. This requires a strategy for how multiple rectangles of various sizes and aspect ratios can all fit into a containing rectangle both for aesthetics and smallest size. `BoxPanel` doesn't do that; it's using a simpler technique for dividing space. `BoxPanel`'s technique is to determine the least square number that's greater than the child count. For example, 9 items would fit in a 3x3 square. 10 items require a 4x4 square. However, you can often fit items while still removing one row or column of the starting square, to save space. In the count=10 example, that fits in a 4x3 or 3x4 rectangle. You might wonder why the panel wouldn't instead choose 5x2 for 10 items, because that fits the item number neatly. However, in practice, panels are sized as rectangles that seldom have a strongly oriented aspect ratio. The least-squares technique is a way to bias the sizing logic to work well with typical layout shapes and not encourage sizing where the cell shapes get odd aspect ratios. @@ -227,9 +227,9 @@ You might wonder why the panel wouldn't instead choose 5x2 for 10 items, because **Reference** -* [**FrameworkElement.ArrangeOverride**](/uwp/api/windows.ui.xaml.frameworkelement.arrangeoverride) -* [**FrameworkElement.MeasureOverride**](/uwp/api/windows.ui.xaml.frameworkelement.measureoverride) -* [**Panel**](/uwp/api/Windows.UI.Xaml.Controls.Panel) +* [**FrameworkElement.ArrangeOverride**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.frameworkelement.arrangeoverride) +* [**FrameworkElement.MeasureOverride**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.frameworkelement.measureoverride) +* [**Panel**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.Controls.Panel) **Concepts** diff --git a/hub/apps/develop/camera/basic-photo-capture.md b/hub/apps/develop/camera/basic-photo-capture.md index 72abb52745..5c2e648f33 100644 --- a/hub/apps/develop/camera/basic-photo-capture.md +++ b/hub/apps/develop/camera/basic-photo-capture.md @@ -81,7 +81,7 @@ You can also get a result frame when you stop the video by calling [**StopWithRe ### Play and edit captured video files -Once you have captured a video to a file, you may want to load the file and play it back within your app's UI. You can do this using the **[MediaPlayerElement](/uwp/api/Windows.UI.Xaml.Controls.MediaPlayerElement)** XAML control and an associated **[MediaPlayer](/uwp/api/windows.media.playback.mediaplayer)**. For information on playing media in a XAML page, see [Play audio and video with MediaPlayer](/windows/uwp/audio-video-camera/play-audio-and-video-with-mediaplayer). +Once you have captured a video to a file, you may want to load the file and play it back within your app's UI. You can do this using the **[MediaPlayerElement](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.Controls.MediaPlayerElement)** XAML control and an associated **[MediaPlayer](/uwp/api/windows.media.playback.mediaplayer)**. For information on playing media in a XAML page, see [Play audio and video with MediaPlayer](/windows/uwp/audio-video-camera/play-audio-and-video-with-mediaplayer). You can also create a **[MediaClip](/uwp/api/windows.media.editing.mediaclip)** object from a video file by calling **[CreateFromFileAsync](/uwp/api/windows.media.editing.mediaclip.createfromfileasync)**. A **[MediaComposition](/uwp/api/windows.media.editing.mediacomposition)** provides basic video editing functionality like arranging the sequence of **MediaClip** objects, trimming video length, creating layers, adding background music, and applying video effects. For more information on working with media compositions, see [Media compositions and editing](/windows/uwp/audio-video-camera/media-compositions-and-editing). diff --git a/hub/apps/develop/input/handle-pointer-input.md b/hub/apps/develop/input/handle-pointer-input.md index 2c4939b692..2007a509cb 100644 --- a/hub/apps/develop/input/handle-pointer-input.md +++ b/hub/apps/develop/input/handle-pointer-input.md @@ -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 += @@ -205,7 +205,7 @@ 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); @@ -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. @@ -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,7 +376,7 @@ void Target_PointerReleased(object sender, PointerRoutedEventArgs e) } else { - Target.Fill = new SolidColorBrush(Windows.UI.Colors.Blue); + Target.Fill = new SolidColorBrush(Microsoft.UI.Colors.Blue); } } ``` @@ -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. @@ -448,7 +448,7 @@ 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); @@ -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. @@ -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(); @@ -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()) @@ -702,9 +702,9 @@ We define a **[UserControl](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml 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 diff --git a/hub/apps/develop/input/keyboard-accelerators.md b/hub/apps/develop/input/keyboard-accelerators.md index ca8595bf21..42861a7fc2 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.appbarbutton) 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