mirror of https://github.com/microsoft/PowerToys.git synced 2026-09-01 19:51:34 +02:00

Files

Noraa Junker 6c9fb8ce52 [Shortcut Guide] Add Windows key hold activation options (#49661 )

## Summary of the Pull Request

Adds configurable Windows-key hold activation to Shortcut Guide while
keeping the regular activation shortcut independent.

Users can choose to disable Windows-key activation, show taskbar
indicators, or open the full Shortcut Guide. Full-guide mode also
supports a configurable hold duration and optional close-on-release
behavior.

## PR Checklist

- [ ] Closes: N/A
- [x] **Communication:** The UX and behavior were discussed before
implementation
- [x] **Tests:** Added/updated and all pass
- [x] **Localization:** All end-user-facing strings can be localized
- [x] **Dev docs:** Added/updated
- [ ] **New binaries:** Not applicable
- [ ] **Documentation updated:** Not applicable

## Detailed Description of the Pull Request / Additional comments

- Adds Off, taskbar-indicator, and full-guide Windows-key actions to
Settings.
- Adds a 100–5,000 ms hold-duration setting and a full-guide
close-on-release option.
- Handles left and right Windows keys and suppresses Start after an
activated hold.
- Routes Windows-key holds through a dedicated event so custom
activation shortcuts remain independent.
- Clears previous pressed-key registrations before refreshing them to
prevent duplicate long-press callbacks.
- Preserves compatibility with the existing `press_time` setting and
documents the new options.

## Validation Steps Performed

- Built the affected ARM64 Debug Settings, Runner, Shortcut Guide
module-interface, and Shortcut Guide UI projects.
- `ShortcutGuide.UnitTests`: 7/7 passed.
- Targeted Settings tests: 12/12 passed.
- Manually verified Off, taskbar-indicator, full-guide close-on-release,
and full-guide persistent modes.
- Verified configured hold thresholds, both Windows keys, Start
suppression, and regular-shortcut independence.
- Validated the final Settings XAML layout in the running Settings app.

---------

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Muyuan Li (from Dev Box) <muyuanli@microsoft.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 2b3acca3-e49b-4936-8fb9-6f669bd449db

2026-08-13 22:27:39 +02:00

5.9 KiB

Raw Blame History

Shortcut Guide

Public overview - Microsoft Learn

Quick Links

All Issues
Bugs
Pull Requests

Overview

Shortcut Guide is a PowerToy that displays an overlay of available keyboard shortcuts when a user-set keyboard shortcut is pressed. It helps users discover and remember keyboard shortcuts for Windows and apps.

Note

The spec for the manifest files is in development and will be linked here once available.

Usage

Press the user-defined hotkey to display the full overlay.
Optionally, hold either Windows key to show taskbar indicators or the full overlay after a configurable delay.
Press the hotkey again or press ESC to dismiss the overlay. A full overlay opened by holding the Windows key can either close on key release or remain open, depending on the setting.

The Hold Windows key setting is independent of the activation shortcut:

Off leaves the Windows key behavior unchanged.
Show taskbar indicators is the default and always hides the indicators when the Windows key is released.
Open Shortcut Guide can close on Windows-key release or remain open.

The hold duration accepts values from 100 through 5,000 milliseconds and defaults to 900 milliseconds.

Build and Debug Instructions

Build

Open PowerToys.slnx in Visual Studio
Select Release or Debug in the Solutions Configuration drop-down menu
From the Build menu, choose Build Solution
The executable is named PowerToys.ShortcutGuide.exe

Debug

Right-click the ShortcutGuide.Ui project and select 'Set as Startup Project'
Right-click the project again and select 'Debug'

Note

When run in debug mode, the window behaves differently than in release mode. It will not automatically close when loosing focus, it will be displayed on top of all other windows, and it is not hidden from the taskbar.

Project Structure

The Shortcut Guide module consists of the following 4 projects:

`ShortcutGuide.Ui`

This is the main UI project for the Shortcut Guide module. Upon startup it does the following tasks:

Copies the built-in manifest files to the users manifest directory (overwriting existing files).
Generate the index.yml manifest file.
Populate the PowerToys shortcut manifest with the user-defined shortcuts.
Starts the UI.

`excluded_app.cpp`

This file contains one function with the following signature:

__declspec(dllexport) bool IsCurrentWindowExcludedFromShortcutGuide()

This function checks if the current window is excluded from the Shortcut Guide overlay. It returns true if the current window is excluded otherwise it returns false.

`tasklist_positions.cpp`

This file contains helper functions to retrieve the positions of the taskbar buttons. It exports the following function:

__declspec(dllexport) TasklistButton* get_buttons(HMONITOR monitor, int* size)

This function retrieves the positions of the taskbar buttons for a given monitor. It returns an array of TasklistButton structures (max 10), which contain the position and size of each button.

monitor must be the monitor handle of the monitor containing the taskbar instance of which the buttons should be retrieved.

size will contain the resulting array size.

It determines the positions through Windows FindWindowEx function. For the primary taskbar it searches for:

A window called "Shell_TrayWnd"
that contains a window called "ReBarWindow32"
that contains a window called "MSTaskSwWClass"
that contains a window called "MSTaskListWClass"

For any secondary taskbar it searches for:

A window called "Shell_SecondaryTrayWnd"
that contains a window called "WorkerW"
that contains a window called "MSTaskListWClass"

It then enumerates all the button elements inside "MSTaskListWClass" while skipping such with a same name (which implies the user does not use combining taskbar buttons)

If this method fails, which it will for newer versions of Windows, it falls back to searching for:

A window called "Shell_TrayWnd" or "Shell_SecondaryTrayWnd"
that contains a window called "Windows.UI.Composition.DesktopWindowContentBridge"
that contains a window called "Windows.UI.Input.InputSite.WindowClass"
the first child element

It then enumerates all the button elements inside the selected while skipping such with a same name (which implies the user does not use combining taskbar buttons) and such that do not start with "Appid:" (which are not actual taskbar buttons related to apps, but others like the widgets or the search button).

`ShortcutGuide.IndexYmlGenerator`

This application generates the index.yml manifest file.

It is a separate project so that its code can be easier ported to WinGet in the future.

`ShortcutGuideModuleInterface`

The module interface that handles opening and closing the user interface.

Features and Limitations

Currently the displayed shortcuts (Except the ones from PowerToys) are not localized.
It's currently rated as a P3 (lower priority) module

Future Development

Implementing with WinGet to get new shortcut manifest files
Adding localization support for the built-in manifest files

5.9 KiB Raw Blame History