11 KiB
11 KiB
source_files, generated_at, model, schema_version, sha256
| source_files | generated_at | model | schema_version | sha256 | |||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
2026-04-16T03:26:54.981028+00:00 | Qwen/Qwen3-Coder-Next-FP8 | 1 | efa128df50cbdb70 |
ViewerTestSummary Events Module Documentation
1. Purpose
This module defines a suite of Prism PubSubEvent<T>-based notification events used within the DTS Viewer (specifically for the ViewerTestSummary component) to decouple state changes in test channel, event, graph, and summary selection from UI components and view models. These events enable loose coupling between data-loading, selection, and UI-update logic—particularly important given the module’s role in supporting both standard test viewers and reuse for PSD reports (as indicated by issue #24417 comments). Events cover changes in data file/folder selection, counts of loaded/selected items, progress updates during data reading/calculation, and modifications to channel selections (including line-fit operations).
2. Public Interface
All types are public and reside in DTS.Common.Events. Each inherits from PubSubEvent<T> (Prism.Events), meaning they are intended for subscription/publishing via an IEventAggregator.
Event Classes & Payload Types
| Event Class | Payload Type | Description |
|---|---|---|
ChannelSelectionCountNotification |
int |
Notifies when the count of selected test channels changes. |
ChannelsModificationNotification |
List<ITestChannel> |
Notifies when the set of selected test channels is modified (e.g., added/removed). |
ChannelSelectionChangeNotification |
List<ITestChannel> |
Notifies when the selected test channel list changes (semantically similar to ChannelsModificationNotification, but distinct event). |
GraphChannelReadCalcProgressChangedEvent |
GraphChannelReadCalcProgressChangedEventArgs |
Reports progress during graph channel read/calculation. |
GraphChannelsReadCompletedNotification |
GraphChannelsReadCompletedNotificationArgs |
Signals completion of reading graph channels. |
DataFileSelectedEvent |
DataFileSelectionArg |
Signals selection of a specific data file (avoids triggering DataFolderChangedEvent subscribers). |
TestLoadedCountNotification |
TestLoadedCountNotificationArg |
Notifies when the count of loaded tests changes. |
GraphLoadedCountNotification |
GraphLoadedCountNotificationArg |
Notifies when the count of loaded graphs changes. |
TestSummaryCountNotification |
TestSummaryCountNotificationArg |
Notifies when the count of test summaries changes. |
GraphClearNotification |
GraphClearNotificationArg |
Signals that a graph has been cleared. |
GraphSelectedEventCountNotification |
GraphSelectedEventCountNotificationArg |
Notifies when the count of selected events in a graph changes. |
GraphSelectedChannelCountNotification |
GraphSelectedChannelCountNotificationArg |
Notifies when the count of selected channels in a graph changes. |
GraphSelectedChannelsNotification |
GraphSelectedChannelsNotificationArg |
Notifies when the set of selected channels in a graph changes. |
GraphSelectedEventsNotification |
GraphSelectedEventsNotificationArg |
Notifies when the set of selected events in a graph changes. |
ChannelsModificationLineFitNotification |
LineFitArgs |
Notifies that a line-fit operation is requested on a specific channel over a range of indices. |
TestSummaryChangeNotification |
TestSummaryChangeNotificationArg |
Notifies when the list of selected test summaries changes. |
DataFolderChangedEvent |
DataFolderSelectionArg |
Signals a change in the selected data folder (triggers broader updates). |
Payload Class Definitions
| Payload Class | Key Properties | Notes |
|---|---|---|
GraphChannelReadCalcProgressChangedEventArgs |
string ProgressMessage, double ProgressPercent, IBaseViewModel GraphVM |
Used for progress reporting; GraphVM identifies the associated graph view model. |
GraphChannelsReadCompletedNotificationArgs |
bool IsReadCompleted, IBaseViewModel GraphVM |
IsReadCompleted indicates success/failure of read operation. |
DataFileSelectionArg |
string File, IBaseViewModel ParentVM |
File is the selected file path; ParentVM supports reuse for PSD reports. |
TestLoadedCountNotificationArg |
int LoadedCount, IBaseViewModel ParentVM |
LoadedCount reflects number of loaded tests; ParentVM enables scoping. |
GraphLoadedCountNotificationArg |
int LoadedCount, IBaseViewModel ParentVM |
LoadedCount reflects number of loaded graphs. |
TestSummaryCountNotificationArg |
int SummaryCount, IBaseViewModel ParentVM |
SummaryCount reflects number of summaries. |
GraphClearNotificationArg |
bool GraphClear, IBaseViewModel ParentVM |
GraphClear likely indicates whether the graph is now empty. |
GraphSelectedEventCountNotificationArg |
int SelectedEventCount, IBaseViewModel ParentVM |
SelectedEventCount reflects number of selected events. |
GraphSelectedChannelCountNotificationArg |
int SelectedChannelCount, IBaseViewModel ParentVM |
SelectedChannelCount reflects number of selected channels. |
GraphSelectedChannelsNotificationArg |
List<ITestChannel> SelectedChannels, IBaseViewModel ParentVM |
SelectedChannels is the current set of selected channels. |
GraphSelectedEventsNotificationArg |
BindingList<ITestEvent> SelectedEvents, IBaseViewModel ParentVM |
SelectedEvents uses BindingList<T> (supports UI binding). |
LineFitArgs |
ITestChannel Channel, ulong StartIndex, ulong EndIndex |
Immutable; constructor enforces non-null Channel. |
TestSummaryChangeNotificationArg |
List<ITestSummary> SummaryList, IBaseViewModel ParentVM, int TotalSummaryCount |
SummaryList is the new selection; TotalSummaryCount may include unselected summaries. |
DataFolderSelectionArg |
string Path, string File, bool SetSelected, bool SelectAll, IBaseViewModel ParentVM |
SetSelected controls UI selection; SelectAll controls whether to auto-select all tests (e.g., for export). |
3. Invariants
- All events are notifications (i.e., fire-and-forget); no return value or cancellation is expected.
GraphSelectedEventsNotificationArg.SelectedEventsis aSystem.ComponentModel.BindingList<ITestEvent>; subscribers may rely on its change notification capabilities.LineFitArgsis immutable: its properties are read-only and set only via constructor.DataFileSelectedEventis distinct fromDataFolderChangedEvent—publishing one does not imply publishing the other (see comment inDataFileSelectedEvent.cs).- All payload classes with
ParentVMproperties useIBaseViewModelto support scoping for reuse (e.g., PSD reports), implying that event handlers should respectParentVMto avoid cross-view interference. DataFolderSelectionArg.SetSelecteddefaults tofalse;SelectAlldefaults tofalse.ChannelsModificationNotificationandChannelSelectionChangeNotificationboth carryList<ITestChannel>but are separate events—subscribers must distinguish them intentionally.
4. Dependencies
Dependencies of this module:
- Prism.Events: All events inherit from
PubSubEvent<T>. - DTS.Common.Interface:
ITestChannel,ITestEvent,ITestSummary(fromDTS.Common.Interface)IBaseViewModel(fromDTS.Common.Base)
- DTS.Common.Base: Provides
IBaseViewModelandGraphChannelReadCalcProgressChangedEventArgs.
Dependencies on this module:
- Any module/view model that needs to react to viewer state changes (e.g., UI updates, data loading, graph rendering) will subscribe to these events.
- Specifically, components handling test summary views, graph rendering, and data file/folder navigation likely depend on this module.
5. Gotchas
- Ambiguous naming:
ChannelsModificationNotificationandChannelSelectionChangeNotificationboth carryList<ITestChannel>and have near-identical summaries ("The selected Test Summary list changed event" / "The number of selected Graphs changed event"). Their distinct existence suggests semantic differences (e.g., one for additions/removals, one for reordering), but this is not documented in the source. - Inconsistent summaries: Several event summaries incorrectly describe the event (e.g.,
GraphLoadedCountNotificationsays "The number of selected Tests changed event" instead of graphs). This may mislead developers. DataFileSelectedEventvsDataFolderChangedEvent: The comment inDataFileSelectedEvent.csexplicitly warns against triggeringDataFolderChangedEventsubscribers—subscribers must not assume these events are interchangeable.TestSummaryChangeNotificationArg.TotalSummaryCount: Not clarified whether this includes only summaries inSummaryListor all available summaries.GraphClearNotificationArg.GraphClear: The boolean name suggests a flag, but its meaning (e.g.,true= cleared vs.true= not cleared) is ambiguous without implementation context.- No validation on payloads: Payload classes have no validation (e.g.,
ProgressPercentcould be outside [0,100],SelectedChannelscould be null). Subscribers must defensively handle invalid values. - No ordering guarantees: Events may be published in any order (e.g.,
GraphChannelsReadCompletedNotificationmay fire beforeGraphChannelReadCalcProgressChangedEventcompletes). - None identified from source alone for: thread-safety, lifecycle management, or disposal requirements.