--- 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` 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`. ### 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`). | | `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`). | | `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`, 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` 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.