PowerToys/doc/devdocs/modules/keystrokeoverlay.md

Keystroke Overlay - Will live in doc/devdocs/modules

Public overview - Microsoft Learn

Quick Links

All Issues
Bugs
Pull Requests

Overview

Keystroke Overlay is a PowerToys module that displays keyboard input live. There are three different display modes. Single-key display shows the last key pressed, e.g. "o." Last five keys display shows the last five keys pressed, e.g. "h e l l o." Shortcut display supports shortcuts, e.g. "ctrl + v." This module is meant to be used as a helpful tool for educators, presenters, and/or visually impaired users.

Architecture

The Keystroke Overlay module consists of three main components:

keystrokeoverlay/
├── KeystrokeOverlayKeyboardService/     # Keyboard Hook
├── KeystrokeOverlayXAML/                # The overlaying display UI
└── KeystrokeOverlayModuleInterface/     # DLL Interface

Keyboard Service (KeystrokeOverlayKeyboardService)

The Keyboard Service component is responsible for:

• Compiles KeystrokeEvent.h, EventQueue.h, Batcher.cpp, and KeyboardListener.cpp into PowerToys.KeystrokeOverlayKeystrokeServer.exe
• Implements keyboard hooks to detect key presses
• Manages the trigger mechanism for displaying the keystroke overlay
• Handles keyboard input processing

UI Layer (KeystrokeOverlayXAML)

The UI component is responsible for:

• Displaying the overlay of pressed keys
• Managing the visual positioning of the overlay

Module Interface (KeystrokeOverlayModuleInterface)

The Module Interface, implemented in KeystrokeOverlayModuleInterface/dllmain.cpp, is responsible for:

• Handling communication between PowerToys Runner and the KeystrokeOverlay process
• Managing module lifecycle (enable/disable/settings)
• Launching and terminating the PowerToys.KeystrokeOverlay.exe process (as well as PowerToys.KeystrokeOverlayKeystrokeServer.exe as a child process)

Implementation Details

Activation Mechanism

The Keystroke Overlay is activated when:

1. A user presses or holds any key
2. After a brief delay (around 300ms per setting), the overlay appears
3. Upon releasing the key(s), the overlay hovers for around 300ms or a value specified in settings, then disappears

Character Sets

The module supports multiple language-specific characters. Since the module uses keyboard codes to detect key presses and trigger the display, various keyboards and languages are supported by Keystroke Overlay, as long as they are supported by Windows.

Known Behaviors

• If a key is pressed and held, this is processed as several presses of the same key in rapid succession
• Stream mode detects capital letters as shortcuts because the shift key is pressed and separates them from words; e.g. “Hello” in stream mode appears as “H ello”

Future Considerations

• Add support for different appearances, other than left-to-right. Right-to-left or center-outwards would be beneficial, especially for users who communicate in languages that read right-to-left
• Add support for default positioning, e.g. top-left, bottom-center, middle-right, …

Debugging

To debug the Keystroke Overlay module via runner approach, follow these steps:

0. Get familiar with the overall Debugging Process for PowerToys.
1. Build the entire PowerToys solution in Visual Studio
2. Navigate to the KeystrokeOverlay folder in Solution Explorer
3. Open the file you want to debug and set breakpoints at the relevant locations
4. Find the runner project in the root of the solution
5. Right-click on the runner project and select "Set as Startup Project"
6. Start debugging by pressing F5 or clicking the "Start" button
7. When the PowerToys Runner launches, enable the Keystroke Overlay module in the UI
8. Use the Visual Studio Debug menu or press Ctrl+Alt+P to open "Reattach to Process"
9. Find and select "PowerToys.KeystrokeOverlay.exe" in the process list
10. Trigger the action in Keystroke Overlay that should hit your breakpoint
11. Verify that the debugger breaks at your breakpoint and you can inspect variables and step through code

This process allows you to debug the Keystroke Overlay module while it's running as part of the full PowerToys application.

Alternative Debugging Approach

To directly debug the Keystroke Overlay UI component:

0. Get familiar with the overall Debugging Process for PowerToys.
1. Build the entire PowerToys solution in Visual Studio
2. Navigate to the KeystrokeOverlay folder in Solution Explorer
3. Open the file you want to debug and set breakpoints at the relevant locations
4. Right-click on the KeystrokeOverlayUI project and select "Set as Startup Project"
5. Start debugging by pressing F5 or clicking the "Start" button
6. Verify that the debugger breaks at your breakpoint and you can inspect variables and step through code

Any known issues with debugging here