--- source_files: - 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 generated_at: "2026-04-16T02:55:52.161759+00:00" model: "Qwen/Qwen3-Coder-Next-FP8" schema_version: 1 sha256: "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`** ```csharp 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`** ```csharp 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`** ```csharp 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`** ```csharp 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`** ```csharp 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`** ```csharp public class PopupWindowAction : TriggerAction ``` 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`** ```csharp 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`. - `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`) - **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.