--- source_files: - Common/DTS.Common/RibbonControl/ViewModel/RibbonViewModel.cs generated_at: "2026-04-16T03:24:21.475189+00:00" model: "Qwen/Qwen3-Coder-Next-FP8" schema_version: 1 sha256: "09c91cf175024b99" --- # ViewModel ## Documentation: `RibbonViewModel` --- ### 1. Purpose `RibbonViewModel` 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 ConfirmationRequest { get; }`** Exposes an interaction request for displaying confirmation dialogs (e.g., “Are you sure?”). Subclasses raise this to prompt user confirmation. - **`DelegateCommand 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` - **Prism Libraries**: - `Prism.Events.IEventAggregator` (for `ShowStatus` event) - `Prism.Commands.DelegateCommand` (for `CloseCommand`) - `Prism.Regions.IRegionManager` (dependency injection, not used directly in this class) - `Prism.Interactivity.InteractionRequest` (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` - Subclasses (e.g., `RibbonViewModel`) 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.