91 lines
6.5 KiB
Markdown
91 lines
6.5 KiB
Markdown
---
|
||
source_files:
|
||
- Common/DTS.Common/Interface/StatusAndProgressBar/IStatusAndProgressBarView.cs
|
||
- Common/DTS.Common/Interface/StatusAndProgressBar/IStatusAndProgressFooterView.cs
|
||
- Common/DTS.Common/Interface/StatusAndProgressBar/IStatusAndProgressBarFooterViewModel.cs
|
||
- Common/DTS.Common/Interface/StatusAndProgressBar/IStatusAndProgressBarViewModel.cs
|
||
- Common/DTS.Common/Interface/StatusAndProgressBar/StatusAndProgressDelegates.cs
|
||
generated_at: "2026-04-16T03:02:37.844436+00:00"
|
||
model: "Qwen/Qwen3-Coder-Next-FP8"
|
||
schema_version: 1
|
||
sha256: "bab676b640992f00"
|
||
---
|
||
|
||
# StatusAndProgressBar
|
||
|
||
## Documentation: Status and Progress UI Infrastructure
|
||
|
||
### 1. Purpose
|
||
This module defines the core interfaces and delegates for a status bar and progress bar UI component system, intended to decouple view logic from business logic in a MVVM (Model-View-ViewModel) architecture. It provides a standardized contract for views (`IStatusAndProgressBarView`, `IStatusAndProgressFooterView`) and their associated view models (`IStatusAndProgressBarViewModel`, `IStatusAndProgressBarFooterViewModel`) to manage status text, progress state, and error handling. The delegates (`StatusAndProgressDelegates`) define the callback signatures used to update UI elements programmatically, enabling cross-thread or asynchronous updates in WPF/WinForms environments.
|
||
|
||
---
|
||
|
||
### 2. Public Interface
|
||
|
||
#### Interfaces
|
||
- **`IStatusAndProgressBarView`**
|
||
*Inherits:* `IBaseView`
|
||
*Description:* Marker interface for the primary status and progress bar view. No additional members defined—intended to be implemented by concrete UI controls (e.g., a user control hosting status text and a progress bar).
|
||
|
||
- **`IStatusAndProgressFooterView`**
|
||
*Inherits:* `IBaseView`
|
||
*Description:* Marker interface for a footer-specific status and progress view. Likely used in contexts where status/progress is rendered in a footer region (e.g., bottom of a window or panel).
|
||
|
||
- **`IStatusAndProgressBarViewModel`**
|
||
*Inherits:* `IBaseViewModel`
|
||
*Properties:*
|
||
- `IBaseView View { get; set; }` — Gets or sets the associated view (note: typed as base `IBaseView`, not the more specific `IStatusAndProgressBarView`).
|
||
- `IBaseViewModel Parent { get; set; }` — Gets or sets the parent view model.
|
||
- `string ProgressBarName { get; set; }` — Gets or sets a name/identifier for the progress bar (likely used for binding or region targeting).
|
||
- `object ContextSearchRegion { get; set; }` — Gets or sets a context object used to locate or scope the UI region where the view should be displayed (e.g., a region manager token or control name).
|
||
|
||
- **`IStatusAndProgressBarFooterViewModel`**
|
||
*Inherits:* `IBaseViewModel`
|
||
*Properties:*
|
||
- `IStatusAndProgressFooterView View { get; set; }` — Gets or sets the associated footer view (note: typed more specifically than the parent interface’s `View` property).
|
||
|
||
#### Delegates
|
||
Defined in `StatusAndProgressDelegates.cs` (namespace: `DTS.Common.Interface.StatusAndProgressBar`):
|
||
- `SetProgressValueDelegate(double value)` — Callback to set progress bar value (0.0–100.0 or similar scale).
|
||
- `SetStatusTextDelegate(string text)` — Callback to update status text.
|
||
- `SetProgressVisibilityDelegate(bool bVisible)` — Callback to show/hide the progress bar.
|
||
- `SetStatusColorDelegate(Color color)` — Callback to set status text color (WPF `System.Windows.Media.Color`).
|
||
- `ActionCompleteDelegate()` — Callback invoked when a long-running action completes.
|
||
- `StatusIntDelegate(int status)` — Callback to update status using an integer code (e.g., enum or state ID).
|
||
- `StatusExIntDelegate(int status, params object[] extra)` — Extended status update with additional context data.
|
||
- `ErrorCallback(string errorString, string unit) → DialogResult` — Callback to display an error dialog; returns user’s response (e.g., `OK`, `Retry`).
|
||
|
||
---
|
||
|
||
### 3. Invariants
|
||
- **No explicit validation rules** are defined in the interfaces or delegates themselves. Validation (e.g., `ProgressBarName` non-null, `value` in [0,100]) must be enforced by implementations.
|
||
- **View/ViewModel coupling**: Every view model (`IStatusAndProgressBarViewModel`, `IStatusAndProgressBarFooterViewModel`) requires a corresponding view instance via the `View` property. The view model must be initialized with a valid view before UI updates are safe.
|
||
- **Threading**: Delegates like `SetProgressValueDelegate` and `SetStatusTextDelegate` suggest cross-thread UI updates are expected, but the interfaces do not enforce dispatcher marshaling—implementations must handle thread safety.
|
||
- **No ordering guarantees**: The interfaces do not specify the order in which delegates must be invoked (e.g., visibility change before value update).
|
||
|
||
---
|
||
|
||
### 4. Dependencies
|
||
- **Internal dependencies**:
|
||
- `DTS.Common.Base` (via `IBaseView`, `IBaseViewModel`) — Base abstractions for views and view models.
|
||
- **External dependencies**:
|
||
- `System.Windows.Forms` (for `DialogResult` in `ErrorCallback`)
|
||
- `System.Windows.Media` (for `Color` in `SetStatusColorDelegate`)
|
||
- **Consumers**:
|
||
- Likely consumed by UI modules implementing status/progress views (e.g., `DTS.UI.MainWindow` or `DTS.UI.Workspace`).
|
||
- View models implementing `IStatusAndProgressBarViewModel` would be used by view layers to bind progress/status to UI controls.
|
||
|
||
---
|
||
|
||
### 5. Gotchas
|
||
- **Ambiguous `View` property typing**:
|
||
`IStatusAndProgressBarViewModel.View` is typed as `IBaseView`, while `IStatusAndProgressBarFooterViewModel.View` is typed as `IStatusAndProgressFooterView`. This inconsistency may cause confusion or require casting in implementations.
|
||
- **Missing progress range definition**:
|
||
`ProgressBarName` implies multiple progress bars may exist, but no interface defines how ranges (min/max) or units are configured.
|
||
- **`ContextSearchRegion` purpose unclear**:
|
||
The type `object` and lack of documentation make its usage ambiguous (e.g., is it a region name string, a Prism `IRegion` object, or a custom key?).
|
||
- **No error state handling in interfaces**:
|
||
While `ErrorCallback` exists, the view models lack properties/methods to *trigger* or *clear* error states (e.g., `IsError`, `LastErrorMessage`).
|
||
- **Delegate namespace mismatch**:
|
||
Delegates reside in `DTS.Common.Interface.StatusAndProgressBar` (lowercase `status`), while interfaces use `DTS.Common.Interface` (uppercase `Status`). This may cause namespace resolution issues if not handled consistently.
|
||
- **None identified from source alone.** |