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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
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	2026-04-16T03:02:37.844436+00:00	Qwen/Qwen3-Coder-Next-FP8	1	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.