87 lines
6.9 KiB
Markdown
87 lines
6.9 KiB
Markdown
|
---
|
|||
|
|
source_files:
|
|||
|
|
- Common/DTS.CommonCore/Interface/StatusAndProgressBar/IStatusAndProgressBarView.cs
|
|||
|
|
- Common/DTS.CommonCore/Interface/StatusAndProgressBar/IStatusAndProgressFooterView.cs
|
|||
|
|
- Common/DTS.CommonCore/Interface/StatusAndProgressBar/IStatusAndProgressBarFooterViewModel.cs
|
|||
|
|
- Common/DTS.CommonCore/Interface/StatusAndProgressBar/IStatusAndProgressBarViewModel.cs
|
|||
|
|
- Common/DTS.CommonCore/Interface/StatusAndProgressBar/StatusAndProgressDelegates.cs
|
|||
|
|
generated_at: "2026-04-16T02:23:18.111923+00:00"
|
|||
|
|
model: "Qwen/Qwen3-Coder-Next-FP8"
|
|||
|
|
schema_version: 1
|
|||
|
|
sha256: "329090afc20c7c34"
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# 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-like architecture. It enables consistent status reporting (text, color, progress value/visibility) across different parts of the application—particularly in search or long-running operations—by establishing standardized contracts between view models and views. The interfaces `IStatusAndProgressBarViewModel`, `IStatusAndProgressBarFooterViewModel`, and their corresponding view interfaces (`IStatusAndProgressBarView`, `IStatusAndProgressFooterView`) provide the structural foundation for injecting and managing status/progress UI elements, while the delegates in `StatusAndProgressDelegates` define the callback signatures used to drive UI updates imperatively.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 2. Public Interface
|
|||
|
|
|
|||
|
|
#### Interfaces
|
|||
|
|
- **`IStatusAndProgressBarView : IBaseView`**
|
|||
|
|
Marker interface for a view that displays status and progress information. No additional members; inherits from `IBaseView`.
|
|||
|
|
|
|||
|
|
- **`IStatusAndProgressFooterView : IBaseView`**
|
|||
|
|
Marker interface for a footer-specific status/progress view. Inherits from `IBaseView`. Likely used for a dedicated footer region (e.g., bottom of window).
|
|||
|
|
|
|||
|
|
- **`IStatusAndProgressBarViewModel : IBaseViewModel`**
|
|||
|
|
View model for the main status/progress UI.
|
|||
|
|
- `IBaseView View { get; set; }` — Gets or sets the associated view (note: typed as `IBaseView`, *not* `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 mapping).
|
|||
|
|
- `object ContextSearchRegion { get; set; }` — Gets or sets an object representing the search context/region (purpose inferred from name; likely used to scope or correlate search operations).
|
|||
|
|
|
|||
|
|
- **`IStatusAndProgressBarFooterViewModel : IBaseViewModel`**
|
|||
|
|
View model for the footer status/progress UI.
|
|||
|
|
- `IStatusAndProgressFooterView View { get; set; }` — Gets or sets the associated footer view (correctly typed to its specific view interface).
|
|||
|
|
|
|||
|
|
#### Delegates (in `StatusAndProgressDelegates.cs`)
|
|||
|
|
- **`SetProgressValueDelegate(double value)`** — Callback to set the progress bar’s current value.
|
|||
|
|
- **`SetStatusTextDelegate(string text)`** — Callback to update the status text.
|
|||
|
|
- **`SetProgressVisibilityDelegate(bool bVisible)`** — Callback to show/hide the progress bar.
|
|||
|
|
- **`SetStatusColorDelegate(Color color)`** — Callback to set the status text color (uses `System.Windows.Media.Color`).
|
|||
|
|
- **`ActionCompleteDelegate()`** — Callback invoked when an action completes.
|
|||
|
|
- **`StatusIntDelegate(int status)`** — Callback to report a numeric status code.
|
|||
|
|
- **`StatusExIntDelegate(int status, params object[] extra)`** — Extended status callback with additional context.
|
|||
|
|
- **`ErrorCallback(string errorString, string unit) : DialogResult`** — Callback for error reporting; returns a dialog result (e.g., OK/Cancel) to allow user interaction.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 3. Invariants
|
|||
|
|
- All view interfaces (`IStatusAndProgressBarView`, `IStatusAndProgressFooterView`) inherit from `IBaseView`, implying they are part of a unified view hierarchy.
|
|||
|
|
- View models inherit from `IBaseViewModel`, enforcing a consistent base contract.
|
|||
|
|
- `IStatusAndProgressBarViewModel` uses `IBaseView` for its `View` property (not the more specific `IStatusAndProgressBarView`), suggesting either intentional flexibility or a potential inconsistency.
|
|||
|
|
- `IStatusAndProgressBarFooterViewModel` correctly uses `IStatusAndProgressFooterView` for its `View` property, indicating stricter typing for the footer variant.
|
|||
|
|
- No explicit validation rules or ordering guarantees are defined in the interfaces themselves; constraints must be enforced by implementations.
|
|||
|
|
- The `ContextSearchRegion` property implies that this view model is primarily used in search-related workflows, though the type is generic (`object`), allowing broad usage.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 4. Dependencies
|
|||
|
|
|
|||
|
|
#### Dependencies *of* this module:
|
|||
|
|
- `DTS.Common.Base` — Provides `IBaseView` and `IBaseViewModel`, which all interfaces inherit from.
|
|||
|
|
- `System.Windows.Forms` — Referenced for `DialogResult` (used in `ErrorCallback`).
|
|||
|
|
- `System.Windows.Media` — Referenced for `Color` (used in `SetStatusColorDelegate`).
|
|||
|
|
|
|||
|
|
#### Dependencies *on* this module:
|
|||
|
|
- Any module implementing or consuming status/progress UI components (e.g., search modules, long-running operation controllers) will depend on these interfaces and delegates.
|
|||
|
|
- Concrete implementations of `IStatusAndProgressBarViewModel`/`IStatusAndProgressBarFooterViewModel` must bind to views implementing `IStatusAndProgressBarView`/`IStatusAndProgressFooterView`.
|
|||
|
|
- UI layers (e.g., WPF/WinForms views) will depend on the delegate types to register callbacks for status/progress updates.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 5. Gotchas
|
|||
|
|
- **Typing Inconsistency**: `IStatusAndProgressBarViewModel.View` is typed as `IBaseView`, while `IStatusAndProgressBarFooterViewModel.View` is correctly typed as `IStatusAndProgressFooterView`. This may cause confusion or require casting in implementations.
|
|||
|
|
- **Ambiguous `ContextSearchRegion`**: The purpose and expected type of `ContextSearchRegion` is not documented beyond its name. Its usage must be inferred from concrete implementations.
|
|||
|
|
- **No Direct Progress Bar API**: The interfaces themselves do not expose progress bar methods; all updates occur via the delegate callbacks. This is by design but requires consumers to understand the delegate-based update pattern.
|
|||
|
|
- **Mixed UI Frameworks**: Delegates use both `System.Windows.Forms.DialogResult` (WinForms) and `System.Windows.Media.Color` (WPF), suggesting this module may be shared across UI frameworks or used in hybrid applications. This could introduce subtle compatibility issues if not carefully managed.
|
|||
|
|
- **No Error Handling Contract**: While `ErrorCallback` exists, the interfaces do not specify *when* it should be invoked or how errors propagate. This is likely implementation-specific.
|
|||
|
|
- **None identified from source alone.** (Note: The above are *inferred* from inconsistencies and naming, not explicit gotchas in the source.)
|