mirror of
https://github.com/microsoft/PowerToys
synced 2025-08-22 18:17:19 +00:00
725535b760
## Summary of the Pull Request Accumulated information from internal transition about the modules development, and reworked it to be added in dev docs. Also the dev docs intself was restructured to be more organized. New pages was verified by transition team. ## PR Checklist - [x] **Dev docs:** Added/updated --------- Co-authored-by: Zhaopeng Wang (from Dev Box) <zhaopengwang@microsoft.com> Co-authored-by: Hao Liu <liuhao3418@gmail.com> Co-authored-by: Peiyao Zhao <105847726+zhaopy536@users.noreply.github.com> Co-authored-by: Mengyuan <162882040+chenmy77@users.noreply.github.com> Co-authored-by: zhaopeng wang <33367956+wang563681252@users.noreply.github.com> Co-authored-by: Jaylyn Barbee <51131738+Jaylyn-Barbee@users.noreply.github.com>
94 lines
3.1 KiB
Markdown
94 lines
3.1 KiB
Markdown
# Keyboard Manager Debugging Guide
|
|
|
|
This document provides guidance on debugging the Keyboard Manager module in PowerToys.
|
|
|
|
## Module Overview
|
|
|
|
Keyboard Manager consists of two main components:
|
|
- **Keyboard Manager Editor**: UI application for configuring key and shortcut remappings
|
|
- **Keyboard Manager Engine**: Background process that intercepts and handles keyboard events
|
|
|
|
## Development Environment Setup
|
|
|
|
1. Clone the PowerToys repository
|
|
2. Open `PowerToys.sln` in Visual Studio
|
|
3. Ensure all NuGet packages are restored
|
|
4. Build the entire solution in Debug configuration
|
|
|
|
## Debugging the Editor (UI)
|
|
|
|
### Setup
|
|
|
|
1. In Visual Studio, right-click on the `KeyboardManagerEditor` project
|
|
2. Select "Set as Startup Project"
|
|
|
|
### Common Debugging Scenarios
|
|
|
|
#### UI Rendering Issues
|
|
|
|
Breakpoints to consider:
|
|
- `EditKeyboardWindow.cpp`: `CreateWindow()` method
|
|
- `EditShortcutsWindow.cpp`: `CreateWindow()` method
|
|
|
|
#### Configuration Changes
|
|
|
|
When debugging configuration changes:
|
|
1. Set breakpoints in `KeyboardManagerState.cpp` around the `SetRemappedKeys()` or `SetRemappedShortcuts()` methods
|
|
2. Monitor the JSON serialization process in the save functions
|
|
|
|
### Testing UI Behavior
|
|
|
|
The `KeyboardManagerEditorTest` project contains tests for the UI functionality. Run these tests to validate UI changes.
|
|
|
|
## Debugging the Engine (Remapping Logic)
|
|
|
|
### Setup
|
|
|
|
1. In Visual Studio, right-click on the `KeyboardManagerEngine` project
|
|
2. Select "Set as Startup Project"
|
|
3. Press F5 to start debugging
|
|
|
|
### Key Event Flow
|
|
|
|
The keyboard event processing follows this sequence:
|
|
1. Low-level keyboard hook captures an event
|
|
2. `KeyboardEventHandlers.cpp` processes the event
|
|
3. `KeyboardManager.cpp` applies remapping logic
|
|
4. Event is either suppressed, modified, or passed through
|
|
|
|
### Breakpoints to Consider
|
|
|
|
- `main.cpp`: `StartLowlevelKeyboardHook()` - Hook initialization
|
|
- `KeyboardEventHandlers.cpp`: `HandleKeyboardEvent()` - Entry point for each keyboard event
|
|
- `KeyboardManager.cpp`: `HandleKeyEvent()` - Processing individual key events
|
|
- `KeyboardManager.cpp`: `HandleShortcutRemapEvent()` - Processing shortcut remapping
|
|
|
|
### Logging and Trace
|
|
|
|
Enable detailed logging by setting the `_DEBUG` and `KBM_VERBOSE_LOGGING` preprocessor definitions.
|
|
|
|
## Common Issues and Troubleshooting
|
|
|
|
### Multiple Instances
|
|
|
|
If you encounter issues with multiple instances, check the mutex logic in `KeyboardManagerEditor.cpp`. The editor uses `PowerToys_KBMEditor_InstanceMutex` to ensure single instance.
|
|
|
|
### Key Events Not Being Intercepted
|
|
|
|
1. Verify the hook is properly installed by setting a breakpoint in the hook procedure
|
|
2. Check if any other application is capturing keyboard events at a lower level
|
|
3. Ensure the correct configuration is being loaded from the settings JSON
|
|
|
|
### UI Freezes or Crashes
|
|
|
|
1. Check XAML Islands initialization in the Editor
|
|
2. Verify UI thread is not being blocked by IO operations
|
|
3. Look for exceptions in the event handling code
|
|
|
|
## Advanced Debugging
|
|
|
|
### Debugging Both Components Simultaneously
|
|
|
|
To debug both the Editor and Engine:
|
|
1. Launch the Engine first in debug mode
|
|
2. Attach the debugger to the Editor process when it starts |