DP44/enriched-qwen3-coder-next/Common/DTS.Common/RibbonControl/ViewModel.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.Common/RibbonControl/ViewModel/RibbonViewModel.cs	2026-04-16T03:24:21.475189+00:00	Qwen/Qwen3-Coder-Next-FP8	1	09c91cf175024b99

ViewModel

Documentation: RibbonViewModel<TModel>

---

1. Purpose

RibbonViewModel<TModel> is a base view model class for ribbon-based UI views in a Prism-based WPF application. It provides standardized initialization, cleanup, and command infrastructure (e.g., CloseCommand, ConfirmationRequest) for ribbon UI components, while integrating with Prism’s event aggregation (IEventAggregator), region management (IRegionManager), and dependency injection (IUnityContainer). It is designed to be subclassed to implement specific ribbon functionality, enforcing consistent lifecycle management (e.g., Initialize, Cleanup) and status reporting via the ShowStatus event.

---

2. Public Interface

Constructor

• RibbonViewModel(IRibbonView view, IRegionManager regionManager, IEventAggregator eventAggregator, IUnityContainer unityContainer)
  Protected constructor; initializes dependencies and calls CreateCommands(). Not intended for direct instantiation—used by DI container to construct subclasses.

Properties

• TModel Model { get; set; }
  The data model associated with this view model. Set externally (e.g., via navigation parameters or dependency injection).
• IRibbonView View { get; }
  Reference to the associated view (typically set by Prism’s view-first navigation).

Commands

• InteractionRequest<Confirmation> ConfirmationRequest { get; }
  Exposes an interaction request for displaying confirmation dialogs (e.g., “Are you sure?”). Subclasses raise this to prompt user confirmation.
• DelegateCommand<object> CloseCommand { get; }
  Command to close the view/model. Execution triggers CloseMethod(), which calls CleanupAtClose() → Cleanup().

Virtual Methods

• void Activated()
  Called after the view model is activated (e.g., via Prism’s INavigationAware). Default implementation is a no-op; override for activation logic.
• void Initialize()
  Publishes a ShowStatus event with StatusState.Busy and message "Loading" (from Strings.Strings.Loading). Intended for synchronous initialization.
• void Initialize(object parameter)
  Same as Initialize(), but accepts a parameter (currently unused beyond publishing the same busy status).
• void Initialize(object parameter, object model)
  Empty implementation; no behavior defined.
• Task InitializeAsync()
  Async version of Initialize(); dispatches the ShowStatus event on the UI thread via Dispatcher.CurrentDispatcher.InvokeAsync.
• Task InitializeAsync(object parameter)
  Async version of Initialize(object parameter); same behavior as above.
• void Cleanup()
  Sets Model = default(TModel). Override to perform additional cleanup (e.g., unsubscribe from events).
• Task CleanupAsync()
  Returns Task.CompletedTask; no-op. Override for async cleanup logic.

Properties (Public)

• bool IsMenuIncluded { get; set; }
  Controls visibility of the menu section in the ribbon UI. Default: true. Raises PropertyChanged on change.
• bool IsNavigationIncluded { get; set; }
  Controls visibility of the navigation section in the ribbon UI. Default: false. Raises PropertyChanged on change.
• int Percentage { get; set; }
  Likely used for progress indication (no usage in source; no binding context defined).
• string IsBusyMessage { get; set; }
  Stores a custom busy message (no usage in source; likely intended for UI binding).
• bool IsBusy { get; set; }
  Indicates busy state (no usage in source; likely intended for UI binding).
• bool IsDirty { get; set; }
  Indicates whether the model has unsaved changes (no usage in source; likely intended for UI binding).

Note

: IsBusy, IsBusyMessage, Percentage, and IsDirty are defined but not used in this class. Their purpose is inferred from naming but not implemented beyond storage.

---

3. Invariants

• Model may be null (e.g., before initialization or after Cleanup()).
• View is set once during construction and never modified.
• ConfirmationRequest and CloseCommand are initialized in CreateCommands() and never reassigned.
• IsMenuIncluded defaults to true; IsNavigationIncluded defaults to false.
• ShowStatus events published during Initialize* methods always use StatusState.Busy and "Loading" message.
• CloseCommand execution always triggers Cleanup() (synchronously), but Cleanup() does not automatically close the view (no view reference is used to trigger closing).

---

4. Dependencies

Dependencies of RibbonViewModel<TModel>

• Prism Libraries:
  • Prism.Events.IEventAggregator (for ShowStatus event)
  • Prism.Commands.DelegateCommand<T> (for CloseCommand)
  • Prism.Regions.IRegionManager (dependency injection, not used directly in this class)
  • Prism.Interactivity.InteractionRequest<Confirmation> (for ConfirmationRequest)
• Unity Container: IUnityContainer (for DI, not used directly in this class).
• Custom Dependencies:
  • DTS.Common.Base.BasePropertyChanged (base class for INotifyPropertyChanged support)
  • DTS.Common.Events.ShowStatus (event type for status updates)
  • DTS.Common.Interactivity.Confirmation (type for confirmation dialogs)
  • DTS.Common.RibbonControl.IRibbonView (view interface)
  • DTS.Common.Strings.Strings (source of "Loading" string)
• System: System.Threading.Tasks.Task, System.Windows.Threading.Dispatcher.

Dependencies on RibbonViewModel<TModel>

• Subclasses (e.g., RibbonViewModel<SomeModel>) are expected to be registered with Unity and used in Prism navigation.
• IRibbonView implementations likely depend on this view model via data context binding.

---

5. Gotchas

• Initialize(object parameter, object model) is empty — no logic is implemented despite the signature suggesting model injection. Subclasses must override to handle model assignment.
• IsBusy, IsBusyMessage, Percentage, and IsDirty are unused — they exist as properties but are never read/written by this class. Their purpose is unclear without downstream UI bindings.
• CloseCommand does not close the view — it only calls Cleanup(). View closing must be handled externally (e.g., via Prism’s INavigationAware.OnNavigatedFrom() or view-specific logic).
• Dispatcher.CurrentDispatcher may be unsafe — InitializeAsync uses Dispatcher.CurrentDispatcher, which may not be the UI thread dispatcher in non-UI contexts (e.g., background tasks). Prefer Application.Current.Dispatcher if UI thread is guaranteed.
• No validation on Model assignment — Model can be set to any TModel (including null) without checks.
• Cleanup() is synchronous only — CleanupAsync() is a no-op stub. Async cleanup logic must be explicitly overridden.
• No handling of parameter in Initialize(object parameter) — the parameter is ignored despite being passed.
• Activated() is not called automatically — subclasses must ensure it is invoked (e.g., via Prism’s INavigationAware).

None identified beyond the above.