mirror of
https://github.com/microsoft/PowerToys.git
synced 2026-09-01 19:51:34 +02:00
446bb9f241
## Summary of the Pull Request Adds an accessible search box to the Shortcut Guide title bar that filters shortcuts on the currently selected application page. The query matches shortcut names, descriptions, modifier names, and displayed key labels while preserving the existing pinned, recommended, category, and taskbar grouping. ## PR Checklist - [x] Closes: #48791 - [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 a localized title-bar `AutoSuggestBox` with a find icon and UI Automation identity. - Filters only the selected app page using case-insensitive matching across names, descriptions, modifiers, virtual-key display names, and rendered special-key aliases. - Keeps only sections containing matches and shows a polite live-region no-results state with correct pane spacing. - Preserves the query when switching app pages, but clears it when Shortcut Guide closes. - Adds `Ctrl+F` to focus search; the first `Escape` clears a query and the next closes the overlay. - Keeps query text local to the UI with no logging or telemetry. Related issues: #48860 requests several broader navigation/readability changes; #49459 requests direct physical-key interception rather than text search. ## Screenshots ### Filter Windows shortcuts by displayed key label <img src="https://raw.githubusercontent.com/niels9001/PowerToys/pr-assets-shortcut-guide-search/.github/pr-assets/shortcut-guide-search/windows-alt-filter.png" width="667" alt="Shortcut Guide Windows page filtered by Alt" /> ### Keep the query while switching to the PowerToys page <img src="https://raw.githubusercontent.com/niels9001/PowerToys/pr-assets-shortcut-guide-search/.github/pr-assets/shortcut-guide-search/powertoys-opa-filter.png" width="660" alt="Shortcut Guide PowerToys page filtered by opa" /> ## Validation Steps Performed - Built `ShortcutGuide.Ui` for ARM64 Debug with the repository build scripts. - Built `ShortcutGuide.UnitTests` for ARM64 Debug and passed all 23 tests (16 search cases plus 7 existing tests) with `vstest.console.exe`. - Verified via UIA and guarded keyboard input that name/key-label filtering updates immediately, empty sections disappear, and no matches show the localized live-region state. - Verified the query persists when switching Windows to PowerToys, `Ctrl+F` focuses search, first `Escape` clears, second `Escape` closes, and reopening starts with an empty query. - Rebuilt after the final no-results accessibility and 16px top-margin adjustment. --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: b8ffa76b-3cf0-4a67-9adb-a13c5dd9f125 Copilot-Session: 4a96c2c2-6954-4784-8257-e0de0fac15a7 Copilot-Session: 1f00def4-e790-4071-96c6-a81c9c2adba5 Copilot-Session: 76e284a6-9a03-4105-bae6-4ed7fc92042d
127 lines
6.0 KiB
Markdown
127 lines
6.0 KiB
Markdown
# Shortcut Guide
|
|
|
|
[Public overview - Microsoft Learn](https://learn.microsoft.com/en-us/windows/powertoys/shortcut-guide)
|
|
|
|
## Quick Links
|
|
|
|
[All Issues](https://github.com/microsoft/PowerToys/issues?q=is%3Aopen%20label%3A%22Product-Shortcut%20Guide%22)<br>
|
|
[Bugs](https://github.com/microsoft/PowerToys/issues?q=is%3Aopen%20label%3AIssue-Bug%20label%3A%22Product-Shortcut%20Guide%22)<br>
|
|
[Pull Requests](https://github.com/microsoft/PowerToys/pulls?q=is%3Apr+is%3Aopen+label%3A%22Product-Shortcut+Guide%22+)
|
|
|
|
## 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.
|
|
|
|
- Use the title-bar search box to filter shortcuts on the selected application page
|
|
- Press Ctrl+F to focus search. Escape clears an active search before dismissing the overlay
|
|
-
|
|
The hold duration accepts values from 100 through 5,000 milliseconds and defaults to 900 milliseconds.
|
|
|
|
## Build and Debug Instructions
|
|
|
|
### Build
|
|
1. Open PowerToys.slnx in Visual Studio
|
|
2. Select Release or Debug in the Solutions Configuration drop-down menu
|
|
3. From the Build menu, choose Build Solution
|
|
4. The executable is named PowerToys.ShortcutGuide.exe
|
|
|
|
### Debug
|
|
1. Right-click the ShortcutGuide.Ui project and select 'Set as Startup Project'
|
|
2. 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`](/src/modules/ShortcutGuide/ShortcutGuide.Ui/ShortcutGuide.Ui.csproj)
|
|
|
|
This is the main UI project for the Shortcut Guide module. Upon startup it does the following tasks:
|
|
|
|
1. Copies the built-in manifest files to the users manifest directory (overwriting existing files).
|
|
2. Generate the `index.yml` manifest file.
|
|
3. Populate the PowerToys shortcut manifest with the user-defined shortcuts.
|
|
4. Starts the UI.
|
|
|
|
### Related files in PowerToys.Interop
|
|
|
|
#### [`excluded_app.cpp`](/src/modules/ShortcutGuide/ShortcutGuide.CPPProject/excluded_app.cpp)
|
|
|
|
This file contains one function with the following signature:
|
|
|
|
```cpp
|
|
__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`](/src/modules/ShortcutGuide/ShortcutGuide.CPPProject/tasklist_positions.cpp)
|
|
|
|
This file contains helper functions to retrieve the positions of the taskbar buttons. It exports the following function:
|
|
|
|
```cpp
|
|
__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`](/src/modules/ShortcutGuide/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`](/src/modules/ShortcutGuide/ShortcutGuideModuleInterface/ShortcutGuideModuleInterface.vcxproj)
|
|
|
|
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 |