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

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