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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
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	2026-04-16T02:52:16.683380+00:00	Qwen/Qwen3-Coder-Next-FP8	1	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.