Beyhan Oğur
29 KiB
29 KiB
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
- Introduction
- Project Structure
- Core Components
- Architecture Overview
- Detailed Component Analysis
- Dependency Analysis
- Performance Considerations
- Troubleshooting Guide
- Conclusion
- 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.
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
- MainWindow.axaml
- AgentsTabControl.axaml
- DialogWindow.axaml
- HexDumpControl.axaml
- EditTextBlock.axaml
- TextBoxKey.axaml
- GroupBox.cs
- GroupBox.Theme.xaml
- AvalonEditBehaviour.cs
- WindowResizeBehaviour.cs
- InverseBooleanValueConverter.cs
- JoinArrayValueConverter.cs
- StringToResourceConverter.cs
Section sources
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
- AgentsTabControl.axaml
- HotkeysTabControl.axaml
- MacrosTabControl.axaml
- OptionsTabControl.axaml
- SkillsTabControl.axaml
- GeneralControl.axaml
- AboutControl.axaml
- HexDumpControl.axaml
- EditTextBlock.axaml
- TextBoxKey.axaml
- GroupBox.cs
- GroupBox.Theme.xaml
- AvalonEditBehaviour.cs
- WindowResizeBehaviour.cs
- InverseBooleanValueConverter.cs
- JoinArrayValueConverter.cs
- 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.
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
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.
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
Section sources
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.
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
- AgentsTabControl.axaml
- HotkeysTabControl.axaml
- MacrosTabControl.axaml
- OptionsTabControl.axaml
- SkillsTabControl.axaml
- GeneralControl.axaml
- AboutControl.axaml
Section sources
- AgentsTabControl.axaml
- HotkeysTabControl.axaml
- MacrosTabControl.axaml
- OptionsTabControl.axaml
- SkillsTabControl.axaml
- GeneralControl.axaml
- 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.
classDiagram
class HexDumpControl {
+Data
+SelectedRange
+AutoScroll
+CopySelection()
}
class ListBoxAutoScrollBehaviour {
+Attach(control)
+OnCollectionChanged()
}
HexDumpControl --> ListBoxAutoScrollBehaviour : "uses"
Diagram sources
Section sources
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.
classDiagram
class EditTextBlock {
+Text
+IsEditable
+HighlightMode
}
class AvalonEditBehaviour {
+Attach(editor)
+SetLanguage(mode)
}
EditTextBlock --> AvalonEditBehaviour : "enhances"
Diagram sources
Section sources
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.
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
Section sources
GroupBox
- Purpose: Themed container for grouping related controls.
- Customization:
- Style defined in theme dictionary.
- Extensible header and content regions.
classDiagram
class GroupBox {
+Header
+Content
}
class GroupBoxTheme {
+Styles
+Templates
}
GroupBox --> GroupBoxTheme : "styled by"
Diagram sources
Section sources
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.
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
Section sources
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
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.
flowchart TD
Resize["Window resized"] --> Measure["Measure available space"]
Measure --> Adjust["Adjust column widths and scrollbars"]
Adjust --> Update["Rebind and re-render"]
Diagram sources
Section sources
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.
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
- JoinArrayValueConverter.cs
- StringToResourceConverter.cs
- CloseOnClickBehaviour.cs
- ComboBoxBehavior.cs
- WindowInitializedBehaviour.cs
Section sources
- InverseBooleanValueConverter.cs
- JoinArrayValueConverter.cs
- StringToResourceConverter.cs
- CloseOnClickBehaviour.cs
- ComboBoxBehavior.cs
- 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.
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
Section sources
Specialized Windows
- DebugWindow: Diagnostic tools and live data inspection.
- HuePickerWindow: Color selection utility.
- NewProfileWindow: Profile creation workflow.
- ObjectInspectorWindow: Inspect runtime objects and properties.
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
Section sources
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.
graph LR
Views["Views"] --> VMs["ViewModels"]
Views --> Controls["Custom Controls"]
Controls --> Behaviours["Behaviours"]
Controls --> Converters["Converters"]
Views --> Resources["Themes & Icons"]
Diagram sources
- MainWindow.axaml
- AgentsTabControl.axaml
- HexDumpControl.axaml
- AvalonEditBehaviour.cs
- InverseBooleanValueConverter.cs
- Icons.xaml
Section sources
- MainWindow.axaml
- AgentsTabControl.axaml
- HexDumpControl.axaml
- AvalonEditBehaviour.cs
- InverseBooleanValueConverter.cs
- 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
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]