DP44/enriched-qwen3-coder-next/Common/DTS.Common/Interface/StatusAndProgressBar.md

---
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.**