ClassicAssist.Avalonia/.qoder/repowiki/en/content/User Interface Guide/Custom Controls Library/TextBoxKey.md

# TextBoxKey Control Documentation

<cite>
**Referenced Files in This Document**
- [TextBoxKey.axaml.cs](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml.cs)
- [TextBoxKey.axaml](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml)
- [HotkeyManager.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyManager.cs)
- [ShortcutKeys.cs](file://ClassicAssist.Shared/Data/Hotkeys/ShortcutKeys.cs)
- [HotkeyEntry.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyEntry.cs)
- [HotkeysTabControl.axaml.cs](file://ClassicAssist.Avalonia/Views/HotkeysTabControl.axaml.cs)
- [HotkeysTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/HotkeysTabViewModel.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 TextBoxKey control is a specialized input control designed for capturing and displaying keyboard shortcuts and hotkey combinations in the ClassicAssist application. It provides an intuitive user interface for users to configure keyboard bindings, handling modifier keys (Ctrl, Alt, Shift), special keys, and complex key combinations while ensuring cross-platform compatibility and accessibility.

This control serves as the primary interface for hotkey configuration throughout the application, allowing users to easily assign keyboard shortcuts to various commands and actions within the game client.

## Project Structure

The TextBoxKey control is implemented as part of the Avalonia UI framework integration, following modern MVVM patterns and leveraging Avalonia's cross-platform capabilities. The control consists of both markup and code-behind files that work together to provide a seamless user experience.

```mermaid
graph TB
subgraph "Avalonia Controls"
TK["TextBoxKey.axaml"]
TKC["TextBoxKey.axaml.cs"]
end
subgraph "Shared Hotkey System"
HM["HotkeyManager.cs"]
SK["ShortcutKeys.cs"]
HE["HotkeyEntry.cs"]
end
subgraph "UI Integration"
HTC["HotkeysTabControl.axaml.cs"]
HTVM["HotkeysTabViewModel.cs"]
end
TK --> TKC
TKC --> HM
TKC --> SK
TKC --> HE
HTC --> TK
HTVM --> HM
```

**Diagram sources**
- [TextBoxKey.axaml.cs:1-200](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml.cs#L1-L200)
- [HotkeyManager.cs:1-100](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyManager.cs#L1-L100)
- [HotkeysTabControl.axaml.cs:1-150](file://ClassicAssist.Avalonia/Views/HotkeysTabControl.axaml.cs#L1-L150)

**Section sources**
- [TextBoxKey.axaml.cs:1-200](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml.cs#L1-L200)
- [TextBoxKey.axaml:1-100](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml#L1-L100)

## Core Components

### TextBoxKey Control Properties

The TextBoxKey control exposes several key properties that define its behavior and appearance:

#### KeyBinding Property
The primary property that stores the current key combination. This property supports both simple keys and complex combinations with modifiers.

#### AllowModifiers Property
A boolean flag that determines whether modifier keys (Ctrl, Alt, Shift) are allowed in the key combination. When set to false, only regular keys are accepted.

#### IsRecording Property
Indicates whether the control is currently capturing keyboard input for a new key binding.

#### ValidationState Property
Represents the current validation state of the entered key combination, including conflict detection results.

### Keyboard Input Handling

The control implements sophisticated keyboard event handling to capture and process user input:

#### Modifier Key Detection
- **Ctrl**: Detected through Ctrl key events and combined with other keys
- **Alt**: Handled separately due to platform-specific behavior differences  
- **Shift**: Processed along with other modifier combinations

#### Special Key Support
The control recognizes and properly displays special keys such as:
- Function keys (F1-F12)
- Navigation keys (Arrow keys, Home, End, Page Up/Down)
- System keys (Escape, Tab, Enter, Backspace)
- Media keys and multimedia functions

#### International Keyboard Support
The implementation accounts for different keyboard layouts and regional variations, ensuring consistent behavior across international setups.

**Section sources**
- [TextBoxKey.axaml.cs:50-150](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml.cs#L50-L150)
- [ShortcutKeys.cs:1-100](file://ClassicAssist.Shared/Data/Hotkeys/ShortcutKeys.cs#L1-L100)

## Architecture Overview

The TextBoxKey control follows a layered architecture pattern that separates concerns between UI presentation, input processing, and business logic:

```mermaid
sequenceDiagram
participant User as "User"
participant TK as "TextBoxKey Control"
participant VM as "ViewModel"
participant HM as "HotkeyManager"
participant Config as "Configuration"
User->>TK : Presses key combination
TK->>TK : Capture keyboard event
TK->>TK : Process modifiers and key
TK->>HM : Validate key combination
HM-->>TK : Validation result
TK->>VM : Update KeyBinding property
VM->>Config : Save to configuration
Config-->>VM : Confirmation
VM-->>TK : Update display
```

**Diagram sources**
- [TextBoxKey.axaml.cs:100-200](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml.cs#L100-L200)
- [HotkeyManager.cs:50-150](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyManager.cs#L50-L150)
- [HotkeysTabViewModel.cs:1-100](file://ClassicAssist.Shared/UI/ViewModels/HotkeysTabViewModel.cs#L1-L100)

## Detailed Component Analysis

### TextBoxKey Class Implementation

The TextBoxKey class extends Avalonia's base control functionality to provide specialized keyboard input handling:

#### Key Event Processing Flow

```mermaid
flowchart TD
Start([Key Event Received]) --> CheckFocus{"Control Has Focus?"}
CheckFocus --> |No| IgnoreEvent["Ignore Event"]
CheckFocus --> |Yes| ProcessModifiers["Process Modifier Keys"]
ProcessModifiers --> DetectKey["Detect Primary Key"]
DetectKey --> ValidateCombination["Validate Key Combination"]
ValidateCombination --> ConflictCheck{"Conflict Detected?"}
ConflictCheck --> |Yes| ShowError["Display Error State"]
ConflictCheck --> |No| UpdateBinding["Update KeyBinding Property"]
ShowError --> UpdateDisplay["Update Visual State"]
UpdateBinding --> UpdateDisplay
UpdateDisplay --> NotifyVM["Notify ViewModel"]
IgnoreEvent --> End([End])
NotifyVM --> End
```

**Diagram sources**
- [TextBoxKey.axaml.cs:150-250](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml.cs#L150-L250)

#### Display Formatting Logic

The control implements intelligent formatting for displaying key combinations:

- **Modifier Order**: Consistent ordering (Ctrl + Alt + Shift + Key)
- **Special Key Names**: Human-readable names for function and system keys
- **Platform Adaptation**: Platform-specific key name localization
- **Visual Indicators**: Color coding for valid vs invalid combinations

### Hotkey Management Integration

The TextBoxKey control integrates seamlessly with the application's hotkey management system:

#### Conflict Detection Algorithm

```mermaid
classDiagram
class TextBoxKey {
+KeyBinding KeyBinding
+bool AllowModifiers
+bool IsRecording
+ValidationState ValidationState
+CaptureKey() void
+ClearBinding() void
-ValidateCombination() bool
-FormatKeyDisplay() string
}
class HotkeyManager {
+RegisterHotkey(KeyBinding) bool
+UnregisterHotkey(KeyBinding) bool
+HasConflict(KeyBinding) bool
+GetConflictingEntries(KeyBinding) HotkeyEntry[]
+SaveToConfiguration() void
}
class KeyBinding {
+Key Key
+bool Ctrl
+bool Alt
+bool Shift
+Equals(KeyBinding) bool
+ToString() string
}
class HotkeyEntry {
+string Name
+KeyBinding Binding
+Action Command
+bool IsActive
}
TextBoxKey --> HotkeyManager : "uses"
TextBoxKey --> KeyBinding : "manages"
HotkeyManager --> HotkeyEntry : "manages"
HotkeyManager --> KeyBinding : "validates"
```

**Diagram sources**
- [TextBoxKey.axaml.cs:1-100](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml.cs#L1-L100)
- [HotkeyManager.cs:1-100](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyManager.cs#L1-L100)
- [ShortcutKeys.cs:1-50](file://ClassicAssist.Shared/Data/Hotkeys/ShortcutKeys.cs#L1-L50)

### Cross-Platform Compatibility

The control handles platform-specific keyboard behaviors:

#### Windows-Specific Handling
- Proper Alt key processing without triggering menu navigation
- Correct handling of Windows key combinations
- Unicode character support for international keyboards

#### Linux/macOS Considerations
- Super/Meta key mapping for command shortcuts
- Different modifier key precedence rules
- Application focus management for global hotkeys

**Section sources**
- [TextBoxKey.axaml.cs:200-300](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml.cs#L200-L300)
- [HotkeyManager.cs:100-200](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyManager.cs#L100-L200)

## Dependency Analysis

The TextBoxKey control has well-defined dependencies on the shared hotkey infrastructure:

```mermaid
graph LR
subgraph "UI Layer"
TK["TextBoxKey Control"]
HTC["HotkeysTabControl"]
end
subgraph "Business Logic"
HM["HotkeyManager"]
SK["ShortcutKeys"]
end
subgraph "Data Layer"
HE["HotkeyEntry"]
CFG["Configuration"]
end
TK --> HM
TK --> SK
HTC --> TK
HM --> HE
HM --> CFG
SK --> HE
```

**Diagram sources**
- [TextBoxKey.axaml.cs:1-50](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml.cs#L1-L50)
- [HotkeyManager.cs:1-50](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyManager.cs#L1-L50)

### Coupling and Cohesion Analysis

The control maintains high cohesion by encapsulating all keyboard input logic within itself while maintaining loose coupling with external components through well-defined interfaces.

**Section sources**
- [TextBoxKey.axaml.cs:1-100](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml.cs#L1-L100)
- [HotkeyManager.cs:1-100](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyManager.cs#L1-L100)

## Performance Considerations

### Input Processing Optimization

The control implements several performance optimizations:

- **Debounced Input**: Prevents rapid successive key captures during modifier key sequences
- **Efficient String Formatting**: Caches formatted key display strings to avoid repeated calculations
- **Minimal Event Handlers**: Uses efficient event routing to reduce overhead
- **Lazy Loading**: Defers expensive operations until needed

### Memory Management

- **Weak References**: Uses weak references for event handlers to prevent memory leaks
- **Resource Cleanup**: Properly disposes of keyboard hooks and event subscriptions
- **Garbage Collection Friendly**: Avoids creating unnecessary objects during normal operation

## Troubleshooting Guide

### Common Issues and Solutions

#### Key Not Being Captured
- Ensure the control has focus when pressing keys
- Check if `AllowModifiers` is set appropriately
- Verify that no other control is consuming the keyboard events

#### Incorrect Display Format
- Review the key combination for unsupported combinations
- Check platform-specific limitations
- Validate the key binding against the hotkey manager

#### Conflict Detection Failures
- Clear existing conflicting bindings before setting new ones
- Verify hotkey manager initialization
- Check for duplicate entries in configuration

### Debugging Techniques

Enable detailed logging by setting appropriate debug flags in the configuration. The control provides visual feedback through color changes and status messages to aid in debugging.

**Section sources**
- [TextBoxKey.axaml.cs:250-350](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml.cs#L250-L350)

## Conclusion

The TextBoxKey control provides a robust, cross-platform solution for keyboard shortcut configuration in the ClassicAssist application. Its modular design, comprehensive error handling, and attention to accessibility make it a reliable component for managing user-defined hotkeys. The control successfully balances usability with technical complexity, providing an intuitive interface while maintaining clean separation of concerns and optimal performance.

## Appendices

### Accessibility Features

The control includes several accessibility features:
- **Screen Reader Support**: Proper announcements of key combinations
- **Keyboard Navigation**: Full keyboard operability
- **High Contrast Support**: Visual indicators for different states
- **Focus Management**: Clear focus indicators and navigation

### Configuration Examples

Key bindings are typically stored in XML configuration files with the following structure:

```xml
<HotkeyEntry Name="ExampleCommand">
  <KeyBinding>
    <Key>F1</Key>
    <Modifiers>Ctrl,Alt</Modifiers>
  </KeyBinding>
</HotkeyEntry>
```

### Best Practices

When implementing custom key bindings:
- Always validate combinations before saving
- Provide clear user feedback for conflicts
- Consider platform-specific conventions
- Test with multiple keyboard layouts
- Implement proper cleanup of hotkey registrations