138 lines
12 KiB
Markdown
138 lines
12 KiB
Markdown
---
|
||
source_files:
|
||
- Common/DTS.Common/Events/LoadViewList.cs
|
||
- Common/DTS.Common/Events/LoadExportList.cs
|
||
- Common/DTS.Common/Events/ClearSelectedExportsEvent.cs
|
||
- Common/DTS.Common/Events/LoginUserEvent.cs
|
||
- Common/DTS.Common/Events/TextPastedEvent.cs
|
||
- Common/DTS.Common/Events/BusyIndicatorChangeNotification.cs
|
||
- Common/DTS.Common/Events/ComActiveEvent.cs
|
||
- Common/DTS.Common/Events/CloseApplicationRequested.cs
|
||
- Common/DTS.Common/Events/TabControlSelectionChanged.cs
|
||
- Common/DTS.Common/Events/RaiseNotification.cs
|
||
- Common/DTS.Common/Events/PageSetActiveEvent.cs
|
||
- Common/DTS.Common/Events/GroupTemplateChangeNotification.cs
|
||
- Common/DTS.Common/Events/DatabaseVersionChangedEvent.cs
|
||
- Common/DTS.Common/Events/SetSaveButton.cs
|
||
- Common/DTS.Common/Events/DBConnectionEvent.cs
|
||
- Common/DTS.Common/Events/AutomaticModeStatusEvent.cs
|
||
- Common/DTS.Common/Events/SetPageVisibilityEvent.cs
|
||
- Common/DTS.Common/Events/LogoutUserEvent.cs
|
||
- Common/DTS.Common/Events/TestEvent.cs
|
||
- Common/DTS.Common/Events/PageSelectionChanged.cs
|
||
- Common/DTS.Common/Events/PageNameEvent.cs
|
||
- Common/DTS.Common/Events/UserEvent.cs
|
||
- Common/DTS.Common/Events/ListViewStatusEvent.cs
|
||
- Common/DTS.Common/Events/HelpTextEvent.cs
|
||
- Common/DTS.Common/Events/PageModifiedEvent.cs
|
||
- Common/DTS.Common/Events/AssemblyListNotification.cs
|
||
- Common/DTS.Common/Events/FeedbackEvent.cs
|
||
- Common/DTS.Common/Events/CancelProcess.cs
|
||
- Common/DTS.Common/Events/TabControlSelectionEventArgs.cs
|
||
- Common/DTS.Common/Events/SLICE6MulticastPropertyEvent.cs
|
||
- Common/DTS.Common/Events/AppStatusEvent.cs
|
||
- Common/DTS.Common/Events/PageErrorEvent.cs
|
||
- Common/DTS.Common/Events/PageNavigationRequestEvent.cs
|
||
- Common/DTS.Common/Events/ProgressBarEvent.cs
|
||
- Common/DTS.Common/Events/NotificationContentEventArgs.cs
|
||
- Common/DTS.Common/Events/ShowStatus.cs
|
||
generated_at: "2026-04-16T02:56:22.448304+00:00"
|
||
model: "Qwen/Qwen3-Coder-Next-FP8"
|
||
schema_version: 1
|
||
sha256: "5962f3d1e4d996fb"
|
||
---
|
||
|
||
# DTS.Common.Events Module Documentation
|
||
|
||
## 1. Purpose
|
||
This module defines a centralized set of Prism `PubSubEvent`-based events used for cross-module communication within the DTS application. It serves as the canonical event bus contract, enabling decoupled communication between UI components, services, and modules. Events cover application lifecycle (login/logout, shutdown), state changes (busy/available, database connection, automatic mode), UI interactions (tab selection, page navigation, page modification), and domain-specific operations (COM status, SLICE6 multicast configuration, export management). The module ensures consistent event naming, argument structures, and semantics across the application.
|
||
|
||
## 2. Public Interface
|
||
|
||
### Event Classes (All inherit from `PubSubEvent<T>` unless noted)
|
||
|
||
| Event Name | Payload Type | Description |
|
||
|------------|--------------|-------------|
|
||
| `LoadViewModulEvent` | `LoadViewModulArg` | Requests loading of a view module. *(Note: Typo in class name — likely intended `LoadViewModuleEvent`)* |
|
||
| `LoadExportModuleEvent` | `LoadExportModuleArg` | Requests loading of an export module. *(Note: Typo in class name — likely intended `LoadExportModuleEvent`)* |
|
||
| `ClearSelectedExportsEvent` | `ClearSelectedExportsArg` | Clears currently selected exports. |
|
||
| `LoginUserEvent` | `LoginUserArg` | Signals user login; includes `UserName`. |
|
||
| `TextPastedEvent` | `ITextPastedEventArgs` | Notifies of text paste operation; includes `Text`, `Sender`, `Id`, `Tag`. |
|
||
| `BusyIndicatorChangeNotification` | `bool` | Toggles busy indicator state (`true` = busy, `false` = available). |
|
||
| `CommActiveEvent` | `ComStatusArg` | Indicates COM status change (`CommandStart`, `ResponseStart`). |
|
||
| `CloseApplicationRequested` | `object` | Requests application shutdown. |
|
||
| `TabControlSelectionChanged` | `TabControlSelectionEventArgs` | Notifies of tab selection change; includes `Operation` (`TabControlOperation`) and `Item`. |
|
||
| `RaiseNotification` | `NotificationContentEventArgs` | Triggers a notification popup with `Message`, `MessageDetails`, `Image` (`PopupWindowImage`), and `Title`. |
|
||
| `PageSetActiveEvent` | `PageSetActiveEventArg` | Notifies a page has been set active; includes `Page` (`IDataPROPage`). |
|
||
| `GroupTemplateChangeNotification` | `IBaseModel` | Notifies of selected group template change. |
|
||
| `DatabaseVersionChangedEvent` | `DatabaseVersionChangedEventArgs` | Notifies of database version change; includes `Version`. |
|
||
| `SetSaveButton` | `SaveButtonUsability` | Enables/disables the Save button via `IsUsable`. |
|
||
| `DBConnectionEvent` | `DBConnectionArg` | Notifies of database connection status; includes `Connected`, `DBName`, `Server`. |
|
||
| `AutomaticModeStatusEvent` | `AutomaticModeStatusEventArgs` | Notifies automatic mode status; includes `TextSet`, `Text`. |
|
||
| `SetPageHeaderVisibilityEvent` | `SetPageHeaderVisibilityEventArgs` | Sets visibility of page header; includes `SetVisiblity`, `Visibility` (`System.Windows.Visibility`). *(Note: Typo in property name `SetVisiblity`)* |
|
||
| `LogoutUserEvent` | `LogoutUserArg` | Notifies user logout; includes `Reason` (`DatabaseSwitch`). |
|
||
| `TestEvent` | `TestEventArg` | Notifies test status (`TestStarted`, `TestEnded`). |
|
||
| `PageSelectionChanged` | `PageSelectionChangedArg` | Notifies page selection change; includes `Page`, `Count`. |
|
||
| `PageNameEvent` | `PageNameEventArg` | Notifies page name update; uses `CompositePresentationEvent` (Prism’s base for multi-subscriber events). |
|
||
| `UserEvent` | `UserEventArg` | Notifies user-related events (e.g., `ViewingUserChanged`); includes `EventType`, `Argument`. |
|
||
| `ListViewStatusEvent` | `ListViewStatusArg` | Notifies ListView status (`Unloaded`, `ScrollToBottom`); includes `Status`, `Id`. |
|
||
| `HelpTextEvent` | `HelpTextEventArg` | Notifies help text tooltip request; includes `Sender`, `E` (`ToolTipEventArgs`). |
|
||
| `PageModifiedEvent` | `PageModifiedArg` | Notifies page modification state (`Clear`, `Modified`, `Saved`); includes `PageStatus`, `Page`, `Handled`. |
|
||
| `AssemblyListNotification` / `AssemblyListNotificationViewer` | `AssemblyListInfo` | Notifies assembly list changes; includes `AssemblyList` (`List<Assembly>`). |
|
||
| `FeedbackEvent` | `FeedbackArg` | Notifies feedback with `Severity` (`Information`, `Warning`, `Error`, `ResponseStarting`, `CommandStarting`) and `Message`. |
|
||
| `CancelProcessEvent` | `CancelProcess` | Requests cancellation of a process; includes `IsBusy`, `ProcessId`. |
|
||
| `SLICE6MulticastPropertyEventChanged` | `SLICE6MulticastPropertyEventArgs` | Notifies SLICE6 multicast property changes; includes `SLICE6Property`, `SLICE6MulticastAddress`, `SLICE6MulticastCommandPort`, `SLICE6MulticastResponsePort`. |
|
||
| `AppStatusEvent` | `AppStatusArg` | Notifies app status (`Busy`, `Available`, `Shutdown`, `Close`, `UserLogout`). |
|
||
| `AppStatusExEvent` | `AppStatusExArg` | Extended app status; includes `Status` (`AppStatusArg`) and `Name` (source process name). |
|
||
| `PageErrorEvent` | `PageErrorArg` | Surfaces errors to the application; includes `Errors` (`string[]`), `Page`, `Handled`. Provides static helper `SurfaceApplicationError(string)`. |
|
||
| `PageNavigationRequestEvent` | `PageNavigationRequest` | Requests navigation to `Destination` (`Sensor`, `TestSetups`) with `DestinationArg` and `Caller`. |
|
||
| `ProgressBarEvent` | `ProgressBarEventArg` | Updates progress bar state; includes `ProgressBarName`, `ProgressBarColor`, `ProgressBarPercentage`, `ProgressBarText`, `ProgressBarVisibility`. |
|
||
|
||
### Helper Methods
|
||
- `PageErrorEvent.SurfaceApplicationError(string)`: Static method to publish a `PageErrorEvent` with a single error message.
|
||
|
||
---
|
||
|
||
## 3. Invariants
|
||
|
||
- **Event Naming Consistency**: Event class names follow `PascalCase` + `Event` suffix (e.g., `LoginUserEvent`). Payload argument classes follow `PascalCase` + `Arg`/`EventArgs` suffix (e.g., `LoginUserArg`, `NotificationContentEventArgs`).
|
||
- **Payload Immutability**: Most payload properties are read-only (`get;` only) or initialized via constructor to prevent mutation after publication.
|
||
- **Prism Dependency**: All events derive from `Prism.Events.PubSubEvent<T>` (except `PageNameEvent`, which uses `CompositePresentationEvent<T>`).
|
||
- **Null Safety**: Payloads like `DatabaseVersionChangedEventArgs.Version`, `AutomaticModeStatusEventArgs.Text`, `ProgressBarEventArg.ProgressBarName` default to `string.Empty` or `null` where appropriate.
|
||
- **Enum Encapsulation**: Domain-specific enums (`ComStatusArg`, `Severity`, `AppStatusArg`, etc.) are strongly typed and defined within the same file as their associated event args.
|
||
- **Event Aggregator Usage**: Events are intended to be published via Prism’s `IEventAggregator`. `PageErrorEvent` explicitly demonstrates this pattern.
|
||
|
||
---
|
||
|
||
## 4. Dependencies
|
||
|
||
### Dependencies *on* this module
|
||
- **Prism Library**: All events rely on `Prism.Events.PubSubEvent<T>` and `Prism.Ioc.IContainerLocator` (for `PageErrorEvent.SurfaceApplicationError`).
|
||
- **DTS.Common.Base**: `GroupTemplateChangeNotification` uses `IBaseModel`; `BusyIndicatorChangeNotification` references `DTS.Common.Base` namespace.
|
||
- **DTS.Common.Interface**: `PageSetActiveEvent` uses `IDataPROPage`.
|
||
- **System.Windows**: `ProgressBarEvent`, `SetPageHeaderVisibilityEvent`, `HelpTextEvent` use WPF types (`Color`, `Visibility`, `ToolTipEventArgs`).
|
||
- **System.Reflection**: `AssemblyListNotification` uses `Assembly`.
|
||
- **DTS.Common.Enums**: Multiple events use enums like `TabControlOperation`, `PopupWindowImage`, `SLICE6Properties`.
|
||
- **DTS.Common.Utilities.Logging**: `PageErrorEvent` references `APILogger`.
|
||
|
||
### Dependencies *of* this module
|
||
- None (this is a foundational module).
|
||
|
||
---
|
||
|
||
## 5. Gotchas
|
||
|
||
- **Typo in Event Names**: `LoadViewModulEvent` and `LoadExportModuleEvent` are likely misspellings of `LoadViewModuleEvent` and `LoadExportModuleEvent`.
|
||
- **Inconsistent Naming for Event Args**: Some use `Arg` (e.g., `LoginUserArg`), others `EventArgs` (e.g., `NotificationContentEventArgs`).
|
||
- **Redundant Events**: `AppStatusEvent` and `AppStatusExEvent` overlap in purpose; `AppStatusExEvent` adds source process name.
|
||
- **Misleading Comments**: Several events (e.g., `LogoutUserEvent`, `PageSelectionChanged`, `UserEvent`) have comments stating "mark itself busy or available" despite having domain-specific payloads unrelated to busy state.
|
||
- **Property Name Typos**: `SetPageHeaderVisibilityEventArgs.SetVisiblity` (missing 'i').
|
||
- **`PageNameEvent` Uses `CompositePresentationEvent`**: Unlike all other events, `PageNameEvent` inherits from `CompositePresentationEvent<T>`, implying different subscription semantics (e.g., multiple subscribers may be expected).
|
||
- **`ITextPastedEventArgs` Interface**: The event payload is an interface, requiring implementers to define concrete types.
|
||
- **`SaveButtonUsability` vs `SetSaveButton`**: The event name `SetSaveButton` is a verb phrase, while other events use noun phrases (e.g., `PageModifiedEvent`).
|
||
- **`ProgressBarEventArg` Default Values**: Default constructor sets `ProgressBarName = "Footer"`; other properties default to `false`/`double.NaN`/`null`.
|
||
- **`StatusInfo.Text` Auto-Initialization**: If `text` is `null`, `StatusInfo` attempts to fetch localized text via `Strings.Strings.ResourceManager`. Consumers must ensure resource keys exist.
|
||
- **`PageErrorEvent.SurfaceApplicationError`**: Uses `ContainerLocator.Container` directly — tightly couples to Prism’s container resolution mechanism.
|
||
- **`DBConnectionEvent` Payload**: `DBName` and `Server` are included even when `Connected = false`, which may be misleading.
|
||
- **`FeedbackEvent.Severity` Values**: Includes `ResponseStarting` and `CommandStarting`, which are not standard severity levels (typically `Information`, `Warning`, `Error` are used).
|
||
- **`TestEventArg.Status` is `private set`**: Cannot be modified after construction, but `TestEventArg` is not sealed — subclasses could override. |