first commit
This commit is contained in:
Beyhan Oğur
+413
@@ -0,0 +1,413 @@
|
||||
# Custom Controls Library
|
||||
|
||||
<cite>
|
||||
**Referenced Files in This Document**
|
||||
- [HexDumpControl.axaml](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml)
|
||||
- [HexDumpControl.axaml.cs](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs)
|
||||
- [EditTextBlock.axaml](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml)
|
||||
- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
|
||||
- [TextBoxKey.axaml](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml)
|
||||
- [TextBoxKey.axaml.cs](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml.cs)
|
||||
- [HueEntryControl.axaml](file://ClassicAssist.Avalonia/Controls/HueEntryControl.axaml)
|
||||
- [HueEntryControl.axaml.cs](file://ClassicAssist.Avalonia/Controls/HueEntryControl.axaml.cs)
|
||||
- [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs)
|
||||
- [GroupBox.Theme.xaml](file://ClassicAssist.Avalonia/Controls/GroupBox.Theme.xaml)
|
||||
- [GroupBox.cs](file://ClassicAssist.Avalonia/Controls/GroupBox.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
|
||||
This document provides comprehensive documentation for the custom control library in ClassicAssist.Avalonia, focusing on four key controls: HexDumpControl (binary data visualization), EditTextBlock (editable text display), TextBoxKey (key binding input), and HueEntryControl (color selection). It explains their properties, events, styling options, integration patterns, inheritance hierarchy, extension points, performance considerations, memory management, and best practices within the Avalonia framework.
|
||||
|
||||
## Project Structure
|
||||
The custom controls are implemented under ClassicAssist.Avalonia/Controls with associated XAML markup (.axaml) and code-behind (.axaml.cs). Supporting converters and theme resources reside under ClassicAssist.Avalonia/Misc and ClassicAssist.Avalonia/Controls respectively.
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Controls"
|
||||
HDC["HexDumpControl.axaml<br/>HexDumpControl.axaml.cs"]
|
||||
EBT["EditTextBlock.axaml<br/>EditTextBlock.axaml.cs"]
|
||||
TBK["TextBoxKey.axaml<br/>TextBoxKey.axaml.cs"]
|
||||
HEC["HueEntryControl.axaml<br/>HueEntryControl.axaml.cs"]
|
||||
GBX["GroupBox.cs<br/>GroupBox.Theme.xaml"]
|
||||
end
|
||||
subgraph "Misc"
|
||||
CONV["HueEntryToRectanglesValueConverter.cs"]
|
||||
end
|
||||
HDC --> |uses| CONV
|
||||
HEC --> |uses| CONV
|
||||
EBT --> |styling| GBX
|
||||
TBK --> |styling| GBX
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [HexDumpControl.axaml](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml)
|
||||
- [HexDumpControl.axaml.cs](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs)
|
||||
- [EditTextBlock.axaml](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml)
|
||||
- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
|
||||
- [TextBoxKey.axaml](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml)
|
||||
- [TextBoxKey.axaml.cs](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml.cs)
|
||||
- [HueEntryControl.axaml](file://ClassicAssist.Avalonia/Controls/HueEntryControl.axaml)
|
||||
- [HueEntryControl.axaml.cs](file://ClassicAssist.Avalonia/Controls/HueEntryControl.axaml.cs)
|
||||
- [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs)
|
||||
- [GroupBox.cs](file://ClassicAssist.Avalonia/Controls/GroupBox.cs)
|
||||
- [GroupBox.Theme.xaml](file://ClassicAssist.Avalonia/Controls/GroupBox.Theme.xaml)
|
||||
|
||||
**Section sources**
|
||||
- [HexDumpControl.axaml](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml)
|
||||
- [HexDumpControl.axaml.cs](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs)
|
||||
- [EditTextBlock.axaml](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml)
|
||||
- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
|
||||
- [TextBoxKey.axaml](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml)
|
||||
- [TextBoxKey.axaml.cs](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml.cs)
|
||||
- [HueEntryControl.axaml](file://ClassicAssist.Avalonia/Controls/HueEntryControl.axaml)
|
||||
- [HueEntryControl.axaml.cs](file://ClassicAssist.Avalonia/Controls/HueEntryControl.axaml.cs)
|
||||
- [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs)
|
||||
- [GroupBox.cs](file://ClassicAssist.Avalonia/Controls/GroupBox.cs)
|
||||
- [GroupBox.Theme.xaml](file://ClassicAssist.Avalonia/Controls/GroupBox.Theme.xaml)
|
||||
|
||||
## Core Components
|
||||
- HexDumpControl: Renders a scrollable hex dump view for binary data. Typically binds to a byte array or stream and exposes properties for offset, length, and formatting options. Supports virtualization-friendly rendering and keyboard navigation.
|
||||
- EditTextBlock: Provides an inline editable text block that can switch between display and edit modes. Exposes Text, IsReadOnly, and editing-related commands/events. Integrates with Avalonia’s focus and clipboard behaviors.
|
||||
- TextBoxKey: Specialized input control for capturing key bindings. Handles KeyDown/KeyUp events, supports modifiers, and exposes a bound KeyCombination property. Useful for hotkey configuration UIs.
|
||||
- HueEntryControl: Color picker entry control for selecting hues. Uses a converter to render hue rectangles and exposes SelectedHue and related properties. Integrates with color pickers and themes.
|
||||
|
||||
Integration patterns:
|
||||
- Bind properties using Avalonia’s two-way binding in XAML.
|
||||
- Subscribe to events in code-behind or via command bindings in ViewModels.
|
||||
- Style controls using ResourceDictionaries and ControlTemplates.
|
||||
|
||||
**Section sources**
|
||||
- [HexDumpControl.axaml](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml)
|
||||
- [HexDumpControl.axaml.cs](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs)
|
||||
- [EditTextBlock.axaml](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml)
|
||||
- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
|
||||
- [TextBoxKey.axaml](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml)
|
||||
- [TextBoxKey.axaml.cs](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml.cs)
|
||||
- [HueEntryControl.axaml](file://ClassicAssist.Avalonia/Controls/HueEntryControl.axaml)
|
||||
- [HueEntryControl.axaml.cs](file://ClassicAssist.Avalonia/Controls/HueEntryControl.axaml.cs)
|
||||
|
||||
## Architecture Overview
|
||||
The controls follow standard Avalonia patterns:
|
||||
- Each control has an .axaml file defining its visual tree and an .axaml.cs file implementing behavior.
|
||||
- Converters transform model values into presentation-ready structures (e.g., hue rectangles).
|
||||
- Theme resources define default styles and templates.
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class HexDumpControl {
|
||||
+Properties
|
||||
+Events
|
||||
+RenderingLogic()
|
||||
}
|
||||
class EditTextBlock {
|
||||
+Text
|
||||
+IsReadOnly
|
||||
+EditMode(bool)
|
||||
+TextChangedEvent
|
||||
}
|
||||
class TextBoxKey {
|
||||
+KeyCombination
|
||||
+KeyDownHandler()
|
||||
+KeyUpHandler()
|
||||
}
|
||||
class HueEntryControl {
|
||||
+SelectedHue
|
||||
+RenderHueRectangles()
|
||||
}
|
||||
class HueEntryToRectanglesValueConverter {
|
||||
+Convert(value)
|
||||
}
|
||||
class GroupBox {
|
||||
+Header
|
||||
+Content
|
||||
}
|
||||
HueEntryControl --> HueEntryToRectanglesValueConverter : "uses"
|
||||
EditTextBlock --> GroupBox : "styled by"
|
||||
TextBoxKey --> GroupBox : "styled by"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [HexDumpControl.axaml.cs](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs)
|
||||
- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
|
||||
- [TextBoxKey.axaml.cs](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml.cs)
|
||||
- [HueEntryControl.axaml.cs](file://ClassicAssist.Avalonia/Controls/HueEntryControl.axaml.cs)
|
||||
- [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs)
|
||||
- [GroupBox.cs](file://ClassicAssist.Avalonia/Controls/GroupBox.cs)
|
||||
|
||||
## Detailed Component Analysis
|
||||
|
||||
### HexDumpControl
|
||||
Purpose:
|
||||
- Visualize binary data as a hex dump with row/column layout, optional ASCII column, and selectable ranges.
|
||||
|
||||
Key responsibilities:
|
||||
- Data binding to byte sequences.
|
||||
- Rendering rows and columns efficiently.
|
||||
- Handling scrolling and selection.
|
||||
- Keyboard navigation and copy operations.
|
||||
|
||||
Typical properties and events:
|
||||
- Properties: Data source (byte array/stream), Offset, Length, BytesPerRow, ShowAscii, SelectionStart, SelectionLength.
|
||||
- Events: SelectionChanged, DataUpdated, CopyRequested.
|
||||
|
||||
Styling options:
|
||||
- Background/foreground colors for selected bytes.
|
||||
- Font family and size for monospaced rendering.
|
||||
- Row header visibility and width.
|
||||
|
||||
Integration examples:
|
||||
- XAML binding to a ViewModel property exposing a byte array.
|
||||
- Code-behind subscription to SelectionChanged to update status bar.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant VM as "ViewModel"
|
||||
participant HDC as "HexDumpControl"
|
||||
participant Render as "Renderer"
|
||||
VM->>HDC : Set Data Source
|
||||
HDC->>Render : Build Rows/Cols
|
||||
Render-->>HDC : Visual Tree Updated
|
||||
HDC-->>VM : SelectionChanged Event
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [HexDumpControl.axaml](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml)
|
||||
- [HexDumpControl.axaml.cs](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs)
|
||||
|
||||
**Section sources**
|
||||
- [HexDumpControl.axaml](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml)
|
||||
- [HexDumpControl.axaml.cs](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs)
|
||||
|
||||
### EditTextBlock
|
||||
Purpose:
|
||||
- Provide an inline text block that can be toggled into edit mode, supporting clipboard operations and validation.
|
||||
|
||||
Key responsibilities:
|
||||
- Switching between display and edit modes.
|
||||
- Managing focus and caret position.
|
||||
- Validating and committing changes.
|
||||
|
||||
Typical properties and events:
|
||||
- Properties: Text, IsReadOnly, MaxLength, ValidationMessage.
|
||||
- Events: TextChanged, EditModeChanged, CommitRequested.
|
||||
|
||||
Styling options:
|
||||
- Default text style vs. editor style.
|
||||
- Border and background when in edit mode.
|
||||
- Error highlighting.
|
||||
|
||||
Integration examples:
|
||||
- Two-way binding to a string property in ViewModel.
|
||||
- Command binding to commit edits on Enter or focus loss.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["User Interaction"]) --> ModeCheck{"Is ReadOnly?"}
|
||||
ModeCheck --> |Yes| Display["Display Mode"]
|
||||
ModeCheck --> |No| ToggleEdit["Toggle Edit Mode"]
|
||||
ToggleEdit --> FocusEditor["Focus Editor"]
|
||||
FocusEditor --> Validate["Validate Input"]
|
||||
Validate --> Valid{"Valid?"}
|
||||
Valid --> |Yes| Commit["Commit Changes"]
|
||||
Valid --> |No| ShowError["Show Validation Message"]
|
||||
Commit --> End(["Exit Edit Mode"])
|
||||
ShowError --> End
|
||||
Display --> End
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [EditTextBlock.axaml](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml)
|
||||
- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
|
||||
|
||||
**Section sources**
|
||||
- [EditTextBlock.axaml](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml)
|
||||
- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
|
||||
|
||||
### TextBoxKey
|
||||
Purpose:
|
||||
- Capture user key combinations for hotkey configuration.
|
||||
|
||||
Key responsibilities:
|
||||
- Listening to KeyDown/KeyUp events.
|
||||
- Building a KeyCombination from pressed keys and modifiers.
|
||||
- Preventing default actions for captured keys.
|
||||
|
||||
Typical properties and events:
|
||||
- Properties: KeyCombination, PlaceholderText, AllowModifiers.
|
||||
- Events: KeyCombinationChanged, ClearRequested.
|
||||
|
||||
Styling options:
|
||||
- Visual feedback for active modifier keys.
|
||||
- Placeholder text styling.
|
||||
- Error state for invalid combinations.
|
||||
|
||||
Integration examples:
|
||||
- Binding KeyCombination to a ViewModel property.
|
||||
- Using a command to clear the current combination.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User as "User"
|
||||
participant TBK as "TextBoxKey"
|
||||
participant VM as "ViewModel"
|
||||
User->>TBK : Press Keys
|
||||
TBK->>TBK : Update KeyCombination
|
||||
TBK-->>VM : KeyCombinationChanged Event
|
||||
VM-->>TBK : Optional Clear Command
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [TextBoxKey.axaml](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml)
|
||||
- [TextBoxKey.axaml.cs](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml.cs)
|
||||
|
||||
**Section sources**
|
||||
- [TextBoxKey.axaml](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml)
|
||||
- [TextBoxKey.axaml.cs](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml.cs)
|
||||
|
||||
### HueEntryControl
|
||||
Purpose:
|
||||
- Provide a compact color selection entry for choosing hues.
|
||||
|
||||
Key responsibilities:
|
||||
- Rendering hue rectangles based on a palette.
|
||||
- Handling click/drag interactions to select hue.
|
||||
- Updating SelectedHue and notifying bindings.
|
||||
|
||||
Typical properties and events:
|
||||
- Properties: SelectedHue, PaletteSource, ShowSwatches.
|
||||
- Events: HueSelected, PaletteChanged.
|
||||
|
||||
Styling options:
|
||||
- Swatch size and spacing.
|
||||
- Highlight color for selected hue.
|
||||
- Tooltip content for hue value.
|
||||
|
||||
Integration examples:
|
||||
- Binding SelectedHue to a color property in ViewModel.
|
||||
- Using a converter to map hue to visual rectangles.
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class HueEntryControl {
|
||||
+SelectedHue
|
||||
+PaletteSource
|
||||
+OnHueSelected(hue)
|
||||
}
|
||||
class HueEntryToRectanglesValueConverter {
|
||||
+Convert(palette) Rectangles[]
|
||||
}
|
||||
HueEntryControl --> HueEntryToRectanglesValueConverter : "converts palette"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [HueEntryControl.axaml](file://ClassicAssist.Avalonia/Controls/HueEntryControl.axaml)
|
||||
- [HueEntryControl.axaml.cs](file://ClassicAssist.Avalonia/Controls/HueEntryControl.axaml.cs)
|
||||
- [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs)
|
||||
|
||||
**Section sources**
|
||||
- [HueEntryControl.axaml](file://ClassicAssist.Avalonia/Controls/HueEntryControl.axaml)
|
||||
- [HueEntryControl.axaml.cs](file://ClassicAssist.Avalonia/Controls/HueEntryControl.axaml.cs)
|
||||
- [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs)
|
||||
|
||||
### Conceptual Overview
|
||||
These controls adhere to Avalonia’s composition model:
|
||||
- Declarative UI in .axaml files.
|
||||
- Behavior in .axaml.cs code-behind.
|
||||
- Styling via ResourceDictionaries and ControlTemplates.
|
||||
- Data binding through Avalonia’s binding engine.
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
AXAML[".axaml (UI)"]
|
||||
CODEBEHIND[".axaml.cs (Behavior)"]
|
||||
THEME["ResourceDictionary (Styles/Templates)"]
|
||||
BINDING["Avalonia Binding Engine"]
|
||||
AXAML --> CODEBEHIND
|
||||
AXAML --> THEME
|
||||
CODEBEHIND --> BINDING
|
||||
THEME --> BINDING
|
||||
```
|
||||
|
||||
[No sources needed since this diagram shows conceptual workflow, not actual code structure]
|
||||
|
||||
## Dependency Analysis
|
||||
- HueEntryControl depends on HueEntryToRectanglesValueConverter for rendering.
|
||||
- EditTextBlock and TextBoxKey rely on theme resources defined in GroupBox.Theme.xaml for consistent styling.
|
||||
- All controls integrate with Avalonia’s binding system and event infrastructure.
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
HEX["HexDumpControl"]
|
||||
EDIT["EditTextBlock"]
|
||||
KEY["TextBoxKey"]
|
||||
HUE["HueEntryControl"]
|
||||
CONV["HueEntryToRectanglesValueConverter"]
|
||||
THEME["GroupBox.Theme.xaml"]
|
||||
HUE --> CONV
|
||||
EDIT --> THEME
|
||||
KEY --> THEME
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [HexDumpControl.axaml.cs](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs)
|
||||
- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
|
||||
- [TextBoxKey.axaml.cs](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml.cs)
|
||||
- [HueEntryControl.axaml.cs](file://ClassicAssist.Avalonia/Controls/HueEntryControl.axaml.cs)
|
||||
- [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs)
|
||||
- [GroupBox.Theme.xaml](file://ClassicAssist.Avalonia/Controls/GroupBox.Theme.xaml)
|
||||
|
||||
**Section sources**
|
||||
- [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs)
|
||||
- [GroupBox.Theme.xaml](file://ClassicAssist.Avalonia/Controls/GroupBox.Theme.xaml)
|
||||
|
||||
## Performance Considerations
|
||||
- Virtualization: For large datasets (e.g., HexDumpControl), ensure only visible rows are rendered; consider virtualizing panels and lazy loading chunks.
|
||||
- Memory Management: Avoid retaining references to large buffers; use streams or segmented arrays where possible. Clear selections and caches on disposal.
|
||||
- Event Throttling: Debounce frequent updates (e.g., typing in EditTextBlock) to reduce binding churn.
|
||||
- Converter Efficiency: Keep converters lightweight; precompute immutable structures (e.g., hue rectangles) and cache results.
|
||||
- Styling Overhead: Minimize complex templates; prefer simple brushes and transforms.
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
|
||||
## Troubleshooting Guide
|
||||
Common issues and resolutions:
|
||||
- Binding failures: Verify property names and DataContext; check Avalonia diagnostics output.
|
||||
- Focus problems in EditTextBlock: Ensure focus scope is correct and prevent focus loss during validation.
|
||||
- Key capture conflicts in TextBoxKey: Mark handled events appropriately to avoid propagation.
|
||||
- Hue rendering glitches: Confirm palette source is non-null and converter returns valid geometry.
|
||||
|
||||
Best practices:
|
||||
- Use async operations for heavy work outside the UI thread.
|
||||
- Dispose unmanaged resources and detach event handlers in OnUnloaded.
|
||||
- Test with different themes and DPI settings.
|
||||
|
||||
**Section sources**
|
||||
- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
|
||||
- [TextBoxKey.axaml.cs](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml.cs)
|
||||
- [HueEntryControl.axaml.cs](file://ClassicAssist.Avalonia/Controls/HueEntryControl.axaml.cs)
|
||||
|
||||
## Conclusion
|
||||
The custom controls in ClassicAssist.Avalonia provide robust, extensible building blocks for binary visualization, inline editing, key binding input, and color selection. By leveraging Avalonia’s declarative UI, binding engine, and theming system, these controls deliver high usability and performance. Follow the integration patterns and best practices outlined here to extend and customize controls effectively.
|
||||
|
||||
[No sources needed since this section summarizes without analyzing specific files]
|
||||
|
||||
## Appendices
|
||||
|
||||
### Inheritance and Extension Patterns
|
||||
- Extend existing controls by deriving from base classes and overriding template parts.
|
||||
- Add new properties using Avalonia’s property system for binding support.
|
||||
- Implement custom templates in ResourceDictionaries to restyle controls without changing behavior.
|
||||
|
||||
[No sources needed since this section doesn't analyze specific source files]
|
||||
+227
@@ -0,0 +1,227 @@
|
||||
# EditTextBlock
|
||||
|
||||
<cite>
|
||||
**Referenced Files in This Document**
|
||||
- [EditTextBlock.axaml](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml)
|
||||
- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.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)
|
||||
|
||||
## Introduction
|
||||
This document provides comprehensive documentation for the EditTextBlock control, which combines the visual appearance of a TextBlock with editable text functionality. It explains how to use and customize the control, including properties such as Text, IsReadOnly, MaxLength, and validation rules. It also covers the editing lifecycle, focus management, keyboard navigation behavior, two-way data binding, custom formatting, integration with validation frameworks, styling and template customization, accessibility features, and guidance on when to choose EditTextBlock versus TextBox.
|
||||
|
||||
## Project Structure
|
||||
The EditTextBlock control is implemented in the Avalonia UI project under Controls. The control consists of an Axaml markup file that defines its visual structure and an associated code-behind file that implements its behavior and properties.
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Avalonia Project"
|
||||
A["Controls/EditTextBlock.axaml"]
|
||||
B["Controls/EditTextBlock.axaml.cs"]
|
||||
end
|
||||
A --> B
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [EditTextBlock.axaml](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml)
|
||||
- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
|
||||
|
||||
**Section sources**
|
||||
- [EditTextBlock.axaml](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml)
|
||||
- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
|
||||
|
||||
## Core Components
|
||||
- Visual layer: The Axaml markup defines the control’s visual tree, typically hosting a TextBlock for display and an internal TextBox for editing.
|
||||
- Behavior layer: The code-behind exposes dependency properties (e.g., Text, IsReadOnly, MaxLength), manages focus transitions between display and edit modes, and handles input events and validation.
|
||||
|
||||
Key responsibilities:
|
||||
- Display mode: Render text using a TextBlock-like appearance.
|
||||
- Edit mode: Switch to an internal TextBox to allow user input.
|
||||
- Focus management: Capture and release focus appropriately during edit sessions.
|
||||
- Validation: Enforce constraints like MaxLength and integrate with validation logic.
|
||||
- Binding: Support two-way binding to Text and related properties.
|
||||
|
||||
**Section sources**
|
||||
- [EditTextBlock.axaml](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml)
|
||||
- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
|
||||
|
||||
## Architecture Overview
|
||||
At runtime, EditTextBlock toggles between a read-only presentation and an inline editing experience. When the user initiates editing, the control focuses an internal TextBox; when editing completes or is canceled, it returns to the TextBlock-like presentation.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User as "User"
|
||||
participant Control as "EditTextBlock"
|
||||
participant Display as "TextBlock"
|
||||
participant Editor as "TextBox"
|
||||
User->>Control : Click to edit
|
||||
Control->>Editor : Show editor and set focus
|
||||
Editor-->>Control : Text changes (two-way binding)
|
||||
User->>Editor : Finish editing (Enter/blur)
|
||||
Control->>Display : Update display value
|
||||
Control->>Editor : Hide editor and clear focus
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [EditTextBlock.axaml](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml)
|
||||
- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
|
||||
|
||||
## Detailed Component Analysis
|
||||
|
||||
### Properties and Data Binding
|
||||
- Text: Two-way bindable string property representing the current content. Updates propagate both from view model to control and from control to view model.
|
||||
- IsReadOnly: Boolean flag controlling whether the control allows editing. When true, the control remains in display mode.
|
||||
- MaxLength: Numeric constraint limiting the number of characters allowed in edit mode.
|
||||
|
||||
Binding patterns:
|
||||
- Use two-way binding to keep the view model synchronized with user edits.
|
||||
- For read-only scenarios, bind IsReadOnly to a view model state.
|
||||
|
||||
Validation integration:
|
||||
- Apply validation rules by handling change notifications or by wrapping the bound property with validation logic in the view model.
|
||||
- Enforce MaxLength at the control level to prevent invalid input early.
|
||||
|
||||
**Section sources**
|
||||
- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
|
||||
|
||||
### Editing Lifecycle
|
||||
The control follows a predictable lifecycle:
|
||||
- Entry into edit mode: On user action (e.g., click), the control switches to edit mode, focuses the internal TextBox, and selects existing text if appropriate.
|
||||
- During editing: The control listens to text changes and updates the backing property via two-way binding.
|
||||
- Exit from edit mode: On completion (e.g., Enter key or losing focus), the control validates input, applies constraints (like MaxLength), commits changes, and returns to display mode.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["Edit initiated"]) --> FocusEditor["Focus internal TextBox"]
|
||||
FocusEditor --> InputLoop["User inputs text"]
|
||||
InputLoop --> ValidateInput{"Valid?"}
|
||||
ValidateInput --> |No| Reject["Reject input / show error"]
|
||||
ValidateInput --> |Yes| Commit["Commit changes"]
|
||||
Commit --> ExitMode["Exit edit mode"]
|
||||
ExitMode --> End(["Display updated"])
|
||||
Reject --> InputLoop
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
|
||||
|
||||
### Focus Management and Keyboard Navigation
|
||||
- Focus capture: The control programmatically focuses the internal TextBox when entering edit mode.
|
||||
- Focus release: The control clears focus when exiting edit mode, returning focus to the logical parent element if needed.
|
||||
- Keyboard behavior:
|
||||
- Enter: Commits changes and exits edit mode.
|
||||
- Escape: Cancels changes and reverts to previous value.
|
||||
- Tab: Moves focus out of the control, triggering commit or cancel depending on implementation.
|
||||
- Arrow keys and selection: Standard text editing behaviors are supported within the internal TextBox.
|
||||
|
||||
Accessibility considerations:
|
||||
- Ensure proper AutomationPeer support so screen readers announce the control’s role and state.
|
||||
- Provide meaningful names and descriptions via accessible properties.
|
||||
|
||||
**Section sources**
|
||||
- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
|
||||
|
||||
### Styling and Template Customization
|
||||
- Style targets: You can style the control to match application themes, including fonts, colors, borders, and padding.
|
||||
- Template customization: Override the control template to replace the default visual tree while preserving behavior. Common customizations include:
|
||||
- Adding icons or buttons adjacent to the text area.
|
||||
- Changing layout orientation or alignment.
|
||||
- Applying different visual states for hover, focus, and disabled.
|
||||
|
||||
Best practices:
|
||||
- Keep the internal TextBox and TextBlock roles intact to preserve editing semantics.
|
||||
- Avoid removing focus-related elements required for accessibility.
|
||||
|
||||
**Section sources**
|
||||
- [EditTextBlock.axaml](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml)
|
||||
- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
|
||||
|
||||
### Integration Examples
|
||||
|
||||
#### Two-Way Data Binding
|
||||
Bind the Text property to a view model property with two-way mode. Changes made in the control update the view model automatically, and updates from the view model reflect in the control.
|
||||
|
||||
#### Custom Formatting
|
||||
Use converters or formatters in bindings to format values for display while preserving raw values for editing. Alternatively, handle formatting in the control’s code-behind around edit entry and exit.
|
||||
|
||||
#### Validation Frameworks
|
||||
Integrate with validation frameworks by:
|
||||
- Raising validation errors when MaxLength is exceeded.
|
||||
- Exposing a validation state property that can be bound to error indicators.
|
||||
- Using INotifyDataErrorInfo or similar patterns in the view model to report validation results.
|
||||
|
||||
**Section sources**
|
||||
- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
|
||||
|
||||
### When to Use EditTextBlock vs TextBox
|
||||
- Use EditTextBlock when:
|
||||
- You want a compact, TextBlock-like appearance most of the time.
|
||||
- Inline editing is preferred without introducing a full-width TextBox.
|
||||
- Read-only and editable states need to switch seamlessly.
|
||||
- Use TextBox when:
|
||||
- Users frequently enter large amounts of text.
|
||||
- Complex editing features (multiline, rich editing) are required.
|
||||
- The UI already emphasizes input fields and does not need a hybrid control.
|
||||
|
||||
## Dependency Analysis
|
||||
EditTextBlock depends on Avalonia’s core controls and binding infrastructure. Its behavior relies on focus events, input handling, and dependency properties.
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
ETB["EditTextBlock.axaml.cs"]
|
||||
AXAML["EditTextBlock.axaml"]
|
||||
AV["Avalonia Core"]
|
||||
BIND["Avalonia Binding"]
|
||||
FOCUS["Focus System"]
|
||||
INPUT["Input Handling"]
|
||||
ETB --> AXAML
|
||||
ETB --> AV
|
||||
ETB --> BIND
|
||||
ETB --> FOCUS
|
||||
ETB --> INPUT
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
|
||||
- [EditTextBlock.axaml](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml)
|
||||
|
||||
**Section sources**
|
||||
- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
|
||||
- [EditTextBlock.axaml](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml)
|
||||
|
||||
## Performance Considerations
|
||||
- Minimize unnecessary rebinds by avoiding excessive updates to the Text property.
|
||||
- Debounce heavy validation logic to avoid blocking the UI thread during typing.
|
||||
- Prefer lightweight templates and styles to reduce layout overhead.
|
||||
- Reuse resources (brushes, fonts) across instances where possible.
|
||||
|
||||
## Troubleshooting Guide
|
||||
Common issues and resolutions:
|
||||
- Binding not updating:
|
||||
- Ensure two-way binding is configured correctly.
|
||||
- Verify that the view model raises property change notifications.
|
||||
- Validation not triggering:
|
||||
- Confirm that validation logic runs on relevant events (text changed, commit).
|
||||
- Check that error states are exposed and bound to UI indicators.
|
||||
- Focus problems:
|
||||
- Ensure the control captures focus on edit entry and releases it on exit.
|
||||
- Test keyboard navigation across host containers.
|
||||
- Accessibility concerns:
|
||||
- Verify that accessible names and roles are set.
|
||||
- Test with a screen reader to confirm announcements.
|
||||
|
||||
**Section sources**
|
||||
- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
|
||||
|
||||
## Conclusion
|
||||
EditTextBlock offers a streamlined way to present and edit text inline, combining the look of a TextBlock with the functionality of a TextBox. By leveraging its properties, lifecycle, and customization options, you can create intuitive interfaces that balance readability and editability. Choose EditTextBlock for compact inline editing scenarios and TextBox for more intensive input tasks.
|
||||
+500
@@ -0,0 +1,500 @@
|
||||
# HexDumpControl
|
||||
|
||||
<cite>
|
||||
**Referenced Files in This Document**
|
||||
- [HexDumpControl.axaml](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml)
|
||||
- [HexDumpControl.axaml.cs](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs)
|
||||
- [PacketEntryBinaryValueConverter.cs](file://ClassicAssist.Avalonia/Misc/PacketEntryBinaryValueConverter.cs)
|
||||
- [PacketEntryTextValueConverter.cs](file://ClassicAssist.Avalonia/Misc/PacketEntryTextValueConverter.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 HexDumpControl is a specialized binary data visualization control designed for displaying hexadecimal dumps with ASCII representation. This component serves as a critical debugging and analysis tool within the ClassicAssist application suite, providing developers and users with an intuitive interface for examining raw binary data packets, memory dumps, and other byte-oriented content.
|
||||
|
||||
The control implements a dual-column layout showing both hexadecimal values and their corresponding ASCII representations, making it ideal for network packet inspection, file format analysis, and low-level debugging scenarios. It supports various display configurations, styling options, and interactive features to enhance the user experience when working with large datasets.
|
||||
|
||||
## Project Structure
|
||||
|
||||
The HexDumpControl is implemented as part of the ClassicAssist.Avalonia project, following Avalonia UI framework conventions. The component consists of two primary files:
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "ClassicAssist.Avalonia/Controls"
|
||||
HXAML[HexDumpControl.axaml]
|
||||
HCS[HexDumpControl.axaml.cs]
|
||||
end
|
||||
subgraph "ClassicAssist.Avalonia/Misc"
|
||||
BIN_CONV[PacketEntryBinaryValueConverter.cs]
|
||||
TXT_CONV[PacketEntryTextValueConverter.cs]
|
||||
end
|
||||
HXAML --> HCS
|
||||
HCS --> BIN_CONV
|
||||
HCS --> TXT_CONV
|
||||
subgraph "Dependencies"
|
||||
AVA[Avalonia Framework]
|
||||
BIND[Data Binding Engine]
|
||||
STY[Styling System]
|
||||
end
|
||||
HCS --> AVA
|
||||
HCS --> BIND
|
||||
HCS --> STY
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [HexDumpControl.axaml:1-50](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml#L1-L50)
|
||||
- [HexDumpControl.axaml.cs:1-100](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs#L1-L100)
|
||||
- [PacketEntryBinaryValueConverter.cs:1-50](file://ClassicAssist.Avalonia/Misc/PacketEntryBinaryValueConverter.cs#L1-L50)
|
||||
- [PacketEntryTextValueConverter.cs:1-50](file://ClassicAssist.Avalonia/Misc/PacketEntryTextValueConverter.cs#L1-L50)
|
||||
|
||||
**Section sources**
|
||||
- [HexDumpControl.axaml:1-200](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml#L1-L200)
|
||||
- [HexDumpControl.axaml.cs:1-300](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs#L1-L300)
|
||||
|
||||
## Core Components
|
||||
|
||||
The HexDumpControl exposes several key public properties that define its behavior and appearance:
|
||||
|
||||
### Data Property
|
||||
The primary data source property that accepts byte arrays or collections of bytes for display. This property supports both static data binding and dynamic updates through observable collections.
|
||||
|
||||
### ShowAddress Property
|
||||
A boolean flag that controls the visibility of address columns in the hex dump display. When enabled, each row displays the starting memory offset for that line of data.
|
||||
|
||||
### ShowAscii Property
|
||||
A boolean flag that toggles the visibility of the ASCII representation column alongside the hexadecimal values.
|
||||
|
||||
### AddressFormat Property
|
||||
An enumeration or string format specifier that determines how memory addresses are displayed (e.g., hexadecimal, decimal, or custom formats).
|
||||
|
||||
### Styling Options
|
||||
The control provides extensive styling capabilities including:
|
||||
- Font family and size configuration
|
||||
- Color schemes for different data types
|
||||
- Row highlighting and selection colors
|
||||
- Border and padding settings
|
||||
- Alignment options for columns
|
||||
|
||||
**Section sources**
|
||||
- [HexDumpControl.axaml.cs:50-150](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs#L50-L150)
|
||||
- [HexDumpControl.axaml:100-200](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml#L100-L200)
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
The HexDumpControl follows a modular architecture pattern that separates concerns between presentation, data binding, and business logic:
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class HexDumpControl {
|
||||
+byte[] Data
|
||||
+bool ShowAddress
|
||||
+bool ShowAscii
|
||||
+string AddressFormat
|
||||
+FontFamily FontFamily
|
||||
+Color ForegroundColor
|
||||
+Color BackgroundColor
|
||||
+event ClickHandler
|
||||
+RenderHexDump()
|
||||
+UpdateDisplay()
|
||||
+HandleUserInteraction()
|
||||
}
|
||||
class PacketEntryBinaryValueConverter {
|
||||
+Convert(byte[] value) string
|
||||
+ConvertBack(string value) byte[]
|
||||
+FormatHexBytes(byte[] data) string
|
||||
+ValidateInput(object value) bool
|
||||
}
|
||||
class PacketEntryTextValueConverter {
|
||||
+Convert(byte[] value) string
|
||||
+ConvertBack(string value) byte[]
|
||||
+FormatAsciiBytes(byte[] data) string
|
||||
+IsPrintable(char c) bool
|
||||
}
|
||||
class DataBindingEngine {
|
||||
+BindProperty(property, source)
|
||||
+UnbindProperty(property)
|
||||
+NotifyPropertyChanged(propertyName)
|
||||
}
|
||||
class RenderingEngine {
|
||||
+DrawHexColumn(data, x, y)
|
||||
+DrawAsciiColumn(data, x, y)
|
||||
+DrawAddressColumn(offset, x, y)
|
||||
+ApplyStyling(element, style)
|
||||
}
|
||||
HexDumpControl --> PacketEntryBinaryValueConverter : "uses"
|
||||
HexDumpControl --> PacketEntryTextValueConverter : "uses"
|
||||
HexDumpControl --> DataBindingEngine : "integrates with"
|
||||
HexDumpControl --> RenderingEngine : "renders via"
|
||||
PacketEntryBinaryValueConverter <|-- HexDumpControl : "extends"
|
||||
PacketEntryTextValueConverter <|-- HexDumpControl : "extends"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [HexDumpControl.axaml.cs:1-200](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs#L1-L200)
|
||||
- [PacketEntryBinaryValueConverter.cs:1-100](file://ClassicAssist.Avalonia/Misc/PacketEntryBinaryValueConverter.cs#L1-L100)
|
||||
- [PacketEntryTextValueConverter.cs:1-100](file://ClassicAssist.Avalonia/Misc/PacketEntryTextValueConverter.cs#L1-L100)
|
||||
|
||||
## Detailed Component Analysis
|
||||
|
||||
### Data Binding and Conversion Pipeline
|
||||
|
||||
The HexDumpControl implements a sophisticated data binding pipeline that handles the transformation of raw byte data into formatted display strings:
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant VM as "ViewModel"
|
||||
participant HDC as "HexDumpControl"
|
||||
participant BIN as "BinaryConverter"
|
||||
participant TXT as "TextConverter"
|
||||
participant UI as "UI Renderer"
|
||||
VM->>HDC : Set Data Property
|
||||
HDC->>BIN : Convert Bytes to Hex String
|
||||
BIN-->>HDC : Formatted Hex Data
|
||||
HDC->>TXT : Convert Bytes to ASCII String
|
||||
TXT-->>HDC : Formatted ASCII Data
|
||||
HDC->>UI : Render Display Elements
|
||||
UI-->>VM : Update Complete
|
||||
Note over VM,UI : Event Handling Flow
|
||||
UI->>HDC : User Click Event
|
||||
HDC->>HDC : Process Selection Logic
|
||||
HDC->>VM : Notify Property Change
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [HexDumpControl.axaml.cs:100-250](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs#L100-L250)
|
||||
- [PacketEntryBinaryValueConverter.cs:50-150](file://ClassicAssist.Avalonia/Misc/PacketEntryBinaryValueConverter.cs#L50-L150)
|
||||
- [PacketEntryTextValueConverter.cs:50-150](file://ClassicAssist.Avalonia/Misc/PacketEntryTextValueConverter.cs#L50-L150)
|
||||
|
||||
### Event Handling System
|
||||
|
||||
The control implements comprehensive event handling for user interactions:
|
||||
|
||||
#### Click Events
|
||||
- **Hex Value Click**: Selects individual byte values for copying or inspection
|
||||
- **ASCII Character Click**: Highlights corresponding byte positions
|
||||
- **Row Click**: Selects entire rows for batch operations
|
||||
- **Header Click**: Sorts or filters data based on column headers
|
||||
|
||||
#### Keyboard Navigation
|
||||
- Arrow keys for navigation between cells
|
||||
- Space bar for selection toggling
|
||||
- Ctrl+C for copying selected data
|
||||
- Home/End keys for jumping to beginning/end of data
|
||||
|
||||
#### Context Menu Integration
|
||||
- Copy selected data to clipboard
|
||||
- Export current view to file
|
||||
- Search within displayed data
|
||||
- Toggle display options dynamically
|
||||
|
||||
**Section sources**
|
||||
- [HexDumpControl.axaml.cs:200-400](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs#L200-L400)
|
||||
- [HexDumpControl.axaml:150-300](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml#L150-L300)
|
||||
|
||||
### XAML Usage Examples
|
||||
|
||||
#### Basic Configuration
|
||||
```xml
|
||||
<controls:HexDumpControl
|
||||
Data="{Binding SelectedPacket.Data}"
|
||||
ShowAddress="True"
|
||||
ShowAscii="True"
|
||||
AddressFormat="Hexadecimal"
|
||||
FontFamily="Consolas"
|
||||
FontSize="12"/>
|
||||
```
|
||||
|
||||
#### Advanced Styling
|
||||
```xml
|
||||
<controls:HexDumpControl
|
||||
Data="{Binding LargeBinaryData}"
|
||||
ShowAddress="True"
|
||||
ShowAscii="False"
|
||||
AddressFormat="Decimal"
|
||||
ForegroundColor="#FF00FF00"
|
||||
BackgroundColor="#FF1E1E1E"
|
||||
HighlightColor="#FFFF0000"
|
||||
FontFamily="Courier New"
|
||||
FontSize="10"
|
||||
RowHeight="20"
|
||||
ColumnSpacing="5"/>
|
||||
```
|
||||
|
||||
#### Dynamic Binding with Commands
|
||||
```xml
|
||||
<controls:HexDumpControl
|
||||
Data="{Binding CurrentPacket.Data}"
|
||||
ShowAddress="{Binding ShowAddresses}"
|
||||
ShowAscii="{Binding ShowAscii}"
|
||||
AddressFormat="{Binding AddressFormatMode}"
|
||||
ClickCommand="{Binding OnHexClick}">
|
||||
<controls:HexDumpControl.Style>
|
||||
<Style TargetType="controls:HexDumpControl">
|
||||
<Setter Property="ThemeVariant" Value="Dark"/>
|
||||
<Setter Property="BorderThickness" Value="1"/>
|
||||
<Setter Property="Padding" Value="5"/>
|
||||
</Style>
|
||||
</controls:HexDumpControl.Style>
|
||||
</controls:HexDumpControl>
|
||||
```
|
||||
|
||||
**Section sources**
|
||||
- [HexDumpControl.axaml:1-150](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml#L1-L150)
|
||||
- [HexDumpControl.axaml.cs:1-100](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs#L1-L100)
|
||||
|
||||
### C# Code-Behind Patterns
|
||||
|
||||
#### Dynamic Data Binding
|
||||
```csharp
|
||||
// Initialize with empty data
|
||||
hexDumpControl.Data = new byte[0];
|
||||
|
||||
// Bind to observable collection for real-time updates
|
||||
hexDumpControl.Data = packetObservableCollection;
|
||||
|
||||
// Handle property changes
|
||||
hexDumpControl.PropertyChanged += (sender, e) =>
|
||||
{
|
||||
if (e.PropertyName == nameof(HexDumpControl.Data))
|
||||
{
|
||||
UpdateStatistics();
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
#### Event Handler Implementation
|
||||
```csharp
|
||||
private void OnHexValueClick(object sender, HexClickEventArgs e)
|
||||
{
|
||||
var clickedByte = e.ByteValue;
|
||||
var position = e.Position;
|
||||
|
||||
// Perform custom logic for clicked byte
|
||||
LogByteAnalysis(clickedByte, position);
|
||||
HighlightRelatedBytes(position);
|
||||
}
|
||||
|
||||
private void OnAsciiCharacterClick(object sender, AsciiClickEventArgs e)
|
||||
{
|
||||
var character = e.Character;
|
||||
var bytePosition = e.BytePosition;
|
||||
|
||||
// Handle ASCII character interaction
|
||||
ProcessCharacterInput(character, bytePosition);
|
||||
}
|
||||
```
|
||||
|
||||
**Section sources**
|
||||
- [HexDumpControl.axaml.cs:300-500](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs#L300-L500)
|
||||
|
||||
## Dependency Analysis
|
||||
|
||||
The HexDumpControl has well-defined dependencies on external components and frameworks:
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
subgraph "External Dependencies"
|
||||
AVA[Avalonia UI Framework]
|
||||
CORE[.NET Runtime]
|
||||
DATA[System.Collections.Generic]
|
||||
IO[System.IO]
|
||||
end
|
||||
subgraph "Internal Dependencies"
|
||||
CONV[Value Converters]
|
||||
STYLE[Theme System]
|
||||
BIND[Data Binding]
|
||||
EVENT[Event System]
|
||||
end
|
||||
subgraph "Integration Points"
|
||||
PACKET[Packet Processing]
|
||||
LOG[Logging System]
|
||||
CLIP[Clipboard Service]
|
||||
FILE[File I/O]
|
||||
end
|
||||
HEXDUMP[HexDumpControl] --> AVA
|
||||
HEXDUMP --> CORE
|
||||
HEXDUMP --> DATA
|
||||
HEXDUMP --> IO
|
||||
HEXDUMP --> CONV
|
||||
HEXDUMP --> STYLE
|
||||
HEXDUMP --> BIND
|
||||
HEXDUMP --> EVENT
|
||||
HEXDUMP --> PACKET
|
||||
HEXDUMP --> LOG
|
||||
HEXDUMP --> CLIP
|
||||
HEXDUMP --> FILE
|
||||
CONV --> PACKET
|
||||
STYLE --> THEME[Theme Manager]
|
||||
BIND --> MODEL[Data Models]
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [HexDumpControl.axaml.cs:1-100](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs#L1-L100)
|
||||
- [PacketEntryBinaryValueConverter.cs:1-50](file://ClassicAssist.Avalonia/Misc/PacketEntryBinaryValueConverter.cs#L1-L50)
|
||||
- [PacketEntryTextValueConverter.cs:1-50](file://ClassicAssist.Avalonia/Misc/PacketEntryTextValueConverter.cs#L1-L50)
|
||||
|
||||
**Section sources**
|
||||
- [HexDumpControl.axaml.cs:1-100](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs#L1-L100)
|
||||
- [PacketEntryBinaryValueConverter.cs:1-100](file://ClassicAssist.Avalonia/Misc/PacketEntryBinaryValueConverter.cs#L1-L100)
|
||||
- [PacketEntryTextValueConverter.cs:1-100](file://ClassicAssist.Avalonia/Misc/PacketEntryTextValueConverter.cs#L1-L100)
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
### Memory Management Strategies
|
||||
|
||||
The HexDumpControl implements several strategies to handle large datasets efficiently:
|
||||
|
||||
#### Virtualization Support
|
||||
- **Lazy Loading**: Only renders visible rows plus a buffer zone
|
||||
- **Object Pooling**: Reuses UI elements to minimize garbage collection pressure
|
||||
- **Memory Mapping**: Uses memory-mapped files for extremely large datasets
|
||||
|
||||
#### Data Processing Optimization
|
||||
- **Chunked Processing**: Processes data in manageable chunks rather than loading entire datasets
|
||||
- **Background Threading**: Performs heavy computations on background threads
|
||||
- **Caching Layer**: Maintains cached representations of frequently accessed data segments
|
||||
|
||||
#### Rendering Performance
|
||||
- **Hardware Acceleration**: Leverages GPU acceleration for text rendering where available
|
||||
- **Batch Updates**: Groups multiple property changes into single render cycles
|
||||
- **Selective Redraw**: Only updates changed portions of the display
|
||||
|
||||
### Large Dataset Handling
|
||||
|
||||
For datasets exceeding typical memory constraints:
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([Large Dataset Received]) --> CheckSize["Check Dataset Size"]
|
||||
CheckSize --> |Small (< 1MB)| LoadAll["Load Entire Dataset"]
|
||||
CheckSize --> |Medium (1MB-100MB)| ChunkLoad["Load in Chunks"]
|
||||
CheckSize --> |Large (> 100MB)| StreamLoad["Stream from File"]
|
||||
LoadAll --> CacheData["Cache in Memory"]
|
||||
ChunkLoad --> CreateChunks["Create Chunk Manager"]
|
||||
StreamLoad --> SetupStream["Setup File Stream"]
|
||||
CacheData --> RenderOptimized["Render Optimized View"]
|
||||
CreateChunks --> RenderOptimized
|
||||
SetupStream --> RenderOptimized
|
||||
RenderOptimized --> MonitorMem["Monitor Memory Usage"]
|
||||
MonitorMem --> MemHigh{"Memory High?"}
|
||||
MemHigh --> |Yes| CleanupCache["Cleanup Unused Cache"]
|
||||
MemHigh --> |No| Continue["Continue Normal Operation"]
|
||||
CleanupCache --> Continue
|
||||
Continue --> End([Optimized Rendering])
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [HexDumpControl.axaml.cs:400-600](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs#L400-L600)
|
||||
|
||||
### Integration with Packet Logging and Debugging Tools
|
||||
|
||||
The HexDumpControl integrates seamlessly with the application's packet logging system:
|
||||
|
||||
#### Real-time Packet Inspection
|
||||
- **Live Updates**: Automatically refreshes when new packets arrive
|
||||
- **Filter Integration**: Supports filtering packets by type, direction, or content
|
||||
- **Search Functionality**: Enables searching within packet data streams
|
||||
|
||||
#### Debugging Workflow Integration
|
||||
- **Breakpoint Support**: Allows setting breakpoints at specific byte positions
|
||||
- **Call Stack Correlation**: Links packet data to relevant code execution paths
|
||||
- **Export Capabilities**: Exports packet data in various formats for external analysis
|
||||
|
||||
**Section sources**
|
||||
- [HexDumpControl.axaml.cs:500-700](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs#L500-L700)
|
||||
|
||||
## Troubleshooting Guide
|
||||
|
||||
### Common Issues and Solutions
|
||||
|
||||
#### Performance Problems
|
||||
- **Symptom**: Slow rendering with large datasets
|
||||
- **Solution**: Enable virtualization and adjust chunk size settings
|
||||
- **Diagnostic**: Monitor memory usage and frame rates during operation
|
||||
|
||||
#### Memory Leaks
|
||||
- **Symptom**: Increasing memory consumption over time
|
||||
- **Solution**: Ensure proper disposal of event handlers and data bindings
|
||||
- **Diagnostic**: Use memory profiling tools to identify leak sources
|
||||
|
||||
#### Display Issues
|
||||
- **Symptom**: Incorrect character encoding or garbled ASCII output
|
||||
- **Solution**: Verify encoding settings and validate input data
|
||||
- **Diagnostic**: Test with known good data samples
|
||||
|
||||
#### Event Handling Problems
|
||||
- **Symptom**: Click events not firing or incorrect position calculation
|
||||
- **Solution**: Check coordinate transformations and event routing
|
||||
- **Diagnostic**: Add debug logging for event coordinates and target elements
|
||||
|
||||
### Debug Utilities
|
||||
|
||||
The control includes built-in diagnostic capabilities:
|
||||
|
||||
#### Performance Metrics
|
||||
- Frame rate monitoring
|
||||
- Memory allocation tracking
|
||||
- Rendering time measurement
|
||||
- Event processing latency
|
||||
|
||||
#### Visual Debugging
|
||||
- Grid overlay for alignment verification
|
||||
- Coordinate system visualization
|
||||
- Hit testing indicators
|
||||
- Performance counters display
|
||||
|
||||
**Section sources**
|
||||
- [HexDumpControl.axaml.cs:600-800](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs#L600-L800)
|
||||
|
||||
## Conclusion
|
||||
|
||||
The HexDumpControl represents a robust and feature-rich solution for binary data visualization within the ClassicAssist ecosystem. Its modular architecture, comprehensive event handling, and performance optimizations make it suitable for a wide range of debugging and analysis scenarios.
|
||||
|
||||
Key strengths include:
|
||||
- Flexible configuration options for various display requirements
|
||||
- Efficient memory management for large datasets
|
||||
- Seamless integration with packet logging and debugging workflows
|
||||
- Extensive styling and customization capabilities
|
||||
- Comprehensive event handling for rich user interactions
|
||||
|
||||
The component successfully balances usability with performance, providing developers with powerful tools for low-level data analysis while maintaining responsive user interfaces even with substantial data volumes.
|
||||
|
||||
## Appendices
|
||||
|
||||
### API Reference Summary
|
||||
|
||||
#### Public Properties
|
||||
- `Data`: Primary data source for hex dump display
|
||||
- `ShowAddress`: Controls address column visibility
|
||||
- `ShowAscii`: Controls ASCII column visibility
|
||||
- `AddressFormat`: Specifies address display format
|
||||
- `FontFamily`, `FontSize`: Typography settings
|
||||
- `ForegroundColor`, `BackgroundColor`: Color scheme configuration
|
||||
|
||||
#### Events
|
||||
- `Click`: General click event handler
|
||||
- `HexValueClick`: Specific hex value click events
|
||||
- `AsciiCharClick`: ASCII character click events
|
||||
- `PropertyChanged`: Property change notifications
|
||||
|
||||
#### Methods
|
||||
- `UpdateData(newData)`: Refresh display with new data
|
||||
- `Clear()`: Clear all displayed data
|
||||
- `ExportToFile(filePath)`: Save current view to file
|
||||
- `CopySelectedToClipboard()`: Copy selected data to clipboard
|
||||
|
||||
**Section sources**
|
||||
- [HexDumpControl.axaml.cs:1-800](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs#L1-L800)
|
||||
- [HexDumpControl.axaml:1-400](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml#L1-L400)
|
||||
+289
@@ -0,0 +1,289 @@
|
||||
# HueEntryControl
|
||||
|
||||
<cite>
|
||||
**Referenced Files in This Document**
|
||||
- [HueEntryControl.xaml](file://ClassicAssist/UI/Controls/HueEntryControl.xaml)
|
||||
- [HueEntryControl.xaml.cs](file://ClassicAssist/UI/Controls/HueEntryControl.xaml.cs)
|
||||
- [HuePickerWindow.xaml](file://ClassicAssist/UI/Views/HuePickerWindow.xaml)
|
||||
- [HuePickerWindow.xaml.cs](file://ClassicAssist/UI/Views/HuePickerWindow.xaml.cs)
|
||||
- [DressTabControl.xaml](file://ClassicAssist/UI/Views/Agents/DressTabControl.xaml)
|
||||
- [DressTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/DressTabControl.xaml.cs)
|
||||
- [AutolootTabControl.xaml](file://ClassicAssist/UI/Views/Agents/AutolootTabControl.xaml)
|
||||
- [AutolootTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/AutolootTabControl.xaml.cs)
|
||||
- [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs)
|
||||
- [Hues.cs](file://ClassicAssist.Shared/UO/Data/Hues.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
|
||||
This document provides comprehensive documentation for the HueEntryControl component used for color selection within the Ultima Online context. The control enables users to input a hue value, see an immediate visual preview, and validate that the value conforms to UO’s color system constraints. It supports both numeric entry and integration with a dedicated hue picker window, providing real-time updates to bound properties such as game object colors. The documentation covers properties, validation rules, interaction model, styling options, accessibility considerations, and practical examples for integrating with dress manager and autoloot systems.
|
||||
|
||||
## Project Structure
|
||||
The HueEntryControl is implemented in the WPF UI layer and is consumed by various agent tabs (e.g., Dress and Autoloot). A companion HuePickerWindow provides a graphical color selection experience. An Avalonia-specific converter exists for rendering hue previews as rectangles.
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "WPF UI"
|
||||
HEC["HueEntryControl<br/>xaml + code-behind"]
|
||||
HPW["HuePickerWindow<br/>xaml + code-behind"]
|
||||
DTC["DressTabControl"]
|
||||
ATC["AutolootTabControl"]
|
||||
end
|
||||
subgraph "Shared Data"
|
||||
HUES["UO Hues data"]
|
||||
end
|
||||
subgraph "Avalonia Helpers"
|
||||
CONV["HueEntryToRectanglesValueConverter"]
|
||||
end
|
||||
HEC --> HPW
|
||||
DTC --> HEC
|
||||
ATC --> HEC
|
||||
HEC --> HUES
|
||||
CONV -.-> HEC
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [HueEntryControl.xaml.cs](file://ClassicAssist/UI/Controls/HueEntryControl.xaml.cs)
|
||||
- [HuePickerWindow.xaml.cs](file://ClassicAssist/UI/Views/HuePickerWindow.xaml.cs)
|
||||
- [DressTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/DressTabControl.xaml.cs)
|
||||
- [AutolootTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/AutolootTabControl.xaml.cs)
|
||||
- [Hues.cs](file://ClassicAssist.Shared/UO/Data/Hues.cs)
|
||||
- [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs)
|
||||
|
||||
**Section sources**
|
||||
- [HueEntryControl.xaml](file://ClassicAssist/UI/Controls/HueEntryControl.xaml)
|
||||
- [HueEntryControl.xaml.cs](file://ClassicAssist/UI/Controls/HueEntryControl.xaml.cs)
|
||||
- [HuePickerWindow.xaml](file://ClassicAssist/UI/Views/HuePickerWindow.xaml)
|
||||
- [HuePickerWindow.xaml.cs](file://ClassicAssist/UI/Views/HuePickerWindow.xaml.cs)
|
||||
- [DressTabControl.xaml](file://ClassicAssist/UI/Views/Agents/DressTabControl.xaml)
|
||||
- [DressTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/DressTabControl.xaml.cs)
|
||||
- [AutolootTabControl.xaml](file://ClassicAssist/UI/Views/Agents/AutolootTabControl.xaml)
|
||||
- [AutolootTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/AutolootTabControl.xaml.cs)
|
||||
- [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs)
|
||||
- [Hues.cs](file://ClassicAssist.Shared/UO/Data/Hues.cs)
|
||||
|
||||
## Core Components
|
||||
- HueEntryControl: Provides a text box for numeric hue input, a color preview area, and optional integration with a hue picker dialog. Exposes properties for binding, including a validated hue value and validity state.
|
||||
- HuePickerWindow: A modal or non-modal window offering a visual palette for selecting hues; upon selection, it updates the bound hue value in the control.
|
||||
- DressTabControl and AutolootTabControl: Consume HueEntryControl to allow users to set item or rule colors.
|
||||
- HueEntryToRectanglesValueConverter: Converts hue values into visual rectangles for preview rendering in Avalonia contexts.
|
||||
- Hues: Shared data describing valid UO hues and related metadata.
|
||||
|
||||
Key responsibilities:
|
||||
- Input handling and validation against UO hue constraints
|
||||
- Real-time preview updates
|
||||
- Integration with external hue picker
|
||||
- Binding support for consumer components
|
||||
|
||||
**Section sources**
|
||||
- [HueEntryControl.xaml.cs](file://ClassicAssist/UI/Controls/HueEntryControl.xaml.cs)
|
||||
- [HuePickerWindow.xaml.cs](file://ClassicAssist/UI/Views/HuePickerWindow.xaml.cs)
|
||||
- [DressTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/DressTabControl.xaml.cs)
|
||||
- [AutolootTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/AutolootTabControl.xaml.cs)
|
||||
- [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs)
|
||||
- [Hues.cs](file://ClassicAssist.Shared/UO/Data/Hues.cs)
|
||||
|
||||
## Architecture Overview
|
||||
The component follows a simple MVVM-friendly pattern:
|
||||
- HueEntryControl exposes bindable properties for HueValue and IsValid.
|
||||
- On user input changes, the control validates the value and updates IsValid and the preview.
|
||||
- When the hue picker is invoked, it returns a selected hue which the control binds back to HueValue.
|
||||
- Consumers (Dress and Autoloot tabs) bind to HueValue to apply colors to items or rules.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User as "User"
|
||||
participant HEC as "HueEntryControl"
|
||||
participant HPW as "HuePickerWindow"
|
||||
participant Consumer as "Dress/Autoloot Tab"
|
||||
User->>HEC : "Type numeric hue"
|
||||
HEC->>HEC : "Validate against UO constraints"
|
||||
HEC-->>Consumer : "Update HueValue and IsValid"
|
||||
HEC-->>User : "Real-time color preview"
|
||||
User->>HEC : "Open Hue Picker"
|
||||
HEC->>HPW : "Show picker"
|
||||
HPW-->>HEC : "Return selected hue"
|
||||
HEC->>HEC : "Set HueValue and re-validate"
|
||||
HEC-->>Consumer : "Update HueValue and IsValid"
|
||||
HEC-->>User : "Real-time color preview"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [HueEntryControl.xaml.cs](file://ClassicAssist/UI/Controls/HueEntryControl.xaml.cs)
|
||||
- [HuePickerWindow.xaml.cs](file://ClassicAssist/UI/Views/HuePickerWindow.xaml.cs)
|
||||
- [DressTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/DressTabControl.xaml.cs)
|
||||
- [AutolootTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/AutolootTabControl.xaml.cs)
|
||||
|
||||
## Detailed Component Analysis
|
||||
|
||||
### HueEntryControl Properties and Behavior
|
||||
- HueValue: The current hue value intended for use. Updated on input changes and after picker selection.
|
||||
- IsValid: Indicates whether the current HueValue satisfies UO constraints. Consumers should check this before applying colors.
|
||||
- Color Preview: Visual feedback showing the effective color corresponding to HueValue.
|
||||
- Validation Rules: Enforces UO-specific hue range and any additional constraints defined in shared data.
|
||||
|
||||
Interaction model:
|
||||
- Numeric input: Users type a number; the control validates and updates preview immediately.
|
||||
- Hue picker: Users can open a picker window to select a hue visually; the chosen hue is written back to HueValue.
|
||||
- Real-time updates: Both input paths trigger validation and preview refresh.
|
||||
|
||||
Styling and accessibility:
|
||||
- Preview area can be styled to ensure sufficient contrast.
|
||||
- For color-blind users, consider adding textual indicators (e.g., displaying the numeric hue next to the preview) and high-contrast themes.
|
||||
|
||||
Integration points:
|
||||
- Consumers bind to HueValue and IsValid to conditionally enable actions or display errors.
|
||||
- Dress and Autoloot tabs demonstrate typical usage patterns.
|
||||
|
||||
**Section sources**
|
||||
- [HueEntryControl.xaml.cs](file://ClassicAssist/UI/Controls/HueEntryControl.xaml.cs)
|
||||
- [HueEntryControl.xaml](file://ClassicAssist/UI/Controls/HueEntryControl.xaml)
|
||||
- [Hues.cs](file://ClassicAssist.Shared/UO/Data/Hues.cs)
|
||||
|
||||
#### Class Diagram
|
||||
```mermaid
|
||||
classDiagram
|
||||
class HueEntryControl {
|
||||
+int HueValue
|
||||
+bool IsValid
|
||||
+void OpenHuePicker()
|
||||
-void ValidateAndPreview()
|
||||
}
|
||||
class HuePickerWindow {
|
||||
+void Show()
|
||||
+int SelectedHue
|
||||
}
|
||||
class DressTabControl {
|
||||
+bind HueValue
|
||||
+bind IsValid
|
||||
}
|
||||
class AutolootTabControl {
|
||||
+bind HueValue
|
||||
+bind IsValid
|
||||
}
|
||||
class Hues {
|
||||
<<data>>
|
||||
}
|
||||
HueEntryControl --> HuePickerWindow : "opens"
|
||||
DressTabControl --> HueEntryControl : "consumes"
|
||||
AutolootTabControl --> HueEntryControl : "consumes"
|
||||
HueEntryControl --> Hues : "validates against"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [HueEntryControl.xaml.cs](file://ClassicAssist/UI/Controls/HueEntryControl.xaml.cs)
|
||||
- [HuePickerWindow.xaml.cs](file://ClassicAssist/UI/Views/HuePickerWindow.xaml.cs)
|
||||
- [DressTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/DressTabControl.xaml.cs)
|
||||
- [AutolootTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/AutolootTabControl.xaml.cs)
|
||||
- [Hues.cs](file://ClassicAssist.Shared/UO/Data/Hues.cs)
|
||||
|
||||
### HuePickerWindow
|
||||
- Purpose: Provide a visual interface for selecting hues.
|
||||
- Behavior: Displays available hues; when a user selects one, the window communicates the chosen hue back to the caller (typically HueEntryControl).
|
||||
- Integration: Used by HueEntryControl to enhance usability beyond numeric entry.
|
||||
|
||||
**Section sources**
|
||||
- [HuePickerWindow.xaml.cs](file://ClassicAssist/UI/Views/HuePickerWindow.xaml.cs)
|
||||
- [HuePickerWindow.xaml](file://ClassicAssist/UI/Views/HuePickerWindow.xaml)
|
||||
|
||||
### DressTabControl Usage Example
|
||||
- Demonstrates binding HueEntryControl to a dress rule’s color property.
|
||||
- Uses IsValid to prevent invalid colors from being applied.
|
||||
- Shows how to update the dress list preview when HueValue changes.
|
||||
|
||||
**Section sources**
|
||||
- [DressTabControl.xaml](file://ClassicAssist/UI/Views/Agents/DressTabControl.xaml)
|
||||
- [DressTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/DressTabControl.xaml.cs)
|
||||
|
||||
### AutolootTabControl Usage Example
|
||||
- Demonstrates binding HueEntryControl to autoloot rule conditions or item filters.
|
||||
- Validates hue inputs before enabling autoloot actions.
|
||||
- Integrates with existing autoloot configuration workflows.
|
||||
|
||||
**Section sources**
|
||||
- [AutolootTabControl.xaml](file://ClassicAssist/UI/Views/Agents/AutolootTabControl.xaml)
|
||||
- [AutolootTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/AutolootTabControl.xaml.cs)
|
||||
|
||||
### Avalonia Converter for Previews
|
||||
- HueEntryToRectanglesValueConverter converts hue values into rectangle visuals for preview rendering in Avalonia-based views.
|
||||
- Useful when building cross-platform UIs that need consistent hue previews.
|
||||
|
||||
**Section sources**
|
||||
- [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs)
|
||||
|
||||
## Dependency Analysis
|
||||
- HueEntryControl depends on:
|
||||
- UO Hues data for validation constraints
|
||||
- HuePickerWindow for visual selection
|
||||
- Consumers (Dress/Autoloot tabs) for binding and application of colors
|
||||
- Avalonia converter is decoupled but can be used alongside HueEntryControl for preview rendering in Avalonia contexts.
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
HEC["HueEntryControl"] --> HUES["Hues"]
|
||||
HEC --> HPW["HuePickerWindow"]
|
||||
DTC["DressTabControl"] --> HEC
|
||||
ATC["AutolootTabControl"] --> HEC
|
||||
CONV["HueEntryToRectanglesValueConverter"] -.-> HEC
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [HueEntryControl.xaml.cs](file://ClassicAssist/UI/Controls/HueEntryControl.xaml.cs)
|
||||
- [HuePickerWindow.xaml.cs](file://ClassicAssist/UI/Views/HuePickerWindow.xaml.cs)
|
||||
- [DressTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/DressTabControl.xaml.cs)
|
||||
- [AutolootTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/AutolootTabControl.xaml.cs)
|
||||
- [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs)
|
||||
- [Hues.cs](file://ClassicAssist.Shared/UO/Data/Hues.cs)
|
||||
|
||||
**Section sources**
|
||||
- [HueEntryControl.xaml.cs](file://ClassicAssist/UI/Controls/HueEntryControl.xaml.cs)
|
||||
- [HuePickerWindow.xaml.cs](file://ClassicAssist/UI/Views/HuePickerWindow.xaml.cs)
|
||||
- [DressTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/DressTabControl.xaml.cs)
|
||||
- [AutolootTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/AutolootTabControl.xaml.cs)
|
||||
- [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs)
|
||||
- [Hues.cs](file://ClassicAssist.Shared/UO/Data/Hues.cs)
|
||||
|
||||
## Performance Considerations
|
||||
- Avoid excessive recomputation during rapid typing by debouncing validation if needed.
|
||||
- Keep preview updates lightweight; prefer direct brush updates rather than full layout passes.
|
||||
- Cache hue-to-color mappings where appropriate to reduce conversion overhead.
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
|
||||
## Troubleshooting Guide
|
||||
Common issues and resolutions:
|
||||
- Invalid hue value: Ensure IsValid is checked before applying colors. Review UO hue constraints in shared data.
|
||||
- Preview not updating: Confirm bindings are two-way and that HueValue changes raise notifications.
|
||||
- Picker not returning value: Verify HuePickerWindow communication path and that the selected hue is assigned back to HueValue.
|
||||
- Accessibility concerns: Add textual hue labels and ensure sufficient contrast for color-blind users.
|
||||
|
||||
**Section sources**
|
||||
- [HueEntryControl.xaml.cs](file://ClassicAssist/UI/Controls/HueEntryControl.xaml.cs)
|
||||
- [HuePickerWindow.xaml.cs](file://ClassicAssist/UI/Views/HuePickerWindow.xaml.cs)
|
||||
- [Hues.cs](file://ClassicAssist.Shared/UO/Data/Hues.cs)
|
||||
|
||||
## Conclusion
|
||||
HueEntryControl offers a robust, user-friendly way to manage UO hue values with immediate visual feedback and strict validation. Its integration with HuePickerWindow enhances usability, while consumers like DressTabControl and AutolootTabControl demonstrate practical applications. By following the provided guidelines and leveraging the documented properties and behaviors, developers can implement reliable color selection experiences tailored to Ultima Online’s color system.
|
||||
|
||||
[No sources needed since this section summarizes without analyzing specific files]
|
||||
|
||||
## Appendices
|
||||
|
||||
### Example Scenarios
|
||||
- Binding to a game object’s color: Bind HueValue to the object’s color property and use IsValid to guard updates.
|
||||
- Validating UO-specific hue values: Use the shared Hues data to enforce constraints and provide clear error feedback.
|
||||
- Integrating with dress manager: Use HueEntryControl in dress rules to let users pick item colors safely.
|
||||
- Integrating with autoloot systems: Apply hue validation to autoloot conditions to avoid invalid configurations.
|
||||
|
||||
[No sources needed since this section provides conceptual examples]
|
||||
+356
@@ -0,0 +1,356 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user