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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
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	2026-04-16T02:17:22.225930+00:00	Qwen/Qwen3-Coder-Next-FP8	1	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.