Skip to content

Commit cb8a356

Browse files
stevewhimsstevewhims
authored
Updating based on latest doc (#4818)
1 parent 4709b69 commit cb8a356

File tree

2 files changed

+120
-12
lines changed

2 files changed

+120
-12
lines changed

‎hub/apps/toc.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -998,7 +998,7 @@ items:
998998
href: windows-app-sdk/migrate-to-windows-app-sdk/guides/feature-area-guides-ovw.md
999999
- name: User interface migration (including WinUI 3)
10001000
href: windows-app-sdk/migrate-to-windows-app-sdk/guides/winui3.md
1001-
- name: Keyboard API and events parity between UWP and Windows App SDK
1001+
- name: Keyboard API and events parity between UWP and WinUI 3
10021002
href: windows-app-sdk/migrate-to-windows-app-sdk/guides/keyboard-events.md
10031003
- name: Windowing functionality migration
10041004
href: windows-app-sdk/migrate-to-windows-app-sdk/guides/windowing.md

‎hub/apps/windows-app-sdk/migrate-to-windows-app-sdk/guides/keyboard-events.md

Lines changed: 119 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,19 @@
11
---
2-
title: Keyboard API and events parity between UWP and Windows App SDK
2+
title: Keyboard API and events parity between UWP and WinUI 3
33
description: The migration of apps from UWP to the WinUI 3 might require a few changes in the way input keyboard events are handled.
44
ms.topic: article
55
ms.date: 09/16/2024
66
keywords: Windows, App, SDK, migrate, migrating, migration, port, porting, input, keyboard, events
77
ms.localizationpriority: medium
88
---
99

10-
# Keyboard API and events parity between UWP and Windows App SDK
10+
# Keyboard API and events parity between UWP and WinUI 3
1111

1212
The migration of apps from the Universal Windows Platform (UWP) to the Windows App SDK (specifically, WinUI 3) might require a few changes in the way input keyboard events are handled, primarily due to the app model differences. This topic describes commonly identified differences.
1313

1414
By using **UIElement**-specific WinUI 3 event handlers, and developing custom solutions for event routing, you can easily transition your apps to modern Windows applications.
1515

16-
## Mapping to Windows App SDK APIs for UWP APIs
16+
## Mapping to WinUI 3 APIs from UWP APIs
1717

1818
### UWP APIs
1919

@@ -24,17 +24,125 @@ In UWP, **CoreWindow** serves as the fundamental component attached directly to
2424
* **CharacterReceived**. Event raised when a new character is received by the input queue.
2525
* **CoreDispatcher.AcceleratorKeyActivated**. Event raised when an accelerator key is activated (either pressed or held down).
2626

27-
### Windows App SDK APIs (WinUI 3)
28-
29-
The Windows App SDK (WinUI 3) has a different concept from **CoreWindow**. Instead, WinUI 3 provides an input event handling mechanism using **Microsoft.Ui.Xaml.UIElement** (UIElement). Each class that inherits from **UIElement** can implement various keyboard or pointer events (which are also present in UWP's **CoreWindow**) such as **KeyUp**, **KeyDown**, **CharacterReceived**, and others. This approach allows event handling at the level of a specific UI control.
30-
31-
## UWP sample apps for keyboard events and KeyboardAccelerator
27+
```csharp
28+
public sealed partial class MainPage : Page
29+
{
30+
public MainPage()
31+
{
32+
this.InitializeComponent();
33+
var coreWindow = CoreWindow.GetForCurrentThread();
34+
coreWindow.KeyDown += CoreWindow_KeyDown;
35+
coreWindow.KeyUp += CoreWindow_KeyUp;
36+
coreWindow.CharacterReceived += CoreWindow_CharacterReceived;
37+
coreWindow.Dispatcher.AcceleratorKeyActivated += Dispatcher_AcceleratorKeyActivated;
38+
}
39+
40+
private void CoreWindow_KeyDown(CoreWindow sender, KeyEventArgs args)
41+
{
42+
System.Diagnostics.Debug.WriteLine($"KeyDown: {args.VirtualKey}");
43+
}
44+
private void CoreWindow_KeyUp(CoreWindow sender, KeyEventArgs args)
45+
{
46+
System.Diagnostics.Debug.WriteLine($"KeyUp: {args.VirtualKey}");
47+
}
48+
49+
private void CoreWindow_CharacterReceived(CoreWindow sender, CharacterReceivedEventArgs args)
50+
{
51+
System.Diagnostics.Debug.WriteLine($"CharacterReceived: {(char)args.KeyCode}");
52+
}
53+
54+
private void Dispatcher_AcceleratorKeyActivated(CoreDispatcher sender, AcceleratorKeyEventArgs args)
55+
{
56+
if (args.EventType == CoreAcceleratorKeyEventType.KeyDown)
57+
{
58+
bool isCtrlPressed = (Window.Current.CoreWindow.GetKeyState(VirtualKey.Control) & CoreVirtualKeyStates.Down) ==
59+
CoreVirtualKeyStates.Down;
60+
if (isCtrlPressed && args.VirtualKey == VirtualKey.C)
61+
{
62+
System.Diagnostics.Debug.WriteLine("Ctrl+C Pressed");
63+
}
64+
else if (args.VirtualKey == VirtualKey.F1)
65+
{
66+
System.Diagnostics.Debug.WriteLine("F1 Key Pressed");
67+
}
68+
}
69+
}
70+
}
71+
```
72+
73+
### WinUI 3 APIs (Windows App SDK)
74+
75+
WinUI 3 (Windows App SDK) has a different concept from **CoreWindow**. Instead, WinUI 3 provides an input event handling mechanism using **Microsoft.Ui.Xaml.UIElement** (UIElement). Each class that inherits from **UIElement** can implement various keyboard or pointer events (which are also present in UWP's **CoreWindow**) such as **KeyUp**, **KeyDown**, **CharacterReceived**, and others. This approach allows event handling at the level of a specific UI control.
76+
77+
For detailed info about event handling, see [Keyboard events](/windows/apps/design/input/keyboard-events). You can associate keyboard events either XAML or in imperative source code. These examples demonstrate key event handling through code and accelerator key events in XAML.
78+
79+
```xaml
80+
<Window
81+
x:Class="SampleApp.MainWindow"
82+
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
83+
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
84+
xmlns:local="using:SampleApp"
85+
xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
86+
xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
87+
mc:Ignorable="d">
88+
89+
<StackPanel Orientation="Horizontal" x:Name="stackPanelControl" HorizontalAlignment="Center" VerticalAlignment="Center">
90+
<Button x:Name="myButton" Click="myButton_Click">Click Me</Button>
91+
<StackPanel.KeyboardAccelerators>
92+
<KeyboardAccelerator Key="C" Modifiers="Control" Invoked="OnCtrlCInvoked"/>
93+
</StackPanel.KeyboardAccelerators>
94+
</StackPanel>
95+
</Window>
96+
```
97+
98+
```csharp
99+
public sealed partial class MainWindow : Window
100+
{
101+
public MainWindow()
102+
{
103+
this.InitializeComponent();
104+
stackPanelControl.KeyDown += OnKeyDownHandler;
105+
stackPanelControl.KeyUp += OnKeyUpHandler;
106+
stackPanelControl.CharacterReceived += OnCharacterReceivedHandler;
107+
}
108+
109+
private void myButton_Click(object sender, RoutedEventArgs e)
110+
{
111+
myButton.Content = "Clicked";
112+
}
113+
114+
private void OnKeyDownHandler(object sender, KeyRoutedEventArgs e)
115+
{
116+
System.Diagnostics.Debug.WriteLine($"KeyDown: {e.Key}");
117+
}
118+
119+
private void OnKeyUpHandler(object sender, KeyRoutedEventArgs e)
120+
{
121+
System.Diagnostics.Debug.WriteLine($"KeyUp: {e.Key}");
122+
}
123+
124+
private void OnCharacterReceivedHandler(UIElement sender, CharacterReceivedRoutedEventArgs args)
125+
{
126+
System.Diagnostics.Debug.WriteLine($"CharacterReceived: {(char)args.Character}");
127+
}
128+
129+
private void OnCtrlCInvoked(KeyboardAccelerator sender, KeyboardAcceleratorInvokedEventArgs args)
130+
{
131+
if (args.KeyboardAccelerator.Key == VirtualKey.C && args.KeyboardAccelerator.Modifiers == VirtualKeyModifiers.Control)
132+
{
133+
System.Diagnostics.Debug.WriteLine("Ctrl+C Pressed");
134+
args.Handled = true;
135+
}
136+
}
137+
}
138+
```
139+
140+
## UWP sample apps for keyboard events
32141

33142
* [UWP custom edit control sample app](https://github.com/microsoft/Windows-universal-samples/blob/0db108e9d0af7386767194b3293c4082c1c8daa7/Samples/CustomEditControl/cs/CustomEditControl.xaml.cs#L55).
34143
* [UWP basic suspension sample app](https://github.com/microsoft/Windows-universal-samples/blob/0db108e9d0af7386767194b3293c4082c1c8daa7/Samples/BasicSuspension/cs/Common/NavigationHelper.cs#L194).
35-
* [UWP sample apps containing 'AcceleratorKeyEventArgs'](https://github.com/search?q=repo%3Amicrosoft%2FWindows-universal-samples+AcceleratorKeyEventArgs+&type=code).
36144

37-
## Windows App SDK sample apps for keyboard events and KeyboardAccelerator
145+
## WinUI 3 sample apps for keyboard events and KeyboardAccelerator
38146

39147
* [Input sample apps: KeyboardShortcutManager.xaml](https://github.com/microsoft/WindowsAppSDK-Samples/blob/main/Samples/Input/cs-winui/KeyboardShortcutManager.xaml)
40148
* [Input sample apps: KeyboardShortcutManager.xaml.cs](https://github.com/microsoft/WindowsAppSDK-Samples/blob/main/Samples/Input/cs-winui/KeyboardShortcutManager.xaml.cs)
@@ -49,7 +157,7 @@ The Windows App SDK (WinUI 3) has a different concept from **CoreWindow**. Inste
49157
* [UIElement.KeyDown event (Windows.UI.Xaml)](/uwp/api/windows.ui.xaml.uielement.keydown)
50158
* [UIElement.KeyUp event (Windows.UI.Xaml)](/uwp/api/windows.ui.xaml.uielement.keyup)
51159

52-
### Windows App SDK APIs (WinUI 3)
160+
### WinUI 3 APIs (Windows App SDK)
53161

54162
* [KeyboardAccelerator class (Microsoft.UI.Xaml.Input)](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.keyboardaccelerator)
55163
* [UIElement.CharacterReceived event (Microsoft.UI.Xaml)](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.characterreceived)

0 commit comments

Comments
 (0)