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