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

---
source_files:
  - Common/DTS.CommonCore/Events/LoginUserEvent.cs
  - Common/DTS.CommonCore/Events/TextPastedEvent.cs
  - Common/DTS.CommonCore/Events/BusyIndicatorChangeNotification.cs
  - Common/DTS.CommonCore/Events/ComActiveEvent.cs
  - Common/DTS.CommonCore/Events/CloseApplicationRequested.cs
  - Common/DTS.CommonCore/Events/TabControlSelectionChanged.cs
  - Common/DTS.CommonCore/Events/RaiseNotification.cs
  - Common/DTS.CommonCore/Events/PageSetActiveEvent.cs
  - Common/DTS.CommonCore/Events/GroupTemplateChangeNotification.cs
  - Common/DTS.CommonCore/Events/DatabaseVersionChangedEvent.cs
  - Common/DTS.CommonCore/Events/SetSaveButton.cs
  - Common/DTS.CommonCore/Events/DBConnectionEvent.cs
  - Common/DTS.CommonCore/Events/AutomaticModeStatusEvent.cs
  - Common/DTS.CommonCore/Events/SetPageVisibilityEvent.cs
  - Common/DTS.CommonCore/Events/LogoutUserEvent.cs
  - Common/DTS.CommonCore/Events/PageNameEvent.cs
  - Common/DTS.CommonCore/Events/TestEvent.cs
  - Common/DTS.CommonCore/Events/PageSelectionChanged.cs
  - Common/DTS.CommonCore/Events/UserEvent.cs
  - Common/DTS.CommonCore/Events/ListViewStatusEvent.cs
  - Common/DTS.CommonCore/Events/HelpTextEvent.cs
  - Common/DTS.CommonCore/Events/PageModifiedEvent.cs
  - Common/DTS.CommonCore/Events/FeedbackEvent.cs
  - Common/DTS.CommonCore/Events/AssemblyListNotification.cs
  - Common/DTS.CommonCore/Events/CancelProcess.cs
  - Common/DTS.CommonCore/Events/TabControlSelectionEventArgs.cs
  - Common/DTS.CommonCore/Events/SLICE6MulticastPropertyEvent.cs
  - Common/DTS.CommonCore/Events/AppStatusEvent.cs
  - Common/DTS.CommonCore/Events/PageErrorEvent.cs
  - Common/DTS.CommonCore/Events/PageNavigationRequestEvent.cs
  - Common/DTS.CommonCore/Events/ProgressBarEvent.cs
  - Common/DTS.CommonCore/Events/NotificationContentEventArgs.cs
  - Common/DTS.CommonCore/Events/ShowStatus.cs
generated_at: "2026-04-16T02:17:22.225930+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "9cee3f5e2ea58fa5"
---

# DTS.Common.Events Module Documentation

## 1. Purpose

This module defines a centralized set of Prism-based events for inter-module communication within the DTS application. It serves as the canonical event catalog for cross-cutting concerns such as user authentication, UI state management (busy indicators, page visibility, tab selection), database connectivity, application lifecycle, and domain-specific notifications (e.g., COM status, test execution, feedback). Events are implemented as `CompositePresentationEvent<T>` subclasses, enabling decoupled pub/sub communication between view models, services, and UI components across the application.

## 2. Public Interface

All event types are defined in the `DTS.Common.Events` namespace and inherit from `CompositePresentationEvent<T>`.

### Event Classes and Payload Types

| Event Class | Payload Type | Description |
|-------------|--------------|-------------|
| `LoginUserEvent` | `LoginUserArg` | Notifies of a user login attempt. Payload contains `UserName`. |
| `LogoutUserEvent` | `LogoutUserArg` | Notifies of a user logout. Payload contains `Reason` (currently only `DatabaseSwitch`). |
| `BusyIndicatorChangeNotification` | `bool` | Indicates whether the application/busy indicator should be active (`true`) or inactive (`false`). |
| `CommActiveEvent` | `ComStatusArg` | Notifies of COM communication state changes. Payload is `CommandStart` or `ResponseStart`. |
| `CloseApplicationRequested` | `object` | Signals that the application should close. Payload is unused (`object`). |
| `TabControlSelectionChanged` | `TabControlSelectionEventArgs` | Signals tab selection change. Payload includes `Operation` (`TabControlOperation`) and `Item`. |
| `RaiseNotification` | `NotificationContentEventArgs` | Triggers a UI notification (modal dialog). Payload includes `Message`, `MessageDetails`, `Image`, and `Title`. |
| `PageSetActiveEvent` | `PageSetActiveEventArg` | Notifies that a page has been set active. Payload contains `Page` implementing `IDataPROPage`. |
| `GroupTemplateChangeNotification` | `IBaseModel` | Signals that the selected group template has changed. Payload is the new template model. |
| `DatabaseVersionChangedEvent` | `DatabaseVersionChangedEventArgs` | Notifies of database version change. Payload contains `Version` string. |
| `SetSaveButton` | `SaveButtonUsability` | Enables/disables the Save button. Payload contains `IsUsable` boolean. |
| `DBConnectionEvent` | `DBConnectionArg` | Notifies of database connection status change. Payload includes `Connected`, `DBName`, and `Server`. |
| `AutomaticModeStatusEvent` | `AutomaticModeStatusEventArgs` | Notifies of automatic mode status change. Payload includes `TextSet` (bool) and `Text` (string). |
| `SetPageHeaderVisibilityEvent` | `SetPageHeaderVisibilityEventArgs` | Sets visibility of the page header. Payload includes `SetVisiblity` (bool) and `Visibility` (`System.Windows.Visibility`). |
| `PageNameEvent` | `PageNameEventArg` | Notifies that a page’s display name has changed. Payload includes `Name` (string) and `Page` (object). |
| `TestEvent` | `TestEventArg` | Notifies of test execution status. Payload includes `Status` (`TestStarted` or `TestEnded`). |
| `PageSelectionChanged` | `PageSelectionChangedArg` | Notifies of page selection change. Payload includes `Page` (object) and `Count` (int). |
| `UserEvent` | `UserEventArg` | Generic user-related event. Payload includes `EventType` (`ViewingUserChanged`) and `Argument` (object). |
| `ListViewStatusEvent` | `ListViewStatusArg` | Notifies of ListView status change. Payload includes `Status` (`Unloaded` or `ScrollToBottom`) and `Id` (string). |
| `HelpTextEvent` | `HelpTextEventArg` | Triggers help text display (e.g., tooltip). Payload includes `Sender` and `E` (`ToolTipEventArgs`). |
| `PageModifiedEvent` | `PageModifiedArg` | Notifies of page modification state change. Payload includes `PageStatus` (`Clear`, `Modified`, `Saved`), `Page`, and `Handled` (bool). |
| `FeedbackEvent` | `FeedbackArg` | Sends feedback (e.g., logging, status) to feedback page. Payload includes `Severity` (`Information`, `Warning`, `Error`, `ResponseStarting`, `CommandStarting`) and `Message`. |
| `AssemblyListNotification` / `AssemblyListNotificationViewer` | `AssemblyListInfo` | Notifies of assembly list changes. Payload contains `AssemblyList` (`List<Assembly>`). |
| `CancelProcessEvent` | `CancelProcess` | Requests cancellation of a process. Payload includes `IsBusy` and `ProcessId`. |
| `SLICE6MulticastPropertyEventChanged` | `SLICE6MulticastPropertyEventArgs` | Notifies of SLICE6 multicast property changes. Payload includes `SLICE6Property`, `SLICE6MulticastAddress`, `SLICE6MulticastCommandPort`, and `SLICE6MulticastResponsePort`. |
| `AppStatusEvent` | `AppStatusArg` | Notifies of high-level application status. Payload is `Busy`, `Available`, `Shutdown`, `Close`, or `UserLogout`. |
| `AppStatusExEvent` | `AppStatusExArg` | Extended app status event. Payload includes `Status` (`AppStatusArg`) and `Name` (string, process name). |
| `PageErrorEvent` | `PageErrorArg` | Surfaces errors to the application. Payload includes `Errors` (string array), `Page`, and `Handled` (bool). Includes static helper `SurfaceApplicationError(string)`. |
| `PageNavigationRequestEvent` | `PageNavigationRequest` | Requests navigation to a page. Payload includes `Destination` (`Sensor`, `TestSetups`), `DestinationArg`, and `Caller`. |
| `ProgressBarEvent` | `ProgressBarEventArg` | Controls progress bar state. Payload includes `ProgressBarName`, `ProgressBarColor`, `SetPercentage`/`ProgressBarPercentage`, `SetText`/`ProgressBarText`, `SetVisibility`/`ProgressBarVisibility`. |
| `ShowStatus` | `StatusInfo` | Notifies of process status. Payload includes `CurrentState` (`Idle`, `Busy`, `DoneNoError`, `DoneFailed`), `IsOk`, `Percentage`, `Text`, and `ProcessId`. |

### Supporting Types

| Type | Description |
|------|-------------|
| `LoginUserArg` | Payload for `LoginUserEvent`. Contains `UserName` (string). |
| `DBConnectionArg` | Payload for `DBConnectionEvent`. Contains `Connected` (bool), `DBName`, `Server` (strings). |
| `AutomaticModeStatusEventArgs` | Payload for `AutomaticModeStatusEvent`. Contains `TextSet` (bool), `Text` (string). |
| `SaveButtonUsability` | Payload for `SetSaveButton`. Contains `IsUsable` (bool). |
| `PageSetActiveEventArg` | Payload for `PageSetActiveEvent`. Contains `Page` (`IDataPROPage`). |
| `DatabaseVersionChangedEventArgs` | Payload for `DatabaseVersionChangedEvent`. Contains `Version` (string). |
| `PageNameEventArg` | Payload for `PageNameEvent`. Contains `Name` (string, read-only), `Page` (object, read-only). Constructor sets both. |
| `PageSelectionChangedArg` | Payload for `PageSelectionChanged`. Contains `Page` (object, read-only), `Count` (int, read-only). Constructor sets both. |
| `UserEventArg` | Payload for `UserEvent`. Contains `EventType` (`Events.ViewingUserChanged`, read-only), `Argument` (object, read-only). Constructor sets both. |
| `ListViewStatusArg` | Payload for `ListViewStatusEvent`. Contains `Status` (`ListViewStatus` enum, read-only), `Id` (string, read-only). Constructor sets both. |
| `HelpTextEventArg` | Payload for `HelpTextEvent`. Contains `Sender` (object), `E` (`ToolTipEventArgs`). |
| `PageModifiedArg` | Payload for `PageModifiedEvent`. Contains `PageStatus` (`Status` enum, read-only), `Page` (object, read-only), `Handled` (bool, writable). Constructor sets first two. |
| `FeedbackArg` | Payload for `FeedbackEvent`. Contains `Severity` (`Severity` enum, read-only), `Message` (string, read-only). Constructor sets both. |
| `AssemblyListInfo` | Payload for `AssemblyListNotification`/`AssemblyListNotificationViewer`. Contains `AssemblyList` (`List<Assembly>`). |
| `CancelProcess` | Payload for `CancelProcessEvent`. Contains `IsBusy` (bool), `ProcessId` (int). |
| `SLICE6MulticastPropertyEventArgs` | Payload for `SLICE6MulticastPropertyEventChanged`. Contains `SLICE6Property`, `SLICE6MulticastAddress`, `SLICE6MulticastCommandPort`, `SLICE6MulticastResponsePort`. |
| `AppStatusExArg` | Payload for `AppStatusExEvent`. Contains `Status` (`AppStatusArg`, read-only), `Name` (string, read-only). Constructor sets both. |
| `PageErrorArg` | Payload for `PageErrorEvent`. Contains `Errors` (string[], read-only), `Page` (object, read-only), `Handled` (bool, writable). Constructor sets first two. |
| `PageNavigationRequest` | Payload for `PageNavigationRequestEvent`. Contains `Destination` (`Destinations` enum, read-only), `DestinationArg` (object, read-only), `Caller` (object, read-only). Constructor sets all. |
| `ProgressBarEventArg` | Payload for `ProgressBarEvent`. Contains `ProgressBarName`, `ProgressBarColor`, `SetPercentage`, `ProgressBarPercentage`, `SetText`, `ProgressBarText`, `SetVisibility`, `ProgressBarVisibility`. |
| `StatusInfo` | Payload for `ShowStatus`. Contains `CurrentState` (`StatusState` enum), `IsOk`, `Percentage`, `Text`, `ProcessId`. Includes `IsBusy` property and `Unsubscribe()` method. |
| `TabControlSelectionEventArgs` | Payload for `TabControlSelectionChanged`. Contains `Operation` (`TabControlOperation`), `Item`. Constructor sets both. |
| `NotificationContentEventArgs` | Payload for `RaiseNotification`. Contains `Message`, `MessageDetails`, `Image` (`PopupWindowImage`), `Title`. |
| `NotificationContentEventArgsWithoutTitle` | Simplified payload for notifications without title. Contains `Message`, `MessageDetails`, `Image`. |

## 3. Invariants

- **Event Naming**: All event types follow the `XxxEvent` naming convention (e.g., `CloseApplicationRequested`, `ProgressBarEvent`).
- **Payload Immutability**: Payload classes generally expose properties as `get;` (read-only) after construction, with values set via constructor parameters. Exceptions include `Handled` (writable flag in `PageModifiedArg`, `PageErrorArg`), `IsUsable` (`SaveButtonUsability`), and `Set*` properties (`ProgressBarEventArg`).
- **Prism Dependency**: All events inherit from `CompositePresentationEvent<T>`, requiring Prism’s `Microsoft.Practices.Prism.Events` library.
- **Namespace Consistency**: All types reside in the `DTS.Common.Events` namespace.
- **Enum Values**: Enums (`ComStatusArg`, `TestEventStatus`, `Severity`, `AppStatusArg`, `StatusInfo.StatusState`, `UserEventArg.Events`, `ListViewStatusArg.ListViewStatus`, `PageNavigationRequest.Destinations`) define discrete, named states. No implicit ordering or numeric assumptions should be made.
- **Null Safety**: Payload properties are not guaranteed non-null unless specified (e.g., `ProgressBarEventArg.ProgressBarName` defaults to `"Footer"`). Consumers should validate nulls.

## 4. Dependencies

### Dependencies *of* this module:
- **Prism Library**: `Microsoft.Practices.Prism.Events` (for `CompositePresentationEvent<T>` and `EventBase`).
- **WPF**: `System.Windows`, `System.Windows.Media`, `System.Windows.Controls`, `System.Windows.Threading` (via `Visibility`, `Color`, `ToolTipEventArgs`).
- **.NET Reflection**: `System.Reflection` (for `Assembly` in `AssemblyListInfo`).
- **DTS Common Infrastructure**:
  - `DTS.Common.Base` (`IBaseModel`, `IDataPROPage`)
  - `DTS.Common.Enums` (`TabControlOperation`, `PopupWindowImage`, `SLICE6Properties`)
  - `DTS.Common.Utilities.Logging` (`APILogger`)
  - `Microsoft.Practices.ServiceLocation` (`IEventAggregator`, `ServiceLocator`)
  - `DTS.Common.Strings` (for `Strings.Strings.ResourceManager` in `StatusInfo` constructor)

### Dependencies *on* this module:
- **View Models & Services**: All modules that need to signal state changes (e.g., login/logout, database status, page navigation, progress updates) publish events defined here.
- **UI Components**: Views subscribe to events to update UI (e.g., progress bars, busy indicators, notifications, page headers).
- **Event Aggregator Consumers**: Any module using Prism’s `IEventAggregator` to subscribe/publish these events.

## 5. Gotchas

- **Inconsistent Naming**: `SetSaveButton` event is defined in `SetSaveButton.cs`, but its payload class is `SaveButtonUsability`. Similarly, `ShowStatus` event uses `StatusInfo` payload. Ensure correct pairing.
- **Typos in Properties**: `SetPageHeaderVisibilityEventArgs.SetVisiblity` has a typo (`Visiblity` instead of `Visibility`). This is preserved from source.
- **Redundant Events**: Several events (`BusyIndicatorChangeNotification`, `AppStatusEvent`, `AppStatusExEvent`, `DBConnectionEvent`) overlap in purpose (busy/available state). Consumers must determine which to use based on context or legacy constraints.
- **Unused/Incomplete Events**: `TestEvent`, `UserEvent`, `ListViewStatusEvent`, `HelpTextEvent`, `AssemblyListNotificationViewer`, `SLICE6MulticastPropertyEventChanged` have minimal documentation and unclear usage. Verify with domain experts.
- **Static Helper Side Effects**: `PageErrorEvent.SurfaceApplicationError()` uses `ServiceLocator` internally. This may fail if `ServiceLocator` is not initialized or configured.
- **Enum Values Not Exhaustive**: `ComStatusArg` and `TestEventStatus` only define two values each; future extensions may require new enum members.
- **Payload Mutability**: While most payload properties are read-only, `Handled` (in `PageModifiedArg`, `PageErrorArg`) is writable and may be set by subscribers. Ensure publishers check `Handled` if needed.
- **Null `Text` in `StatusInfo`**: If `text` is `null` in `StatusInfo` constructor, it defaults to a resource string or enum name. Ensure `Strings.Strings` is initialized.
- **`NotificationContentEventArgsWithoutTitle`**: A separate class (not used by any event) exists but is not tied to any event. Likely leftover from refactoring.
- **`AssemblyListNotification` vs `AssemblyListNotificationViewer`**: Two identical events exist. Clarify intent or consolidate if redundant.
- **`ProgressBarEventArg` Defaults**: Default constructor sets `ProgressBarName = "Footer"`. Other properties default to `false`, `double.NaN`, or `null`. Ensure consumers set required fields explicitly.