# Hotkey Management

<cite>
**Referenced Files in This Document**
- [HotkeyManager.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyManager.cs)
- [HotkeyEntry.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyEntry.cs)
- [ShortcutKeys.cs](file://ClassicAssist.Shared/Data/Hotkeys/ShortcutKeys.cs)
- [HotkeyChangedEventArgs.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyChangedEventArgs.cs)
- [HotkeyCommand.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/HotkeyCommand.cs)
- [HotkeyCommandAttribute.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/HotkeyCommandAttribute.cs)
- [HotkeysTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/HotkeysTabControl.xaml.cs)
- [HotkeysTabControl.xaml](file://ClassicAssist.Avalonia/Views/HotkeysTabControl.xaml)
- [HotkeyEntryViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/HotkeyEntryViewModel.cs)
- [HotkeysTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/HotkeysTabViewModel.cs)
- [TextBoxKey.axaml.cs](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml.cs)
- [ToggleHotkeys.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/ToggleHotkeys.cs)
</cite>

## Table of Contents
1. [Introduction](#introduction)
2. [Project Structure](#project-structure)
3. [Core Components](#core-components)
4. [Architecture Overview](#architecture-overview)
5. [Detailed Component Analysis](#detailed-component-analysis)
6. [Dependency Analysis](#dependency-analysis)
7. [Performance Considerations](#performance-considerations)
8. [Troubleshooting Guide](#troubleshooting-guide)
9. [Conclusion](#conclusion)
10. [Appendices](#appendices)

## Introduction

The ClassicAssist.Avalonia hotkey management system provides a comprehensive framework for handling keyboard shortcuts and global hotkeys across the application. This system supports both local key bindings within the application context and global hotkeys that work even when the application is not focused. The architecture follows MVVM patterns and integrates seamlessly with Avalonia UI framework while maintaining cross-platform compatibility.

The hotkey system is designed to be extensible, allowing developers to register custom commands, handle conflicts between different components, and persist user preferences across application sessions. It supports modifier keys (Ctrl, Alt, Shift), function keys, and complex key combinations.

## Project Structure

The hotkey management system is organized into several key components:

```mermaid
graph TB
subgraph "Core Hotkey System"
HM[HotkeyManager]
HE[HotkeyEntry]
SK[ShortcutKeys]
HCA[HotkeyChangedEventArgs]
end
subgraph "Command Framework"
HC[HotkeyCommand]
HCAtr[HotkeyCommandAttribute]
TH[ToggleHotkeys]
end
subgraph "UI Layer"
HTV[HotkeysTabViewModel]
HEV[HotkeyEntryViewModel]
TK[TextBoxKey Control]
HTC[HotkeysTabControl]
end
HM --> HE
HM --> SK
HM --> HCA
HE --> HC
HC --> HCAtr
HTV --> HEV
HTC --> HTV
TK --> HEV
```

**Diagram sources**
- [HotkeyManager.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyManager.cs)
- [HotkeyEntry.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyEntry.cs)
- [HotkeysTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/HotkeysTabViewModel.cs)
- [HotkeyEntryViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/HotkeyEntryViewModel.cs)

**Section sources**
- [HotkeyManager.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyManager.cs)
- [HotkeysTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/HotkeysTabControl.xaml.cs)

## Core Components

### HotkeyManager Class Architecture

The `HotkeyManager` serves as the central coordinator for all hotkey operations in the application. It manages the lifecycle of hotkey registrations, handles conflict resolution, and coordinates between the UI layer and the underlying platform-specific implementations.

Key responsibilities include:
- Global hotkey registration and unregistration
- Conflict detection and resolution
- Event dispatching to registered handlers
- Configuration persistence and loading
- Cross-platform abstraction layer

### HotkeyEntry Data Structure

The `HotkeyEntry` class represents individual hotkey configurations, containing:
- Key combination definition (modifier keys + primary key)
- Associated command or action reference
- Priority level for conflict resolution
- Description and metadata
- Enabled/disabled state

### ShortcutKeys Utility

The `ShortcutKeys` class provides utility methods for parsing, validating, and manipulating key combinations. It handles:
- String-to-key conversion
- Key combination validation
- Platform-specific key code mapping
- Modifier key normalization

**Section sources**
- [HotkeyManager.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyManager.cs)
- [HotkeyEntry.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyEntry.cs)
- [ShortcutKeys.cs](file://ClassicAssist.Shared/Data/Hotkeys/ShortcutKeys.cs)

## Architecture Overview

The hotkey system follows a layered architecture pattern with clear separation of concerns:

```mermaid
sequenceDiagram
participant User as "User"
participant UI as "UI Layer"
participant VM as "ViewModel Layer"
participant HM as "HotkeyManager"
participant CMD as "Command Handler"
participant OS as "Operating System"
User->>UI : Presses key combination
UI->>VM : TextBoxKey captures input
VM->>HM : RegisterHotkey(keyCombination, command)
HM->>OS : Register global hotkey
OS-->>HM : Hotkey event
HM->>CMD : Execute command
CMD-->>VM : Update UI state
VM-->>UI : Refresh display
Note over HM,CMD : Command execution flow
HM->>HM : Check for conflicts
HM->>HM : Dispatch to appropriate handler
```

**Diagram sources**
- [HotkeyManager.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyManager.cs)
- [TextBoxKey.axaml.cs](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml.cs)
- [HotkeyEntryViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/HotkeyEntryViewModel.cs)

## Detailed Component Analysis

### HotkeyManager Implementation

The `HotkeyManager` implements a singleton pattern to ensure centralized hotkey management throughout the application lifecycle.

#### Key Registration Process

```mermaid
flowchart TD
Start([RegisterHotkey Request]) --> Validate["Validate Key Combination"]
Validate --> Valid{"Valid Combination?"}
Valid --> |No| ReturnError["Return Validation Error"]
Valid --> |Yes| CheckConflict["Check for Conflicts"]
CheckConflict --> ConflictFound{"Conflict Found?"}
ConflictFound --> |Yes| ResolveConflict["Resolve Based on Priority"]
ConflictFound --> |No| RegisterGlobal["Register Global Hotkey"]
ResolveConflict --> RegisterGlobal
RegisterGlobal --> StoreEntry["Store HotkeyEntry"]
StoreEntry --> NotifyUI["Notify UI Updates"]
NotifyUI --> End([Registration Complete])
ReturnError --> End
```

**Diagram sources**
- [HotkeyManager.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyManager.cs)

#### Conflict Resolution Mechanism

The system employs a priority-based conflict resolution strategy:

1. **Priority Levels**: Each hotkey entry has an associated priority value
2. **Component Ownership**: Built-in commands have higher priority than user-defined ones
3. **Last-Write-Wins**: When priorities are equal, the last registration takes precedence
4. **Graceful Degradation**: Lower priority hotkeys remain functional but may be disabled

### Command Framework

The hotkey command framework provides a flexible mechanism for associating actions with key combinations.

#### HotkeyCommand Base Class

The `HotkeyCommand` class serves as the base for all hotkey-executable commands:

```mermaid
classDiagram
class HotkeyCommand {
+string Name
+string Description
+bool CanExecute()
+void Execute(object parameter)
+event EventHandler Executed
+event EventHandler CanExecuteChanged
}
class ToggleHotkeys {
+bool IsEnabled
+void Execute(object parameter)
-void ToggleHotkeyState()
}
class BandageSelf {
+void Execute(object parameter)
-void PerformBandageAction()
}
HotkeyCommand <|-- ToggleHotkeys
HotkeyCommand <|-- BandageSelf
```

**Diagram sources**
- [HotkeyCommand.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/HotkeyCommand.cs)
- [ToggleHotkeys.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/ToggleHotkeys.cs)

#### Custom Command Registration

Developers can create custom hotkey commands by extending the base `HotkeyCommand` class and registering them through the command manager.

### UI Integration

The UI layer provides intuitive interfaces for hotkey configuration and management.

#### TextBoxKey Control

The `TextBoxKey` control offers a specialized input field for capturing key combinations:

- Real-time key capture and display
- Visual feedback for pressed keys
- Support for modifier key combinations
- Input validation and error handling

#### Hotkeys Tab Interface

The `HotkeysTabControl` provides a comprehensive interface for managing all hotkey configurations:

- Grid view of all registered hotkeys
- Inline editing capabilities
- Search and filtering functionality
- Import/export configuration support

**Section sources**
- [HotkeyCommand.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/HotkeyCommand.cs)
- [TextBoxKey.axaml.cs](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml.cs)
- [HotkeysTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/HotkeysTabControl.xaml.cs)

## Dependency Analysis

The hotkey system maintains loose coupling between components through well-defined interfaces:

```mermaid
graph LR
subgraph "External Dependencies"
Avalonia[Avalonia UI]
Platform[Platform Abstraction]
Config[Configuration Manager]
end
subgraph "Internal Dependencies"
HM[HotkeyManager]
VM[ViewModels]
UI[UI Controls]
Commands[Command Handlers]
end
Avalonia --> UI
Platform --> HM
Config --> HM
HM --> VM
VM --> UI
HM --> Commands
Commands --> Platform
```

**Diagram sources**
- [HotkeyManager.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyManager.cs)
- [HotkeysTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/HotkeysTabViewModel.cs)

### Cross-Platform Considerations

The system abstracts platform-specific differences through the following mechanisms:

- **Key Code Mapping**: Unified key codes across Windows, macOS, and Linux
- **Modifier Key Normalization**: Consistent handling of Ctrl/Cmd, Alt/Option, Shift keys
- **Global Hotkey APIs**: Platform-specific global hotkey registration
- **Event Handling**: Abstracted event dispatching mechanism

**Section sources**
- [ShortcutKeys.cs](file://ClassicAssist.Shared/Data/Hotkeys/ShortcutKeys.cs)
- [HotkeyManager.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyManager.cs)

## Performance Considerations

The hotkey system is optimized for minimal performance impact:

- **Lazy Loading**: Hotkey entries are loaded on-demand rather than at startup
- **Efficient Lookup**: Hash-based key combination lookup for O(1) performance
- **Memory Management**: Automatic cleanup of unused hotkey entries
- **Threading**: Asynchronous hotkey processing to prevent UI blocking

## Troubleshooting Guide

### Common Issues and Solutions

#### Hotkey Not Responding

**Symptoms**: Pressing a configured hotkey produces no response

**Possible Causes**:
- Hotkey conflict with another component
- Application focus issues
- Platform-specific limitations

**Resolution Steps**:
1. Check for conflicting hotkeys in the Hotkeys tab
2. Verify the hotkey is enabled and properly registered
3. Test with a simple command first
4. Review platform-specific restrictions

#### Global Hotkey Not Working

**Symptoms**: Global hotkeys don't work when application is not focused

**Possible Causes**:
- Insufficient permissions (especially on macOS)
- Antivirus software interference
- Platform-specific limitations

**Resolution Steps**:
1. Run application with elevated privileges if required
2. Check system settings for accessibility permissions
3. Temporarily disable security software for testing
4. Verify platform support for global hotkeys

#### Configuration Persistence Issues

**Symptoms**: Hotkey settings don't save between sessions

**Possible Causes**:
- File permission problems
- Corrupted configuration file
- Serialization errors

**Resolution Steps**:
1. Check application data directory permissions
2. Backup and reset configuration file
3. Review error logs for serialization issues
4. Verify configuration file format

### Debugging Tools

The system includes built-in debugging capabilities:

- **Hotkey Event Logging**: Detailed logging of all hotkey events
- **Conflict Detection**: Real-time conflict monitoring and reporting
- **Performance Metrics**: Hotkey registration and execution timing
- **Configuration Validation**: Pre-save validation of hotkey configurations

**Section sources**
- [HotkeyManager.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyManager.cs)
- [HotkeysTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/HotkeysTabViewModel.cs)

## Conclusion

The ClassicAssist.Avalonia hotkey management system provides a robust, extensible, and user-friendly framework for handling keyboard shortcuts. Its modular architecture ensures maintainability while supporting complex use cases through its command framework and conflict resolution mechanisms. The system's cross-platform design and comprehensive UI integration make it suitable for diverse deployment scenarios.

Key strengths include:
- Comprehensive conflict resolution strategies
- Extensible command framework
- Intuitive user interface for configuration
- Cross-platform compatibility
- Robust error handling and debugging support

Future enhancements could include advanced macro recording, hotkey profiles, and cloud synchronization of configurations.

## Appendices

### Example: Implementing Custom Hotkey Handlers

To implement a custom hotkey handler:

1. Create a new class extending `HotkeyCommand`
2. Override the `Execute` method with your logic
3. Register the command through the command manager
4. Bind a key combination in the UI or configuration

### Configuration File Format

Hotkey configurations are stored in JSON format with the following structure:

```json
{
  "hotkeys": [
    {
      "id": "unique_identifier",
      "key_combination": "Ctrl+Alt+A",
      "command_name": "YourCommandName",
      "priority": 1,
      "enabled": true,
      "description": "Optional description"
    }
  ]
}
```

### Testing Best Practices

- Use unit tests for command logic
- Implement integration tests for hotkey registration
- Test cross-platform compatibility
- Validate conflict resolution scenarios
- Monitor performance under load