195 lines
13 KiB
Markdown
195 lines
13 KiB
Markdown
---
|
||
source_files:
|
||
- Common/DTS.CommonCore/Interface/ITabView.cs
|
||
- Common/DTS.CommonCore/Interface/IMainView.cs
|
||
- Common/DTS.CommonCore/Interface/IMenuView.cs
|
||
- Common/DTS.CommonCore/Interface/IShellView.cs
|
||
- Common/DTS.CommonCore/Interface/INavigationView.cs
|
||
- Common/DTS.CommonCore/Interface/IViewerShellView.cs
|
||
- Common/DTS.CommonCore/Interface/ITabViewModel.cs
|
||
- Common/DTS.CommonCore/Interface/IMenuViewModel.cs
|
||
- Common/DTS.CommonCore/Interface/INavigationViewModel.cs
|
||
- Common/DTS.CommonCore/Interface/IPluginComponent.cs
|
||
- Common/DTS.CommonCore/Interface/IShellViewModel.cs
|
||
- Common/DTS.CommonCore/Interface/IViewerShellViewModel.cs
|
||
- Common/DTS.CommonCore/Interface/IMainViewModel.cs
|
||
- Common/DTS.CommonCore/Interface/IAssemblyInfo.cs
|
||
- Common/DTS.CommonCore/Interface/IDataPROPage.cs
|
||
generated_at: "2026-04-16T02:12:22.294556+00:00"
|
||
model: "Qwen/Qwen3-Coder-Next-FP8"
|
||
schema_version: 1
|
||
sha256: "c067eaab6be3056e"
|
||
---
|
||
|
||
# DTS.Common.Interface Module Documentation
|
||
|
||
## 1. Purpose
|
||
This module defines a set of core interfaces that establish the contract for the application’s view and view model layer within the DTS (Data Test System) architecture. It enforces a structured separation of concerns using a view/view model pattern, where each view interface (`ITabView`, `IMainView`, `IMenuView`, `INavigationView`, `IShellView`, `IViewerShellView`) corresponds to a specific UI region or shell, and each view model interface (`ITabViewModel`, `IMainViewModel`, etc.) exposes its associated view and manages region-specific context (e.g., `ContextMainRegion`, `ContextNavigationRegion`). Additionally, it provides infrastructure for plugin discovery (`IPluginComponent`) and assembly-level metadata (`IAssemblyInfo`), as well as a detailed contract for data entry pages (`IDataPROPage`). The module serves as the foundational abstraction layer for UI composition and plugin extensibility.
|
||
|
||
## 2. Public Interface
|
||
|
||
### Interfaces (No implementation classes provided; only contracts)
|
||
|
||
#### View Interfaces
|
||
- **`ITabView : IBaseView`**
|
||
Represents a tab-specific view. No additional members beyond inheritance.
|
||
|
||
- **`IMainView : IBaseView`**
|
||
Represents the main application view. No additional members beyond inheritance.
|
||
|
||
- **`IMenuView : IBaseView`**
|
||
Represents a menu-specific view. No additional members beyond inheritance.
|
||
|
||
- **`INavigationView : IBaseView`**
|
||
Represents a navigation-specific view. No additional members beyond inheritance.
|
||
|
||
- **`IShellView : IBaseWindow`**
|
||
Represents the top-level shell window view (e.g., main application window). Inherits from `IBaseWindow`, not `IBaseView`.
|
||
|
||
- **`IViewerShellView : IBaseView`**
|
||
Represents a dedicated viewer shell view (e.g., for inspection or preview). Inherits from `IBaseView`.
|
||
|
||
#### View Model Interfaces
|
||
- **`ITabViewModel : IBaseViewModel`**
|
||
- `ITabView View { get; }` — Returns the associated tab view instance.
|
||
|
||
- **`IMenuViewModel : IBaseViewModel`**
|
||
- `IMenuView View { get; }` — Returns the associated menu view instance.
|
||
|
||
- **`INavigationViewModel : IBaseViewModel`**
|
||
- `INavigationView NavigationView { get; }` — Returns the associated navigation view instance.
|
||
|
||
- **`IShellViewModel : IBaseWindowModel`**
|
||
- `IShellView View { get; }` — Returns the associated shell view instance.
|
||
- `List<FrameworkElement> GetRegions()` — Returns a list of named UI regions (e.g., for region injection).
|
||
- `object ContextMainRegion { get; set; }` — Gets/sets the data context for the main region.
|
||
|
||
- **`IViewerShellViewModel : IBaseViewModel`**
|
||
- `IViewerShellView View { get; }` — Returns the associated viewer shell view instance.
|
||
- `List<FrameworkElement> GetRegions()` — Returns a list of named UI regions.
|
||
- `object ContextMainRegion { get; set; }` — Gets/sets the data context for the main region.
|
||
|
||
- **`IMainViewModel : IBaseViewModel`**
|
||
- `IBaseView View { get; }` — Returns the associated main view instance.
|
||
- `object ContextNavigationRegion { get; set; }` — Context for the navigation region.
|
||
- `object ContextGraphRegion { get; set; }` — Context for the graph region.
|
||
- `object ContextTestsRegion { get; set; }` — Context for the tests region.
|
||
- `object ContextGraphsRegion { get; set; }` — Context for the graphs region.
|
||
- `object ContextLegendRegion { get; set; }` — Context for the legend region.
|
||
- `object ContextDiagRegion { get; set; }` — Context for the diagnostics region.
|
||
- `object ContextStatsRegion { get; set; }` — Context for the statistics region.
|
||
- `object ContextCursorRegion { get; set; }` — Context for the cursor region.
|
||
- `object ContextPropertyRegion { get; set; }` — Context for the property region.
|
||
- `List<FrameworkElement> GetRegions()` — Returns a list of named UI regions.
|
||
|
||
#### Plugin & Metadata Interfaces
|
||
- **`IPluginComponent`**
|
||
- `string ProgId { get; }` — Programmatic identifier used to instantiate the plugin component.
|
||
|
||
- **`IAssemblyImageAttribute : Attribute`** *(abstract base class)*
|
||
- `string AssemblyName { get; }`
|
||
- `string AssemblyGroup { get; }`
|
||
- `eAssemblyRegion AssemblyRegion { get; }`
|
||
- `BitmapImage AssemblyImage { get; }`
|
||
- `BitmapImage GetAssemblyImage()`
|
||
- `string GetAssemblyName()`
|
||
- `string GetAssemblyGroup()`
|
||
- `eAssemblyRegion GetAssemblyRegion()`
|
||
- `Type GetAttributeType()`
|
||
*Applied via `[assembly: ImageAttribute(...)]` at assembly level.*
|
||
|
||
- **`IAssemblyNameAttribute : Attribute`** *(abstract base class)*
|
||
- `string AssemblyName { get; }`
|
||
- `string GetAssemblyName()`
|
||
*Applied via `[assembly: TextAttribute(...)]` at assembly level.*
|
||
|
||
#### Data Entry Page Interface
|
||
- **`IDataPROPage : INotifyPropertyChanged`**
|
||
- `Visibility TestSetupChangeButtonVisible { get; set; }`
|
||
- `Visibility AutomaticModeStatusVisible { get; set; }`
|
||
- `string PageName { get; set; }`
|
||
- `ImageSource PageImage { get; set; }`
|
||
- `bool IsAdd { get; set; }`
|
||
- `bool UsesModifyEnhancements { get; set; }`
|
||
- `string EditIDString { get; set; }`
|
||
- `string AddIDString { get; set; }`
|
||
- `string ModifiedObjectName { get; set; }`
|
||
- `bool AutomaticProgression { get; set; }`
|
||
- `bool RecoveryDownloadMode { get; set; }`
|
||
- `string UniqueId { get; }`
|
||
- `string GetName()`
|
||
- `long GetID()`
|
||
- `void SetID(long id)`
|
||
- `Color TileColor { get; }`
|
||
- `void SetTileColor(Color c)`
|
||
- `void SavePage(object obj)`
|
||
- `string CurrentSearchTerm { get; set; }`
|
||
- `void ClearSearchTerm()`
|
||
- `void SetEnabled(bool bEnable)`
|
||
- `bool UsesNAVControl { get; set; }`
|
||
- `bool UsesSearchControl { get; set; }`
|
||
- `bool UsesSelectControl { get; set; }`
|
||
- `void VerifyProgress(object o)`
|
||
- `void SaveAndExit()`
|
||
- `void RefreshButtonPressed()`
|
||
- `void SetDoneButtonIsEnabled(bool bEnabled)`
|
||
- `void SetBackButtonIsEnabled(bool bEnabled)`
|
||
- `void DoneButtonPress()`
|
||
- `bool HasBackButton { get; set; }`
|
||
- `bool HasRefreshButton { get; set; }`
|
||
- `bool HasCancelButton { get; set; }`
|
||
- `bool HasSaveButton { get; set; }`
|
||
- `void SetCancelEnabled(bool bEnabled)`
|
||
- `bool HasNextButton { get; set; }`
|
||
- `Color ContentBackgroundColor { get; set; }`
|
||
- `object MainContent { get; set; }`
|
||
- `ContentControl GetMainContentControl()`
|
||
- `void SetReturning()`
|
||
- `bool Validate(ref List<string> errors, ref List<string> warnings, bool displayWindow)`
|
||
- `bool OKToProceed()`
|
||
- `void FormClosing(Action OnComplete = null)`
|
||
- `bool ControlInOnSetActive { get; set; }`
|
||
- `void OnSetActive()`
|
||
- `void UnSet()`
|
||
- `void SetCurrentItem(object o)`
|
||
- `void SetupPageAvailable()`
|
||
|
||
- **`DataProPageProperties`** *(enum)*
|
||
Lists all properties on `IDataPROPage` that are considered stateful and observable (e.g., for binding or change tracking). Includes:
|
||
`UsesModifyEnhancements`, `TestSetupChangeButtonVisible`, `AutomaticModeStatusVisible`, `PageName`, `PageImage`, `IsAdd`, `EditIDString`, `AddIDString`, `ModifiedObjectName`, `AutomaticProgression`, `RecoveryDownloadMode`, `UsesNAVControl`, `UsesSearchControl`, `UsesSelectControl`, `HasBackButton`, `HasRefreshButton`, `HasCancelButton`, `HasSaveButton`, `HasNextButton`, `ContentBackgroundColor`, `MainContent`, `GenerateReportsVisible`.
|
||
|
||
## 3. Invariants
|
||
|
||
- **View-ViewModel Pairing**: Each view model interface (`*ViewModel`) exposes a strongly-typed `View` property (or `NavigationView` in `INavigationViewModel`) that must return the corresponding view interface instance.
|
||
- **Region Context Management**: `IShellViewModel` and `IViewerShellViewModel` expose `ContextMainRegion`; `IMainViewModel` exposes multiple named region contexts (`ContextNavigationRegion`, `ContextGraphRegion`, etc.). These must be set to valid data contexts before region binding occurs.
|
||
- **Region List Consistency**: `GetRegions()` methods across `IShellViewModel`, `IViewerShellViewModel`, and `IMainViewModel` must return a list of `FrameworkElement` instances representing named regions (e.g., for Prism-style region injection).
|
||
- **Unique Page Identity**: `IDataPROPage.UniqueId` must be non-null and stable for the lifetime of the page instance.
|
||
- **Page State Validation**: `Validate()` must populate `errors` and `warnings` lists and return `false` if validation fails; `OKToProceed()` must reflect whether the page is in a state to proceed (e.g., after validation).
|
||
- **Assembly Attributes**: `ImageAttribute` and `TextAttribute` are assembly-level attributes (`AttributeUsage(AttributeTargets.Assembly, AllowMultiple = false)`), meaning each assembly may define at most one of each.
|
||
- **Inheritance Hierarchy**: All view interfaces inherit from `IBaseView` (or `IBaseWindow` for `IShellView`), and all view model interfaces inherit from `IBaseViewModel` (or `IBaseWindowModel` for `IShellViewModel`). This implies a strict hierarchy enforced by the base layer (`DTS.Common.Base`).
|
||
|
||
## 4. Dependencies
|
||
|
||
### Dependencies *of* this module:
|
||
- `DTS.Common.Base` — Provides base interfaces (`IBaseView`, `IBaseViewModel`, `IBaseWindow`, `IBaseWindowModel`) and likely core types like `eAssemblyRegion`.
|
||
- `System.Windows` — Required for `FrameworkElement`, `BitmapImage`, `Color`, `ContentControl`, and `Visibility`.
|
||
- `System.Collections.Generic`, `System.ComponentModel`, `System.Windows.Media` — Used in `IDataPROPage` and `IAssemblyInfo`.
|
||
|
||
### Dependencies *on* this module:
|
||
- UI composition modules (e.g., shell, navigation, plugin loaders) — These depend on the view/view model interfaces to wire up regions and bind contexts.
|
||
- Plugin infrastructure — Uses `IPluginComponent.ProgId` for dynamic instantiation.
|
||
- Assembly metadata consumers — Use `IAssemblyImageAttribute`/`IAssemblyNameAttribute` (via reflection) to discover plugin metadata.
|
||
- Data entry page host frameworks — Rely on `IDataPROPage` to manage page lifecycle, validation, and UI state.
|
||
|
||
## 5. Gotchas
|
||
|
||
- **`INavigationViewModel.NavigationView` is misnamed**: Despite the interface name, `INavigationViewModel` exposes `INavigationView NavigationView { get; }`, not `INavigationView View { get; }`. This breaks the naming consistency of other view models (e.g., `ITabViewModel.View`).
|
||
- **`IShellView` inherits from `IBaseWindow`, not `IBaseView`**: This is inconsistent with all other view interfaces and may indicate a design distinction for top-level windows vs. nested views.
|
||
- **`IAssemblyImageAttribute` vs. `ImageAttribute`**: `IAssemblyImageAttribute` is an interface, while `ImageAttribute` is its abstract base class. Implementers must inherit from `ImageAttribute`, not implement `IAssemblyImageAttribute` directly.
|
||
- **`GenerateReportsVisible` in `DataProPageProperties` enum but not declared in `IDataPROPage`**: The enum includes `GenerateReportsVisible`, but no corresponding property or method exists in `IDataPROPage`. This is likely an oversight or incomplete refactoring.
|
||
- **Missing `IBaseView`/`IBaseWindow` definitions**: Since the base interfaces are in `DTS.Common.Base`, their contract (e.g., whether `IBaseView` has a `DataContext` property) is unknown and critical to understanding the full interface semantics.
|
||
- **No documentation for `eAssemblyRegion`**: The enum `eAssemblyRegion` is referenced in `IAssemblyImageAttribute` but not defined in this module; its values and semantics are unknown.
|
||
- **`IAssemblyImageAttribute.GetType()` and `GetAttributeType()`**: Both methods exist in `IAssemblyImageAttribute` and `ImageAttribute`. Their purpose is unclear — `GetType()` is standard `object.GetType()`, but `GetAttributeType()` likely returns the concrete attribute type (e.g., `typeof(MyImageAttribute)`). This duplication may cause confusion.
|
||
- **`IDataPROPage` has many mutable properties**: The interface exposes numerous `set` properties (e.g., `PageName`, `PageImage`, `HasBackButton`), implying runtime mutability. This may conflict with MVVM best practices if not carefully managed by view model synchronization.
|
||
|
||
None identified from source alone beyond the above. |