init

enriched-qwen3-coder-next/Common/DTS.CommonCore/Events/DTS.Viewer/ViewerTestSummary.md

@@ -0,0 +1,136 @@
+---
+source_files:
+  - Common/DTS.CommonCore/Events/DTS.Viewer/ViewerTestSummary/ChannelSelectionCountNotification.cs
+  - Common/DTS.CommonCore/Events/DTS.Viewer/ViewerTestSummary/ChannelsModificationNotification.cs
+  - Common/DTS.CommonCore/Events/DTS.Viewer/ViewerTestSummary/ChannelSelectionChangeNotification.cs
+  - Common/DTS.CommonCore/Events/DTS.Viewer/ViewerTestSummary/GraphChannelReadCalcProgressChangedEvent.cs
+  - Common/DTS.CommonCore/Events/DTS.Viewer/ViewerTestSummary/GraphChannelsReadCompletedNotification.cs
+  - Common/DTS.CommonCore/Events/DTS.Viewer/ViewerTestSummary/DataFileSelectedEvent.cs
+  - Common/DTS.CommonCore/Events/DTS.Viewer/ViewerTestSummary/GraphLoadedCountNotification.cs
+  - Common/DTS.CommonCore/Events/DTS.Viewer/ViewerTestSummary/TestLoadedCountNotification.cs
+  - Common/DTS.CommonCore/Events/DTS.Viewer/ViewerTestSummary/TestSummaryCountNotification.cs
+  - Common/DTS.CommonCore/Events/DTS.Viewer/ViewerTestSummary/GraphClearNotification.cs
+  - Common/DTS.CommonCore/Events/DTS.Viewer/ViewerTestSummary/GraphSelectedChannelCountNotification.cs
+  - Common/DTS.CommonCore/Events/DTS.Viewer/ViewerTestSummary/GraphSelectedChannelsNotification.cs
+  - Common/DTS.CommonCore/Events/DTS.Viewer/ViewerTestSummary/ChannelsModificationLineFitNotification.cs
+  - Common/DTS.CommonCore/Events/DTS.Viewer/ViewerTestSummary/TestSummaryChangeNotification.cs
+  - Common/DTS.CommonCore/Events/DTS.Viewer/ViewerTestSummary/DataFolderChangedEvent.cs
+generated_at: "2026-04-16T02:50:13.872680+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "cf000c210789fe90"
+---
+
+# Documentation: DTS.Viewer Test Summary Events Module
+
+## 1. Purpose  
+This module defines a set of Prism-based event types used for decoupled communication within the DTS Viewer component, specifically for tracking and propagating changes related to test data selection, channel state, graph loading, and progress updates. It serves as a central event bus for UI and view model layers to react to state changes in the Test Summary view (e.g., when channels are selected, graphs are loaded, or data files/folders change), enabling modular and testable architecture without tight coupling between components.
+
+## 2. Public Interface  
+
+All event classes inherit from `CompositePresentationEvent<TPayload>` (Prism event type), and payloads are strongly typed. Public types are:
+
+### Event Classes (Payload Types in parentheses):
+
+- **`ChannelSelectionCountNotification`** (`int`)  
+  Published when the count of selected test channels changes.
+
+- **`ChannelsModificationNotification`** (`List<ITestChannel>`)  
+  Published when the set of selected test channels is modified (e.g., added/removed). Payload is the *current* list of selected channels.
+
+- **`ChannelSelectionChangeNotification`** (`List<ITestChannel>`)  
+  Published when the selected test channel list changes. Payload is the *new* list of selected channels.  
+  *Note: Semantically similar to `ChannelsModificationNotification`; distinction unclear from source.*
+
+- **`GraphChannelReadCalcProgressChangedEvent`** (`GraphChannelReadCalcProgressChangedEventArgs`)  
+  Published to report progress during graph channel read/calculation. Payload contains:
+  - `ProgressMessage`: string description of current operation.
+  - `ProgressPercent`: double (0–100) indicating completion percentage.
+  - `GraphVM`: `IBaseViewModel` instance associated with the graph.
+
+- **`GraphChannelsReadCompletedNotification`** (`GraphChannelsReadCompletedNotificationArgs`)  
+  Published when reading channels for a graph completes. Payload contains:
+  - `IsReadCompleted`: bool indicating success/failure status.
+  - `GraphVM`: `IBaseViewModel` instance associated with the graph.
+
+- **`DataFileSelectedEvent`** (`DataFileSelectionArg`)  
+  Published when a specific data file is selected (distinct from folder-level changes). Payload contains:
+  - `File`: string path to the selected file.
+  - `ParentVM`: `IBaseViewModel` referencing the owner view model (for multi-view reuse).
+
+- **`GraphLoadedCountNotification`** (`GraphLoadedCountNotificationArg`)  
+  Published when the count of loaded graphs changes. Payload contains:
+  - `LoadedCount`: int number of loaded graphs.
+  - `ParentVM`: `IBaseViewModel` instance (for multi-view reuse).
+
+- **`TestLoadedCountNotification`** (`TestLoadedCountNotificationArg`)  
+  Published when the count of loaded tests changes. Payload contains:
+  - `LoadedCount`: int number of loaded tests.
+  - `ParentVM`: `IBaseViewModel` instance.
+
+- **`TestSummaryCountNotification`** (`TestSummaryCountNotificationArg`)  
+  Published when the count of items in the test summary list changes. Payload contains:
+  - `SummaryCount`: int number of summary items.
+  - `ParentVM`: `IBaseViewModel` instance.
+
+- **`GraphClearNotification`** (`GraphClearNotificationArg`)  
+  Published when a graph is cleared. Payload contains:
+  - `GraphClear`: bool (always `true` per usage; likely legacy naming).
+  - `ParentVM`: `IBaseViewModel` instance.
+
+- **`GraphSelectedChannelCountNotification`** (`GraphSelectedChannelCountNotificationArg`)  
+  Published when the count of selected channels *for a specific graph* changes. Payload contains:
+  - `SelectedChannelCount`: int number of selected channels.
+  - `ParentVM`: `IBaseViewModel` instance.
+
+- **`GraphSelectedChannelsNotification`** (`GraphSelectedChannelsNotificationArg`)  
+  Published when the set of selected channels *for a specific graph* changes. Payload contains:
+  - `SelectedChannels`: `List<ITestChannel>` (current selection).
+  - `ParentVM`: `IBaseViewModel` instance.
+
+- **`ChannelsModificationLineFitNotification`** (`LineFitArgs`)  
+  Published to request or notify about line-fit calculations on a channel. Payload contains:
+  - `Channel`: `ITestChannel` to process.
+  - `StartIndex`: `ulong` start index for fit range.
+  - `EndIndex`: `ulong` end index for fit range.
+
+- **`TestSummaryChangeNotification`** (`TestSummaryChangeNotificationArg`)  
+  Published when the test summary list changes. Payload contains:
+  - `SummaryList`: `List<ITestSummary>` (new summary items).
+  - `ParentVM`: `IBaseViewModel` instance.
+
+- **`DataFolderChangedEvent`** (`DataFolderSelectionArg`)  
+  Published when the data folder path changes. Payload contains:
+  - `Path`: string folder path.
+  - `File`: string file path (may be null or empty).
+  - `SetSelected`: bool flag indicating whether to select the file in UI/viewer (default `false`).
+  - `ParentVM`: `IBaseViewModel` instance.
+
+## 3. Invariants  
+
+- All events derive from `CompositePresentationEvent<T>`, implying they are published/subscribed via Prism’s `EventAggregator`.
+- Payloads are *always* passed by reference (no defensive copies implied by source).
+- `ParentVM` is consistently present in all events related to multi-view reuse (commented as part of issue #24417), and must be non-null when used in contexts requiring view model scoping.
+- `DataFileSelectedEvent` is explicitly intended *not* to trigger `DataFolderChangedEvent` subscribers (per inline comment), indicating a semantic distinction between file-level and folder-level selection.
+- `GraphClearNotificationArg.GraphClear` is always `true` in practice (despite being a `bool` property), suggesting legacy naming or incomplete refactoring.
+
+## 4. Dependencies  
+
+### Dependencies *of* this module:
+- `Microsoft.Practices.Prism.Events` (Prism library for event aggregation).
+- `DTS.Common.Base` (provides `IBaseViewModel`).
+- `DTS.Common.Interface` (provides `ITestChannel`, `ITestSummary`).
+- `DTS.Common.Interface.TestDefinition` (provides `ITestSummary` via `TestSummaryChangeNotification`).
+
+### Dependencies *on* this module:
+- Any component in the Viewer/Test Summary UI or view models that needs to react to selection, loading, or progress changes (e.g., `IBaseViewModel` implementations, UI controls).
+- Likely consumed by modules handling graph rendering, channel selection, and data file/folder navigation.
+
+## 5. Gotchas  
+
+- **Ambiguous event semantics**: `ChannelsModificationNotification` and `ChannelSelectionChangeNotification` both carry `List<ITestChannel>` and have near-identical documentation ("selected Test Summary list changed" vs "selected Graphs changed"). Without runtime usage context, it is unclear if they serve distinct purposes or are redundant.
+- **`GraphClear` property naming**: `GraphClearNotificationArg.GraphClear` is always `true` (per usage pattern), suggesting it should be a constant or removed. Its presence may mislead consumers into expecting variable state.
+- **`DataFileSelectedEvent` vs `DataFolderChangedEvent`**: Though both involve file/folder paths, `DataFileSelectedEvent` is explicitly designed *not* to trigger `DataFolderChangedEvent` subscriptions. Consumers must avoid conflating the two.
+- **`LineFitArgs` immutability**: `LineFitArgs` has read-only properties (`Channel`, `StartIndex`, `EndIndex`) initialized via constructor, but `ChannelsModificationLineFitNotification` is a *notification* (not a request), implying consumers should not mutate the payload.
+- **`ParentVM` usage**: All events with `ParentVM` are tied to multi-view reuse (issue #24417). Omitting or misassigning `ParentVM` may cause incorrect view scoping in PSD report or other derived viewers.
+- **No validation rules**: Payloads (e.g., `List<ITestChannel>`, `IBaseViewModel`) are not validated in the event definitions. Consumers must handle nulls, empty lists, or invalid states.