# Binding and Conversion System **Referenced Files in This Document** - [StringToResourceConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/StringToResourceConverter.cs) - [JoinArrayValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/JoinArrayValueConverter.cs) - [LockStatusValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/LockStatusValueConverter.cs) - [DateTimeToTimeSpanValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/DateTimeToTimeSpanValueConverter.cs) - [EnumBindingSourceExtension.cs](file://ClassicAssist/UI/Misc/EnumBindingSourceExtension.cs) - [InverseBooleanConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/InverseBooleanConverter.cs) - [HexToIntValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/HexToIntValueConverter.cs) - [IntToHexStringValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/IntToHexStringValueConverter.cs) - [CellWidthValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/CellWidthValueConverter.cs) - [PriorityMultiValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/PriorityMultiValueConverter.cs) - [SetSkillLockMultiValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/SetSkillLockMultiValueConverter.cs) - [ValueConverterGroup.cs](file://ClassicAssist/UI/Misc/ValueConverters/ValueConverterGroup.cs) - [EnumMatchToBooleanConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/EnumMatchToBooleanConverter.cs) - [Avalonia StringToResourceConverter](file://ClassicAssist.Avalonia/Misc/StringToResourceConverter.cs) - [Avalonia JoinArrayValueConverter](file://ClassicAssist.Avalonia/Misc/JoinArrayValueConverter.cs) - [Avalonia LockStatusValueConverter](file://ClassicAssist.Avalonia/Misc/LockStatusValueConverter.cs) - [Avalonia DateTimeToTimeSpanValueConverter](file://ClassicAssist.Avalonia/Misc/DateTimeToTimeSpanValueConverter.cs) - [Avalonia EnumBindingSourceExtension](file://ClassicAssist.Avalonia/Misc/EnumBindingSourceExtension.cs) - [Avalonia InverseBooleanValueConverter](file://ClassicAssist.Avalonia/Misc/InverseBooleanValueConverter.cs) ## 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 data binding and value conversion system used across the WPF and Avalonia UI layers. It focuses on custom value converters for common scenarios such as string-to-resource lookup, array joining, lock status formatting, and date/time conversions. It also documents the enum binding extension that enables type-safe enumeration bindings and outlines best practices for creating new converters, implementing two-way bindings, and optimizing performance for large datasets. ## Project Structure The binding and conversion system is implemented in both WPF and Avalonia projects: - WPF converters and extensions are located under ClassicAssist/UI/Misc/ValueConverters and ClassicAssist/UI/Misc. - Avalonia equivalents are located under ClassicAssist.Avalonia/Misc. ```mermaid graph TB subgraph "WPF" A["StringToResourceConverter.cs"] B["JoinArrayValueConverter.cs"] C["LockStatusValueConverter.cs"] D["DateTimeToTimeSpanValueConverter.cs"] E["EnumBindingSourceExtension.cs"] F["InverseBooleanConverter.cs"] G["HexToIntValueConverter.cs"] H["IntToHexStringValueConverter.cs"] I["CellWidthValueConverter.cs"] J["PriorityMultiValueConverter.cs"] K["SetSkillLockMultiValueConverter.cs"] L["ValueConverterGroup.cs"] M["EnumMatchToBooleanConverter.cs"] end subgraph "Avalonia" A2["StringToResourceConverter.cs"] B2["JoinArrayValueConverter.cs"] C2["LockStatusValueConverter.cs"] D2["DateTimeToTimeSpanValueConverter.cs"] E2["EnumBindingSourceExtension.cs"] F2["InverseBooleanValueConverter.cs"] end A --> A2 B --> B2 C --> C2 D --> D2 E --> E2 F --> F2 ``` **Diagram sources** - [StringToResourceConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/StringToResourceConverter.cs) - [JoinArrayValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/JoinArrayValueConverter.cs) - [LockStatusValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/LockStatusValueConverter.cs) - [DateTimeToTimeSpanValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/DateTimeToTimeSpanValueConverter.cs) - [EnumBindingSourceExtension.cs](file://ClassicAssist/UI/Misc/EnumBindingSourceExtension.cs) - [InverseBooleanConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/InverseBooleanConverter.cs) - [HexToIntValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/HexToIntValueConverter.cs) - [IntToHexStringValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/IntToHexStringValueConverter.cs) - [CellWidthValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/CellWidthValueConverter.cs) - [PriorityMultiValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/PriorityMultiValueConverter.cs) - [SetSkillLockMultiValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/SetSkillLockMultiValueConverter.cs) - [ValueConverterGroup.cs](file://ClassicAssist/UI/Misc/ValueConverters/ValueConverterGroup.cs) - [EnumMatchToBooleanConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/EnumMatchToBooleanConverter.cs) - [Avalonia StringToResource Converter](file://ClassicAssist.Avalonia/Misc/StringToResourceConverter.cs) - [Avalonia JoinArrayValueConverter](file://ClassicAssist.Avalonia/Misc/JoinArrayValueConverter.cs) - [Avalonia LockStatusValueConverter](file://ClassicAssist.Avalonia/Misc/LockStatusValueConverter.cs) - [Avalonia DateTimeToTimeSpanValueConverter](file://ClassicAssist.Avalonia/Misc/DateTimeToTimeSpanValueConverter.cs) - [Avalonia EnumBindingSourceExtension](file://ClassicAssist.Avalonia/Misc/EnumBindingSourceExtension.cs) - [Avalonia InverseBooleanValueConverter](file://ClassicAssist.Avalonia/Misc/InverseBooleanValueConverter.cs) **Section sources** - [StringToResourceConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/StringToResourceConverter.cs) - [JoinArrayValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/JoinArrayValueConverter.cs) - [LockStatusValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/LockStatusValueConverter.cs) - [DateTimeToTimeSpanValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/DateTimeToTimeSpanValueConverter.cs) - [EnumBindingSourceExtension.cs](file://ClassicAssist/UI/Misc/EnumBindingSourceExtension.cs) - [InverseBooleanConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/InverseBooleanConverter.cs) - [HexToIntValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/HexToIntValueConverter.cs) - [IntToHexStringValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/IntToHexStringValueConverter.cs) - [CellWidthValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/CellWidthValueConverter.cs) - [PriorityMultiValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/PriorityMultiValueConverter.cs) - [SetSkillLockMultiValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/SetSkillLockMultiValueConverter.cs) - [ValueConverterGroup.cs](file://ClassicAssist/UI/Misc/ValueConverters/ValueConverterGroup.cs) - [EnumMatchToBooleanConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/EnumMatchToBooleanConverter.cs) - [Avalonia StringToResource Converter](file://ClassicAssist.Avalonia/Misc/StringToResourceConverter.cs) - [Avalonia JoinArrayValueConverter](file://ClassicAssist.Avalonia/Misc/JoinArrayValueConverter.cs) - [Avalonia LockStatusValueConverter](file://ClassicAssist.Avalonia/Misc/LockStatusValueConverter.cs) - [Avalonia DateTimeToTimeSpanValueConverter](file://ClassicAssist.Avalonia/Misc/DateTimeToTimeSpanValueConverter.cs) - [Avalonia EnumBindingSourceExtension](file://ClassicAssist.Avalonia/Misc/EnumBindingSourceExtension.cs) - [Avalonia InverseBooleanValueConverter](file://ClassicAssist.Avalonia/Misc/InverseBooleanValueConverter.cs) ## Core Components This section summarizes the key converters and extensions used throughout the application. - String-to-resource lookup converter - Purpose: Converts a string key into a localized resource value at runtime. - Typical usage: Displaying user-facing strings from resource dictionaries. - Platform variants: WPF and Avalonia implementations exist. - Array joining converter - Purpose: Joins an array or collection into a single string using a specified separator. - Typical usage: Building display strings from multiple values. - Lock status formatter - Purpose: Formats skill or stat lock states into human-readable text or icons. - Typical usage: Rendering lock indicators in lists and grids. - Date/time to time span converter - Purpose: Converts a DateTime to a TimeSpan for duration displays. - Typical usage: Showing elapsed or remaining time. - Enum binding source extension - Purpose: Provides a markup-friendly way to bind to all members of an enumeration with optional descriptions. - Typical usage: Populating ComboBoxes or RadioButtons with enum options. - Boolean helpers - Inverse boolean converter: Flips a boolean value for visibility toggles and similar patterns. - Enum match to boolean converter: Maps an enum value to a boolean based on equality or matching logic. - Hexadecimal converters - Hex to int: Parses hex strings into integers. - Int to hex string: Formats integers as hexadecimal strings. - Multi-value converters - Priority multi-value converter: Combines multiple inputs to compute a priority. - Set skill lock multi-value converter: Applies lock state changes based on multiple conditions. - Value converter group - Purpose: Chains multiple converters together to perform sequential transformations. **Section sources** - [StringToResourceConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/StringToResourceConverter.cs) - [JoinArrayValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/JoinArrayValueConverter.cs) - [LockStatusValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/LockStatusValueConverter.cs) - [DateTimeToTimeSpanValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/DateTimeToTimeSpanValueConverter.cs) - [EnumBindingSourceExtension.cs](file://ClassicAssist/UI/Misc/EnumBindingSourceExtension.cs) - [InverseBooleanConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/InverseBooleanConverter.cs) - [HexToIntValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/HexToIntValueConverter.cs) - [IntToHexStringValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/IntToHexStringValueConverter.cs) - [CellWidthValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/CellWidthValueConverter.cs) - [PriorityMultiValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/PriorityMultiValueConverter.cs) - [SetSkillLockMultiValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/SetSkillLockMultiValueConverter.cs) - [ValueConverterGroup.cs](file://ClassicAssist/UI/Misc/ValueConverters/ValueConverterGroup.cs) - [EnumMatchToBooleanConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/EnumMatchToBooleanConverter.cs) - [Avalonia StringToResource Converter](file://ClassicAssist.Avalonia/Misc/StringToResourceConverter.cs) - [Avalonia JoinArrayValueConverter](file://ClassicAssist.Avalonia/Misc/JoinArrayValueConverter.cs) - [Avalonia LockStatusValueConverter](file://ClassicAssist.Avalonia/Misc/LockStatusValueConverter.cs) - [Avalonia DateTimeToTimeSpanValueConverter](file://ClassicAssist.Avalonia/Misc/DateTimeToTimeSpanValueConverter.cs) - [Avalonia EnumBindingSourceExtension](file://ClassicAssist.Avalonia/Misc/EnumBindingSourceExtension.cs) - [Avalonia InverseBooleanValueConverter](file://ClassicAssist.Avalonia/Misc/InverseBooleanValueConverter.cs) ## Architecture Overview The binding system integrates with the UI framework’s binding engine. Converters implement platform-specific interfaces (e.g., IValueConverter in WPF or IValueConverter in Avalonia). The enum binding extension provides a convenient markup extension to enumerate types and optionally use description attributes for display names. ```mermaid classDiagram class StringToResourceConverter { +Convert(value, targetType, parameter, culture) object +ConvertBack(value, targetType, parameter, culture) object } class JoinArrayValueConverter { +Convert(values, 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 DateTimeToTimeSpanValueConverter { +Convert(value, targetType, parameter, culture) object +ConvertBack(value, targetType, parameter, culture) object } class EnumBindingSourceExtension { +ProvideValue(serviceProvider) object } class InverseBooleanConverter { +Convert(value, targetType, parameter, culture) object +ConvertBack(value, targetType, parameter, culture) object } class HexToIntValueConverter { +Convert(value, targetType, parameter, culture) object +ConvertBack(value, targetType, parameter, culture) object } class IntToHexStringValueConverter { +Convert(value, targetType, parameter, culture) object +ConvertBack(value, targetType, parameter, culture) object } class CellWidthValueConverter { +Convert(value, targetType, parameter, culture) object +ConvertBack(value, targetType, parameter, culture) object } class PriorityMultiValueConverter { +Convert(values, targetType, parameter, culture) object +ConvertBack(value, targetType, parameters, culture) object } class SetSkillLockMultiValueConverter { +Convert(values, targetType, parameter, culture) object +ConvertBack(value, targetType, parameters, culture) object } class ValueConverterGroup { +Convert(value, targetType, parameter, culture) object +ConvertBack(value, targetType, parameter, culture) object } class EnumMatchToBooleanConverter { +Convert(value, targetType, parameter, culture) object +ConvertBack(value, targetType, parameter, culture) object } ``` **Diagram sources** - [StringToResourceConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/StringToResourceConverter.cs) - [JoinArrayValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/JoinArrayValueConverter.cs) - [LockStatusValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/LockStatusValueConverter.cs) - [DateTimeToTimeSpanValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/DateTimeToTimeSpanValueConverter.cs) - [EnumBindingSourceExtension.cs](file://ClassicAssist/UI/Misc/EnumBindingSourceExtension.cs) - [InverseBooleanConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/InverseBooleanConverter.cs) - [HexToIntValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/HexToIntValueConverter.cs) - [IntToHexStringValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/IntToHexStringValueConverter.cs) - [CellWidthValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/CellWidthValueConverter.cs) - [PriorityMultiValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/PriorityMultiValueConverter.cs) - [SetSkillLockMultiValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/SetSkillLockMultiValueConverter.cs) - [ValueConverterGroup.cs](file://ClassicAssist/UI/Misc/ValueConverters/ValueConverterGroup.cs) - [EnumMatchToBooleanConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/EnumMatchToBooleanConverter.cs) ## Detailed Component Analysis ### String-to-Resource Lookup Converter - Purpose: Resolves a string key to a localized resource value. - Behavior: - Accepts a key string and returns the corresponding resource entry. - Supports culture-aware resolution when applicable. - Two-way binding: - Typically one-way; ConvertBack may return the original key if needed by specific scenarios. - Usage example path: - [StringToResourceConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/StringToResourceConverter.cs) - [Avalonia StringToResource Converter](file://ClassicAssist.Avalonia/Misc/StringToResourceConverter.cs) **Section sources** - [StringToResourceConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/StringToResourceConverter.cs) - [Avalonia StringToResource Converter](file://ClassicAssist.Avalonia/Misc/StringToResourceConverter.cs) ### Array Joining Converter - Purpose: Concatenates elements of an array or collection into a single string using a configurable separator. - Behavior: - Ignores null entries unless configured otherwise. - Supports trimming and case normalization via parameters. - Two-way binding: - Can split a joined string back into an array if required by the model. - Usage example path: - [JoinArrayValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/JoinArrayValueConverter.cs) - [Avalonia JoinArrayValueConverter](file://ClassicAssist.Avalonia/Misc/JoinArrayValueConverter.cs) **Section sources** - [JoinArrayValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/JoinArrayValueConverter.cs) - [Avalonia JoinArrayValueConverter](file://ClassicAssist.Avalonia/Misc/JoinArrayValueConverter.cs) ### Lock Status Formatter - Purpose: Translates internal lock flags into readable labels or visual indicators. - Behavior: - Maps lock enums to display strings or icon resources. - May combine multiple lock states into a composite label. - Two-way binding: - ConvertBack can map a selected label/icon back to the appropriate lock flag. - Usage example path: - [LockStatusValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/LockStatusValueConverter.cs) - [Avalonia LockStatusValueConverter](file://ClassicAssist.Avalonia/Misc/LockStatusValueConverter.cs) **Section sources** - [LockStatusValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/LockStatusValueConverter.cs) - [Avalonia LockStatusValueConverter](file://ClassicAssist.Avalonia/Misc/LockStatusValueConverter.cs) ### Date/Time to Time Span Converter - Purpose: Converts a DateTime to a TimeSpan representing duration relative to now or another reference point. - Behavior: - Computes absolute or relative durations. - Supports formatting parameters for display. - Two-way binding: - Usually one-way; ConvertBack may not be meaningful unless editing raw TimeSpan values. - Usage example path: - [DateTimeToTimeSpanValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/DateTimeToTimeSpanValueConverter.cs) - [Avalonia DateTimeToTimeSpanValueConverter](file://ClassicAssist.Avalonia/Misc/DateTimeToTimeSpanValueConverter.cs) **Section sources** - [DateTimeToTimeSpanValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/DateTimeToTimeSpanValueConverter.cs) - [Avalonia DateTimeToTimeSpanValueConverter](file://ClassicAssist.Avalonia/Misc/DateTimeToTimeSpanValueConverter.cs) ### Enum Binding Source Extension - Purpose: Exposes all members of an enumeration to XAML/Axaml bindings, optionally using description attributes for friendly names. - Behavior: - Enumerates type members and builds a list suitable for ItemsSource binding. - Supports filtering and ordering parameters. - Two-way binding: - Works with SelectedItem bindings to update the underlying enum property. - Usage example path: - [EnumBindingSourceExtension.cs](file://ClassicAssist/UI/Misc/EnumBindingSourceExtension.cs) - [Avalonia EnumBindingSourceExtension](file://ClassicAssist.Avalonia/Misc/EnumBindingSourceExtension.cs) **Section sources** - [EnumBindingSourceExtension.cs](file://ClassicAssist/UI/Misc/EnumBindingSourceExtension.cs) - [Avalonia EnumBindingSourceExtension](file://ClassicAssist.Avalonia/Misc/EnumBindingSourceExtension.cs) ### Boolean Helpers and Enum Matching - Inverse boolean converter: - Flips boolean values for visibility toggles and conditional rendering. - Usage example path: [InverseBooleanConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/InverseBooleanConverter.cs), [Avalonia InverseBooleanValueConverter](file://ClassicAssist.Avalonia/Misc/InverseBooleanValueConverter.cs) - Enum match to boolean converter: - Compares an enum value against expected values and returns a boolean. - Usage example path: [EnumMatchToBooleanConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/EnumMatchToBooleanConverter.cs) **Section sources** - [InverseBooleanConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/InverseBooleanConverter.cs) - [Avalonia InverseBooleanValueConverter](file://ClassicAssist.Avalonia/Misc/InverseBooleanValueConverter.cs) - [EnumMatchToBooleanConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/EnumMatchToBooleanConverter.cs) ### Hexadecimal Converters - Hex to int converter: - Parses hexadecimal strings into integer values. - Usage example path: [HexToIntValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/HexToIntValueConverter.cs) - Int to hex string converter: - Formats integers as uppercase/lowercase hex strings. - Usage example path: [IntToHexStringValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/IntToHexStringValueConverter.cs) **Section sources** - [HexToIntValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/HexToIntValueConverter.cs) - [IntToHexStringValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/IntToHexStringValueConverter.cs) ### Multi-Value Converters - Priority multi-value converter: - Aggregates multiple inputs to compute a numeric priority. - Usage example path: [PriorityMultiValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/PriorityMultiValueConverter.cs) - Set skill lock multi-value converter: - Determines lock state updates based on multiple conditions. - Usage example path: [SetSkillLockMultiValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/SetSkillLockMultiValueConverter.cs) **Section sources** - [PriorityMultiValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/PriorityMultiValueConverter.cs) - [SetSkillLockMultiValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/SetSkillLockMultiValueConverter.cs) ### Value Converter Group - Purpose: Chains multiple converters sequentially to transform values step-by-step. - Behavior: - Applies each converter in order, passing output to the next. - Useful for composing complex transformations without extra code-behind. - Usage example path: [ValueConverterGroup.cs](file://ClassicAssist/UI/Misc/ValueConverters/ValueConverterGroup.cs) **Section sources** - [ValueConverterGroup.cs](file://ClassicAssist/UI/Misc/ValueConverters/ValueConverterGroup.cs) ### Additional Converters - Cell width converter: - Adjusts column widths based on content metrics. - Usage example path: [CellWidthValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/CellWidthValueConverter.cs) **Section sources** - [CellWidthValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/CellWidthValueConverter.cs) ## Dependency Analysis The converters are loosely coupled and primarily depend on the UI framework’s binding interfaces. Some converters rely on shared utilities or resource managers for localization and formatting. ```mermaid graph LR SR["StringToResourceConverter"] --> RES["Resource Manager"] JA["JoinArrayValueConverter"] --> STR["String Utilities"] LS["LockStatusValueConverter"] --> ENUMS["Lock Enums"] DTTS["DateTimeToTimeSpanValueConverter"] --> TIME["Time Utilities"] EBS["EnumBindingSourceExtension"] --> REF["Reflection API"] INV["InverseBooleanConverter"] --> BOOL["Boolean Logic"] HEXI["HexToIntValueConverter"] --> PARSE["Parsing Utilities"] HEXO["IntToHexStringValueConverter"] --> FORMAT["Formatting Utilities"] CW["CellWidthValueConverter"] --> MEASURE["Measure Utilities"] PMV["PriorityMultiValueConverter"] --> AGG["Aggregation Logic"] SSL["SetSkillLockMultiValueConverter"] --> LOCK["Lock State Logic"] VCG["ValueConverterGroup"] --> CHAIN["Converter Chain"] ``` [No diagram sources since this diagram shows conceptual dependencies rather than direct file mappings] **Section sources** - [StringToResourceConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/StringToResourceConverter.cs) - [JoinArrayValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/JoinArrayValueConverter.cs) - [LockStatusValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/LockStatusValueConverter.cs) - [DateTimeToTimeSpanValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/DateTimeToTimeSpanValueConverter.cs) - [EnumBindingSourceExtension.cs](file://ClassicAssist/UI/Misc/EnumBindingSourceExtension.cs) - [InverseBooleanConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/InverseBooleanConverter.cs) - [HexToIntValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/HexToIntValueConverter.cs) - [IntToHexStringValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/IntToHexStringValueConverter.cs) - [CellWidthValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/CellWidthValueConverter.cs) - [PriorityMultiValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/PriorityMultiValueConverter.cs) - [SetSkillLockMultiValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/SetSkillLockMultiValueConverter.cs) - [ValueConverterGroup.cs](file://ClassicAssist/UI/Misc/ValueConverters/ValueConverterGroup.cs) ## Performance Considerations - Prefer one-way bindings where possible to reduce overhead. - Cache expensive computations inside converters and invalidate only when inputs change. - Use ValueConverterGroup judiciously; deep chains can degrade performance on large collections. - For large datasets, consider virtualization and avoid heavy formatting in item templates. - Reuse converter instances where feasible to minimize allocations. - Avoid synchronous blocking operations within Convert methods; offload work to background tasks and update bound properties asynchronously. [No sources needed since this section provides general guidance] ## Troubleshooting Guide Common issues and resolutions: - Resource lookup failures: - Ensure keys exist in resource dictionaries and cultures are correctly set. - Verify the converter receives the expected key type. - Null or empty arrays: - Handle nulls explicitly in JoinArrayValueConverter to prevent exceptions. - Incorrect lock status display: - Confirm enum values align with converter expectations and mapping tables. - Date/time edge cases: - Guard against null dates and invalid ranges in DateTimeToTimeSpanValueConverter. - Enum binding population: - Check that the target enum type is correct and description attributes are applied if used. - Two-way binding inconsistencies: - Implement ConvertBack consistently and ensure it returns compatible types. **Section sources** - [StringToResourceConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/StringToResourceConverter.cs) - [JoinArrayValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/JoinArrayValueConverter.cs) - [LockStatusValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/LockStatusValueConverter.cs) - [DateTimeToTimeSpanValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/DateTimeToTimeSpanValueConverter.cs) - [EnumBindingSourceExtension.cs](file://ClassicAssist/UI/Misc/EnumBindingSourceExtension.cs) ## Conclusion The binding and conversion system provides a robust foundation for transforming and presenting data across WPF and Avalonia UIs. By leveraging specialized converters and the enum binding extension, developers can create expressive, maintainable interfaces. Following the guidelines for two-way bindings and performance optimization ensures smooth experiences even with large datasets. [No sources needed since this section summarizes without analyzing specific files] ## Appendices ### Creating New Converters - Steps: - Implement the platform’s IValueConverter interface. - Provide Convert and ConvertBack methods with clear parameter handling. - Add unit tests for typical and edge-case inputs. - Register the converter in resource dictionaries or markup extensions as needed. - Example paths: - [InverseBooleanConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/InverseBooleanConverter.cs) - [HexToIntValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/HexToIntValueConverter.cs) - [IntToHexStringValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/IntToHexStringValueConverter.cs) **Section sources** - [InverseBooleanConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/InverseBooleanConverter.cs) - [HexToIntValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/HexToIntValueConverter.cs) - [IntToHexStringValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/IntToHexStringValueConverter.cs) ### Implementing Two-Way Bindings - Guidelines: - Ensure ConvertBack returns a value compatible with the source property type. - Validate inputs and handle invalid formats gracefully. - Keep ConvertBack fast and side-effect free. - Example paths: - [JoinArrayValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/JoinArrayValueConverter.cs) - [LockStatusValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/LockStatusValueConverter.cs) - [ValueConverterGroup.cs](file://ClassicAssist/UI/Misc/ValueConverters/ValueConverterGroup.cs) **Section sources** - [JoinArrayValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/JoinArrayValueConverter.cs) - [LockStatusValueConverter.cs](file://ClassicAssist/UI/Misc/ValueConverters/LockStatusValueConverter.cs) - [ValueConverterGroup.cs](file://ClassicAssist/UI/Misc/ValueConverters/ValueConverterGroup.cs) ### Optimizing Binding Performance for Large Datasets - Recommendations: - Use one-way bindings where possible. - Minimize heavy computations in Convert; cache results and invalidate selectively. - Prefer lightweight formatting and avoid synchronous IO. - Leverage virtualization and paging for large collections. - Profile binding churn and refactor hot paths. [No sources needed since this section provides general guidance]