217 lines
13 KiB
Markdown
217 lines
13 KiB
Markdown
---
|
||
source_files:
|
||
- Common/DTS.Common/Interface/ITabView.cs
|
||
- Common/DTS.Common/Interface/IMainView.cs
|
||
- Common/DTS.Common/Interface/IMenuView.cs
|
||
- Common/DTS.Common/Interface/IShellView.cs
|
||
- Common/DTS.Common/Interface/INavigationView.cs
|
||
- Common/DTS.Common/Interface/IViewerShellView.cs
|
||
- Common/DTS.Common/Interface/ITabViewModel.cs
|
||
- Common/DTS.Common/Interface/IMenuViewModel.cs
|
||
- Common/DTS.Common/Interface/INavigationViewModel.cs
|
||
- Common/DTS.Common/Interface/IPluginComponent.cs
|
||
- Common/DTS.Common/Interface/IShellViewModel.cs
|
||
- Common/DTS.Common/Interface/IViewerShellViewModel.cs
|
||
- Common/DTS.Common/Interface/IMainViewModel.cs
|
||
- Common/DTS.Common/Interface/IAssemblyInfo.cs
|
||
- Common/DTS.Common/Interface/IDataPROPage.cs
|
||
generated_at: "2026-04-16T02:52:16.683380+00:00"
|
||
model: "Qwen/Qwen3-Coder-Next-FP8"
|
||
schema_version: 1
|
||
sha256: "66a737bed57053a7"
|
||
---
|
||
|
||
# Documentation: DTS.Common.Interface Module
|
||
|
||
## 1. Purpose
|
||
This module defines a set of core interfaces that establish the contract for the application’s view and view model layer within a modular, region-based UI architecture—likely built on WPF given the use of `FrameworkElement`, `ContentControl`, and `ImageSource`. It enforces separation of concerns between UI presentation (`*View` interfaces) and business logic/state management (`*ViewModel` interfaces), while supporting plugin extensibility via `IPluginComponent`. The interfaces collectively enable a structured shell-based UI with distinct regions (e.g., navigation, graph, diagnostics), tabbed content (`ITabView`), menu interaction (`IMenuView`), and specialized viewer contexts (`IViewerShellView`). It serves as the foundational abstraction layer for UI composition and region binding in the DTS system.
|
||
|
||
## 2. Public Interface
|
||
|
||
### Interfaces (No implementation details—only signatures and documented behavior from source)
|
||
|
||
#### View Interfaces
|
||
- **`ITabView : IBaseView`**
|
||
Marker interface for tab-specific views. No additional members beyond base view contract.
|
||
|
||
- **`IMainView : IBaseView`**
|
||
Marker interface for the main application view. No additional members beyond base view contract.
|
||
|
||
- **`IMenuView : IBaseView`**
|
||
Marker interface for menu-specific views. No additional members beyond base view contract.
|
||
|
||
- **`IShellView : IBaseWindow`**
|
||
Marker interface for the main application shell window. Inherits from `IBaseWindow`, implying window-level responsibilities.
|
||
|
||
- **`INavigationView : IBaseView`**
|
||
Marker interface for navigation UI components. No additional members beyond base view contract.
|
||
|
||
- **`IViewerShellView : IBaseView`**
|
||
Marker interface for a dedicated viewer shell view. Inherits from `IBaseView`, not `IBaseWindow`, suggesting it may be hosted within another window.
|
||
|
||
#### ViewModel 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 navigation view instance (note: property name differs from `View` used in other view models).
|
||
|
||
- **`IShellViewModel : IBaseWindowModel`**
|
||
- `IShellView View { get; }`
|
||
Returns the shell view instance.
|
||
- `List<FrameworkElement> GetRegions();`
|
||
Returns a list of `FrameworkElement` instances representing named UI regions (e.g., for region injection).
|
||
- `object ContextMainRegion { get; set; }`
|
||
Gets/sets the data context bound to the main shell region.
|
||
|
||
- **`IViewerShellViewModel : IBaseViewModel`**
|
||
- `IViewerShellView View { get; }`
|
||
Returns the viewer shell view instance.
|
||
- `List<FrameworkElement> GetRegions();`
|
||
Returns a list of `FrameworkElement` instances representing viewer-specific UI regions.
|
||
- `object ContextMainRegion { get; set; }`
|
||
Gets/sets the data context for the viewer’s main region.
|
||
|
||
- **`IMainViewModel : IBaseViewModel`**
|
||
- `IBaseView View { get; }`
|
||
Returns the main view instance.
|
||
- `object ContextNavigationRegion { get; set; }`
|
||
- `object ContextGraphRegion { get; set; }`
|
||
- `object ContextTestsRegion { get; set; }`
|
||
- `object ContextGraphsRegion { get; set; }`
|
||
- `object ContextLegendRegion { get; set; }`
|
||
- `object ContextDiagRegion { get; set; }`
|
||
- `object ContextStatsRegion { get; set; }`
|
||
- `object ContextCursorRegion { get; set; }`
|
||
- `object ContextPropertyRegion { get; set; }`
|
||
Gets/sets data contexts for multiple named regions.
|
||
- `List<FrameworkElement> GetRegions();`
|
||
Returns a list of `FrameworkElement` instances representing all main view regions.
|
||
|
||
#### Plugin & Assembly Interfaces
|
||
- **`IPluginComponent`**
|
||
- `string ProgId { get; }`
|
||
Unique programmatic identifier used to instantiate the plugin component.
|
||
|
||
- **`IAssemblyImageAttribute`**
|
||
Interface for assembly-level metadata about images:
|
||
- `string AssemblyName { get; }`
|
||
- `BitmapImage AssemblyImage { get; }`
|
||
- `eAssemblyRegion AssemblyRegion { get; }`
|
||
- `Type GetType();`
|
||
- `BitmapImage GetAssemblyImage();`
|
||
- `string GetAssemblyName();`
|
||
- `eAssemblyRegion GetAssemblyRegion();`
|
||
|
||
- **`ImageAttribute : Attribute, IAssemblyImageAttribute`**
|
||
Abstract base class for assembly-level image attributes. Defines contract for `[assembly: Image(...)]` usage.
|
||
|
||
- **`IAssemblyNameAttribute`**
|
||
Interface for assembly-level name metadata:
|
||
- `string AssemblyName { get; }`
|
||
- `Type GetType();`
|
||
- `string GetAssemblyName();`
|
||
|
||
- **`TextAttribute : Attribute, IAssemblyNameAttribute`**
|
||
Abstract base class for assembly-level text/name attributes.
|
||
|
||
#### DataPRO Page Interface
|
||
- **`IDataPROPage : INotifyPropertyChanged`**
|
||
Defines contract for a UI page in the DataPRO workflow. Includes:
|
||
- **Properties**:
|
||
- `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; }` *(read-only)*
|
||
- `bool UsesNAVControl { get; set; }`
|
||
- `bool UsesSearchControl { get; set; }`
|
||
- `bool UsesSelectControl { get; set; }`
|
||
- `bool HasBackButton { get; set; }`
|
||
- `bool HasRefreshButton { get; set; }`
|
||
- `bool HasCancelButton { get; set; }`
|
||
- `bool HasSaveButton { get; set; }`
|
||
- `bool HasNextButton { get; set; }`
|
||
- `Color TileColor { get; }` *(read-only)*
|
||
- `Color ContentBackgroundColor { get; set; }`
|
||
- `object MainContent { get; set; }`
|
||
- `bool ControlInOnSetActive { get; set; }`
|
||
- **Methods**:
|
||
- `string GetName();`
|
||
- `long GetID();`
|
||
- `void SetID(long id);`
|
||
- `void SetTileColor(Color c);`
|
||
- `void SavePage(object obj);`
|
||
- `void ClearSearchTerm();`
|
||
- `void SetEnabled(bool bEnable);`
|
||
- `void VerifyProgress(object o);`
|
||
- `void SaveAndExit();`
|
||
- `void RefreshButtonPressed();`
|
||
- `void SetDoneButtonIsEnabled(bool bEnabled);`
|
||
- `void SetBackButtonIsEnabled(bool bEnabled);`
|
||
- `void DoneButtonPress();`
|
||
- `void SetCancelEnabled(bool bEnabled);`
|
||
- `bool Validate(ref List<string> errors, ref List<string> warnings, bool displayWindow);`
|
||
- `bool OKToProceed();`
|
||
- `void FormClosing(Action OnComplete = null);`
|
||
- `void OnSetActive();`
|
||
- `void UnSet();`
|
||
- `void SetCurrentItem(object o);`
|
||
- `void SetupPageAvailable();`
|
||
- `ContentControl GetMainContentControl();`
|
||
- `void SetReturning();`
|
||
|
||
- **`DataProPageProperties`**
|
||
Enum listing properties on `IDataPROPage` that may change and require observation or reaction. 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 `*ViewModel` interface exposes a strongly-typed `View` (or `NavigationView` in `INavigationViewModel`) property, implying a 1:1 pairing between view models and their corresponding views.
|
||
- **Region Contract**: `GetRegions()` methods in `IShellViewModel`, `IViewerShellViewModel`, and `IMainViewModel` must return a list of `FrameworkElement` instances that correspond to named UI regions (e.g., for Prism-style region injection or custom region management).
|
||
- **Context Region Binding**: All shell/view model interfaces expose `ContextMainRegion` (or multiple `Context*Region` properties in `IMainViewModel`) to bind data contexts to regions. These are `object`-typed, allowing arbitrary data contexts.
|
||
- **Plugin Identity**: `IPluginComponent.ProgId` must be unique per plugin instance and used for instantiation.
|
||
- **Assembly Metadata**: `ImageAttribute` and `TextAttribute` are assembly-level attributes (via `[AttributeUsage(AttributeTargets.Assembly)]`), meaning they apply to the entire assembly, not individual types.
|
||
- **DataPRO Page Lifecycle**: `IDataPROPage` implements `INotifyPropertyChanged`, indicating reactive updates to its properties. Methods like `OnSetActive`, `UnSet`, `FormClosing`, and `Validate` suggest a managed page lifecycle (e.g., activation/deactivation, validation before proceeding).
|
||
- **Read-Only Properties**: `UniqueId` (in `IDataPROPage`) and `TileColor` (read-only via getter only) are not settable externally, implying they are determined internally or at construction.
|
||
|
||
## 4. Dependencies
|
||
|
||
### Internal Dependencies
|
||
- **`DTS.Common.Base` namespace**: All interfaces inherit from `IBaseView`, `IBaseWindow`, `IBaseViewModel`, or `IBaseWindowModel`. The concrete implementations of these base contracts are not provided here, but their existence is required.
|
||
- **WPF Types**: `System.Windows`, `System.Windows.Controls`, `System.Windows.Media`, `System.Windows.Media.Imaging` — used in `IViewerShellView`, `IShellViewModel`, `IViewerShellViewModel`, `IMainViewModel`, and `IDataPROPage`.
|
||
- **System.Collections.Generic, System.ComponentModel, System**: Used for `List<T>`, `INotifyPropertyChanged`, `Attribute`, etc.
|
||
|
||
### External Dependencies
|
||
- **WPF Framework**: Required for `FrameworkElement`, `ContentControl`, `ImageSource`, `Color`, `BitmapImage`, and `Visibility`.
|
||
- **.NET Standard/CLR**: Standard libraries (`System`, `System.Collections.Generic`, `System.ComponentModel`, `System.Windows`, etc.).
|
||
|
||
### Inferred Consumers
|
||
- UI framework code (e.g., Prism or custom region manager) likely consumes `GetRegions()` and `Context*Region` properties to bind views to regions.
|
||
- Plugin loader/manager likely consumes `IPluginComponent.ProgId` to instantiate plugins.
|
||
- Assembly loader or metadata processor consumes `ImageAttribute`/`TextAttribute` via reflection.
|
||
- DataPRO page host (e.g., a wizard or workflow engine) consumes `IDataPROPage` for page lifecycle and validation.
|
||
|
||
## 5. Gotchas
|
||
|
||
- **Inconsistent Property Naming**: `INavigationViewModel` exposes `NavigationView` instead of `View`, unlike other view models (`ITabViewModel`, `IMenuViewModel`, etc.). This may cause confusion in generic view model consumers.
|
||
- **`IViewerShellView` Inheritance**: `IViewerShellView` inherits from `IBaseView`, not `IBaseWindow`, while `IShellView` inherits from `IBaseWindow`. This suggests `IViewerShellView` is *not* a top-level window, but a hosted control—despite its name implying "shell".
|
||
- **`GetRegions()` Return Type**: All `GetRegions()` methods return `List<FrameworkElement>`, but no contract specifies how these elements map to named regions (e.g., by name, index, or metadata). Consumers must infer region identity externally.
|
||
- **`Context*Region` Types**: All context properties are `object`, offering flexibility but no compile-time safety. Mis-typing a context value could cause runtime binding failures.
|
||
- **`IDataPROPage` Property Count**: 20+ properties and 20+ methods suggest a highly stateful, complex interface. This may indicate tight coupling and difficulty in testing or mocking.
|
||
- **`GenerateReportsVisible` in `DataProPageProperties`**: This enum value is listed in `DataProPageProperties`, but no corresponding property exists in `IDataPROPage`. This mismatch suggests incomplete synchronization or a documentation error.
|
||
- **No Default Implementations**: All interfaces are pure contracts with no default behavior. Consumers must implement all members, including `FormClosing` with optional parameter—requiring careful handling in languages or tools that do not support optional parameters in interfaces.
|
||
- **`GetType()` in Attribute Interfaces**: `IAssemblyImageAttribute` and `IAssemblyNameAttribute` both declare `Type GetType();`, which is redundant with `object.GetType()` and may conflict with the inherited `System.Object.GetType()`—potentially causing ambiguity or requiring explicit interface implementation. |