init

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

@@ -0,0 +1,73 @@
+---
+source_files:
+  - Common/DTS.CommonCore/Events/DTS.Viewer/TestModification/RefreshTestRequestEvent.cs
+  - Common/DTS.CommonCore/Events/DTS.Viewer/TestModification/ShowT0CursorEvent.cs
+  - Common/DTS.CommonCore/Events/DTS.Viewer/TestModification/TestModificationChangedEvent.cs
+  - Common/DTS.CommonCore/Events/DTS.Viewer/TestModification/SetUseZeroForUnfilteredEvent.cs
+  - Common/DTS.CommonCore/Events/DTS.Viewer/TestModification/TestModificationEvent.cs
+  - Common/DTS.CommonCore/Events/DTS.Viewer/TestModification/ShiftT0Event.cs
+generated_at: "2026-04-16T02:49:56.440589+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "42735a65c478074f"
+---
+
+# TestModification
+
+## Documentation: Test Modification Event Definitions
+
+### 1. Purpose  
+This module defines a set of Prism-based event types used for communication within the DTS Viewer component related to test modification operations. These events facilitate decoupled UI and data layer interactions—such as refreshing test data, toggling or shifting the T0 cursor, updating filter behavior, and signaling when a test has been modified—enabling reactive updates across modules without tight coupling. All events inherit from `CompositePresentationEvent<T>` (Prism’s pub/sub mechanism), indicating they are intended for cross-view or cross-module communication in a WPF/Prism-based application.
+
+### 2. Public Interface  
+
+| Event / Type | Signature | Behavior |
+|--------------|-----------|----------|
+| `RefreshTestRequestEvent` | `public class RefreshTestRequestEvent : CompositePresentationEvent<string> { }` | Payload is a `string` representing the **Test ID**. Subscribers use this to refresh the UI/data for the specified test. |
+| `ShowT0CursorEvent` | `public class ShowT0CursorEvent : CompositePresentationEvent<bool> { }` | Payload is a `bool`. `true` to show the T0 cursor, `false` to hide it. |
+| `TestModificationChangedEvent` | `public class TestModificationChangedEvent : CompositePresentationEvent<ITestModificationModel> { }` | Payload is an `ITestModificationModel`. Signals that the current test modification state (e.g., metadata, parameters) has changed. |
+| `SetUseZeroForUnfilteredEvent` | `public class SetUseZeroForUnfilteredEvent : CompositePresentationEvent<bool> { }` | Payload is a `bool`. Controls whether `0` (true) or `P` (false) is displayed in the isocode filter field when modifying an isocode from a filter. |
+| `TestModificationEvent` | `public class TestModificationEvent : CompositePresentationEvent<TestModificationArgs> { }` | Payload is a `TestModificationArgs`. Raised whenever a test is modified by the viewer (e.g., user edits metadata or parameters). Triggers downstream regeneration of ROIs (e.g., by DataPro). |
+| `TestModificationArgs` | `public class TestModificationArgs { public string DataSetDirectory { get; } public string TestId { get; } public TestModificationArgs(string dtsFilePath, string testId) { ... } }` | Encapsulates context for a test modification: `dtsFilePath` → `DataSetDirectory`, and `testId`. |
+| `ShiftT0Event` | `public class ShiftT0Event : CompositePresentationEvent<ShiftT0EventArguments> { }` | Payload is a `ShiftT0EventArguments`. Requests shifting the T0 time (cursor) either by absolute time offset or by sample/step count. |
+| `ShiftT0EventArguments` | `public class ShiftT0EventArguments { public double T0Time { get; } public bool IsInitialization { get; } public int T0Steps { get; } public bool IsKeyPress { get; }` | Contains shift parameters: <br>• `T0Time`: Absolute time value (used in one constructor). <br>• `T0Steps`: Number of steps/samples to shift (used in the other constructor). <br>• `IsInitialization`: Whether this shift is part of initial setup. <br>• `IsKeyPress`: Whether the shift was triggered by a keyboard event (left/right arrow). |
+
+> **Note**: Two distinct constructors for `ShiftT0EventArguments` exist:  
+> - One accepting `(double t0, bool isInitialization)` → sets `T0Time`, `IsInitialization`; `T0Steps = 0`, `IsKeyPress = false`.  
+> - One accepting `(int steps, bool isInitialization, bool isKeyPress)` → sets `T0Steps`, `IsInitialization`, `IsKeyPress`; `T0Time = 0D`.
+
+### 3. Invariants  
+- All events are **non-interactive** (i.e., they carry data only; no return values or side effects in the event class itself).  
+- Payload types are strictly typed:  
+  - `RefreshTestRequestEvent` → `string` (Test ID)  
+  - `ShowT0CursorEvent` → `bool`  
+  - `TestModificationChangedEvent` → `ITestModificationModel` (interface, not concrete type)  
+  - `SetUseZeroForUnfilteredEvent` → `bool`  
+  - `TestModificationEvent` → `TestModificationArgs`  
+  - `ShiftT0Event` → `ShiftT0EventArguments`  
+- `TestModificationArgs.TestId` and `TestModificationArgs.DataSetDirectory` are **immutable** (`private set;`).  
+- In `ShiftT0EventArguments`, `T0Time` and `T0Steps` are mutually exclusive: only one is non-zero/non-default per instance.  
+- `IsInitialization` and `IsKeyPress` are independent flags; both may be `false` (e.g., programmatic shifts not triggered by user input or initialization).
+
+### 4. Dependencies  
+- **External Dependency**:  
+  - `Microsoft.Practices.Prism.Events` (Prism library) — required for `CompositePresentationEvent<T>`.  
+- **Internal Dependency**:  
+  - `DTS.Common.Interface.ITestModificationModel` — referenced in `TestModificationChangedEvent`. This interface must be defined elsewhere in the codebase (not included here).  
+- **Inferred Usage**:  
+  - Events are likely published by the DTS Viewer (e.g., test editing UI) and consumed by modules like DataPro (for ROI regeneration), cursor rendering components, or filter UI logic.  
+  - No direct consumers are listed in the source; usage must be inferred from comments (e.g., `TestModificationEvent` is used by DataPro to regenerate ROI).
+
+### 5. Gotchas  
+- **Ambiguous payload semantics**:  
+  - `DataSetDirectory` in `TestModificationArgs` is initialized from `dtsFilePath`, but its name suggests a *directory* while the parameter is named `dtsFilePath` (which may be a full file path). Clarify whether this expects a directory or file path.  
+  - `ShiftT0EventArguments` has two constructors with overlapping parameters (`isInitialization`) but different semantics. Callers must ensure correct constructor is used—mixing them may lead to `T0Time = 0` when a time shift was intended.  
+- **Missing validation**:  
+  - No validation is present in `ShiftT0EventArguments` constructors (e.g., `steps` could be negative; `T0Time` could be negative). Behavior for invalid values is undefined.  
+- **Namespace quirk**:  
+  - `// ReSharper disable CheckNamespace` is present in multiple files, suggesting intentional deviation from folder-based namespace conventions. Ensure build/linting rules accommodate this.  
+- **No documentation on event subscription/unsubscription patterns**:  
+  - Since these are Prism events, subscribers must manage thread affinity (e.g., `ThreadOption.PublisherThread` vs `UIThread`) explicitly—this is not documented here.  
+- **No deprecation notices**:  
+  - The comment for `TestModificationEvent` ("this event is called currently whenever...") suggests it may be legacy or in flux. No indication of planned replacement or migration path.  
+- **None identified from source alone.**