CmdPal: Add local keyboard listener and use it to handle GoBack key (#41122)

## Summary of the Pull Request

Listener registers a hook on WH_KEYBOARD and raises an event when a key
is pressed down. Main window then uses it to handle the GoBack key that
we can't reach any other way.


<!-- Please review the items on the PR checklist before submitting-->
## PR Checklist

- [x] Related to: #41011
- [ ] **Communication:** I've discussed this with core contributors
already. If the work hasn't been agreed, this work might be rejected
- [ ] **Tests:** Added/updated and all pass
- [ ] **Localization:** All end-user-facing strings can be localized
- [ ] **Dev docs:** Added/updated
- [ ] **New binaries:** Added on the required places
- [ ] [JSON for
signing](https://github.com/microsoft/PowerToys/blob/main/.pipelines/ESRPSigning_core.json)
for new binaries
- [ ] [WXS for
installer](https://github.com/microsoft/PowerToys/blob/main/installer/PowerToysSetup/Product.wxs)
for new binaries and localization folder
- [ ] [YML for CI
pipeline](https://github.com/microsoft/PowerToys/blob/main/.pipelines/ci/templates/build-powertoys-steps.yml)
for new test projects
- [ ] [YML for signed
pipeline](https://github.com/microsoft/PowerToys/blob/main/.pipelines/release.yml)
- [ ] **Documentation updated:** If checked, please file a pull request
on [our docs
repo](https://github.com/MicrosoftDocs/windows-uwp/tree/docs/hub/powertoys)
and link it here: #xxx

<!-- Provide a more detailed description of the PR, other things fixed,
or any additional comments/features here -->
## Detailed Description of the Pull Request / Additional comments

<!-- Describe how you validated the behavior. Add automated tests
wherever possible, but list manual validation steps taken as well -->
## Validation Steps Performed

.github/actions/spell-check/expect.txt

@@ -637,6 +637,7 @@ hmodule
 hmonitor
 homies
 homljgmgpmcbpjbnjpfijnhipfkiclkd
+HOOKPROC
 HORZRES
 HORZSIZE
 Hostbackdropbrush

src/modules/cmdpal/Microsoft.CmdPal.UI/Helpers/LocalKeyboardListener.cs

@@ -0,0 +1,157 @@
+// Copyright (c) Microsoft Corporation
+// The Microsoft Corporation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using ManagedCommon;
+
+using Windows.System;
+using Windows.Win32;
+using Windows.Win32.Foundation;
+using Windows.Win32.UI.WindowsAndMessaging;
+
+namespace Microsoft.CmdPal.UI.Helpers;
+
+/// <summary>
+/// A class that listens for local keyboard events using a Windows hook.
+/// </summary>
+internal sealed class LocalKeyboardListener : IDisposable
+{
+    /// <summary>
+    /// Event that is raised when a key is pressed down.
+    /// </summary>
+    public event EventHandler<LocalKeyboardListenerKeyPressedEventArgs>? KeyPressed;
+
+    private bool _disposed;
+    private UnhookWindowsHookExSafeHandle? _handle;
+    private HOOKPROC? _hookProc; // Keep reference to prevent GC collection
+
+    /// <summary>
+    /// Registers a global keyboard hook to listen for key down events.
+    /// </summary>
+    /// <exception cref="InvalidOperationException">
+    /// Throws if the hook could not be registered, which may happen if the system is unable to set the hook.
+    /// </exception>
+    public void RegisterKeyboardHook()
+    {
+        ObjectDisposedException.ThrowIf(_disposed, this);
+
+        if (_handle is not null && !_handle.IsInvalid)
+        {
+            // Hook is already set
+            return;
+        }
+
+        _hookProc = KeyEventHook;
+        if (!SetWindowKeyHook(_hookProc))
+        {
+            throw new InvalidOperationException("Failed to register keyboard hook.");
+        }
+    }
+
+    /// <summary>
+    /// Attempts to register a global keyboard hook to listen for key down events.
+    /// </summary>
+    /// <returns>
+    /// <see langword="true"/> if the keyboard hook was successfully registered; otherwise, <see langword="false"/>.
+    /// </returns>
+    public bool Start()
+    {
+        if (_disposed)
+        {
+            return false;
+        }
+
+        try
+        {
+            RegisterKeyboardHook();
+            return true;
+        }
+        catch (Exception ex)
+        {
+            Logger.LogError("Failed to register hook", ex);
+            return false;
+        }
+    }
+
+    private void UnregisterKeyboardHook()
+    {
+        if (_handle is not null && !_handle.IsInvalid)
+        {
+            // The SafeHandle should automatically call UnhookWindowsHookEx when disposed
+            _handle.Dispose();
+            _handle = null;
+        }
+
+        _hookProc = null;
+    }
+
+    private bool SetWindowKeyHook(HOOKPROC hookProc)
+    {
+        if (_handle is not null && !_handle.IsInvalid)
+        {
+            // Hook is already set
+            return false;
+        }
+
+        _handle = PInvoke.SetWindowsHookEx(
+            WINDOWS_HOOK_ID.WH_KEYBOARD,
+            hookProc,
+            PInvoke.GetModuleHandle(null),
+            PInvoke.GetCurrentThreadId());
+
+        // Check if the hook was successfully set
+        return _handle is not null && !_handle.IsInvalid;
+    }
+
+    private static bool IsKeyDownHook(LPARAM lParam)
+    {
+        // The 30th bit tells what the previous key state is with 0 being the "UP" state
+        // For more info see https://learn.microsoft.com/windows/win32/winmsg/keyboardproc#lparam-in
+        return ((lParam.Value >> 30) & 1) == 0;
+    }
+
+    private LRESULT KeyEventHook(int nCode, WPARAM wParam, LPARAM lParam)
+    {
+        try
+        {
+            if (nCode >= 0 && IsKeyDownHook(lParam))
+            {
+                InvokeKeyDown((VirtualKey)wParam.Value);
+            }
+        }
+        catch (Exception ex)
+        {
+            Logger.LogError("Failed when invoking key down keyboard hook event", ex);
+        }
+
+        // Call next hook in chain - pass null as first parameter for current hook
+        return PInvoke.CallNextHookEx(null, nCode, wParam, lParam);
+    }
+
+    private void InvokeKeyDown(VirtualKey virtualKey)
+    {
+        if (!_disposed)
+        {
+            KeyPressed?.Invoke(this, new LocalKeyboardListenerKeyPressedEventArgs(virtualKey));
+        }
+    }
+
+    public void Dispose()
+    {
+        Dispose(true);
+        GC.SuppressFinalize(this);
+    }
+
+    private void Dispose(bool disposing)
+    {
+        if (!_disposed)
+        {
+            if (disposing)
+            {
+                UnregisterKeyboardHook();
+            }
+
+            _disposed = true;
+        }
+    }
+}

src/modules/cmdpal/Microsoft.CmdPal.UI/Helpers/LocalKeyboardListenerKeyPressedEventArgs.cs

@@ -0,0 +1,12 @@
+// Copyright (c) Microsoft Corporation
+// The Microsoft Corporation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using Windows.System;
+
+namespace Microsoft.CmdPal.UI.Helpers;
+
+public class LocalKeyboardListenerKeyPressedEventArgs(VirtualKey key) : EventArgs
+{
+    public VirtualKey Key { get; } = key;
+}

src/modules/cmdpal/Microsoft.CmdPal.UI/MainWindow.xaml.cs

@@ -27,6 +27,7 @@ using Microsoft.Windows.AppLifecycle;
 using Windows.ApplicationModel.Activation;
 using Windows.Foundation;
 using Windows.Graphics;
+using Windows.System;
 using Windows.UI;
 using Windows.UI.WindowManagement;
 using Windows.Win32;
@@ -44,7 +45,8 @@ public sealed partial class MainWindow : WindowEx,
     IRecipient<DismissMessage>,
     IRecipient<ShowWindowMessage>,
     IRecipient<HideWindowMessage>,
-    IRecipient<QuitMessage>
+    IRecipient<QuitMessage>,
+    IDisposable
 {
     [System.Diagnostics.CodeAnalysis.SuppressMessage("StyleCop.CSharp.NamingRules", "SA1310:Field names should not contain underscore", Justification = "Stylistically, window messages are WM_")]
     [System.Diagnostics.CodeAnalysis.SuppressMessage("StyleCop.CSharp.NamingRules", "SA1306:Field names should begin with lower-case letter", Justification = "Stylistically, window messages are WM_")]
@@ -54,6 +56,7 @@ public sealed partial class MainWindow : WindowEx,
     private readonly WNDPROC? _originalWndProc;
     private readonly List<TopLevelHotkey> _hotkeys = [];
     private readonly KeyboardListener _keyboardListener;
+    private readonly LocalKeyboardListener _localKeyboardListener;
     private bool _ignoreHotKeyWhenFullScreen = true;
 
     private DesktopAcrylicController? _acrylicController;
@@ -116,6 +119,18 @@ public sealed partial class MainWindow : WindowEx,
         {
             Summon(string.Empty);
         });
+
+        _localKeyboardListener = new LocalKeyboardListener();
+        _localKeyboardListener.KeyPressed += LocalKeyboardListener_OnKeyPressed;
+        _localKeyboardListener.Start();
+    }
+
+    private static void LocalKeyboardListener_OnKeyPressed(object? sender, LocalKeyboardListenerKeyPressedEventArgs e)
+    {
+        if (e.Key == VirtualKey.GoBack)
+        {
+            WeakReferenceMessenger.Default.Send(new GoBackMessage());
+        }
     }
 
     private void SettingsChangedHandler(SettingsModel sender, object? args) => HotReloadSettings();
@@ -376,6 +391,7 @@ public sealed partial class MainWindow : WindowEx,
         // WinUI bug is causing a crash on shutdown when FailFastOnErrors is set to true (#51773592).
         // Workaround by turning it off before shutdown.
         App.Current.DebugSettings.FailFastOnErrors = false;
+        _localKeyboardListener.Dispose();
         DisposeAcrylic();
 
         _keyboardListener.Stop();
@@ -682,4 +698,10 @@ public sealed partial class MainWindow : WindowEx,
 
         return PInvoke.CallWindowProc(_originalWndProc, hwnd, uMsg, wParam, lParam);
     }
+
+    public void Dispose()
+    {
+        _localKeyboardListener.Dispose();
+        DisposeAcrylic();
+    }
 }

src/modules/cmdpal/Microsoft.CmdPal.UI/NativeMethods.txt

@@ -48,3 +48,9 @@ DWM_CLOAKED_APP
 CoWaitForMultipleObjects
 INFINITE
 CWMO_FLAGS
+
+GetCurrentThreadId
+SetWindowsHookEx
+UnhookWindowsHookEx
+CallNextHookEx
+GetModuleHandle