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

# 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)