Beyhan Oğur
13 KiB
TextBoxKey Control Documentation
**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)Table of Contents
- Introduction
- Project Structure
- Core Components
- Architecture Overview
- Detailed Component Analysis
- Dependency Analysis
- Performance Considerations
- Troubleshooting Guide
- Conclusion
- 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.
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
Section sources
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
Architecture Overview
The TextBoxKey control follows a layered architecture pattern that separates concerns between UI presentation, input processing, and business logic:
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
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
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
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
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
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
Dependency Analysis
The TextBoxKey control has well-defined dependencies on the shared hotkey infrastructure:
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
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
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
AllowModifiersis 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
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:
<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