118 lines
7.4 KiB
Markdown
118 lines
7.4 KiB
Markdown
---
|
||
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<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. |