# User Interface Guide **Referenced Files in This Document** - [App.axaml](file://ClassicAssist.Avalonia/App.axaml) - [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs) - [MainWindow.axaml](file://ClassicAssist.Avalonia/Views/MainWindow.axaml) - [MainWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/MainWindow.axaml.cs) - [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) - [GroupBox.Theme.xaml](file://ClassicAssist.Avalonia/Controls/GroupBox.Theme.xaml) - [GroupBox.cs](file://ClassicAssist.Avalonia/Controls/GroupBox.cs) - [Icons.xaml](file://ClassicAssist.Avalonia/Assets/Icons.xaml) - [AvalonEditBehaviour.cs](file://ClassicAssist.Avalonia/Misc/AvalonEditBehaviour.cs) - [WindowResizeBehaviour.cs](file://ClassicAssist.Avalonia/Misc/WindowResizeBehaviour.cs) - [DialogWindow.axaml](file://ClassicAssist.Avalonia/Views/DialogWindow.axaml) - [DialogWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/DialogWindow.axaml.cs) - [DialogWindowViewModel.cs](file://ClassicAssist.Avalonia/ViewModels/DialogWindowViewModel.cs) - [AgentsTabControl.axaml](file://ClassicAssist.Avalonia/Views/AgentsTabControl.axaml) - [AgentsTabControl.axaml.cs](file://ClassicAssist.Avalonia/Views/AgentsTabControl.axaml.cs) - [HotkeysTabControl.axaml](file://ClassicAssist.Avalonia/Views/HotkeysTabControl.axaml) - [HotkeysTabControl.axaml.cs](file://ClassicAssist.Avalonia/Views/HotkeysTabControl.axaml.cs) - [MacrosTabControl.axaml](file://ClassicAssist.Avalonia/Views/MacrosTabControl.axaml) - [MacrosTabControl.axaml.cs](file://ClassicAssist.Avalonia/Views/MacrosTabControl.axaml.cs) - [OptionsTabControl.axaml](file://ClassicAssist.Avalonia/Views/OptionsTabControl.axaml) - [OptionsTabControl.axaml.cs](file://ClassicAssist.Avalonia/Views/OptionsTabControl.axaml.cs) - [SkillsTabControl.axaml](file://ClassicAssist.Avalonia/Views/SkillsTabControl.axaml) - [SkillsTabControl.axaml.cs](file://ClassicAssist.Avalonia/Views/SkillsTabControl.axaml.cs) - [GeneralControl.axaml](file://ClassicAssist.Avalonia/Views/GeneralControl.axaml) - [GeneralControl.axaml.cs](file://ClassicAssist.Avalonia/Views/GeneralControl.axaml.cs) - [AboutControl.axaml](file://ClassicAssist.Avalonia/Views/AboutControl.axaml) - [AboutControl.axaml.cs](file://ClassicAssist.Avalonia/Views/AboutControl.axaml.cs) - [DebugWindow.axaml](file://ClassicAssist.Avalonia/Views/DebugWindow.axaml) - [DebugWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/DebugWindow.axaml.cs) - [HuePickerWindow.axaml](file://ClassicAssist.Avalonia/Views/HuePickerWindow.axaml) - [HuePickerWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/HuePickerWindow.axaml.cs) - [NewProfileWindow.axaml](file://ClassicAssist.Avalonia/Views/NewProfileWindow.axaml) - [NewProfileWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/NewProfileWindow.axaml.cs) - [ObjectInspectorWindow.axaml](file://ClassicAssist.Avalonia/Views/ObjectInspectorWindow.axaml) - [ObjectInspectorWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/ObjectInspectorWindow.axaml.cs) - [AutolootTabControl.axaml](file://ClassicAssist.Avalonia/Views/Agents/AutolootTabControl.axaml) - [CountersTabControl.axaml](file://ClassicAssist.Avalonia/Views/Agents/CountersTabControl.axaml) - [DressTabControl.axaml](file://ClassicAssist.Avalonia/Views/Agents/DressTabControl.axaml) - [FriendsTabControl.axaml](file://ClassicAssist.Avalonia/Views/Agents/FriendsTabControl.axaml) - [OrganizerTabControl.axaml](file://ClassicAssist.Avalonia/Views/Agents/OrganizerTabControl.axaml) - [ScavengerTabControl.axaml](file://ClassicAssist.Avalonia/Views/Agents/ScavengerTabControl.axaml) - [VendorBuyTabControl.axaml](file://ClassicAssist.Avalonia/Views/Agents/VendorBuyTabControl.axaml) - [VendorSellTabControl.axaml](file://ClassicAssist.Avalonia/Views/Agents/VendorSellTabControl.axaml) - [InverseBooleanValueConverter.cs](file://ClassicAssist.Avalonia/Misc/InverseBooleanValueConverter.cs) - [JoinArrayValueConverter.cs](file://ClassicAssist.Avalonia/Misc/JoinArrayValueConverter.cs) - [StringToResourceConverter.cs](file://ClassicAssist.Avalonia/Misc/StringToResourceConverter.cs) - [ListBoxAutoScrollBehaviour.cs](file://ClassicAssist.Avalonia/Misc/ListBoxAutoScrollBehaviour.cs) - [CloseOnClickBehaviour.cs](file://ClassicAssist.Avalonia/Misc/CloseOnClickBehaviour.cs) - [ComboBoxBehavior.cs](file://ClassicAssist.Avalonia/Misc/ComboBoxBehavior.cs) - [WindowInitializedBehaviour.cs](file://ClassicAssist.Avalonia/Misc/WindowInitializedBehaviour.cs) - [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs) - [AvaloniaUIInvoker.cs](file://ClassicAssist.Avalonia/AvaloniaUIInvoker.cs) ## Table of Contents 1. Introduction 2. Project Structure 3. Core Components 4. Architecture Overview 5. Detailed Component Analysis 6. Dependency Analysis 7. Performance Considerations 8. Troubleshooting Guide 9. Conclusion 10. Appendices ## Introduction This guide documents the Avalonia-based user interface for ClassicAssist.Avalonia. It explains the main window layout, tabbed navigation, control hierarchy (including HexDumpControl, EditTextBlock, and TextBoxKey), theming and customization, keyboard shortcuts and accessibility, responsive design considerations, cross-platform UI differences, MVVM binding patterns, and how to extend or customize existing UI elements. ## Project Structure The Avalonia UI is organized into Views, Controls, ViewModels, and shared resources: - Views: Top-level windows and reusable page-like controls (e.g., MainWindow, DialogWindow, tab controls). - Controls: Custom reusable components (e.g., HexDumpControl, EditTextBlock, TextBoxKey, GroupBox). - ViewModels: Presentation logic bound to views via data binding. - Resources: Theme definitions, icons, and converters. ```mermaid graph TB subgraph "Avalonia App" App["App.axaml"] MainWin["Views/MainWindow.axaml"] Tabs["Views/*TabControl.axaml"] Dialog["Views/DialogWindow.axaml"] end subgraph "Custom Controls" Hex["Controls/HexDumpControl.axaml"] EditTxt["Controls/EditTextBlock.axaml"] TxtKey["Controls/TextBoxKey.axaml"] Grp["Controls/GroupBox.cs + .Theme.xaml"] end subgraph "Behaviours & Converters" Beh["Misc/*Behaviour.cs"] Conv["Misc/*ValueConverter.cs"] end App --> MainWin MainWin --> Tabs MainWin --> Dialog Tabs --> Hex Tabs --> EditTxt Tabs --> TxtKey Tabs --> Grp Tabs --> Beh Tabs --> Conv ``` **Diagram sources** - [App.axaml](file://ClassicAssist.Avalonia/App.axaml) - [MainWindow.axaml](file://ClassicAssist.Avalonia/Views/MainWindow.axaml) - [AgentsTabControl.axaml](file://ClassicAssist.Avalonia/Views/AgentsTabControl.axaml) - [DialogWindow.axaml](file://ClassicAssist.Avalonia/Views/DialogWindow.axaml) - [HexDumpControl.axaml](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml) - [EditTextBlock.axaml](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml) - [TextBoxKey.axaml](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml) - [GroupBox.cs](file://ClassicAssist.Avalonia/Controls/GroupBox.cs) - [GroupBox.Theme.xaml](file://ClassicAssist.Avalonia/Controls/GroupBox.Theme.xaml) - [AvalonEditBehaviour.cs](file://ClassicAssist.Avalonia/Misc/AvalonEditBehaviour.cs) - [WindowResizeBehaviour.cs](file://ClassicAssist.Avalonia/Misc/WindowResizeBehaviour.cs) - [InverseBooleanValueConverter.cs](file://ClassicAssist.Avalonia/Misc/InverseBooleanValueConverter.cs) - [JoinArrayValueConverter.cs](file://ClassicAssist.Avalonia/Misc/JoinArrayValueConverter.cs) - [StringToResourceConverter.cs](file://ClassicAssist.Avalonia/Misc/StringToResourceConverter.cs) **Section sources** - [App.axaml](file://ClassicAssist.Avalonia/App.axaml) - [MainWindow.axaml](file://ClassicAssist.Avalonia/Views/MainWindow.axaml) - [AgentsTabControl.axaml](file://ClassicAssist.Avalonia/Views/AgentsTabControl.axaml) - [DialogWindow.axaml](file://ClassicAssist.Avalonia/Views/DialogWindow.axaml) ## Core Components - Main Window: Hosts a tabbed interface and provides global commands and status. - Tab Controls: Feature-specific tabs (Agents, Hotkeys, Macros, Options, Skills, General, About). - Custom Controls: - HexDumpControl: Binary/hex viewer with scrolling and selection. - EditTextBlock: Read-only text block with optional editing affordances. - TextBoxKey: Key capture input for hotkey bindings. - GroupBox: Themed container for grouping related controls. - Behaviours: Reusable interactions attached to controls (auto-scroll, resize, combo box behavior). - Converters: Value conversions used in bindings (boolean inversion, string joining, resource lookup). **Section sources** - [MainWindow.axaml](file://ClassicAssist.Avalonia/Views/MainWindow.axaml) - [AgentsTabControl.axaml](file://ClassicAssist.Avalonia/Views/AgentsTabControl.axaml) - [HotkeysTabControl.axaml](file://ClassicAssist.Avalonia/Views/HotkeysTabControl.axaml) - [MacrosTabControl.axaml](file://ClassicAssist.Avalonia/Views/MacrosTabControl.axaml) - [OptionsTabControl.axaml](file://ClassicAssist.Avalonia/Views/OptionsTabControl.axaml) - [SkillsTabControl.axaml](file://ClassicAssist.Avalonia/Views/SkillsTabControl.axaml) - [GeneralControl.axaml](file://ClassicAssist.Avalonia/Views/GeneralControl.axaml) - [AboutControl.axaml](file://ClassicAssist.Avalonia/Views/AboutControl.axaml) - [HexDumpControl.axaml](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml) - [EditTextBlock.axaml](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml) - [TextBoxKey.axaml](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml) - [GroupBox.cs](file://ClassicAssist.Avalonia/Controls/GroupBox.cs) - [GroupBox.Theme.xaml](file://ClassicAssist.Avalonia/Controls/GroupBox.Theme.xaml) - [AvalonEditBehaviour.cs](file://ClassicAssist.Avalonia/Misc/AvalonEditBehaviour.cs) - [WindowResizeBehaviour.cs](file://ClassicAssist.Avalonia/Misc/WindowResizeBehaviour.cs) - [InverseBooleanValueConverter.cs](file://ClassicAssist.Avalonia/Misc/InverseBooleanValueConverter.cs) - [JoinArrayValueConverter.cs](file://ClassicAssist.Avalonia/Misc/JoinArrayValueConverter.cs) - [StringToResourceConverter.cs](file://ClassicAssist.Avalonia/Misc/StringToResourceConverter.cs) ## Architecture Overview The UI follows MVVM: - Views (AXAML) bind to ViewModels through DataContext. - Behaviours encapsulate view-side interactions without code-behind logic. - Converters adapt model values for display. - Theming and icons are centralized in resource dictionaries. ```mermaid sequenceDiagram participant User as "User" participant Win as "MainWindow.axaml" participant Tab as "AgentsTabControl.axaml" participant VM as "AgentsTabControl ViewModel" participant Ctrl as "HexDumpControl.axaml" participant Beh as "ListBoxAutoScrollBehaviour.cs" User->>Win : Open app Win->>Tab : Load selected tab Tab->>VM : Bind properties and collections Tab->>Ctrl : Render hex dump Ctrl->>Beh : Auto-scroll on update VM-->>Tab : Update UI via INotifyPropertyChanged ``` **Diagram sources** - [MainWindow.axaml](file://ClassicAssist.Avalonia/Views/MainWindow.axaml) - [AgentsTabControl.axaml](file://ClassicAssist.Avalonia/Views/AgentsTabControl.axaml) - [HexDumpControl.axaml](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml) - [ListBoxAutoScrollBehaviour.cs](file://ClassicAssist.Avalonia/Misc/ListBoxAutoScrollBehaviour.cs) ## Detailed Component Analysis ### Main Window Layout and Navigation - The main window hosts a tabbed interface that switches between feature areas such as Agents, Hotkeys, Macros, Options, Skills, General, and About. - Navigation is driven by selecting a tab; each tab loads its corresponding view and binds to a dedicated ViewModel. - Global actions (e.g., opening dialogs or debug windows) are exposed from the main window’s ViewModel and invoked via commands. ```mermaid flowchart TD Start(["App Launch"]) --> Init["Initialize App.axaml"] Init --> ShowMain["Show MainWindow.axaml"] ShowMain --> SelectTab{"User selects tab?"} SelectTab --> |Yes| LoadTab["Load selected Tab Control"] LoadTab --> BindVM["Bind to Tab ViewModel"] BindVM --> Render["Render controls and lists"] SelectTab --> |No| Idle["Keep current tab"] Render --> End(["Ready"]) Idle --> End ``` **Diagram sources** - [App.axaml](file://ClassicAssist.Avalonia/App.axaml) - [MainWindow.axaml](file://ClassicAssist.Avalonia/Views/MainWindow.axaml) - [AgentsTabControl.axaml](file://ClassicAssist.Avalonia/Views/AgentsTabControl.axaml) **Section sources** - [MainWindow.axaml](file://ClassicAssist.Avalonia/Views/MainWindow.axaml) - [AgentsTabControl.axaml](file://ClassicAssist.Avalonia/Views/AgentsTabControl.axaml) ### Tabbed Interface Structure - Agents: Sub-tabs for Autoloot, Counters, Dress, Friends, Organizer, Scavenger, Vendor Buy, Vendor Sell. - Hotkeys: Configure key bindings and commands. - Macros: Manage macro entries and execution. - Options: Application-wide settings. - Skills: Skill management and locks. - General and About: Informational pages. ```mermaid classDiagram class MainWindow { +Tabs +Commands } class AgentsTabControl class HotkeysTabControl class MacrosTabControl class OptionsTabControl class SkillsTabControl class GeneralControl class AboutControl MainWindow --> AgentsTabControl : "hosts" MainWindow --> HotkeysTabControl : "hosts" MainWindow --> MacrosTabControl : "hosts" MainWindow --> OptionsTabControl : "hosts" MainWindow --> SkillsTabControl : "hosts" MainWindow --> GeneralControl : "hosts" MainWindow --> AboutControl : "hosts" ``` **Diagram sources** - [MainWindow.axaml](file://ClassicAssist.Avalonia/Views/MainWindow.axaml) - [AgentsTabControl.axaml](file://ClassicAssist.Avalonia/Views/AgentsTabControl.axaml) - [HotkeysTabControl.axaml](file://ClassicAssist.Avalonia/Views/HotkeysTabControl.axaml) - [MacrosTabControl.axaml](file://ClassicAssist.Avalonia/Views/MacrosTabControl.axaml) - [OptionsTabControl.axaml](file://ClassicAssist.Avalonia/Views/OptionsTabControl.axaml) - [SkillsTabControl.axaml](file://ClassicAssist.Avalonia/Views/SkillsTabControl.axaml) - [GeneralControl.axaml](file://ClassicAssist.Avalonia/Views/GeneralControl.axaml) - [AboutControl.axaml](file://ClassicAssist.Avalonia/Views/AboutControl.axaml) **Section sources** - [AgentsTabControl.axaml](file://ClassicAssist.Avalonia/Views/AgentsTabControl.axaml) - [HotkeysTabControl.axaml](file://ClassicAssist.Avalonia/Views/HotkeysTabControl.axaml) - [MacrosTabControl.axaml](file://ClassicAssist.Avalonia/Views/MacrosTabControl.axaml) - [OptionsTabControl.axaml](file://ClassicAssist.Avalonia/Views/OptionsTabControl.axaml) - [SkillsTabControl.axaml](file://ClassicAssist.Avalonia/Views/SkillsTabControl.axaml) - [GeneralControl.axaml](file://ClassicAssist.Avalonia/Views/GeneralControl.axaml) - [AboutControl.axaml](file://ClassicAssist.Avalonia/Views/AboutControl.axaml) ### Control Hierarchy and Custom Controls #### HexDumpControl - Purpose: Display binary data in hexadecimal and ASCII formats with efficient scrolling. - Key behaviors: - Virtualized rendering for large datasets. - Selection and copy support. - Optional auto-scroll when new data arrives. - Integration points: - Used within agent-related tabs and debug views. - Enhanced by behaviours like auto-scroll. ```mermaid classDiagram class HexDumpControl { +Data +SelectedRange +AutoScroll +CopySelection() } class ListBoxAutoScrollBehaviour { +Attach(control) +OnCollectionChanged() } HexDumpControl --> ListBoxAutoScrollBehaviour : "uses" ``` **Diagram sources** - [HexDumpControl.axaml](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml) - [HexDumpControl.axaml.cs](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs) - [ListBoxAutoScrollBehaviour.cs](file://ClassicAssist.Avalonia/Misc/ListBoxAutoScrollBehaviour.cs) **Section sources** - [HexDumpControl.axaml](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml) - [HexDumpControl.axaml.cs](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs) - [ListBoxAutoScrollBehaviour.cs](file://ClassicAssist.Avalonia/Misc/ListBoxAutoScrollBehaviour.cs) #### EditTextBlock - Purpose: Rich read-only text display with optional editing affordances. - Features: - Syntax highlighting integration via AvalonEdit behaviour. - Copy-to-clipboard support. - Scrollable content with performance optimizations. - Typical usage: Log viewers, property inspectors, and macro output. ```mermaid classDiagram class EditTextBlock { +Text +IsEditable +HighlightMode } class AvalonEditBehaviour { +Attach(editor) +SetLanguage(mode) } EditTextBlock --> AvalonEditBehaviour : "enhances" ``` **Diagram sources** - [EditTextBlock.axaml](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml) - [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs) - [AvalonEditBehaviour.cs](file://ClassicAssist.Avalonia/Misc/AvalonEditBehaviour.cs) **Section sources** - [EditTextBlock.axaml](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml) - [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs) - [AvalonEditBehaviour.cs](file://ClassicAssist.Avalonia/Misc/AvalonEditBehaviour.cs) #### TextBoxKey - Purpose: Capture and display key combinations for hotkey configuration. - Behavior: - Listens to key events and formats them into readable strings. - Supports modifier keys and special keys. - Validates and prevents duplicate bindings at the UI layer. - Integration: - Used in Hotkeys tab and other configuration surfaces. ```mermaid flowchart TD Enter(["KeyDown Event"]) --> Detect["Detect modifiers and key"] Detect --> Format["Format key string"] Format --> Validate{"Duplicate binding?"} Validate --> |Yes| Warn["Show warning"] Validate --> |No| Bind["Update bound value"] Warn --> Exit(["Done"]) Bind --> Exit ``` **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) #### GroupBox - Purpose: Themed container for grouping related controls. - Customization: - Style defined in theme dictionary. - Extensible header and content regions. ```mermaid classDiagram class GroupBox { +Header +Content } class GroupBoxTheme { +Styles +Templates } GroupBox --> GroupBoxTheme : "styled by" ``` **Diagram sources** - [GroupBox.cs](file://ClassicAssist.Avalonia/Controls/GroupBox.cs) - [GroupBox.Theme.xaml](file://ClassicAssist.Avalonia/Controls/GroupBox.Theme.xaml) **Section sources** - [GroupBox.cs](file://ClassicAssist.Avalonia/Controls/GroupBox.cs) - [GroupBox.Theme.xaml](file://ClassicAssist.Avalonia/Controls/GroupBox.Theme.xaml) ### Theming System - Centralized resources include colors, icons, and styles. - Icons are provided via a resource dictionary for consistent visual language across the app. - Themes can be extended by adding or overriding resource entries. ```mermaid graph TB Res["Resources (Colors, Icons)"] Styles["Styles and Templates"] Controls["Custom Controls"] Views["Views"] Res --> Styles Styles --> Controls Styles --> Views Controls --> Views ``` **Diagram sources** - [Icons.xaml](file://ClassicAssist.Avalonia/Assets/Icons.xaml) - [GroupBox.Theme.xaml](file://ClassicAssist.Avalonia/Controls/GroupBox.Theme.xaml) **Section sources** - [Icons.xaml](file://ClassicAssist.Avalonia/Assets/Icons.xaml) - [GroupBox.Theme.xaml](file://ClassicAssist.Avalonia/Controls/GroupBox.Theme.xaml) ### Keyboard Shortcuts and Accessibility - Hotkey capture is handled by TextBoxKey, which formats and validates key combinations. - Global toggles and commands are typically exposed via menu items or toolbar buttons bound to commands in ViewModels. - Accessibility: - Use standard Avalonia controls to inherit platform accessibility features. - Ensure meaningful labels and tool tips for custom controls. **Section sources** - [TextBoxKey.axaml](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml) - [TextBoxKey.axaml.cs](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml.cs) ### Responsive Design and Cross-Platform Considerations - Responsive behaviors: - WindowResizeBehaviour adapts layouts on size changes. - Auto-scroll behaviours improve usability for long lists and logs. - Platform differences: - Font rendering and icon scaling may vary across platforms; use scalable vector icons where possible. - Input handling (keyboard/mouse) is abstracted by Avalonia but may exhibit minor differences in key mapping. ```mermaid flowchart TD Resize["Window resized"] --> Measure["Measure available space"] Measure --> Adjust["Adjust column widths and scrollbars"] Adjust --> Update["Rebind and re-render"] ``` **Diagram sources** - [WindowResizeBehaviour.cs](file://ClassicAssist.Avalonia/Misc/WindowResizeBehaviour.cs) **Section sources** - [WindowResizeBehaviour.cs](file://ClassicAssist.Avalonia/Misc/WindowResizeBehaviour.cs) - [ListBoxAutoScrollBehaviour.cs](file://ClassicAssist.Avalonia/Misc/ListBoxAutoScrollBehaviour.cs) ### MVVM Binding Patterns and Extensibility - Data binding: - Views bind to properties and collections in ViewModels using Avalonia’s binding syntax. - Converters transform values (e.g., boolean inversion, array joining, resource lookup). - Commands: - Actions are implemented as commands in ViewModels and invoked from XAML. - Extending UI elements: - Create new custom controls by extending existing ones (e.g., HexDumpControl). - Add behaviours for reusable interactions (e.g., auto-scroll, click-to-close). - Provide converters for complex formatting needs. ```mermaid sequenceDiagram participant V as "View (XAML)" participant VM as "ViewModel" participant C as "Converter" participant B as "Behaviour" V->>VM : Bind Property VM-->>V : PropertyChanged V->>C : Convert(value) C-->>V : Converted value V->>B : Attach interaction B-->>V : Handle events ``` **Diagram sources** - [InverseBooleanValueConverter.cs](file://ClassicAssist.Avalonia/Misc/InverseBooleanValueConverter.cs) - [JoinArrayValueConverter.cs](file://ClassicAssist.Avalonia/Misc/JoinArrayValueConverter.cs) - [StringToResourceConverter.cs](file://ClassicAssist.Avalonia/Misc/StringToResourceConverter.cs) - [CloseOnClickBehaviour.cs](file://ClassicAssist.Avalonia/Misc/CloseOnClickBehaviour.cs) - [ComboBoxBehavior.cs](file://ClassicAssist.Avalonia/Misc/ComboBoxBehavior.cs) - [WindowInitializedBehaviour.cs](file://ClassicAssist.Avalonia/Misc/WindowInitializedBehaviour.cs) **Section sources** - [InverseBooleanValueConverter.cs](file://ClassicAssist.Avalonia/Misc/InverseBooleanValueConverter.cs) - [JoinArrayValueConverter.cs](file://ClassicAssist.Avalonia/Misc/JoinArrayValueConverter.cs) - [StringToResourceConverter.cs](file://ClassicAssist.Avalonia/Misc/StringToResourceConverter.cs) - [CloseOnClickBehaviour.cs](file://ClassicAssist.Avalonia/Misc/CloseOnClickBehaviour.cs) - [ComboBoxBehavior.cs](file://ClassicAssist.Avalonia/Misc/ComboBoxBehavior.cs) - [WindowInitializedBehaviour.cs](file://ClassicAssist.Avalonia/Misc/WindowInitializedBehaviour.cs) ### Dialogs and Modal Windows - DialogWindow provides a reusable modal dialog pattern with a ViewModel for state and commands. - Common uses: confirmations, prompts, and small configuration panels. ```mermaid sequenceDiagram participant Caller as "Caller ViewModel" participant Win as "DialogWindow.axaml" participant VM as "DialogWindowViewModel" Caller->>Win : ShowDialog() Win->>VM : Initialize with parameters VM-->>Caller : Result on close ``` **Diagram sources** - [DialogWindow.axaml](file://ClassicAssist.Avalonia/Views/DialogWindow.axaml) - [DialogWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/DialogWindow.axaml.cs) - [DialogWindowViewModel.cs](file://ClassicAssist.Avalonia/ViewModels/DialogWindowViewModel.cs) **Section sources** - [DialogWindow.axaml](file://ClassicAssist.Avalonia/Views/DialogWindow.axaml) - [DialogWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/DialogWindow.axaml.cs) - [DialogWindowViewModel.cs](file://ClassicAssist.Avalonia/ViewModels/DialogWindowViewModel.cs) ### Specialized Windows - DebugWindow: Diagnostic tools and live data inspection. - HuePickerWindow: Color selection utility. - NewProfileWindow: Profile creation workflow. - ObjectInspectorWindow: Inspect runtime objects and properties. ```mermaid graph TB Main["MainWindow"] Debug["DebugWindow.axaml"] Hue["HuePickerWindow.axaml"] NewProf["NewProfileWindow.axaml"] Insp["ObjectInspectorWindow.axaml"] Main --> Debug Main --> Hue Main --> NewProf Main --> Insp ``` **Diagram sources** - [DebugWindow.axaml](file://ClassicAssist.Avalonia/Views/DebugWindow.axaml) - [HuePickerWindow.axaml](file://ClassicAssist.Avalonia/Views/HuePickerWindow.axaml) - [NewProfileWindow.axaml](file://ClassicAssist.Avalonia/Views/NewProfileWindow.axaml) - [ObjectInspectorWindow.axaml](file://ClassicAssist.Avalonia/Views/ObjectInspectorWindow.axaml) **Section sources** - [DebugWindow.axaml](file://ClassicAssist.Avalonia/Views/DebugWindow.axaml) - [HuePickerWindow.axaml](file://ClassicAssist.Avalonia/Views/HuePickerWindow.axaml) - [NewProfileWindow.axaml](file://ClassicAssist.Avalonia/Views/NewProfileWindow.axaml) - [ObjectInspectorWindow.axaml](file://ClassicAssist.Avalonia/Views/ObjectInspectorWindow.axaml) ## Dependency Analysis - UI layer depends on ViewModels for state and commands. - Custom controls depend on behaviours and converters for enhanced functionality. - Theming resources are consumed by controls and views. ```mermaid graph LR Views["Views"] --> VMs["ViewModels"] Views --> Controls["Custom Controls"] Controls --> Behaviours["Behaviours"] Controls --> Converters["Converters"] Views --> Resources["Themes & Icons"] ``` **Diagram sources** - [MainWindow.axaml](file://ClassicAssist.Avalonia/Views/MainWindow.axaml) - [AgentsTabControl.axaml](file://ClassicAssist.Avalonia/Views/AgentsTabControl.axaml) - [HexDumpControl.axaml](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml) - [AvalonEditBehaviour.cs](file://ClassicAssist.Avalonia/Misc/AvalonEditBehaviour.cs) - [InverseBooleanValueConverter.cs](file://ClassicAssist.Avalonia/Misc/InverseBooleanValueConverter.cs) - [Icons.xaml](file://ClassicAssist.Avalonia/Assets/Icons.xaml) **Section sources** - [MainWindow.axaml](file://ClassicAssist.Avalonia/Views/MainWindow.axaml) - [AgentsTabControl.axaml](file://ClassicAssist.Avalonia/Views/AgentsTabControl.axaml) - [HexDumpControl.axaml](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml) - [AvalonEditBehaviour.cs](file://ClassicAssist.Avalonia/Misc/AvalonEditBehaviour.cs) - [InverseBooleanValueConverter.cs](file://ClassicAssist.Avalonia/Misc/InverseBooleanValueConverter.cs) - [Icons.xaml](file://ClassicAssist.Avalonia/Assets/Icons.xaml) ## Performance Considerations - Use virtualized lists and grids for large datasets. - Prefer lazy loading of heavy content in tabs. - Avoid excessive UI updates; batch changes in ViewModels. - Leverage auto-scroll behaviours judiciously to prevent jank during rapid updates. [No sources needed since this section provides general guidance] ## Troubleshooting Guide - UI not updating: - Ensure ViewModels implement property change notifications. - Verify bindings target correct paths and converters are applied. - Hotkey conflicts: - Check TextBoxKey validation and ensure duplicates are prevented. - Slow rendering: - Confirm virtualization is enabled for large lists. - Reduce unnecessary bindings and heavy operations in UI thread. **Section sources** - [TextBoxKey.axaml](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml) - [HexDumpControl.axaml](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml) - [ListBoxAutoScrollBehaviour.cs](file://ClassicAssist.Avalonia/Misc/ListBoxAutoScrollBehaviour.cs) ## Conclusion The ClassicAssist.Avalonia UI leverages a clean MVVM architecture, reusable custom controls, and centralized theming to deliver a consistent, extensible experience across platforms. By following the patterns outlined here—using behaviours for interactions, converters for formatting, and ViewModels for state—you can confidently extend and customize the interface while maintaining performance and accessibility. [No sources needed since this section summarizes without analyzing specific files] ## Appendices ### Screenshots and Visual Guides - Main Window: Shows the primary tabbed interface and global commands. - Agents Tab: Displays sub-tabs for various agents and their configurations. - Hex Dump Viewer: Demonstrates binary data visualization and selection. - Hotkeys Tab: Illustrates key capture and binding management. - Dialog Window: Example of modal interactions and confirmation flows. [No sources needed since this section provides conceptual guidance]