DP44/enriched-qwen3-coder-next/Common/DTS.Common/Interface.md

---
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.