beyhan/ClassicAssist.Avalonia
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d5f52cc3d332d8cee0bb5e377018d7c53b6f0543
ClassicAssist.Avalonia/.qoder/repowiki/en/content/User Interface Guide/Custom Controls Library/Custom Controls Library.md
T
Beyhan Oğur d5f52cc3d3 first commit
2026-09-03 04:45:36 +03:00

413 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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]
Reference in New Issue View Git Blame Copy Permalink