PowerToys/doc/devdocs/modules/keyboardmanager/debug.md

# 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