first commit
This commit is contained in:
Beyhan Oğur
+289
@@ -0,0 +1,289 @@
|
||||
# HueEntryControl
|
||||
|
||||
<cite>
|
||||
**Referenced Files in This Document**
|
||||
- [HueEntryControl.xaml](file://ClassicAssist/UI/Controls/HueEntryControl.xaml)
|
||||
- [HueEntryControl.xaml.cs](file://ClassicAssist/UI/Controls/HueEntryControl.xaml.cs)
|
||||
- [HuePickerWindow.xaml](file://ClassicAssist/UI/Views/HuePickerWindow.xaml)
|
||||
- [HuePickerWindow.xaml.cs](file://ClassicAssist/UI/Views/HuePickerWindow.xaml.cs)
|
||||
- [DressTabControl.xaml](file://ClassicAssist/UI/Views/Agents/DressTabControl.xaml)
|
||||
- [DressTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/DressTabControl.xaml.cs)
|
||||
- [AutolootTabControl.xaml](file://ClassicAssist/UI/Views/Agents/AutolootTabControl.xaml)
|
||||
- [AutolootTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/AutolootTabControl.xaml.cs)
|
||||
- [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs)
|
||||
- [Hues.cs](file://ClassicAssist.Shared/UO/Data/Hues.cs)
|
||||
</cite>
|
||||
|
||||
## Table of Contents
|
||||
1. [Introduction](#introduction)
|
||||
2. [Project Structure](#project-structure)
|
||||
3. [Core Components](#core-components)
|
||||
4. [Architecture Overview](#architecture-overview)
|
||||
5. [Detailed Component Analysis](#detailed-component-analysis)
|
||||
6. [Dependency Analysis](#dependency-analysis)
|
||||
7. [Performance Considerations](#performance-considerations)
|
||||
8. [Troubleshooting Guide](#troubleshooting-guide)
|
||||
9. [Conclusion](#conclusion)
|
||||
10. [Appendices](#appendices)
|
||||
|
||||
## Introduction
|
||||
This document provides comprehensive documentation for the HueEntryControl component used for color selection within the Ultima Online context. The control enables users to input a hue value, see an immediate visual preview, and validate that the value conforms to UO’s color system constraints. It supports both numeric entry and integration with a dedicated hue picker window, providing real-time updates to bound properties such as game object colors. The documentation covers properties, validation rules, interaction model, styling options, accessibility considerations, and practical examples for integrating with dress manager and autoloot systems.
|
||||
|
||||
## Project Structure
|
||||
The HueEntryControl is implemented in the WPF UI layer and is consumed by various agent tabs (e.g., Dress and Autoloot). A companion HuePickerWindow provides a graphical color selection experience. An Avalonia-specific converter exists for rendering hue previews as rectangles.
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "WPF UI"
|
||||
HEC["HueEntryControl<br/>xaml + code-behind"]
|
||||
HPW["HuePickerWindow<br/>xaml + code-behind"]
|
||||
DTC["DressTabControl"]
|
||||
ATC["AutolootTabControl"]
|
||||
end
|
||||
subgraph "Shared Data"
|
||||
HUES["UO Hues data"]
|
||||
end
|
||||
subgraph "Avalonia Helpers"
|
||||
CONV["HueEntryToRectanglesValueConverter"]
|
||||
end
|
||||
HEC --> HPW
|
||||
DTC --> HEC
|
||||
ATC --> HEC
|
||||
HEC --> HUES
|
||||
CONV -.-> HEC
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [HueEntryControl.xaml.cs](file://ClassicAssist/UI/Controls/HueEntryControl.xaml.cs)
|
||||
- [HuePickerWindow.xaml.cs](file://ClassicAssist/UI/Views/HuePickerWindow.xaml.cs)
|
||||
- [DressTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/DressTabControl.xaml.cs)
|
||||
- [AutolootTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/AutolootTabControl.xaml.cs)
|
||||
- [Hues.cs](file://ClassicAssist.Shared/UO/Data/Hues.cs)
|
||||
- [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs)
|
||||
|
||||
**Section sources**
|
||||
- [HueEntryControl.xaml](file://ClassicAssist/UI/Controls/HueEntryControl.xaml)
|
||||
- [HueEntryControl.xaml.cs](file://ClassicAssist/UI/Controls/HueEntryControl.xaml.cs)
|
||||
- [HuePickerWindow.xaml](file://ClassicAssist/UI/Views/HuePickerWindow.xaml)
|
||||
- [HuePickerWindow.xaml.cs](file://ClassicAssist/UI/Views/HuePickerWindow.xaml.cs)
|
||||
- [DressTabControl.xaml](file://ClassicAssist/UI/Views/Agents/DressTabControl.xaml)
|
||||
- [DressTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/DressTabControl.xaml.cs)
|
||||
- [AutolootTabControl.xaml](file://ClassicAssist/UI/Views/Agents/AutolootTabControl.xaml)
|
||||
- [AutolootTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/AutolootTabControl.xaml.cs)
|
||||
- [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs)
|
||||
- [Hues.cs](file://ClassicAssist.Shared/UO/Data/Hues.cs)
|
||||
|
||||
## Core Components
|
||||
- HueEntryControl: Provides a text box for numeric hue input, a color preview area, and optional integration with a hue picker dialog. Exposes properties for binding, including a validated hue value and validity state.
|
||||
- HuePickerWindow: A modal or non-modal window offering a visual palette for selecting hues; upon selection, it updates the bound hue value in the control.
|
||||
- DressTabControl and AutolootTabControl: Consume HueEntryControl to allow users to set item or rule colors.
|
||||
- HueEntryToRectanglesValueConverter: Converts hue values into visual rectangles for preview rendering in Avalonia contexts.
|
||||
- Hues: Shared data describing valid UO hues and related metadata.
|
||||
|
||||
Key responsibilities:
|
||||
- Input handling and validation against UO hue constraints
|
||||
- Real-time preview updates
|
||||
- Integration with external hue picker
|
||||
- Binding support for consumer components
|
||||
|
||||
**Section sources**
|
||||
- [HueEntryControl.xaml.cs](file://ClassicAssist/UI/Controls/HueEntryControl.xaml.cs)
|
||||
- [HuePickerWindow.xaml.cs](file://ClassicAssist/UI/Views/HuePickerWindow.xaml.cs)
|
||||
- [DressTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/DressTabControl.xaml.cs)
|
||||
- [AutolootTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/AutolootTabControl.xaml.cs)
|
||||
- [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs)
|
||||
- [Hues.cs](file://ClassicAssist.Shared/UO/Data/Hues.cs)
|
||||
|
||||
## Architecture Overview
|
||||
The component follows a simple MVVM-friendly pattern:
|
||||
- HueEntryControl exposes bindable properties for HueValue and IsValid.
|
||||
- On user input changes, the control validates the value and updates IsValid and the preview.
|
||||
- When the hue picker is invoked, it returns a selected hue which the control binds back to HueValue.
|
||||
- Consumers (Dress and Autoloot tabs) bind to HueValue to apply colors to items or rules.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User as "User"
|
||||
participant HEC as "HueEntryControl"
|
||||
participant HPW as "HuePickerWindow"
|
||||
participant Consumer as "Dress/Autoloot Tab"
|
||||
User->>HEC : "Type numeric hue"
|
||||
HEC->>HEC : "Validate against UO constraints"
|
||||
HEC-->>Consumer : "Update HueValue and IsValid"
|
||||
HEC-->>User : "Real-time color preview"
|
||||
User->>HEC : "Open Hue Picker"
|
||||
HEC->>HPW : "Show picker"
|
||||
HPW-->>HEC : "Return selected hue"
|
||||
HEC->>HEC : "Set HueValue and re-validate"
|
||||
HEC-->>Consumer : "Update HueValue and IsValid"
|
||||
HEC-->>User : "Real-time color preview"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [HueEntryControl.xaml.cs](file://ClassicAssist/UI/Controls/HueEntryControl.xaml.cs)
|
||||
- [HuePickerWindow.xaml.cs](file://ClassicAssist/UI/Views/HuePickerWindow.xaml.cs)
|
||||
- [DressTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/DressTabControl.xaml.cs)
|
||||
- [AutolootTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/AutolootTabControl.xaml.cs)
|
||||
|
||||
## Detailed Component Analysis
|
||||
|
||||
### HueEntryControl Properties and Behavior
|
||||
- HueValue: The current hue value intended for use. Updated on input changes and after picker selection.
|
||||
- IsValid: Indicates whether the current HueValue satisfies UO constraints. Consumers should check this before applying colors.
|
||||
- Color Preview: Visual feedback showing the effective color corresponding to HueValue.
|
||||
- Validation Rules: Enforces UO-specific hue range and any additional constraints defined in shared data.
|
||||
|
||||
Interaction model:
|
||||
- Numeric input: Users type a number; the control validates and updates preview immediately.
|
||||
- Hue picker: Users can open a picker window to select a hue visually; the chosen hue is written back to HueValue.
|
||||
- Real-time updates: Both input paths trigger validation and preview refresh.
|
||||
|
||||
Styling and accessibility:
|
||||
- Preview area can be styled to ensure sufficient contrast.
|
||||
- For color-blind users, consider adding textual indicators (e.g., displaying the numeric hue next to the preview) and high-contrast themes.
|
||||
|
||||
Integration points:
|
||||
- Consumers bind to HueValue and IsValid to conditionally enable actions or display errors.
|
||||
- Dress and Autoloot tabs demonstrate typical usage patterns.
|
||||
|
||||
**Section sources**
|
||||
- [HueEntryControl.xaml.cs](file://ClassicAssist/UI/Controls/HueEntryControl.xaml.cs)
|
||||
- [HueEntryControl.xaml](file://ClassicAssist/UI/Controls/HueEntryControl.xaml)
|
||||
- [Hues.cs](file://ClassicAssist.Shared/UO/Data/Hues.cs)
|
||||
|
||||
#### Class Diagram
|
||||
```mermaid
|
||||
classDiagram
|
||||
class HueEntryControl {
|
||||
+int HueValue
|
||||
+bool IsValid
|
||||
+void OpenHuePicker()
|
||||
-void ValidateAndPreview()
|
||||
}
|
||||
class HuePickerWindow {
|
||||
+void Show()
|
||||
+int SelectedHue
|
||||
}
|
||||
class DressTabControl {
|
||||
+bind HueValue
|
||||
+bind IsValid
|
||||
}
|
||||
class AutolootTabControl {
|
||||
+bind HueValue
|
||||
+bind IsValid
|
||||
}
|
||||
class Hues {
|
||||
<<data>>
|
||||
}
|
||||
HueEntryControl --> HuePickerWindow : "opens"
|
||||
DressTabControl --> HueEntryControl : "consumes"
|
||||
AutolootTabControl --> HueEntryControl : "consumes"
|
||||
HueEntryControl --> Hues : "validates against"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [HueEntryControl.xaml.cs](file://ClassicAssist/UI/Controls/HueEntryControl.xaml.cs)
|
||||
- [HuePickerWindow.xaml.cs](file://ClassicAssist/UI/Views/HuePickerWindow.xaml.cs)
|
||||
- [DressTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/DressTabControl.xaml.cs)
|
||||
- [AutolootTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/AutolootTabControl.xaml.cs)
|
||||
- [Hues.cs](file://ClassicAssist.Shared/UO/Data/Hues.cs)
|
||||
|
||||
### HuePickerWindow
|
||||
- Purpose: Provide a visual interface for selecting hues.
|
||||
- Behavior: Displays available hues; when a user selects one, the window communicates the chosen hue back to the caller (typically HueEntryControl).
|
||||
- Integration: Used by HueEntryControl to enhance usability beyond numeric entry.
|
||||
|
||||
**Section sources**
|
||||
- [HuePickerWindow.xaml.cs](file://ClassicAssist/UI/Views/HuePickerWindow.xaml.cs)
|
||||
- [HuePickerWindow.xaml](file://ClassicAssist/UI/Views/HuePickerWindow.xaml)
|
||||
|
||||
### DressTabControl Usage Example
|
||||
- Demonstrates binding HueEntryControl to a dress rule’s color property.
|
||||
- Uses IsValid to prevent invalid colors from being applied.
|
||||
- Shows how to update the dress list preview when HueValue changes.
|
||||
|
||||
**Section sources**
|
||||
- [DressTabControl.xaml](file://ClassicAssist/UI/Views/Agents/DressTabControl.xaml)
|
||||
- [DressTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/DressTabControl.xaml.cs)
|
||||
|
||||
### AutolootTabControl Usage Example
|
||||
- Demonstrates binding HueEntryControl to autoloot rule conditions or item filters.
|
||||
- Validates hue inputs before enabling autoloot actions.
|
||||
- Integrates with existing autoloot configuration workflows.
|
||||
|
||||
**Section sources**
|
||||
- [AutolootTabControl.xaml](file://ClassicAssist/UI/Views/Agents/AutolootTabControl.xaml)
|
||||
- [AutolootTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/AutolootTabControl.xaml.cs)
|
||||
|
||||
### Avalonia Converter for Previews
|
||||
- HueEntryToRectanglesValueConverter converts hue values into rectangle visuals for preview rendering in Avalonia-based views.
|
||||
- Useful when building cross-platform UIs that need consistent hue previews.
|
||||
|
||||
**Section sources**
|
||||
- [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs)
|
||||
|
||||
## Dependency Analysis
|
||||
- HueEntryControl depends on:
|
||||
- UO Hues data for validation constraints
|
||||
- HuePickerWindow for visual selection
|
||||
- Consumers (Dress/Autoloot tabs) for binding and application of colors
|
||||
- Avalonia converter is decoupled but can be used alongside HueEntryControl for preview rendering in Avalonia contexts.
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
HEC["HueEntryControl"] --> HUES["Hues"]
|
||||
HEC --> HPW["HuePickerWindow"]
|
||||
DTC["DressTabControl"] --> HEC
|
||||
ATC["AutolootTabControl"] --> HEC
|
||||
CONV["HueEntryToRectanglesValueConverter"] -.-> HEC
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [HueEntryControl.xaml.cs](file://ClassicAssist/UI/Controls/HueEntryControl.xaml.cs)
|
||||
- [HuePickerWindow.xaml.cs](file://ClassicAssist/UI/Views/HuePickerWindow.xaml.cs)
|
||||
- [DressTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/DressTabControl.xaml.cs)
|
||||
- [AutolootTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/AutolootTabControl.xaml.cs)
|
||||
- [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs)
|
||||
- [Hues.cs](file://ClassicAssist.Shared/UO/Data/Hues.cs)
|
||||
|
||||
**Section sources**
|
||||
- [HueEntryControl.xaml.cs](file://ClassicAssist/UI/Controls/HueEntryControl.xaml.cs)
|
||||
- [HuePickerWindow.xaml.cs](file://ClassicAssist/UI/Views/HuePickerWindow.xaml.cs)
|
||||
- [DressTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/DressTabControl.xaml.cs)
|
||||
- [AutolootTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/AutolootTabControl.xaml.cs)
|
||||
- [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs)
|
||||
- [Hues.cs](file://ClassicAssist.Shared/UO/Data/Hues.cs)
|
||||
|
||||
## Performance Considerations
|
||||
- Avoid excessive recomputation during rapid typing by debouncing validation if needed.
|
||||
- Keep preview updates lightweight; prefer direct brush updates rather than full layout passes.
|
||||
- Cache hue-to-color mappings where appropriate to reduce conversion overhead.
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
|
||||
## Troubleshooting Guide
|
||||
Common issues and resolutions:
|
||||
- Invalid hue value: Ensure IsValid is checked before applying colors. Review UO hue constraints in shared data.
|
||||
- Preview not updating: Confirm bindings are two-way and that HueValue changes raise notifications.
|
||||
- Picker not returning value: Verify HuePickerWindow communication path and that the selected hue is assigned back to HueValue.
|
||||
- Accessibility concerns: Add textual hue labels and ensure sufficient contrast for color-blind users.
|
||||
|
||||
**Section sources**
|
||||
- [HueEntryControl.xaml.cs](file://ClassicAssist/UI/Controls/HueEntryControl.xaml.cs)
|
||||
- [HuePickerWindow.xaml.cs](file://ClassicAssist/UI/Views/HuePickerWindow.xaml.cs)
|
||||
- [Hues.cs](file://ClassicAssist.Shared/UO/Data/Hues.cs)
|
||||
|
||||
## Conclusion
|
||||
HueEntryControl offers a robust, user-friendly way to manage UO hue values with immediate visual feedback and strict validation. Its integration with HuePickerWindow enhances usability, while consumers like DressTabControl and AutolootTabControl demonstrate practical applications. By following the provided guidelines and leveraging the documented properties and behaviors, developers can implement reliable color selection experiences tailored to Ultima Online’s color system.
|
||||
|
||||
[No sources needed since this section summarizes without analyzing specific files]
|
||||
|
||||
## Appendices
|
||||
|
||||
### Example Scenarios
|
||||
- Binding to a game object’s color: Bind HueValue to the object’s color property and use IsValid to guard updates.
|
||||
- Validating UO-specific hue values: Use the shared Hues data to enforce constraints and provide clear error feedback.
|
||||
- Integrating with dress manager: Use HueEntryControl in dress rules to let users pick item colors safely.
|
||||
- Integrating with autoloot systems: Apply hue validation to autoloot conditions to avoid invalid configurations.
|
||||
|
||||
[No sources needed since this section provides conceptual examples]
|
||||
Reference in New Issue
Block a user