first commit
This commit is contained in:
Beyhan Oğur
@@ -0,0 +1,443 @@
|
||||
# Theming and Styling System
|
||||
|
||||
<cite>
|
||||
**Referenced Files in This Document**
|
||||
- [App.axaml](file://ClassicAssist.Avalonia/App.axaml)
|
||||
- [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
|
||||
- [Program.cs](file://ClassicAssist.Avalonia/Program.cs)
|
||||
- [Icons.xaml](file://ClassicAssist.Avalonia/Assets/Icons.xaml)
|
||||
- [GroupBox.Theme.xaml](file://ClassicAssist.Avalonia/Controls/GroupBox.Theme.xaml)
|
||||
- [StringToResourceConverter.cs](file://ClassicAssist.Avalonia/Misc/StringToResourceConverter.cs)
|
||||
- [InverseBooleanValueConverter.cs](file://ClassicAssist.Avalonia/Misc/InverseBooleanValueConverter.cs)
|
||||
- [JoinArrayValueConverter.cs](file://ClassicAssist.Avalonia/Misc/JoinArrayValueConverter.cs)
|
||||
- [DateTimeToTimeSpanValueConverter.cs](file://ClassicAssist.Avalonia/Misc/DateTimeToTimeSpanValueConverter.cs)
|
||||
- [LockStatusValueConverter.cs](file://ClassicAssist.Avalonia/Misc/LockStatusValueConverter.cs)
|
||||
- [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs)
|
||||
- [PacketEntryBinaryValueConverter.cs](file://ClassicAssist.Avalonia/Misc/PacketEntryBinaryValueConverter.cs)
|
||||
- [PacketEntryTextValueConverter.cs](file://ClassicAssist.Avalonia/Misc/PacketEntryTextValueConverter.cs)
|
||||
- [MainWindow.axaml](file://ClassicAssist.Avalonia/Views/MainWindow.axaml)
|
||||
- [AboutControl.axaml](file://ClassicAssist.Avalonia/Views/AboutControl.axaml)
|
||||
- [DialogWindow.axaml](file://ClassicAssist.Avalonia/Views/DialogWindow.axaml)
|
||||
</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 explains the theming and styling system used by ClassicAssist.Avalonia. It covers resource dictionaries, color schemes, font configurations, visual theme definitions, icon resources, dynamic theme switching, converters for data binding, and guidance for creating custom themes and platform-specific adaptations. The goal is to help you customize colors, fonts, and visual styles consistently across the application while maintaining performance and cross-platform compatibility.
|
||||
|
||||
## Project Structure
|
||||
The Avalonia UI layer organizes theming and styling around Axaml files and C# code-behind:
|
||||
- Application entry points initialize the runtime and configure global resources.
|
||||
- Global resources (colors, icons, base styles) are defined in dedicated Axaml files under Assets and Controls.
|
||||
- Views reference resources via standard Axaml resource references and converters for value transformations.
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
Program["Program.cs"] --> AppAxaml["App.axaml"]
|
||||
AppAxaml --> AppCode["App.axaml.cs"]
|
||||
AppAxaml --> Icons["Assets/Icons.xaml"]
|
||||
AppAxaml --> GroupBoxTheme["Controls/GroupBox.Theme.xaml"]
|
||||
MainWindow["Views/MainWindow.axaml"] --> AppAxaml
|
||||
AboutControl["Views/AboutControl.axaml"] --> AppAxaml
|
||||
DialogWindow["Views/DialogWindow.axaml"] --> AppAxaml
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [Program.cs](file://ClassicAssist.Avalonia/Program.cs)
|
||||
- [App.axaml](file://ClassicAssist.Avalonia/App.axaml)
|
||||
- [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
|
||||
- [Icons.xaml](file://ClassicAssist.Avalonia/Assets/Icons.xaml)
|
||||
- [GroupBox.Theme.xaml](file://ClassicAssist.Avalonia/Controls/GroupBox.Theme.xaml)
|
||||
- [MainWindow.axaml](file://ClassicAssist.Avalonia/Views/MainWindow.axaml)
|
||||
- [AboutControl.axaml](file://ClassicAssist.Avalonia/Views/AboutControl.axaml)
|
||||
- [DialogWindow.axaml](file://ClassicAssist.Avalonia/Views/DialogWindow.axaml)
|
||||
|
||||
**Section sources**
|
||||
- [Program.cs](file://ClassicAssist.Avalonia/Program.cs)
|
||||
- [App.axaml](file://ClassicAssist.Avalonia/App.axaml)
|
||||
- [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
|
||||
- [Icons.xaml](file://ClassicAssist.Avalonia/Assets/Icons.xaml)
|
||||
- [GroupBox.Theme.xaml](file://ClassicAssist.Avalonia/Controls/GroupBox.Theme.xaml)
|
||||
- [MainWindow.axaml](file://ClassicAssist.Avalonia/Views/MainWindow.axaml)
|
||||
- [AboutControl.axaml](file://ClassicAssist.Avalonia/Views/AboutControl.axaml)
|
||||
- [DialogWindow.axaml](file://ClassicAssist.Avalonia/Views/DialogWindow.axaml)
|
||||
|
||||
## Core Components
|
||||
- Application bootstrap and resource initialization:
|
||||
- Entry point sets up the Avalonia application and ensures resources are available at startup.
|
||||
- App.axaml defines global resources and theme-related settings.
|
||||
- App.axaml.cs contains any runtime configuration or programmatic resource adjustments.
|
||||
|
||||
- Icon system:
|
||||
- Centralized icon definitions are provided in an Axaml resource dictionary for reuse across views.
|
||||
|
||||
- Control-level themes:
|
||||
- Control-specific theme resources (e.g., GroupBox) are isolated in dedicated Axaml files for easy override and maintenance.
|
||||
|
||||
- Converters for data binding:
|
||||
- A set of value converters transform bound values into UI-friendly formats (strings, booleans, arrays, etc.).
|
||||
|
||||
Key implementation locations:
|
||||
- Application bootstrap and resource setup: [Program.cs](file://ClassicAssist.Avalonia/Program.cs), [App.axaml](file://ClassicAssist.Avalonia/App.axaml), [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
|
||||
- Icons: [Icons.xaml](file://ClassicAssist.Avalonia/Assets/Icons.xaml)
|
||||
- Control themes: [GroupBox.Theme.xaml](file://ClassicAssist.Avalonia/Controls/GroupBox.Theme.xaml)
|
||||
- Converters: [StringToResourceConverter.cs](file://ClassicAssist.Avalonia/Misc/StringToResourceConverter.cs), [InverseBooleanValueConverter.cs](file://ClassicAssist.Avalonia/Misc/InverseBooleanValueConverter.cs), [JoinArrayValueConverter.cs](file://ClassicAssist.Avalonia/Misc/JoinArrayValueConverter.cs), [DateTimeToTimeSpanValueConverter.cs](file://ClassicAssist.Avalonia/Misc/DateTimeToTimeSpanValueConverter.cs), [LockStatusValueConverter.cs](file://ClassicAssist.Avalonia/Misc/LockStatusValueConverter.cs), [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs), [PacketEntryBinaryValueConverter.cs](file://ClassicAssist.Avalonia/Misc/PacketEntryBinaryValueConverter.cs), [PacketEntryTextValueConverter.cs](file://ClassicAssist.Avalonia/Misc/PacketEntryTextValueConverter.cs)
|
||||
|
||||
**Section sources**
|
||||
- [Program.cs](file://ClassicAssist.Avalonia/Program.cs)
|
||||
- [App.axaml](file://ClassicAssist.Avalonia/App.axaml)
|
||||
- [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
|
||||
- [Icons.xaml](file://ClassicAssist.Avalonia/Assets/Icons.xaml)
|
||||
- [GroupBox.Theme.xaml](file://ClassicAssist.Avalonia/Controls/GroupBox.Theme.xaml)
|
||||
- [StringToResourceConverter.cs](file://ClassicAssist.Avalonia/Misc/StringToResourceConverter.cs)
|
||||
- [InverseBooleanValueConverter.cs](file://ClassicAssist.Avalonia/Misc/InverseBooleanValueConverter.cs)
|
||||
- [JoinArrayValueConverter.cs](file://ClassicAssist.Avalonia/Misc/JoinArrayValueConverter.cs)
|
||||
- [DateTimeToTimeSpanValueConverter.cs](file://ClassicAssist.Avalonia/Misc/DateTimeToTimeSpanValueConverter.cs)
|
||||
- [LockStatusValueConverter.cs](file://ClassicAssist.Avalonia/Misc/LockStatusValueConverter.cs)
|
||||
- [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs)
|
||||
- [PacketEntryBinaryValueConverter.cs](file://ClassicAssist.Avalonia/Misc/PacketEntryBinaryValueConverter.cs)
|
||||
- [PacketEntryTextValueConverter.cs](file://ClassicAssist.Avalonia/Misc/PacketEntryTextValueConverter.cs)
|
||||
|
||||
## Architecture Overview
|
||||
The theming architecture follows a layered approach:
|
||||
- Global resources define shared colors, fonts, and icons.
|
||||
- Control-level themes provide default appearances for specific controls.
|
||||
- Views consume resources and converters to render themed UIs.
|
||||
- Dynamic theme switching can be implemented by replacing or merging resource dictionaries at runtime.
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Global Resources"
|
||||
AppRes["App.axaml<br/>Global resources"]
|
||||
IconsRes["Assets/Icons.xaml<br/>Icon definitions"]
|
||||
end
|
||||
subgraph "Control Themes"
|
||||
GroupBoxTheme["Controls/GroupBox.Theme.xaml<br/>Control-specific styles"]
|
||||
end
|
||||
subgraph "Views"
|
||||
MainWindow["Views/MainWindow.axaml"]
|
||||
AboutControl["Views/AboutControl.axaml"]
|
||||
DialogWindow["Views/DialogWindow.axaml"]
|
||||
end
|
||||
AppRes --> MainWindow
|
||||
AppRes --> AboutControl
|
||||
AppRes --> DialogWindow
|
||||
IconsRes --> MainWindow
|
||||
IconsRes --> AboutControl
|
||||
IconsRes --> DialogWindow
|
||||
GroupBoxTheme --> MainWindow
|
||||
GroupBoxTheme --> AboutControl
|
||||
GroupBoxTheme --> DialogWindow
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [App.axaml](file://ClassicAssist.Avalonia/App.axaml)
|
||||
- [Icons.xaml](file://ClassicAssist.Avalonia/Assets/Icons.xaml)
|
||||
- [GroupBox.Theme.xaml](file://ClassicAssist.Avalonia/Controls/GroupBox.Theme.xaml)
|
||||
- [MainWindow.axaml](file://ClassicAssist.Avalonia/Views/MainWindow.axaml)
|
||||
- [AboutControl.axaml](file://ClassicAssist.Avalonia/Views/AboutControl.axaml)
|
||||
- [DialogWindow.axaml](file://ClassicAssist.Avalonia/Views/DialogWindow.axaml)
|
||||
|
||||
## Detailed Component Analysis
|
||||
|
||||
### Resource Dictionary Structure and Loading
|
||||
- Global resources are declared in the application’s main Axaml file and referenced by views.
|
||||
- Icon resources are centralized in a dedicated Axaml file and included where needed.
|
||||
- Control-level themes are isolated in separate Axaml files to keep control appearance modular.
|
||||
|
||||
Recommended structure:
|
||||
- Global colors and brushes: Define once in App.axaml for consistent usage across the app.
|
||||
- Fonts: Declare font families and sizes globally; override per-control if necessary.
|
||||
- Icons: Store reusable vector or image-based icons in Assets/Icons.xaml and reference by key.
|
||||
- Control themes: Place control-specific styles in Controls/*.Theme.xaml files.
|
||||
|
||||
Resource loading mechanism:
|
||||
- At startup, the application initializes resources from App.axaml.
|
||||
- Views load resources through standard Axaml resource references.
|
||||
- For dynamic changes, replace or merge resource dictionaries programmatically in App.axaml.cs.
|
||||
|
||||
**Section sources**
|
||||
- [App.axaml](file://ClassicAssist.Avalonia/App.axaml)
|
||||
- [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
|
||||
- [Icons.xaml](file://ClassicAssist.Avalonia/Assets/Icons.xaml)
|
||||
- [GroupBox.Theme.xaml](file://ClassicAssist.Avalonia/Controls/GroupBox.Theme.xaml)
|
||||
|
||||
### Color Schemes and Visual Theme Definitions
|
||||
- Colors and brushes should be defined as global resources to ensure consistency.
|
||||
- Use semantic keys (e.g., primary, secondary, background, foreground) to simplify overrides.
|
||||
- Control themes can reference these semantic keys to adapt their appearance.
|
||||
|
||||
Customization steps:
|
||||
- Add new color entries to the global resource dictionary.
|
||||
- Override existing brush keys in a theme-specific resource dictionary.
|
||||
- Apply theme dictionaries at runtime to switch palettes without rebuilding the UI.
|
||||
|
||||
**Section sources**
|
||||
- [App.axaml](file://ClassicAssist.Avalonia/App.axaml)
|
||||
- [GroupBox.Theme.xaml](file://ClassicAssist.Avalonia/Controls/GroupBox.Theme.xaml)
|
||||
|
||||
### Font Configurations
|
||||
- Define font families and sizes in global resources for consistent typography.
|
||||
- Reference fonts in control themes and views using resource keys.
|
||||
- Provide fallback fonts for cross-platform compatibility.
|
||||
|
||||
Platform considerations:
|
||||
- Ensure fonts are embedded or available on all target platforms.
|
||||
- Test rendering differences between Windows, macOS, and Linux.
|
||||
|
||||
**Section sources**
|
||||
- [App.axaml](file://ClassicAssist.Avalonia/App.axaml)
|
||||
- [GroupBox.Theme.xaml](file://ClassicAssist.Avalonia/Controls/GroupBox.Theme.xaml)
|
||||
|
||||
### Icon System
|
||||
- Centralize icons in Assets/Icons.xaml for reuse across views.
|
||||
- Reference icons by key in Axaml bindings or style setters.
|
||||
- Keep icon assets optimized for performance and scalability.
|
||||
|
||||
Usage patterns:
|
||||
- Bind icon properties to resource keys.
|
||||
- Use converters when transforming icon data for display.
|
||||
|
||||
**Section sources**
|
||||
- [Icons.xaml](file://ClassicAssist.Avalonia/Assets/Icons.xaml)
|
||||
- [MainWindow.axaml](file://ClassicAssist.Avalonia/Views/MainWindow.axaml)
|
||||
- [AboutControl.axaml](file://ClassicAssist.Avalonia/Views/AboutControl.axaml)
|
||||
- [DialogWindow.axaml](file://ClassicAssist.Avalonia/Views/DialogWindow.axaml)
|
||||
|
||||
### Dynamic Theme Switching
|
||||
- Implement runtime theme switching by replacing or merging resource dictionaries.
|
||||
- Maintain a mapping of theme names to resource dictionaries.
|
||||
- Trigger updates from user preferences or settings.
|
||||
|
||||
Implementation outline:
|
||||
- In App.axaml.cs, expose methods to apply a theme by name.
|
||||
- Load the corresponding resource dictionary and update the application’s resources.
|
||||
- Notify UI components to refresh styles if necessary.
|
||||
|
||||
**Section sources**
|
||||
- [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
|
||||
- [App.axaml](file://ClassicAssist.Avalonia/App.axaml)
|
||||
|
||||
### Converter Classes for Data Binding and Value Transformation
|
||||
Converters bridge view models and UI elements by transforming data into presentation-ready formats.
|
||||
|
||||
Key converters:
|
||||
- StringToResourceConverter: Resolves string keys to resource values.
|
||||
- InverseBooleanValueConverter: Flips boolean values for visibility toggles.
|
||||
- JoinArrayValueConverter: Concatenates array items into a single string.
|
||||
- DateTimeToTimeSpanValueConverter: Converts DateTime to TimeSpan for duration displays.
|
||||
- LockStatusValueConverter: Maps lock status enums to UI representations.
|
||||
- HueEntryToRectanglesValueConverter: Transforms hue entries into rectangle collections.
|
||||
- PacketEntryBinaryValueConverter: Formats binary packet data for display.
|
||||
- PacketEntryTextValueConverter: Formats text packet data for display.
|
||||
|
||||
Usage examples:
|
||||
- Bind converter parameters to additional context or static resources.
|
||||
- Combine multiple converters using multi-value converters when needed.
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class StringToResourceConverter {
|
||||
+Convert(value, targetType, parameter, culture) object
|
||||
+ConvertBack(value, targetType, parameter, culture) object
|
||||
}
|
||||
class InverseBooleanValueConverter {
|
||||
+Convert(value, targetType, parameter, culture) object
|
||||
+ConvertBack(value, targetType, parameter, culture) object
|
||||
}
|
||||
class JoinArrayValueConverter {
|
||||
+Convert(value, targetType, parameter, culture) object
|
||||
+ConvertBack(value, targetType, parameter, culture) object
|
||||
}
|
||||
class DateTimeToTimeSpanValueConverter {
|
||||
+Convert(value, targetType, parameter, culture) object
|
||||
+ConvertBack(value, targetType, parameter, culture) object
|
||||
}
|
||||
class LockStatusValueConverter {
|
||||
+Convert(value, targetType, parameter, culture) object
|
||||
+ConvertBack(value, targetType, parameter, culture) object
|
||||
}
|
||||
class HueEntryToRectanglesValueConverter {
|
||||
+Convert(value, targetType, parameter, culture) object
|
||||
+ConvertBack(value, targetType, parameter, culture) object
|
||||
}
|
||||
class PacketEntryBinaryValueConverter {
|
||||
+Convert(value, targetType, parameter, culture) object
|
||||
+ConvertBack(value, targetType, parameter, culture) object
|
||||
}
|
||||
class PacketEntryTextValueConverter {
|
||||
+Convert(value, targetType, parameter, culture) object
|
||||
+ConvertBack(value, targetType, parameter, culture) object
|
||||
}
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [StringToResourceConverter.cs](file://ClassicAssist.Avalonia/Misc/StringToResourceConverter.cs)
|
||||
- [InverseBooleanValueConverter.cs](file://ClassicAssist.Avalonia/Misc/InverseBooleanValueConverter.cs)
|
||||
- [JoinArrayValueConverter.cs](file://ClassicAssist.Avalonia/Misc/JoinArrayValueConverter.cs)
|
||||
- [DateTimeToTimeSpanValueConverter.cs](file://ClassicAssist.Avalonia/Misc/DateTimeToTimeSpanValueConverter.cs)
|
||||
- [LockStatusValueConverter.cs](file://ClassicAssist.Avalonia/Misc/LockStatusValueConverter.cs)
|
||||
- [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs)
|
||||
- [PacketEntryBinaryValueConverter.cs](file://ClassicAssist.Avalonia/Misc/PacketEntryBinaryValueConverter.cs)
|
||||
- [PacketEntryTextValueConverter.cs](file://ClassicAssist.Avalonia/Misc/PacketEntryTextValueConverter.cs)
|
||||
|
||||
**Section sources**
|
||||
- [StringToResourceConverter.cs](file://ClassicAssist.Avalonia/Misc/StringToResourceConverter.cs)
|
||||
- [InverseBooleanValueConverter.cs](file://ClassicAssist.Avalonia/Misc/InverseBooleanValueConverter.cs)
|
||||
- [JoinArrayValueConverter.cs](file://ClassicAssist.Avalonia/Misc/JoinArrayValueConverter.cs)
|
||||
- [DateTimeToTimeSpanValueConverter.cs](file://ClassicAssist.Avalonia/Misc/DateTimeToTimeSpanValueConverter.cs)
|
||||
- [LockStatusValueConverter.cs](file://ClassicAssist.Avalonia/Misc/LockStatusValueConverter.cs)
|
||||
- [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs)
|
||||
- [PacketEntryBinaryValueConverter.cs](file://ClassicAssist.Avalonia/Misc/PacketEntryBinaryValueConverter.cs)
|
||||
- [PacketEntryTextValueConverter.cs](file://ClassicAssist.Avalonia/Misc/PacketEntryTextValueConverter.cs)
|
||||
|
||||
### Creating Custom Themes
|
||||
Steps to create a custom theme:
|
||||
- Create a new Axaml resource dictionary with your color palette and font settings.
|
||||
- Override semantic resource keys to change appearance without modifying core styles.
|
||||
- Include the custom theme dictionary in App.axaml or load it dynamically.
|
||||
|
||||
Best practices:
|
||||
- Use semantic keys for maintainability.
|
||||
- Keep theme dictionaries small and focused.
|
||||
- Test across platforms to ensure consistent rendering.
|
||||
|
||||
**Section sources**
|
||||
- [App.axaml](file://ClassicAssist.Avalonia/App.axaml)
|
||||
- [GroupBox.Theme.xaml](file://ClassicAssist.Avalonia/Controls/GroupBox.Theme.xaml)
|
||||
|
||||
### Overriding Default Styles
|
||||
To override default control styles:
|
||||
- Define a new style for the control in a theme dictionary.
|
||||
- Set TargetType and Key to match the control and desired scope.
|
||||
- Reference the overriding style in your theme or view.
|
||||
|
||||
Example pattern:
|
||||
- Create a style that targets a specific control and replaces setters for colors, fonts, and margins.
|
||||
- Ensure the style is loaded after the default theme to take precedence.
|
||||
|
||||
**Section sources**
|
||||
- [GroupBox.Theme.xaml](file://ClassicAssist.Avalonia/Controls/GroupBox.Theme.xaml)
|
||||
- [App.axaml](file://ClassicAssist.Avalonia/App.axaml)
|
||||
|
||||
### Platform-Specific Visual Adaptations
|
||||
Guidelines:
|
||||
- Detect platform at runtime and adjust resources accordingly.
|
||||
- Provide alternative fonts or icons for better native feel.
|
||||
- Validate layout differences due to DPI scaling and window decorations.
|
||||
|
||||
Implementation hints:
|
||||
- Use conditional logic in App.axaml.cs to load platform-specific resources.
|
||||
- Keep platform-specific styles in separate dictionaries for clarity.
|
||||
|
||||
**Section sources**
|
||||
- [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
|
||||
- [App.axaml](file://ClassicAssist.Avalonia/App.axaml)
|
||||
|
||||
## Dependency Analysis
|
||||
The theming system has clear dependencies:
|
||||
- Views depend on global resources and control themes.
|
||||
- Converters are referenced by views to transform data.
|
||||
- Application bootstrap initializes resources and may apply dynamic themes.
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
AppAxaml["App.axaml"] --> MainWindow["Views/MainWindow.axaml"]
|
||||
AppAxaml --> AboutControl["Views/AboutControl.axaml"]
|
||||
AppAxaml --> DialogWindow["Views/DialogWindow.axaml"]
|
||||
Icons["Assets/Icons.xaml"] --> MainWindow
|
||||
Icons --> AboutControl
|
||||
Icons --> DialogWindow
|
||||
GroupBoxTheme["Controls/GroupBox.Theme.xaml"] --> MainWindow
|
||||
GroupBoxTheme --> AboutControl
|
||||
GroupBoxTheme --> DialogWindow
|
||||
Converters["Misc/*ValueConverter.cs"] --> MainWindow
|
||||
Converters --> AboutControl
|
||||
Converters --> DialogWindow
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [App.axaml](file://ClassicAssist.Avalonia/App.axaml)
|
||||
- [Icons.xaml](file://ClassicAssist.Avalonia/Assets/Icons.xaml)
|
||||
- [GroupBox.Theme.xaml](file://ClassicAssist.Avalonia/Controls/GroupBox.Theme.xaml)
|
||||
- [MainWindow.axaml](file://ClassicAssist.Avalonia/Views/MainWindow.axaml)
|
||||
- [AboutControl.axaml](file://ClassicAssist.Avalonia/Views/AboutControl.axaml)
|
||||
- [DialogWindow.axaml](file://ClassicAssist.Avalonia/Views/DialogWindow.axaml)
|
||||
- [StringToResourceConverter.cs](file://ClassicAssist.Avalonia/Misc/StringToResourceConverter.cs)
|
||||
- [InverseBooleanValueConverter.cs](file://ClassicAssist.Avalonia/Misc/InverseBooleanValueConverter.cs)
|
||||
- [JoinArrayValueConverter.cs](file://ClassicAssist.Avalonia/Misc/JoinArrayValueConverter.cs)
|
||||
- [DateTimeToTimeSpanValueConverter.cs](file://ClassicAssist.Avalonia/Misc/DateTimeToTimeSpanValueConverter.cs)
|
||||
- [LockStatusValueConverter.cs](file://ClassicAssist.Avalonia/Misc/LockStatusValueConverter.cs)
|
||||
- [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs)
|
||||
- [PacketEntryBinaryValueConverter.cs](file://ClassicAssist.Avalonia/Misc/PacketEntryBinaryValueConverter.cs)
|
||||
- [PacketEntryTextValueConverter.cs](file://ClassicAssist.Avalonia/Misc/PacketEntryTextValueConverter.cs)
|
||||
|
||||
**Section sources**
|
||||
- [App.axaml](file://ClassicAssist.Avalonia/App.axaml)
|
||||
- [Icons.xaml](file://ClassicAssist.Avalonia/Assets/Icons.xaml)
|
||||
- [GroupBox.Theme.xaml](file://ClassicAssist.Avalonia/Controls/GroupBox.Theme.xaml)
|
||||
- [MainWindow.axaml](file://ClassicAssist.Avalonia/Views/MainWindow.axaml)
|
||||
- [AboutControl.axaml](file://ClassicAssist.Avalonia/Views/AboutControl.axaml)
|
||||
- [DialogWindow.axaml](file://ClassicAssist.Avalonia/Views/DialogWindow.axaml)
|
||||
- [StringToResourceConverter.cs](file://ClassicAssist.Avalonia/Misc/StringToResourceConverter.cs)
|
||||
- [InverseBooleanValueConverter.cs](file://ClassicAssist.Avalonia/Misc/InverseBooleanValueConverter.cs)
|
||||
- [JoinArrayValueConverter.cs](file://ClassicAssist.Avalonia/Misc/JoinArrayValueConverter.cs)
|
||||
- [DateTimeToTimeSpanValueConverter.cs](file://ClassicAssist.Avalonia/Misc/DateTimeToTimeSpanValueConverter.cs)
|
||||
- [LockStatusValueConverter.cs](file://ClassicAssist.Avalonia/Misc/LockStatusValueConverter.cs)
|
||||
- [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs)
|
||||
- [PacketEntryBinaryValueConverter.cs](file://ClassicAssist.Avalonia/Misc/PacketEntryBinaryValueConverter.cs)
|
||||
- [PacketEntryTextValueConverter.cs](file://ClassicAssist.Avalonia/Misc/PacketEntryTextValueConverter.cs)
|
||||
|
||||
## Performance Considerations
|
||||
- Prefer static resources over dynamic bindings for frequently used colors and fonts.
|
||||
- Minimize converter complexity; precompute results when possible.
|
||||
- Avoid excessive resource dictionary merges at runtime; batch updates.
|
||||
- Use vector icons where feasible to reduce memory footprint and improve scaling.
|
||||
- Profile UI rendering when applying heavy themes to identify bottlenecks.
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
|
||||
## Troubleshooting Guide
|
||||
Common issues and resolutions:
|
||||
- Missing resource keys: Ensure all referenced keys exist in global or local resource dictionaries.
|
||||
- Incorrect converter parameters: Verify converter bindings and parameter types.
|
||||
- Theme not applied: Confirm the theme dictionary is loaded and merged after defaults.
|
||||
- Cross-platform inconsistencies: Check font availability and DPI scaling behavior.
|
||||
|
||||
Debugging tips:
|
||||
- Inspect resource resolution order in Axaml.
|
||||
- Log converter inputs and outputs during development.
|
||||
- Use minimal reproducible examples to isolate theme conflicts.
|
||||
|
||||
**Section sources**
|
||||
- [App.axaml](file://ClassicAssist.Avalonia/App.axaml)
|
||||
- [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
|
||||
- [StringToResourceConverter.cs](file://ClassicAssist.Avalonia/Misc/StringToResourceConverter.cs)
|
||||
- [InverseBooleanValueConverter.cs](file://ClassicAssist.Avalonia/Misc/InverseBooleanValueConverter.cs)
|
||||
|
||||
## Conclusion
|
||||
The ClassicAssist.Avalonia theming system leverages Axaml resource dictionaries, centralized icons, and control-level themes to deliver a flexible and maintainable UI. By defining semantic resources, using converters judiciously, and implementing dynamic theme switching, you can create cohesive, customizable, and performant interfaces across platforms. Follow the guidelines above to extend themes, override styles, and adapt visuals for different environments.
|
||||
|
||||
[No sources needed since this section summarizes without analyzing specific files]
|
||||
|
||||
## Appendices
|
||||
|
||||
### Quick Start: Applying a Custom Theme
|
||||
- Create a new Axaml resource dictionary with your theme colors and fonts.
|
||||
- Add the dictionary to App.axaml or load it in App.axaml.cs.
|
||||
- Reference semantic resource keys in views and control themes.
|
||||
- Test on all target platforms and adjust as needed.
|
||||
|
||||
**Section sources**
|
||||
- [App.axaml](file://ClassicAssist.Avalonia/App.axaml)
|
||||
- [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
|
||||
Reference in New Issue
Block a user