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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.CommonCore/Dialogs/IRegionManagerAware.cs.cs Common/DTS.CommonCore/Dialogs/IPopupWindowActionAware.cs Common/DTS.CommonCore/Dialogs/ConfirmationEx.cs Common/DTS.CommonCore/Dialogs/ConfirmationWindow.xaml.cs Common/DTS.CommonCore/Dialogs/NotificationWindow.xaml.cs Common/DTS.CommonCore/Dialogs/PopupWindowAction.cs Common/DTS.CommonCore/Dialogs/BrowseForFolderDialog.cs	2026-04-16T02:16:28.079269+00:00	Qwen/Qwen3-Coder-Next-FP8	1	e520922d284c9033

Dialogs Module Documentation

1. Purpose

This module provides infrastructure for displaying modal and non-modal popup windows in WPF applications using Prism’s IInteractionRequest pattern, along with specialized dialog implementations for confirmations and notifications. It enables consistent UI behavior for user interactions by abstracting window creation, positioning, and content preparation logic. The module also includes a Win32-based folder browser dialog wrapper (BrowseForFolderDialog) for legacy folder selection scenarios. Key components include interfaces for content awareness (IRegionManagerAware, IPopupWindowActionAware), concrete window types (ConfirmationWindow, NotificationWindow), and the core trigger action (PopupWindowAction) that orchestrates dialog display and lifecycle.

2. Public Interface

Interfaces

• IRegionManagerAware

  • IRegionManager RegionManager { get; set; }
  • Allows content (view or view model) to receive a scoped RegionManager instance for region-based navigation within popup windows.

• IPopupWindowActionAware

  • Window HostWindow { get; set; }
  • Notification HostNotification { get; set; }
  • Enables content (view or view model) to access the host window and the original Notification/Confirmation that triggered the dialog.

Classes

• ConfirmationEx

  • Inherits Microsoft.Practices.Prism.Interactivity.InteractionRequest.Confirmation
  • MessageBoxButton Buttons { get; set; } = MessageBoxButton.OKCancel;
  • MessageBoxImage Image { get; set; } = MessageBoxImage.Question;
  • MessageBoxResult Result { get; set; }
  • Extended confirmation payload with configurable button set, icon, and result (used to communicate user choice back to caller).

• ConfirmationWindow

  • static readonly DependencyProperty ConfirmationTemplateProperty
  • DataTemplate ConfirmationTemplate { get; set; }
  • public ConfirmationWindow() — Constructor; removes system menu (close button) via Win32 SetWindowLong.
  • public void Connect(int connectionId, object target) — Throws NotImplementedException; unused.

• NotificationWindow

  • Inherits Window
  • static readonly DependencyProperty NotificationTemplateProperty
  • DataTemplate NotificationTemplate { get; set; }
  • static readonly DependencyProperty ImageUriProperty
  • Uri ImageUri { get; set; } — Defaults to warning_48.png.
  • public NotificationWindow() — Constructor; removes system menu (close button) via Win32 SetWindowLong.
  • public void Connect(int connectionId, object target) — No-op stub.
  • private void CoppyToClibord_Click(...) — Copies "Hello, clipboard" to clipboard (note: typo in method name).

• PopupWindowAction

  • Inherits TriggerAction<FrameworkElement>
  • enum WindowPositions { CenterOwner, CenterScreen }
  • static readonly DependencyProperty WindowContentProperty
  • FrameworkElement WindowContent { get; set; }
  • static readonly DependencyProperty ContentTemplateProperty
  • DataTemplate ContentTemplate { get; set; }
  • static readonly DependencyProperty IsModalProperty
  • bool IsModal { get; set; }
  • static readonly DependencyProperty StartupPositionProperty
  • WindowPositions StartupPosition { get; set; } = CenterScreen
  • static readonly DependencyProperty AllowMultipleNotificationWindowsProperty
  • bool AllowMultipleNotificationWindows { get; set; }
  • protected override void Invoke(object parameter) — Main logic: creates/positions window, sets up content, shows dialog.
  • protected void PrepareContentForWindow(Notification notification, Window wrapperWindow) — Injects RegionManager and sets HostWindow/HostNotification on content implementing IRegionManagerAware/IPopupWindowActionAware.
  • protected Window GetWindow(Notification notification) — Returns window instance (uses WindowContent if provided, else creates ConfirmationWindow/NotificationWindow).
  • protected Window CreateWindow(Notification notification) — Factory for ConfirmationWindow or NotificationWindow based on notification type.
  • private Uri GetImageUri(PopupWindowImage windowImage) — Maps PopupWindowImage enum to image URI (e.g., error_48.png).

• BrowseForFolderDialog

  • public string SelectedFolder { get; protected set; }
  • public string Title { get; set; }
  • public string InitialFolder { get; set; }
  • public string InitialExpandedFolder { get; set; }
  • public string OKButtonText { get; set; }
  • public BROWSEINFOW BrowseInfo { get; protected set; }
  • public BrowseInfoFlags BrowserDialogFlags { get; set; }
  • public BrowseForFolderDialog() — Initializes BROWSEINFOW with default flags (BIF_NEWDIALOGSTYLE).
  • public Nullable<bool> ShowDialog() / ShowDialog(Window owner) — Shows Win32 folder browser dialog; returns true if folder selected, false otherwise.
  • private int BrowseEventHandler(...) — Callback for dialog events (BFFM_INITIALIZED, BFFM_SELCHANGED, etc.); sets initial selection, OK text, and updates SelectedFolder.

Enums & Constants

• BrowseInfoFlags — Flags for BROWSEINFOW.ulFlags (e.g., BIF_RETURNONLYFSDIRS, BIF_NEWDIALOGSTYLE, BIF_USENEWUI).
• MessageFromBrowser — Win32 messages from the dialog (BFFM_INITIALIZED, BFFM_SELCHANGED, BFFM_VALIDATEFAILEDW).
• MessageToBrowser — Win32 messages to the dialog (BFFM_SETSELECTIONW, BFFM_SETOKTEXT, BFFM_SETEXPANDED).
• PopupWindowImage — Used by GetImageUri (values: Error, Question, Warning, Information).

3. Invariants

• System menu removal: Both ConfirmationWindow and NotificationWindow unconditionally remove the system menu (close button) by clearing WS_SYSMENU in the window style during SourceInitialized. This is non-negotiable and applies to all instances.
• RegionManager injection: PrepareContentForWindow ensures that if WindowContent (or its DataContext) lacks a RegionManager, a new scoped RegionManager is created and assigned. This is required for region support inside popups.
• Content ownership: PopupWindowAction.Invoke skips dialog creation if WindowContent.Parent != null (content already in visual tree).
• Single notification window: When AllowMultipleNotificationWindows is false, only one NotificationWindow is tracked via _openedNotificationWindow; subsequent notifications reuse the same window (implementation detail inferred from assignment in Invoke).
• Default image: NotificationWindow.ImageUri defaults to warning_48.png unless overridden.
• Default button/image for ConfirmationEx: Buttons = OKCancel, Image = Question, Result = default (uninitialized).

4. Dependencies

External Dependencies

• Prism Library:
  • Microsoft.Practices.Prism.Regions (IRegionManager, RegionManager.RegionManagerProperty)
  • Microsoft.Practices.Prism.Interactivity.InteractionRequest (IInteractionRequest, Notification, Confirmation, InteractionRequestedEventArgs)
• WPF Framework:
  • System.Windows, System.Windows.Interop, System.Windows.Data
  • System.Windows.Interactivity (TriggerAction)
• Win32 APIs (via P/Invoke):
  • user32.dll: SetWindowLong, GetWindowLong, SendMessageW
  • shell32.dll: SHBrowseForFolderW, SHGetPathFromIDList
• .NET Base:
  • System.Runtime.InteropServices, System.Text, System.Reflection

Internal Dependencies

• DTS.Common.Enums: Uses PopupWindowImage enum (referenced in PopupWindowAction.GetImageUri).
• DTS.Common.Events: Referenced in PopupWindowAction.cs imports (no usage in provided source).

5. Gotchas

• Typo in clipboard method: NotificationWindow.CoppyToClibord_Click has misspelled method name (CoppyToClibord instead of CopyToClipboard).
• Connect methods are stubs: Both ConfirmationWindow.Connect and NotificationWindow.Connect throw NotImplementedException or do nothing; they are not functional.
• BrowseForFolderDialog uses ANSI/Unicode marshaling inconsistently: SendMessageW is overloaded for both uint and MessageToBrowser, but the string overload uses [MarshalAs(UnmanagedType.LPWStr)]. Ensure correct usage to avoid encoding issues.
• BrowseForFolderDialog does not validate InitialExpandedFolder: If InitialExpandedFolder is invalid, the dialog may fail silently or behave unexpectedly.
• PopupWindowAction.Invoke does not handle WindowContent reuse: If WindowContent is reused across multiple invocations, its parent check (WindowContent.Parent != null) may prevent display.
• ConfirmationWindow/NotificationWindow lack close button: Users cannot close via the title bar; must rely on dialog buttons or code-triggered close.
• BrowseForFolderDialog does not expose BROWSEINFO.hwndOwner setter: ShowDialog(Window owner) sets hwndOwner, but direct manipulation of BrowseInfo.hwndOwner after construction may be overwritten.
• PopupWindowAction uses deprecated CenterOverAssociatedObject logic: The property is commented out in Invoke, but remains in the source; developers may mistakenly use it.
• BrowseForFolderDialog uses fixed buffer size (260): Assumes MAX_PATH; may fail for paths >260 characters (Windows limitation, but not documented in API).
• ConfirmationEx.Timeout and TimeoutResult are commented out: No timeout functionality is active despite being defined in source comments.
• PopupWindowAction.AllowMultipleNotificationWindows only affects NotificationWindow: Behavior for ConfirmationWindow is unchanged regardless of this flag.