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