103 lines
6.4 KiB
Markdown
103 lines
6.4 KiB
Markdown
---
|
||
source_files:
|
||
- Common/DTS.Common/Interface/ISO/ExtraProperties/IExtraPropertiesListView.cs
|
||
- Common/DTS.Common/Interface/ISO/ExtraProperties/IExtraPropertiesListViewModel.cs
|
||
- Common/DTS.Common/Interface/ISO/ExtraProperties/IExtraProperty.cs
|
||
generated_at: "2026-04-16T03:06:05.680006+00:00"
|
||
model: "Qwen/Qwen3-Coder-Next-FP8"
|
||
schema_version: 1
|
||
sha256: "fa52f93f74894066"
|
||
---
|
||
|
||
# ExtraProperties
|
||
|
||
## Documentation: Extra Properties List Module
|
||
|
||
---
|
||
|
||
### 1. Purpose
|
||
This module defines the interface contracts for managing a list of *extra properties*—custom key-value metadata associated with data objects in the ISO data processing pipeline. It provides a standardized view-model and view layer abstraction for displaying, editing, filtering, sorting, and manipulating these properties in a UI (likely WPF, given `ICommand` and `ObservableCollection`). The module exists to decouple UI logic for extra properties from domain-specific implementations, enabling reuse across different ISO data entry or review workflows.
|
||
|
||
---
|
||
|
||
### 2. Public Interface
|
||
|
||
#### `IExtraPropertiesListView`
|
||
- **Inherits**: `IBaseView`
|
||
- **Description**: A marker interface for the view (e.g., XAML user control) that renders the extra properties list. No additional members are defined here; behavior is driven entirely by the view model.
|
||
|
||
#### `IExtraPropertiesListViewModel`
|
||
- **Inherits**: `IBaseViewModel`
|
||
- **Methods & Properties**:
|
||
- `void SetPage(IDataPROPage page)`
|
||
Sets the data context page (likely representing a step or section in a data entry workflow) for the list.
|
||
- `void SetParent(object parent)`
|
||
Assigns a parent object (e.g., a container or parent view model) for navigation or coordination.
|
||
- `IExtraPropertiesListView View { get; set; }`
|
||
Gets or sets the associated view instance (MVVM pattern binding).
|
||
- `void CopySelected()`
|
||
Copies currently selected extra properties to the clipboard (likely in a structured format like CSV or tab-delimited).
|
||
- `void DeleteSelected()`
|
||
Removes the selected extra properties from the list.
|
||
- `ObservableCollection<IExtraProperty> ExtraProperties { get; set; }`
|
||
The collection of extra properties displayed in the list; supports change notification.
|
||
- `void SetExtraProperties(IList<IExtraProperty> properties)`
|
||
Replaces the current `ExtraProperties` collection with a new list of properties.
|
||
- `void Filter(object tag, string term)`
|
||
Filters the list based on `term` (search string), optionally scoped by `tag` (e.g., column or category identifier).
|
||
- `void Sort(object o, bool columnClick)`
|
||
Sorts the list, where `o` likely identifies the sort key (e.g., column header), and `columnClick` indicates if triggered by UI interaction.
|
||
- `bool Validate(ref List<string> errors)`
|
||
Validates all extra properties in the list; returns `false` and populates `errors` if any validation failures occur.
|
||
- `bool IsReadOnly { get; set; }`
|
||
Controls whether the list is editable (`true` = read-only, `false` = editable).
|
||
- `IExtraProperty[] SelectedProperties { get; }`
|
||
Returns an array of currently selected extra properties (read-only; no setter).
|
||
|
||
#### `IExtraProperty`
|
||
- **Inherits**: `INotifyPropertyChanged`
|
||
- **Properties & Commands**:
|
||
- `string Key { get; set; }`
|
||
The property’s name/key (e.g., `"Manufacturer"`, `"BatchID"`).
|
||
- `string Value { get; set; }`
|
||
The property’s value (e.g., `"Acme Corp"`, `"B-2024-001"`).
|
||
- `ICommand PasteCommand { get; set; }`
|
||
A command invoked when pasting data (e.g., multi-row CSV) into a single field. Handles parsing and splitting into multiple properties.
|
||
- `UIItemStatus ItemStatus { get; set; }`
|
||
Indicates UI validation status (e.g., `Success`, `Failed`, `Warning`)—values defined in `DTS.Common.Enums.UIItemStatus`.
|
||
|
||
---
|
||
|
||
### 3. Invariants
|
||
- `ExtraProperties` must be an `ObservableCollection<IExtraProperty>`; direct replacement via `SetExtraProperties` must trigger collection change notifications.
|
||
- `SelectedProperties` is read-only and reflects the *current* selection state at the time of access (no guarantee of immutability beyond the array copy).
|
||
- `IsReadOnly` applies globally to all properties in the list; when `true`, edits to `Key`/`Value` should be blocked.
|
||
- `Validate` must inspect *all* properties in `ExtraProperties` and return `false` if any property fails validation (e.g., empty `Key`, invalid `ItemStatus`).
|
||
- `PasteCommand` is expected to handle multi-row input (e.g., newline- or comma-separated values) and may create/modify multiple `IExtraProperty` instances.
|
||
- `Filter` and `Sort` operations must operate on the *current* `ExtraProperties` collection without mutating the underlying data source (unless explicitly intended).
|
||
|
||
---
|
||
|
||
### 4. Dependencies
|
||
|
||
#### This module depends on:
|
||
- `DTS.Common.Base` (for `IBaseView`, `IBaseViewModel`)
|
||
- `DTS.Common.Enums` (for `UIItemStatus`)
|
||
- Standard .NET types: `System.Collections.ObjectModel.ObservableCollection<T>`, `System.ComponentModel.INotifyPropertyChanged`, `System.Windows.Input.ICommand`
|
||
|
||
#### This module is depended upon by:
|
||
- UI components implementing `IExtraPropertiesListView` (e.g., WPF user controls).
|
||
- View models or services that manage ISO data pages (e.g., `IDataPROPage` implementations) requiring extra property editing.
|
||
- Concrete implementations of `IExtraProperty` (e.g., `ExtraProperty` class in a derived project).
|
||
|
||
---
|
||
|
||
### 5. Gotchas
|
||
- **No explicit thread-safety guarantees**: `ObservableCollection` is not thread-safe; UI updates must occur on the UI thread.
|
||
- **`SetExtraProperties` vs. `ExtraProperties`**: Replacing the collection via `SetExtraProperties` may reset selection state (not specified). Consumers should re-select items if needed.
|
||
- **`Filter` and `Sort` signatures are ambiguous**: `object tag` and `object o` are not typed—likely `string` or `DataGridColumn` in practice, but the interface does not enforce this.
|
||
- **`PasteCommand` behavior is implementation-defined**: While documented as handling multi-row pastes, the exact parsing logic (e.g., delimiters, row/column mapping) is not standardized here.
|
||
- **`SelectedProperties` returns an array**: Calling code must not assume the array is a live view; it is a snapshot.
|
||
- **No error handling contract**: `Validate` populates `errors`, but the interface does not specify whether partial failures are allowed or if validation stops on the first error.
|
||
|
||
None identified beyond the above. |