init
This commit is contained in:
@@ -0,0 +1,242 @@
|
||||
---
|
||||
source_files:
|
||||
- Common/DTS.Common/RibbonControl/Classes/ButtonData.cs
|
||||
- Common/DTS.Common/RibbonControl/Classes/SeparatorData.cs
|
||||
- Common/DTS.Common/RibbonControl/Classes/GalleryItemData.cs
|
||||
- Common/DTS.Common/RibbonControl/Classes/ComboBoxData.cs
|
||||
- Common/DTS.Common/RibbonControl/Classes/MenuItemData.cs
|
||||
- Common/DTS.Common/RibbonControl/Classes/SplitMenuItemData.cs
|
||||
- Common/DTS.Common/RibbonControl/Classes/ApplicationMenuItemData.cs
|
||||
- Common/DTS.Common/RibbonControl/Classes/ApplicationSplitMenuItemData.cs
|
||||
- Common/DTS.Common/RibbonControl/Classes/TextBoxData.cs
|
||||
- Common/DTS.Common/RibbonControl/Classes/CheckBoxData.cs
|
||||
- Common/DTS.Common/RibbonControl/Classes/RadioButtonData.cs
|
||||
- Common/DTS.Common/RibbonControl/Classes/ToggleButtonData.cs
|
||||
- Common/DTS.Common/RibbonControl/Classes/SplitButtonData.cs
|
||||
- Common/DTS.Common/RibbonControl/Classes/ContextualTabGroupData.cs
|
||||
- Common/DTS.Common/RibbonControl/Classes/ViewModel.cs
|
||||
- Common/DTS.Common/RibbonControl/Classes/GalleryCategoryData.cs
|
||||
- Common/DTS.Common/RibbonControl/Classes/TabData.cs
|
||||
- Common/DTS.Common/RibbonControl/Classes/RibbonData.cs
|
||||
- Common/DTS.Common/RibbonControl/Classes/GalleryData.cs
|
||||
- Common/DTS.Common/RibbonControl/Classes/ControlData.cs
|
||||
- Common/DTS.Common/RibbonControl/Classes/MenuButtonData.cs
|
||||
- Common/DTS.Common/RibbonControl/Classes/GroupData.cs
|
||||
generated_at: "2026-04-16T03:24:01.428865+00:00"
|
||||
model: "Qwen/Qwen3-Coder-Next-FP8"
|
||||
schema_version: 1
|
||||
sha256: "1a23dab67957c1ec"
|
||||
---
|
||||
|
||||
# RibbonControl Data Model Documentation
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This module defines the data model layer for a ribbon UI control framework. It provides a hierarchy of data classes that represent the structure and state of ribbon UI elements—including tabs, groups, controls, menus, galleries, and context-aware groupings—enabling data binding and declarative UI construction. The classes are designed to support MVVM patterns through `INotifyPropertyChanged` implementations and command binding, with static default data generation via `ViewModelData` for design-time and testing scenarios. The module serves as the backend data contract for a WPF-based ribbon control implementation.
|
||||
|
||||
## 2. Public Interface
|
||||
|
||||
### Core Data Classes
|
||||
|
||||
#### `ButtonData`
|
||||
- **Inherits from**: `ControlData`
|
||||
- **Description**: Represents a standard button control in the ribbon. No additional properties beyond those inherited from `ControlData`.
|
||||
|
||||
#### `SeparatorData`
|
||||
- **Inherits from**: `ControlData`
|
||||
- **Description**: Represents a visual separator between controls. No additional properties beyond `ControlData`.
|
||||
|
||||
#### `GalleryItemData`
|
||||
- **Inherits from**: `ControlData`
|
||||
- **Description**: Represents an individual item within a gallery. No additional properties beyond `ControlData`.
|
||||
|
||||
#### `ComboBoxData`
|
||||
- **Inherits from**: `MenuButtonData`
|
||||
- **Description**: Represents a combo box control. Inherits all properties and behavior from `MenuButtonData`.
|
||||
|
||||
#### `TextBoxData`
|
||||
- **Inherits from**: `ControlData`
|
||||
- **Properties**:
|
||||
- `string Text`: Gets/sets the text content. Raises `PropertyChanged` on change.
|
||||
|
||||
#### `CheckBoxData`
|
||||
- **Inherits from**: `ControlData`
|
||||
- **Properties**:
|
||||
- `bool IsChecked`: Gets/sets the checked state. Raises `PropertyChanged` on change.
|
||||
|
||||
#### `RadioButtonData`
|
||||
- **Inherits from**: `ControlData`
|
||||
- **Properties**:
|
||||
- `bool IsChecked`: Gets/sets the checked state. Raises `PropertyChanged` on change.
|
||||
|
||||
#### `ToggleButtonData`
|
||||
- **Inherits from**: `ControlData`
|
||||
- **Properties**:
|
||||
- `bool IsChecked`: Gets/sets the checked state. Raises `PropertyChanged` on change.
|
||||
|
||||
#### `SplitButtonData`
|
||||
- **Inherits from**: `MenuButtonData`
|
||||
- **Properties**:
|
||||
- `bool IsChecked`: Gets/sets the checked state. Raises `PropertyChanged` on change.
|
||||
- `bool IsCheckable`: Gets/sets whether the button can be toggled. Raises `PropertyChanged` on change.
|
||||
- `ButtonData DropDownButtonData`: Returns a lazily-initialized `ButtonData` instance representing the dropdown portion of the split button.
|
||||
|
||||
#### `MenuItemData`
|
||||
- **Inherits from**: `SplitButtonData`
|
||||
- **Constructors**:
|
||||
- `MenuItemData()`: Calls `this(false)`.
|
||||
- `MenuItemData(bool isApplicationMenu)`: Calls base constructor with `isApplicationMenu`.
|
||||
- **Description**: Represents a menu item. Inherits all properties from `SplitButtonData`.
|
||||
|
||||
#### `SplitMenuItemData`
|
||||
- **Inherits from**: `MenuItemData`
|
||||
- **Constructors**:
|
||||
- `SplitMenuItemData()`: Calls `this(false)`.
|
||||
- `SplitMenuItemData(bool isApplicationMenu)`: Calls base constructor with `isApplicationMenu`.
|
||||
- **Description**: Represents a split menu item (menu item with dropdown). Inherits all properties from `MenuItemData`.
|
||||
|
||||
#### `ApplicationMenuItemData`
|
||||
- **Inherits from**: `MenuItemData`
|
||||
- **Constructors**:
|
||||
- `ApplicationMenuItemData()`: Calls `this(false)`.
|
||||
- `ApplicationMenuItemData(bool isApplicationMenu)`: Calls base constructor with `isApplicationMenu`.
|
||||
- **Description**: Represents a menu item specifically intended for use in the application menu. Inherits all properties from `MenuItemData`.
|
||||
|
||||
#### `ApplicationSplitMenuItemData`
|
||||
- **Inherits from**: `SplitMenuItemData`
|
||||
- **Constructors**:
|
||||
- `ApplicationSplitMenuItemData()`: Calls `this(false)`.
|
||||
- `ApplicationSplitMenuItemData(bool isApplicationMenu)`: Calls base constructor with `isApplicationMenu`.
|
||||
- **Description**: Represents a split menu item for the application menu. Inherits all properties from `SplitMenuItemData`.
|
||||
|
||||
#### `ControlData`
|
||||
- **Base class** for all ribbon control data classes.
|
||||
- **Properties**:
|
||||
- `string Label`
|
||||
- `Uri LargeImage`
|
||||
- `Uri SmallImage`
|
||||
- `string ToolTipTitle`
|
||||
- `string ToolTipDescription`
|
||||
- `Uri ToolTipImage`
|
||||
- `string ToolTipFooterTitle`
|
||||
- `string ToolTipFooterDescription`
|
||||
- `Uri ToolTipFooterImage`
|
||||
- `ICommand Command`
|
||||
- `string KeyTip`
|
||||
- All properties raise `PropertyChanged` on change.
|
||||
|
||||
#### `MenuButtonData`
|
||||
- **Inherits from**: `ControlData`
|
||||
- **Constructors**:
|
||||
- `MenuButtonData()`: Calls `this(false)`.
|
||||
- `MenuButtonData(bool isApplicationMenu)`: Initializes with `isApplicationMenu` flag.
|
||||
- **Properties**:
|
||||
- `bool IsVerticallyResizable`
|
||||
- `bool IsHorizontallyResizable`
|
||||
- `ObservableCollection<ControlData> ControlDataCollection`: Lazily-initialized collection containing galleries, menu items, split menu items, and separators (see implementation for exact composition).
|
||||
- **Note**: Uses internal `_nestingDepth` field to limit recursive menu nesting.
|
||||
|
||||
#### `GalleryCategoryData`
|
||||
- **Inherits from**: `ControlData`
|
||||
- **Properties**:
|
||||
- `ObservableCollection<GalleryItemData> GalleryItemDataCollection`: Lazily-initialized collection of 10 `GalleryItemData` instances with default values (label, images, tooltips, command).
|
||||
- **Generic variant** `GalleryCategoryData<T>` also exists with `ObservableCollection<T> GalleryItemDataCollection`.
|
||||
|
||||
#### `GalleryData`
|
||||
- **Inherits from**: `ControlData`
|
||||
- **Properties**:
|
||||
- `ObservableCollection<GalleryCategoryData> CategoryDataCollection`: Lazily-initialized collection of 3 `GalleryCategoryData` instances with default values.
|
||||
- `GalleryItemData SelectedItem`: Gets/sets the selected item. Raises `PropertyChanged` on change.
|
||||
- `bool CanUserFilter`: Gets/sets whether filtering is enabled. Raises `PropertyChanged` on change.
|
||||
- **Generic variant** `GalleryData<T>` also exists with `ObservableCollection<GalleryCategoryData<T>> CategoryDataCollection` and `T SelectedItem`.
|
||||
|
||||
#### `ContextualTabGroupData`
|
||||
- **Implements**: `INotifyPropertyChanged`
|
||||
- **Constructors**:
|
||||
- `ContextualTabGroupData()`: Calls `this(null)`.
|
||||
- `ContextualTabGroupData(string header)`: Initializes with header.
|
||||
- **Properties**:
|
||||
- `string Header`
|
||||
- `bool IsVisible`
|
||||
- `ObservableCollection<TabData> TabDataCollection`: Lazily-initialized collection.
|
||||
- Used to group tabs that appear together under a contextual header.
|
||||
|
||||
#### `TabData`
|
||||
- **Implements**: `INotifyPropertyChanged`
|
||||
- **Constructors**:
|
||||
- `TabData()`: Calls `this(null)`.
|
||||
- `TabData(string header)`: Initializes with header.
|
||||
- **Properties**:
|
||||
- `string Header`
|
||||
- `string ContextualTabGroupHeader`: Associates tab with a `ContextualTabGroupData`.
|
||||
- `bool IsSelected`
|
||||
- `ObservableCollection<GroupData> GroupDataCollection`: Lazily-initialized collection of 3 `GroupData` instances with default values.
|
||||
|
||||
#### `GroupData`
|
||||
- **Inherits from**: `ControlData`
|
||||
- **Constructors**:
|
||||
- `GroupData(string header)`: Sets `Label` to `header`.
|
||||
- **Properties**:
|
||||
- `ObservableCollection<ControlData> ControlDataCollection`: Lazily-initialized collection containing 1 each of `Button`, `ToggleButton`, `RadioButton`, `CheckBox`, `TextBox`, `MenuButton`, `SplitButton`, and `ComboBox` instances with default values.
|
||||
|
||||
#### `RibbonData`
|
||||
- **Implements**: `INotifyPropertyChanged`
|
||||
- **Properties**:
|
||||
- `ObservableCollection<TabData> TabDataCollection`: Lazily-initialized collection of 4 `TabData` instances. First two tabs are associated with contextual tab groups (`Grp 0`, `Grp 1`), remaining two are non-contextual.
|
||||
- `ObservableCollection<ContextualTabGroupData> ContextualTabGroupDataCollection`: Lazily-initialized collection of 2 `ContextualTabGroupData` instances (`Grp 0`, `Grp 1`), all visible.
|
||||
- `MenuButtonData ApplicationMenuData`: Lazily-initialized application menu button with default values.
|
||||
|
||||
### Static Data Provider
|
||||
|
||||
#### `ViewModelData`
|
||||
- **Namespace**: `DTS.Common.RibbonControl`
|
||||
- **Static Properties**:
|
||||
- `RibbonData RibbonData`: Returns a thread-static instance of `RibbonData`.
|
||||
- `ICommand DefaultCommand`: Returns a `DelegateCommand` that always returns `true` for `CanExecute` and does nothing on `Execute`.
|
||||
- **Internal Constants**: Define default counts for UI elements (e.g., `TabCount = 4`, `ControlCount = 5`, etc.).
|
||||
|
||||
## 3. Invariants
|
||||
|
||||
- All data classes inherit from `ControlData` (except `ContextualTabGroupData` and `RibbonData`), ensuring consistent property set (`Label`, `Command`, `SmallImage`, etc.) across all controls.
|
||||
- `ControlData` properties follow a strict pattern: change detection via reference equality (`==`) before raising `PropertyChanged`.
|
||||
- `ControlDataCollection` properties in `MenuButtonData`, `GroupData`, `GalleryCategoryData`, and `GalleryData` are lazily initialized and populated only once per instance (no re-initialization on subsequent access).
|
||||
- `RibbonData.TabDataCollection` and `ContextualTabGroupDataCollection` are lazily initialized and populated exactly once per instance.
|
||||
- `ViewModelData.RibbonData` uses `[ThreadStatic]`, meaning each thread gets its own independent `RibbonData` instance.
|
||||
- Menu nesting depth is limited to `ViewModelData.MenuItemNestingCount` (value `2`) in `MenuButtonData.ControlDataCollection` via internal `_nestingDepth` tracking.
|
||||
- `IsCheckable` is explicitly set to `true` only for `SplitButtonData` and `SplitMenuItemData` instances in `GroupData` and `MenuButtonData` respectively.
|
||||
- `IsApplicationMenu` flag is propagated through constructors to `MenuButtonData` and its subclasses (`MenuItemData`, `SplitMenuItemData`, etc.) to influence initialization behavior.
|
||||
|
||||
## 4. Dependencies
|
||||
|
||||
### Internal Dependencies (within module)
|
||||
- All classes reside in `DTS.Common.RibbonControl` namespace.
|
||||
- `ControlData` is the base class for most data classes.
|
||||
- `MenuButtonData` is a base class for `SplitButtonData`, `ComboBoxData`, and `MenuItemData` hierarchy.
|
||||
- `SplitButtonData` is a base class for `SplitMenuItemData` and `ApplicationSplitMenuItemData`.
|
||||
- `MenuItemData` is a base class for `SplitMenuItemData` and `ApplicationMenuItemData`.
|
||||
- `ApplicationMenuItemData` and `ApplicationSplitMenuItemData` extend `MenuItemData` and `SplitMenuItemData` respectively with application-menu-specific semantics.
|
||||
|
||||
### External Dependencies
|
||||
- `System.ComponentModel` (`INotifyPropertyChanged`, `PropertyChangedEventArgs`, `DesignerSerializationVisibilityAttribute`)
|
||||
- `System.Windows.Input` (`ICommand`, `DelegateCommand`)
|
||||
- `System.Collections.ObjectModel` (`ObservableCollection<T>`)
|
||||
- `Prism.Commands` (`DelegateCommand`) — used in `ViewModelData.DefaultCommand`
|
||||
- WPF-specific types: `Uri` (for image paths), `DesignerSerializationVisibility`
|
||||
|
||||
### What depends on this module
|
||||
- UI rendering layer (not included in source) — consumes these data classes to bind to WPF controls.
|
||||
- Test or design-time code — uses `ViewModelData` to generate sample data.
|
||||
|
||||
## 5. Gotchas
|
||||
|
||||
- **Thread-Safe Data Isolation**: `ViewModelData.RibbonData` uses `[ThreadStatic]`, meaning each thread gets its own `RibbonData` instance. This may cause unexpected behavior if data is expected to be shared across threads.
|
||||
- **Hardcoded Default Values**: Many collections (`GroupData.ControlDataCollection`, `GalleryCategoryData.GalleryItemDataCollection`, etc.) are populated with hardcoded default values (e.g., `"Paste_16x16.png"`, `"ToolTip Title"`). These are not configurable via public API.
|
||||
- **One-Time Initialization**: Collections like `TabData.GroupDataCollection` and `GroupData.ControlDataCollection` are initialized only once. Modifying the collection after first access will not trigger re-initialization, but adding/removing items is allowed.
|
||||
- **Nesting Depth Limitation**: `MenuButtonData.ControlDataCollection` stops populating menu items after `_nestingDepth` reaches `ViewModelData.MenuItemNestingCount` (2). This limit is internal and not exposed.
|
||||
- **`IsCheckable` Not Universal**: Only `SplitButtonData` and `SplitMenuItemData` instances have `IsCheckable = true` set in their default initialization. Regular `ButtonData`, `ToggleButtonData`, etc., do not have this property set (though `ToggleButtonData`, `CheckBoxData`, `RadioButtonData` have `IsChecked`).
|
||||
- **`GalleryData.SelectedItem` Type Mismatch**: The non-generic `GalleryData` uses `GalleryItemData` for `SelectedItem`, while the generic `GalleryData<T>` uses `T`. Ensure type consistency when using the generic variant.
|
||||
- **`ContextualTabGroupHeader` Not Enforced**: `TabData.ContextualTabGroupHeader` is a string property; there is no validation ensuring it matches an actual `ContextualTabGroupData.Header`.
|
||||
- **`Command` Not Used in Default Logic**: While `Command` properties are set to `ViewModelData.DefaultCommand` in default data, there is no logic in these classes to invoke or validate the command.
|
||||
- **No Public Constructors for Generic Types**: Generic classes (`GalleryCategoryData<T>`, `GalleryData<T>`) lack custom constructors, limiting initialization flexibility.
|
||||
|
||||
None identified from source alone.
|
||||
@@ -0,0 +1,64 @@
|
||||
---
|
||||
source_files:
|
||||
- Common/DTS.Common/RibbonControl/Interface/IRibbonView.cs
|
||||
- Common/DTS.Common/RibbonControl/Interface/IRibbonTabInfoProvider.cs
|
||||
- Common/DTS.Common/RibbonControl/Interface/IRibbonViewModel.cs
|
||||
generated_at: "2026-04-16T03:24:19.205461+00:00"
|
||||
model: "Qwen/Qwen3-Coder-Next-FP8"
|
||||
schema_version: 1
|
||||
sha256: "56a9616e313238db"
|
||||
---
|
||||
|
||||
# Interface
|
||||
|
||||
## Documentation: RibbonControl Interface Module
|
||||
|
||||
### 1. Purpose
|
||||
This module defines foundational interfaces for the ribbon UI control layer within the DTS system. It establishes a contract-based abstraction for ribbon-related view and view model components, enabling separation of concerns between UI presentation (via `IRibbonView`) and business logic/data (via `IRibbonViewModel`), while supporting tab identification through `IRibbonTabInfoProvider`. The interfaces are part of a larger MVVM (Model-View-ViewModel) architecture, inheriting from base interfaces (`IBaseView`, `IBaseViewModel`) to ensure consistency across the application’s UI framework.
|
||||
|
||||
### 2. Public Interface
|
||||
|
||||
- **`IRibbonView`**
|
||||
```csharp
|
||||
public interface IRibbonView : IBaseView
|
||||
```
|
||||
Represents the view layer for the ribbon control. It inherits from `IBaseView`, implying it participates in the base view lifecycle and contract (e.g., data binding, lifecycle events), though its specific behavior is not defined here. No additional members beyond inheritance.
|
||||
|
||||
- **`IRibbonTabInfoProvider`**
|
||||
```csharp
|
||||
public interface IRibbonTabInfoProvider
|
||||
{
|
||||
string RibbonTabUid { get; }
|
||||
}
|
||||
```
|
||||
Provides a standardized way to retrieve a unique identifier (`RibbonTabUid`) for a ribbon tab. Implementers expose this read-only property to allow consumers (e.g., tab management logic) to locate or reference a specific ribbon tab unambiguously.
|
||||
|
||||
- **`IRibbonViewModel`**
|
||||
```csharp
|
||||
public interface IRibbonViewModel : IBaseViewModel
|
||||
{
|
||||
IRibbonView View { get; }
|
||||
}
|
||||
```
|
||||
Serves as the view model for the ribbon control. It enforces a strict relationship with its associated view via the `View` property, ensuring the view model always exposes its bound view instance. Inherits from `IBaseViewModel`, implying it supports base view model functionality (e.g., property change notification, command handling).
|
||||
|
||||
### 3. Invariants
|
||||
- `IRibbonView` must be implemented by a concrete view class that adheres to the `IBaseView` contract (e.g., implements `IBaseView` members like `Initialize`, `Load`, `Unload`, etc., though these are not shown here).
|
||||
- `IRibbonTabInfoProvider.RibbonTabUid` must return a non-null, non-empty string that uniquely identifies a ribbon tab within the application domain.
|
||||
- `IRibbonViewModel.View` must never return `null`; it must always reference a valid instance of a type implementing `IRibbonView`.
|
||||
- All interfaces are part of the `DTS.Common.RibbonControl` namespace and rely on `DTS.Common.Base` for base contracts (`IBaseView`, `IBaseViewModel`).
|
||||
|
||||
### 4. Dependencies
|
||||
- **Depends on**:
|
||||
- `DTS.Common.Base` (specifically `IBaseView`, `IBaseViewModel`)
|
||||
- **Depended on by**:
|
||||
- Concrete implementations of ribbon views (e.g., `RibbonView : IRibbonView`)
|
||||
- Concrete implementations of ribbon view models (e.g., `RibbonViewModel : IRibbonViewModel`)
|
||||
- Components responsible for ribbon tab management (e.g., services or controllers that consume `IRibbonTabInfoProvider` to locate tabs)
|
||||
- *Note*: The source files themselves do not indicate direct usage by other modules, but the interfaces are clearly designed for integration into a larger ribbon UI system.
|
||||
|
||||
### 5. Gotchas
|
||||
- **Ambiguity in `IBaseView`/`IBaseViewModel` contracts**: Since `IRibbonView` and `IRibbonViewModel` inherit from `IBaseView` and `IBaseViewModel` respectively, their full contract depends on definitions in `DTS.Common.Base`, which are not provided here. Behavior such as initialization order, lifecycle events, or property change semantics is assumed but not verifiable from this module alone.
|
||||
- **No explicit validation on `RibbonTabUid`**: While the documentation states `RibbonTabUid` is a unique identifier, the interface does not enforce uniqueness at compile time or runtime. Implementers must ensure uniqueness to avoid runtime tab resolution errors.
|
||||
- **No method definitions**: These interfaces are purely declarative (properties only). Any ribbon-specific logic (e.g., tab activation, command binding) is expected to be handled outside this interface layer.
|
||||
- **None identified from source alone.**
|
||||
@@ -0,0 +1,37 @@
|
||||
---
|
||||
source_files:
|
||||
- Common/DTS.Common/RibbonControl/View/RibbonView.cs
|
||||
generated_at: "2026-04-16T03:24:26.685041+00:00"
|
||||
model: "Qwen/Qwen3-Coder-Next-FP8"
|
||||
schema_version: 1
|
||||
sha256: "543fd86e46a59dbd"
|
||||
---
|
||||
|
||||
# View
|
||||
|
||||
## 1. Purpose
|
||||
This module defines a WPF UI control, `RibbonView`, that serves as a concrete implementation of the `IRibbonView` interface within the `DTS.Common.RibbonControl` namespace. It acts as a lightweight wrapper around `UserControl`, intended to represent the view layer of a ribbon-style user interface (e.g., a Microsoft Office-style ribbon tab bar), likely used in conjunction with a corresponding view model via data binding or a similar MVVM pattern.
|
||||
|
||||
## 2. Public Interface
|
||||
- **`public class RibbonView : UserControl, IRibbonView`**
|
||||
A WPF `UserControl` subclass implementing `IRibbonView`. It exposes no additional public members beyond those inherited from `UserControl` and `IRibbonView`. Its sole purpose is to fulfill the contract of `IRibbonView` and serve as a XAML-hosted view element.
|
||||
|
||||
## 3. Invariants
|
||||
- `RibbonView` must be instantiated on the UI thread (as it derives from `UserControl`).
|
||||
- It must be used in a context where `IRibbonView` is expected (e.g., as a view in an MVVM framework that resolves `IRibbonView` to `RibbonView`).
|
||||
- No runtime validation or state management is performed by `RibbonView` itself (per source alone); it is a passive container.
|
||||
|
||||
## 4. Dependencies
|
||||
- **Depends on**:
|
||||
- `System.Windows.Controls` (for `UserControl`)
|
||||
- `DTS.Common.RibbonControl.IRibbonView` (interface it implements; assumed defined elsewhere in the codebase)
|
||||
- **Depended on by**:
|
||||
- Likely a DI container or MVVM framework that maps `IRibbonView` to `RibbonView` for view resolution.
|
||||
- Potentially XAML files (e.g., `RibbonView.xaml`) referencing this type, though not visible in this source.
|
||||
- Other modules in `DTS.Common.RibbonControl` that consume `IRibbonView`.
|
||||
|
||||
## 5. Gotchas
|
||||
- The class is empty beyond inheritance and interface implementation—no logic, properties, or event handlers are defined in this file. Any ribbon-specific behavior must be implemented in `IRibbonView` (e.g., via properties or events defined in the interface) or in associated XAML/code-behind files not included here.
|
||||
- No documentation comments or XML doc comments are present, so consumers must rely on `IRibbonView`’s contract or external documentation.
|
||||
- The absence of a XAML file reference or `InitializeComponent()` call in this source suggests the control may be defined entirely in XAML (with `RibbonView` as the code-behind) or that the XAML is missing from this snippet.
|
||||
- None identified from source alone.
|
||||
@@ -0,0 +1,118 @@
|
||||
---
|
||||
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.
|
||||
Reference in New Issue
Block a user