--- source_files: - Common/DTS.Common/Events/Hardware/HardwareList/HardwareListShowCompactEvent.cs - Common/DTS.Common/Events/Hardware/HardwareList/HardwareListEditHardwareEvent.cs - Common/DTS.Common/Events/Hardware/HardwareList/HardwareListHardwareSelectedEvent.cs - Common/DTS.Common/Events/Hardware/HardwareList/HardwareReplaceEvent.cs - Common/DTS.Common/Events/Hardware/HardwareList/HardwareSavedEvent.cs - Common/DTS.Common/Events/Hardware/HardwareList/HardwareListHardwareIncludedEvent.cs - Common/DTS.Common/Events/Hardware/HardwareList/HardwareListHardwareTestPTPDomainIDEvent.cs - Common/DTS.Common/Events/Hardware/HardwareList/HardwareListHardwareTestSampleRateEvent.cs - Common/DTS.Common/Events/Hardware/HardwareList/HardwareListHardwareTestClockMasterEvent.cs - Common/DTS.Common/Events/Hardware/HardwareList/HardwareListHardwareTestAAFilterRateEvent.cs generated_at: "2026-04-16T03:25:48.611478+00:00" model: "Qwen/Qwen3-Coder-Next-FP8" schema_version: 1 sha256: "37867324a1f6116a" --- # Hardware List Events Module Documentation --- ## 1. Purpose This module defines a set of Prism-based pub/sub events used to communicate state changes and user actions related to hardware configuration and testing within the DTS (DAS Test System) application. These events facilitate decoupled communication between UI components (e.g., hardware list views) and backend logic, enabling reactive updates when hardware selection, inclusion status, or test-specific parameters (e.g., sample rate, PTP domain ID, clock master status) are modified. The events are grouped under the `DTS.Common.Events.Hardware.HardwareList` namespace and are intended for use in MVVM-based WPF applications leveraging Prism’s event aggregation framework. --- ## 2. Public Interface All classes are event types derived from `Prism.Events.PubSubEvent`. They are published/subscribed via Prism’s `IEventAggregator`. | Event Type | Payload Type | Description | |-----------|--------------|-------------| | `HardwareListShowCompactEvent` | `bool` | Indicates whether the hardware list view should be shown in *compact* (`true`) or *expanded* (`false`) mode. | | `HardwareListEditHardwareEvent` | `string` | Indicates a request to edit hardware; payload is the **serial number** of the hardware to edit. *(Note: Class XML comment incorrectly says “HardwareListHardwareSelectedEvent” — actual class name is `HardwareListEditHardwareEvent`.)* | | `HardwareListHardwareSelectedEvent` | `string[]` | Indicates hardware(s) have been selected; payload is an array of **serial numbers** of selected hardware items. | | `HardwareReplaceEvent` | `Tuple` | Indicates a hardware replacement request; payload is a tuple where `Item1` is the *old* hardware and `Item2` is the *new* hardware. *(Requires `IHardware` interface from `DTS.Common.Interface.DASFactory.Diagnostics.HardwareList`.)* | | `HardwareSavedEvent` | `Tuple` | Indicates hardware was added or updated; payload is a tuple where `Item1` is the **database ID** (int) and `Item2` is the **serial number** (string). | | `HardwareListHardwareIncludedEvent` | `HardwareListHardwareIncludedEventArgs` | Indicates inclusion status of a hardware item changed; payload contains `SerialNumber`, `DASId`, and `Included` (bool). | | `HardwareListHardwareTestPTPDomainIDEvent` | `HardwareListHardwareTestPTPDomainIDEventArgs` | Indicates the PTP domain ID for a hardware item in the current test changed; payload contains `SerialNumber`, `DASId`, and `PTPDomainId` (byte). | | `HardwareListHardwareTestSampleRateEvent` | `HardwareListHardwareTestSampleRateEventArgs` | Indicates the sample rate for a hardware item in the current test changed; payload contains `SerialNumber`, `DASId`, and `TestSampleRate` (double). | | `HardwareListHardwareTestClockMasterEvent` | `HardwareListHardwareTestClockMasterEventArgs` | Indicates the clock master status for a hardware item in the current test changed; payload contains `SerialNumber`, `DASId`, and `IsClockMaster` (bool). | | `HardwareListHardwareTestAAFilterRateEvent` | `HardwareListHardwareTestAAFilterRateEventArgs` | Indicates the anti-aliasing filter rate for a hardware item in the current test changed; payload contains `SerialNumber`, `DASId`, and `TestAAFilterRate` (float). | ### Event Argument Classes (Nested) | Class | Properties | Notes | |------|------------|-------| | `HardwareListHardwareIncludedEventArgs` | `string SerialNumber`, `int DASId`, `bool Included` | Constructor: `HardwareListHardwareIncludedEventArgs(string serial, bool included, int dasId)` | | `HardwareListHardwareTestPTPDomainIDEventArgs` | `string SerialNumber`, `int DASId`, `byte PTPDomainId` | Constructor: `HardwareListHardwareTestPTPDomainIDEventArgs(string serial, int dasId, byte ptpDomainId)` | | `HardwareListHardwareTestSampleRateEventArgs` | `string SerialNumber`, `int DASId`, `double TestSampleRate` | Constructor: `HardwareListHardwareTestSampleRateEventArgs(string serial, double testSampleRate, int dasId)` | | `HardwareListHardwareTestClockMasterEventArgs` | `string SerialNumber`, `int DASId`, `bool IsClockMaster` | Constructor: `HardwareListHardwareTestClockMasterEventArgs(string serial, bool isClockMaster, int dasId)` | | `HardwareListHardwareTestAAFilterRateEventArgs` | `string SerialNumber`, `int DASId`, `float TestAAFilterRate` | Constructor: `HardwareListHardwareTestAAFilterRateEventArgs(string serial, float testAAFilterRate, int dasId)` | > **Note**: All event argument classes have *read-only* properties (set only via constructor). All properties are `public` but setters are `private`. --- ## 3. Invariants - All events inherit from `PubSubEvent`, meaning they follow Prism’s default pub/sub semantics: **one-to-many**, **asynchronous** (on the UI thread by default), and **no guaranteed ordering** of subscribers. - Payload types are strictly typed and non-nullable (e.g., `bool`, `string`, `int`, `byte`, `double`, `float`, `Tuple<...>`, or custom `EventArgs`). - For events carrying `SerialNumber`, the value is expected to be a non-null, non-empty string identifying a hardware unit. - For events carrying `DASId`, the value is expected to be a valid database identifier for a DAS (Data Acquisition System) instance. - `HardwareReplaceEvent`’s payload tuple must contain two non-null `IHardware` instances (though nullability is not enforced by the event type itself). - `HardwareSavedEvent`’s `int` payload (database ID) is expected to be `> 0` for existing hardware, but may be `0` or negative for new hardware (not specified in source — *inferred from typical patterns*). - All `HardwareListHardwareTest*` events are test-scoped: the `DASId` in the payload identifies the *test context* (not necessarily the hardware’s persistent DAS assignment). --- ## 4. Dependencies ### Dependencies *of* this module: - **Prism.Events** (`Prism` library) — required for `PubSubEvent` base class. - **DTS.Common.Interface.DASFactory.Diagnostics.HardwareList** — referenced in `HardwareListEditHardwareEvent`, `HardwareListHardwareSelectedEvent`, `HardwareReplaceEvent`, and `HardwareSavedEvent` via `IHardware` (used only in `HardwareReplaceEvent` payload). ### Dependencies *on* this module: - Any module/UI component that needs to react to hardware list state changes (e.g., view models, services, test runners) will subscribe to one or more of these events. - Likely consumers include: - `HardwareListViewModel` (or similar) - Test configuration UIs (for test-specific events like `*TestSampleRateEvent`) - Persistence services (e.g., `HardwareSavedEvent` subscribers may update DB or cache) --- ## 5. Gotchas - **Misleading XML comment**: `HardwareListEditHardwareEvent`’s class-level XML says “The HardwareListHardwareSelectedEvent event” — this is a copy-paste error; the actual class name is `HardwareListEditHardwareEvent`. - **Ambiguous naming**: `HardwareListHardwareSelectedEvent` vs. `HardwareListHardwareIncludedEvent` — both relate to selection/inclusion but serve different purposes: - `HardwareListHardwareSelectedEvent`: user *selection* (multi-select, UI-level). - `HardwareListHardwareIncludedEvent`: user toggled *inclusion* in the test configuration (logical inclusion/exclusion). - **`HardwareSavedEvent` name mismatch**: Class is named `HardwareSavedEvent`, but XML comment says “The HardwareAddedEvent event” — likely historical artifact. - **No validation on payload values**: Events do not enforce constraints (e.g., `PTPDomainId` range, `TestSampleRate` > 0). Consumers must validate. - **`HardwareReplaceEvent` uses `Tuple`**: Requires `IHardware` interface from an external assembly (`DTS.Common.Interface.DASFactory.Diagnostics.HardwareList`). Ensure this interface is stable and versioned appropriately. - **`HardwareListHardwareIncludedEvent` payload includes `DASId`**: This suggests inclusion status may be *per-DAS*, but the event name does not reflect this nuance — could cause confusion if inclusion is assumed global. - **No cancellation or async support**: Events are fire-and-forget; subscribers cannot cancel or signal failure via the event payload. > **None identified from source alone** for additional gotchas beyond those explicitly noted above.