ViewModel

Documentation: `RibbonViewModel<TModel>`

1. Purpose

RibbonViewModel<TModel> is a base view model class for ribbon-based UI views in the DTS application. It provides foundational infrastructure for command handling (e.g., closing), status reporting via Prism’s event aggregation, model binding, and lifecycle management (initialization, activation, cleanup). It is designed to be subclassed by concrete ribbon view models (e.g., for specific ribbon tabs or panels), enforcing consistent behavior across ribbon-related UI components. The generic type parameter TModel allows binding to domain-specific data models while abstracting common ribbon concerns like busy state, dirty state, and UI element visibility toggles.

2. Public Interface

Properties

public TModel Model { get; set; }
Holds the domain model instance bound to this view model. Settable; cleared during Cleanup().
public IRibbonView View { get; }
Reference to the associated view (UI layer), injected via constructor.
public InteractionRequest<Confirmation> ConfirmationRequest { get; }
Prism interaction request used to trigger confirmation dialogs (e.g., “Are you sure?”). Publicly exposed for XAML binding.
public DelegateCommand<object> CloseCommand { get; }
Delegate command bound to UI close actions (e.g., close button). Executes CloseMethod().
public bool IsMenuIncluded { get; set; }
Controls visibility of the menu area in the ribbon UI. Defaults to true. Raises PropertyChanged on change.
public bool IsNavigationIncluded { get; set; }
Controls visibility of the navigation area in the ribbon UI. Defaults to false. Raises PropertyChanged on change.
public int Percentage { get; set; }
Represents progress percentage (e.g., for busy state). No validation or side effects observed.
public string IsBusyMessage { get; set; }
Message displayed during busy state (e.g., “Saving…”). No automatic binding or update logic observed.
public bool IsBusy { get; set; }
Indicates whether the view model is busy. No automatic status event publishing observed on change.
public bool IsDirty { get; set; }
Indicates whether the model has unsaved changes. No automatic dirty-state handling logic observed.

Methods

public virtual void Activated()
Called after the view model is activated (e.g., via Prism region navigation). Default implementation is a no-op; intended for override.
public virtual void Initialize()
Publishes a ShowStatus event with StatusState.Busy and message "Loading" (from Strings.Strings.Loading). Intended for synchronous initialization.
public virtual void Initialize(object parameter)
Same as Initialize(), but accepts a navigation/initialization parameter. Does not use the parameter in current implementation.
public void Initialize(object parameter, object model)
No implementation provided — body is empty. Behavior undefined.
public virtual async Task InitializeAsync()
Async version of Initialize(). Uses Dispatcher.CurrentDispatcher.InvokeAsync() to marshal the ShowStatus event publish to the UI thread.
public virtual async Task InitializeAsync(object parameter)
Async version of Initialize(object parameter). Same marshaling behavior; parameter unused.
public virtual void Cleanup()
Sets Model to default(TModel) (i.e., null for reference types). Intended for releasing resources before disposal.
public Task CleanupAsync()
Throws NotImplementedException — not implemented.
protected virtual void CloseMethod(object parameter)
Invoked by CloseCommand. Calls CleanupAtClose(), which in turn calls Cleanup().
protected virtual void CreateCommands()
Initializes ConfirmationRequest and CloseCommand. Overridable for subclass command registration.

Protected Properties

protected IEventAggregator Aggregator { get; }
Prism event aggregator for publishing/subscribing to events (e.g., ShowStatus).
protected IUnityContainer Container { get; }
Unity DI container, available for resolution in subclasses.
protected IRegionManager RegionManager { get; }
Prism region manager for navigation and region management.

3. Invariants

Model is settable but must be cleared (set to null) before the view model is fully disposed — this is enforced via Cleanup() called during close.
IsMenuIncluded and IsNavigationIncluded default to true and false, respectively, but no runtime validation prevents invalid states.
IsBusy, IsDirty, Percentage, and IsBusyMessage are not automatically synchronized with status events — they are independent properties with no side effects.
Initialize() and InitializeAsync() always publish a Busy status with the hardcoded "Loading" message — no customization or override hook is provided in the base class.
Initialize(object parameter, object model) is unimplemented — calling it has no effect.

4. Dependencies

Imports/Usings

System, System.ComponentModel, System.Threading.Tasks, System.Windows.Threading
DTS.Common.Base (base class BasePropertyChanged)
DTS.Common.Events (contains ShowStatus event and StatusInfo)
Microsoft.Practices.Prism.* (Prism libraries: DelegateCommand, InteractionRequest, Events, Regions, Unity)
Microsoft.Practices.Unity (IUnityContainer)

External Contracts

IRibbonView — expected interface for the associated view (not defined here).
ShowStatus event — published via IEventAggregator during initialization.
StatusInfo — type used to convey status state (Busy, message string).
Strings.Strings.Loading — localized string resource.

Depended-on By

Subclasses of RibbonViewModel<TModel> (e.g., specific ribbon tab view models).
UI layers (XAML) binding to CloseCommand, ConfirmationRequest, IsMenuIncluded, etc.

5. Gotchas

CleanupAsync() is unimplemented — throws NotImplementedException. Subclasses must override or avoid calling it.
Initialize(object parameter, object model) is a stub — no logic or side effects. Passing a model here does nothing.
No automatic IsBusy ↔ status event sync — setting IsBusy = true does not publish a ShowStatus event. Developers must manually publish ShowStatus if using IsBusy.
Percentage, IsBusyMessage, IsDirty are passive properties — they have no built-in integration with status reporting or dirty-state tracking (e.g., no auto-save or validation).
Initialize() methods publish only "Loading" — no way to customize the status message in the base class.
Dispatcher.CurrentDispatcher used in async methods — assumes the view model is created on the UI thread. May fail if instantiated off-thread.
No explicit disposal pattern — relies on Cleanup() being called (e.g., via CloseCommand), but no IDisposable implementation.
No validation on Model assignment — setting Model = null mid-lifecycle is allowed and may leave view in inconsistent state if not handled by subclasses.

None identified beyond the above.

7.4 KiB Raw Permalink Blame History Unescape Escape