init

enriched-qwen3-coder-next/Common/DTS.CommonCore/Interface/DTS.Viewer/MainView.md

@@ -0,0 +1,125 @@
+---
+source_files:
+  - Common/DTS.CommonCore/Interface/DTS.Viewer/MainView/IMainView.cs
+  - Common/DTS.CommonCore/Interface/DTS.Viewer/MainView/IViewerMainView.cs
+  - Common/DTS.CommonCore/Interface/DTS.Viewer/MainView/IViewerMainViewGrid.cs
+  - Common/DTS.CommonCore/Interface/DTS.Viewer/MainView/IMainViewModel.cs
+  - Common/DTS.CommonCore/Interface/DTS.Viewer/MainView/IViewerMainViewModel.cs
+generated_at: "2026-04-16T02:33:47.869826+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "95ec9f6198f586ac"
+---
+
+# MainView
+
+## Documentation: Main View & ViewModel Interfaces (`DTS.Common.Interface`)
+
+---
+
+### 1. Purpose  
+This module defines the core interfaces for the main view and view model layers of the DTS viewer application. It establishes a contract between the UI (views) and the presentation logic (view models), enabling separation of concerns and testability. The interfaces `IMainView`, `IViewerMainView`, and `IViewerMainViewGrid` represent distinct view roles, while `IMainViewModel` and `IViewerMainViewModel` encapsulate shared and viewer-specific presentation state and behavior—particularly around region management, navigation context, and user interaction (e.g., keyboard input, zoom, calibration settings). This module exists to standardize how the main application shell and viewer components interact with their view models, especially in contexts involving graphing, diagnostics, and test data.
+
+---
+
+### 2. Public Interface  
+
+#### Interfaces (all in `DTS.Common.Interface` namespace)
+
+| Interface | Inheritance | Description |
+|----------|-------------|-------------|
+| `IMainView` | `IBaseView` | Marker interface for the main application view. No additional members defined. |
+| `IViewerMainView` | `IBaseView` | Marker interface for the viewer-specific main view. No additional members defined. |
+| `IViewerMainViewGrid` | `IBaseView` | Marker interface for a grid-based variant of the viewer main view. No additional members defined. |
+| `IMainViewModel` | `IBaseViewModel` | Base view model for the main application. Manages shared region contexts and exposes a read-only `View` reference. |
+| `IViewerMainViewModel` | `IBaseViewModel`, `ISelectedDataViewModel` | Extended view model for the viewer. Adds viewer-specific state (e.g., `Standalone`, `ConfigPath`, permissions), region context management, zoom/keyboard controls, and calibration/view-mode settings. |
+
+##### `IMainViewModel` Members  
+- `IBaseView View { get; }`  
+  Gets the associated 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 or sets the region object for a named UI region (e.g., for Prism region injection). Each corresponds to a distinct visual area in the main view.  
+- `List<FrameworkElement> GetRegions()`  
+  Returns a list of all region `FrameworkElement`s currently assigned to the view model’s context properties.
+
+##### `IViewerMainViewModel` Members  
+- `IBaseView View { get; set; }`  
+  Gets or sets the associated viewer main view instance. *(Note: Setter differs from `IMainViewModel`)*  
+- `bool Standalone { get; set; }`  
+  Indicates whether the viewer is running in standalone mode.  
+- `string ConfigPath { get; set; }`  
+  Path to the configuration file used by the viewer.  
+- `bool DoesUserHaveEditPermission { get; set; }`  
+  Indicates whether the current user has edit permissions in the viewer.  
+- `Common.Enums.IsoViewMode ChannelCodeViewMode { get; set; }`  
+  Gets or sets the view mode for channel code display (e.g., raw, decoded, etc.).  
+- `Common.Enums.Sensors.CalibrationBehaviors CalibrationBehaviorSetting { get; set; }`  
+  Gets or sets the calibration behavior setting (e.g., auto, manual, disabled).  
+- `bool CalibrationBehaviorSettableInViewer { get; set; }`  
+  Indicates whether the user can change `CalibrationBehaviorSetting` in the viewer UI.  
+- `Visibility SettingsVisibility { get; }`  
+  Gets the visibility state of the settings panel (e.g., `Visible`, `Collapsed`).  
+- `void ZoomReset()`  
+  Resets zoom level(s) in the viewer to default.  
+- `void LeftKeyPress()`  
+  Notifies the view model that the left arrow key was pressed (e.g., for timeline navigation).  
+- `void RightKeyPress()`  
+  Notifies the view model that the right arrow key was pressed.  
+- `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; }`  
+  Identical to `IMainViewModel`; manages region contexts for viewer-specific UI areas.  
+- `List<FrameworkElement> GetRegions()`  
+  Identical to `IMainViewModel`; returns all region `FrameworkElement`s.
+
+---
+
+### 3. Invariants  
+- All view interfaces (`IMainView`, `IViewerMainView`, `IViewerMainViewGrid`) must be implemented by concrete WPF `View` classes (e.g., `UserControl` or `Window` subclasses).  
+- All view model interfaces (`IMainViewModel`, `IViewerMainViewModel`) must be implemented by concrete view models that:  
+  - Implement `IBaseViewModel` (implied by inheritance).  
+  - Maintain non-null `View` references (for `IMainViewModel`) or allow `View` assignment (for `IViewerMainViewModel`).  
+  - Ensure `GetRegions()` returns a list containing exactly the `FrameworkElement`s assigned to the 9 `Context*Region` properties.  
+- `IViewerMainViewModel` extends `ISelectedDataViewModel` (not shown here), implying it must also satisfy that interface’s contract (e.g., data selection state).  
+- `Context*Region` properties are expected to hold region objects (e.g., Prism `IRegion` instances or `FrameworkElement` instances) used for UI composition.
+
+---
+
+### 4. Dependencies  
+
+#### Dependencies *of* this module:  
+- `DTS.Common.Base` (provides `IBaseView`, `IBaseViewModel`, `ISelectedDataViewModel`).  
+- `System.Windows` (for `FrameworkElement`, `Visibility`).  
+- `System.Collections.Generic` (for `List<T>`).  
+- `Common.Enums.IsoViewMode`, `Common.Enums.Sensors.CalibrationBehaviors`, `Visibility` (from `System.Windows`).  
+
+#### Dependencies *on* this module:  
+- Any module implementing or consuming main/viewer views/view models (e.g., `DTS.Viewer`, `DTS.App`, or Prism region navigation logic).  
+- Likely used by view model factories, region managers, or shell layout controllers to wire up UI components.  
+
+---
+
+### 5. Gotchas  
+- **Setter visibility mismatch**: `IMainViewModel.View` is read-only (`get;`), while `IViewerMainViewModel.View` is read-write (`get; set;`). This implies `IViewerMainViewModel` may support late view binding (e.g., for dynamic view swapping), whereas `IMainViewModel` assumes fixed view assignment.  
+- **Region naming ambiguity**: The 9 `Context*Region` properties share identical signatures but no documentation on expected types or lifecycle. Consumers must infer semantics from naming (e.g., `ContextDiagRegion` → diagnostics panel).  
+- **No explicit region validation**: `GetRegions()` returns `List<FrameworkElement>`, but there is no guarantee of uniqueness, ordering, or completeness. Implementations must ensure consistency with the `Context*Region` properties.  
+- **Enum dependencies**: `ChannelCodeViewMode` and `CalibrationBehaviorSetting` depend on external enums (`Common.Enums.*`) not included in the source—behavior is undefined without those definitions.  
+- **`Standalone` semantics unclear**: The `Standalone` property exists but its behavioral impact (e.g., feature toggling, UI simplification) is not documented here.  
+- **Key press methods**: `LeftKeyPress()`/`RightKeyPress()` are named descriptively but provide no context (e.g., modifier keys, repeat count). Likely tied to specific timeline navigation behavior.  
+- **No versioning or deprecation markers**: Interfaces are minimal and lack attributes (e.g., `[Obsolete]`) or versioning hints, making evolution tracking difficult.  
+
+None identified beyond the above.