noisedestroyers/DP44
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
DP44/enriched-qwen3-coder-next/Common/DTS.CommonCore/Events.md
noisedestroyers bc3ac1d4c9 init
2026-04-17 14:55:32 -04:00

156 lines
16 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
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.
Reference in New Issue View Git Blame Copy Permalink