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

source_files, generated_at, model, schema_version, sha256

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

Dialogs Module Documentation

1. Purpose

This module provides infrastructure for displaying modal and non-modal dialog windows in a WPF application using Prism's interaction request pattern. It extends standard Prism Confirmation and Notification types with additional UI customization capabilities (e.g., button types, icons, window positioning) and provides dedicated window implementations (ConfirmationWindow, NotificationWindow) that suppress the standard close button via Win32 interop. The PopupWindowAction class acts as a behavior trigger that responds to interaction requests by creating and displaying popup windows, while BrowseForFolderDialog wraps the Win32 SHBrowseForFolder API for folder selection. The module supports region management and custom data context wiring through the IRegionManagerAware and IPopupWindowActionAware interfaces.

2. Public Interface

Interfaces

• IRegionManagerAware

  public interface IRegionManagerAware
  {
      IRegionManager RegionManager { get; set; }
  }
  

  Allows view models or views to receive a RegionManager instance for region-based navigation within a popup window.

• IPopupWindowActionAware

  public interface IPopupWindowActionAware
  {
      Window HostWindow { get; set; }
      Notification HostNotification { get; set; }
  }
  

  Enables views or view models to access the host window and the original Notification/Confirmation context when displayed via PopupWindowAction.

Classes

• ConfirmationEx

  public class ConfirmationEx : Confirmation
  

  Extends Prism's Confirmation with additional properties:

  • Buttons MessageBoxButton { get; set; } = MessageBoxButton.OKCancel
  • Image MessageBoxImage { get; set; } = MessageBoxImage.Question
  • Result MessageBoxResult { get; set; }

• ConfirmationWindow

  public partial class ConfirmationWindow
  

  A window for displaying confirmation dialogs. Key members:

  • ConfirmationTemplate DataTemplate { get; set; }
  • Connect(int connectionId, object target) — throws NotImplementedException
  • Suppresses the close button via GetWindowLong/SetWindowLong on SourceInitialized.

• NotificationWindow

  public partial class NotificationWindow : Window
  

  A window for displaying notification dialogs. Key members:

  • NotificationTemplate DataTemplate { get; set; }
  • ImageUri Uri { get; set; } — defaults to warning_48.png
  • Connect(int connectionId, object target) — empty implementation
  • CoppyToClibord_Click(...) — sets clipboard to "Hello, clipboard"
  • Suppresses the close button via GetWindowLong/SetWindowLong on SourceInitialized.

• PopupWindowAction

  public class PopupWindowAction : TriggerAction<FrameworkElement>
  

  A Prism behavior that displays popup windows in response to interaction requests. Key properties:

  • WindowContent FrameworkElement { get; set; }
  • ContentTemplate DataTemplate { get; set; }
  • IsModal bool { get; set; }
  • StartupPosition WindowPositions { get; set; } — enum: CenterOwner, CenterScreen
  • AllowMultipleNotificationWindows bool { get; set; }
  • CenterOverAssociatedObject bool { get; set; } — commented out in current code
  • TimeoutInterval int and TimeoutResult ResultEnum — commented out

  Key methods:

  • Invoke(object parameter) — handles interaction request, positions window, sets up callbacks, and shows window (modal/non-modal).
  • PrepareContentForWindow(Notification notification, Window wrapperWindow) — injects RegionManager, sets HostWindow/HostNotification on IPopupWindowActionAware targets.
  • GetWindow(Notification notification) — creates or reuses a window.
  • CreateWindow(Notification notification) — instantiates ConfirmationWindow or NotificationWindow based on type.
  • GetImageUri(PopupWindowImage windowImage) — resolves image URIs (e.g., error_48.png, warning_48.png).

• BrowseForFolderDialog

  public class BrowseForFolderDialog
  

  Wraps Win32 SHBrowseForFolder for folder selection. Key properties:

  • SelectedFolder string { get; protected set; }
  • Title string { get; set; }
  • InitialFolder string { get; set; }
  • InitialExpandedFolder string { get; set; }
  • OKButtonText string { get; set; }
  • BrowseInfo BROWSEINFOW { get; protected set; }
  • BrowserDialogFlags BrowseInfoFlags { get; set; }

  Key methods:

  • ShowDialog() / ShowDialog(Window owner) — displays dialog and returns Nullable<bool>.
  • BrowseEventHandler(...) — callback for dialog events (BFFM_INITIALIZED, BFFM_SELCHANGED, etc.).

  Win32 interop:

  • SHBrowseForFolderW, SHGetPathFromIDList, SendMessageW
  • BROWSEINFOW, BrowseInfoFlags, MessageFromBrowser, MessageToBrowser enums/structs.

3. Invariants

• Window Closing Behavior: Both ConfirmationWindow and NotificationWindow unconditionally remove the system menu (and thus the close button) via GetWindowLong/SetWindowLong during SourceInitialized. This is non-negotiable and cannot be overridden.
• RegionManager Injection: PopupWindowAction.PrepareContentForWindow ensures that if WindowContent (or its DataContext) does not already have a RegionManager, a new scoped RegionManager is created and assigned. This is always applied when WindowContent is non-null.
• IPopupWindowActionAware Wiring: If WindowContent or its DataContext implements IPopupWindowActionAware, HostWindow and HostNotification are always set to the created window and notification context.
• Window Content Ownership: PopupWindowAction.Invoke returns early if WindowContent.Parent != null, preventing reuse of content already in a visual tree.
• Multiple Notifications: When AllowMultipleNotificationWindows is false, only one NotificationWindow is retained in _openedNotificationWindow; subsequent notifications reuse this instance (though the code does not show explicit reuse logic beyond assignment).
• BrowseForFolderDialog State: InitialExpandedFolder overrides InitialFolder when set during BFFM_INITIALIZED.

4. Dependencies

External Dependencies

• Prism.Core (via Prism.Regions, IRegionManager, InteractionRequestedEventArgs)
• Microsoft.Xaml.Behaviors (via TriggerAction<FrameworkElement>)
• System.Windows (WPF types: Window, DataTemplate, FrameworkElement, Uri, Clipboard)
• Win32 APIs (via user32.dll, shell32.dll): SetWindowLong, GetWindowLong, SHBrowseForFolderW, SHGetPathFromIDList, SendMessageW

Internal Dependencies

• DTS.Common.Interactivity (for Notification, NotificationContentEventArgs, PopupWindowImage)
• DTS.Common.Enums (for PopupWindowImage)
• DTS.Common.Events (referenced but no direct usage in these files)

Depended Upon By

• Likely used by UI layers (Views) via PopupWindowAction behaviors bound to interaction requests.
• BrowseForFolderDialog is likely consumed by view models or services requiring folder selection.

5. Gotchas

• ConfirmationWindow.Connect throws NotImplementedException: This method is present but non-functional; callers must avoid invoking it.
• NotificationWindow.CoppyToClibord_Click is hardcoded: Sets clipboard to "Hello, clipboard" — likely a placeholder or debugging artifact.
• CenterOverAssociatedObject is commented out: The legacy property is defined but unused; developers should use StartupPosition instead.
• Timeout behavior is commented out: TimeoutInterval and TimeoutResult properties exist only in comments; no auto-cancellation is implemented.
• BrowseForFolderDialog requires OleInitialize() for BIF_NEWDIALOGSTYLE: The documentation comment for BIF_NEWDIALOGSTYLE notes this requirement, but the class does not enforce or perform it.
• BrowseForFolderDialog uses SelectedFolder as both input and output: InitialFolder and InitialExpandedFolder set initial state, but SelectedFolder is updated during BFFM_SELCHANGED and returned as the final selection.
• PopupWindowAction.GetWindow creates a new Window when WindowContent is set: This may lead to unexpected window hierarchy if WindowContent is reused elsewhere.
• No validation of PopupWindowImage values: GetImageUri defaults to "warning_48.png" for unknown values — no exception or warning is raised.