DP44/enriched-partialglm/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-16T12:05:57.382273+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "e520922d284c9033"
---

# Documentation: DTS.Common.Dialogs

## 1. Purpose
This module provides a custom dialog management infrastructure for WPF applications built on the Prism framework. It extends Prism's `InteractionRequest` patterns to support custom window styling (such as hiding the system close button), region management within popups, and specific dialog types like confirmations and notifications. Additionally, it provides a wrapper (`BrowseForFolderDialog`) around the Win32 API `SHBrowseForFolder` for folder selection capabilities not natively available in standard WPF dialogs.

## 2. Public Interface

### Interfaces

**`IRegionManagerAware`**
- `IRegionManager RegionManager { get; set; }`: Allows a view or view model to receive a scoped `IRegionManager` when hosted inside a popup window.

**`IPopupWindowActionAware`**
- `Window HostWindow { get; set; }`: Provides access to the hosting window instance.
- `Notification HostNotification { get; set; }`: Provides access to the notification context (e.g., `Confirmation` or `Notification` object) passed to the window.

### Classes

**`ConfirmationEx`** (Inherits `Confirmation`)
- `MessageBoxButton Buttons { get; set; }`: Defaults to `MessageBoxButton.OKCancel`. Defines buttons shown in the confirmation.
- `MessageBoxImage Image { get; set; }`: Defaults to `MessageBoxImage.Question`. Defines the icon shown.
- `MessageBoxResult Result { get; set; }`: Stores the result of the user interaction.

**`ConfirmationWindow`** (Inherits `Window`)
- `DataTemplate ConfirmationTemplate { get; set; }`: Dependency property used to define the visual presentation of the confirmation content.
- `void Connect(int connectionId, object target)`: Throws `NotImplementedException`.

**`NotificationWindow`** (Inherits `Window`)
- `DataTemplate NotificationTemplate { get; set; }`: Dependency property for the notification content layout.
- `Uri ImageUri { get; set; }`: Dependency property for the notification icon. Defaults to a pack URI pointing to `warning_48.png`.
- `void Connect(int connectionId, object target)`: Empty implementation.

**`PopupWindowAction`** (Inherits `TriggerAction<FrameworkElement>`)
- **Properties**:
    - `FrameworkElement WindowContent`: The root visual element to display in the popup.
    - `DataTemplate ContentTemplate`: The template applied to the content.
    - `bool IsModal`: Determines if the window blocks interaction with the owner.
    - `WindowPositions StartupPosition`: Enum (`CenterOwner`, `CenterScreen`). Defaults to `CenterScreen`.
    - `bool AllowMultipleNotificationWindows`: Prevents or allows concurrent notification windows.
- **Methods**:
    - `protected override void Invoke(object parameter)`: Executes the trigger, creates the window, sets up region managers, and shows the dialog.
    - `protected Window GetWindow(Notification notification)`: Factory method returning the appropriate `Window` wrapper.
    - `protected Window CreateWindow(Notification notification)`: Creates a `ConfirmationWindow` or `NotificationWindow` if `WindowContent` is null.

**`BrowseForFolderDialog`**
- **Properties**:
    - `string SelectedFolder`: The path chosen by the user.
    - `string Title`: The text displayed above the tree view.
    - `string InitialFolder`: The path selected on startup.
    - `string InitialExpandedFolder`: The path selected and expanded on startup.
    - `string OKButtonText`: Custom text for the confirmation button.
    - `BrowseInfoFlags BrowserDialogFlags`: Win32 flags controlling dialog behavior (defaults to `BIF_NEWDIALOGSTYLE`).
- **Methods**:
    - `Nullable<bool> ShowDialog()`: Shows the dialog modally.
    - `Nullable<bool> ShowDialog(Window owner)`: Shows the dialog modally with a WPF window owner.

## 3. Invariants

1.  **Window System Menu Removal**: Both `ConfirmationWindow` and `NotificationWindow` modify the window style upon initialization (`SourceInitialized`) to remove the `WS_SYSMENU` flag. This effectively hides the system menu and the close button from the title bar.
2.  **Region Management**: When `PopupWindowAction` invokes a dialog with `WindowContent` set, it guarantees that a scoped `IRegionManager` is attached to that content if one is not already present.
3.  **Visual Tree Parenting**: `PopupWindowAction.Invoke` will exit immediately without showing a window if `WindowContent` is already a child of another visual element (`WindowContent.Parent != null`).
4.  **Default Dialog Creation**: If `PopupWindowAction.WindowContent` is null, the action defaults to creating either a `ConfirmationWindow` (if the notification is `Confirmation`) or a `NotificationWindow` (if the notification content is `NotificationContentEventArgs`).

## 4. Dependencies

**Internal Dependencies (Inferred):**
- `DTS.Common.Enums`: Required for `PopupWindowImage` enum used in `PopupWindowAction.GetImageUri`.
- `DTS.Common.Events`: Required for `NotificationContentEventArgs` used in `PopupWindowAction.CreateWindow`.

**External Dependencies:**
- `Microsoft.Practices.Prism.Regions`: Used for `IRegionManager` and region scoping.
- `Microsoft.Practices.Prism.Interactivity.InteractionRequest`: Used for `Notification`, `Confirmation`, `InteractionRequestedEventArgs`, and `TriggerAction`.
- `System.Windows.Interactivity`: Used for `TriggerAction<FrameworkElement>`.
- `System.Windows`: Core WPF types.
- `user32.dll`: P/Invoke for window styling (`SetWindowLong`, `GetWindowLong`) and messaging.
- `shell32.dll`: P/Invoke for folder browsing (`SHBrowseForFolderW`, `SHGetPathFromIDList`).

## 5. Gotchas

1.  **Hardcoded Clipboard Text**: `NotificationWindow` contains an event handler `CoppyToClibord_Click` (note the typo in method name) that sets the clipboard text to the hardcoded string "Hello, clipboard". This appears to be debug/test code left in the production source.
2.  **Inconsistent Image Paths**:
    - `NotificationWindow` defaults its `ImageUri` to a path containing `RibbonControl/Images/warning_48.png`.
    - `PopupWindowAction.GetImageUri` constructs paths pointing to `Images/` (without `RibbonControl`).
    - This inconsistency suggests a refactoring mismatch or missing resource files; developers adding new icons should verify the correct pack URI structure.
3.  **Unimplemented Interface Method**: The `Connect` method in `ConfirmationWindow` throws `NotImplementedException`. This method is typically associated with the `IComponentConnector` interface generated by the WPF compiler for XAML parsing. The manual implementation throwing an exception suggests the code-behind may be out of sync with the XAML or manually implementing an interface it shouldn't.
4.  **COM Initialization Requirement**: `BrowseForFolderDialog` defaults to `BIF_NEWDIALOGSTYLE`. The Win32 documentation for this flag states that `OleInitialize` must be called before using the API. This class does not call `OleInitialize`; the consuming application is responsible for COM initialization.
5.  **Commented Out Features**: Both `ConfirmationEx` and `PopupWindowAction` contain significant blocks of commented-out code related to "Timeout" functionality (auto-closing dialogs). This suggests unfinished or deprecated features that may confuse developers looking for timeout capabilities.