DP44/docs/ai/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-17T15:34:12.771311+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "9007c4cfc646753a"
---

# Documentation: DTS.Common.Dialogs

## 1. Purpose

This module provides a WPF dialog infrastructure built on Prism's InteractionRequest pattern. It enables the display of modal and non-modal popup windows (confirmations and notifications) through trigger actions, supports region management within dialogs, and provides a Win32 wrapper for native folder selection dialogs. The module bridges Prism's MVVM-friendly interaction requests with custom WPF window implementations.

---

## 2. Public Interface

### Interfaces

#### `IRegionManagerAware`
Enables objects to receive a scoped `IRegionManager` instance.
```csharp
IRegionManager RegionManager { get; set; }
```

#### `IPopupWindowActionAware`
Enables objects to receive host window and notification context.
```csharp
Window HostWindow { get; set; }
Notification HostNotification { get; set; }
```

---

### Classes

#### `ConfirmationEx : Confirmation`
Extended confirmation with configurable buttons and imagery.

| Property | Type | Default |
|----------|------|---------|
| `Buttons` | `MessageBoxButton` | `MessageBoxButton.OKCancel` |
| `Image` | `MessageBoxImage` | `MessageBoxImage.Question` |
| `Result` | `MessageBoxResult` | (unset) |

---

#### `ConfirmationWindow`
WPF window for displaying confirmations. Removes the system close button via Win32 API.

| Member | Type | Description |
|--------|------|-------------|
| `ConfirmationTemplateProperty` | `DependencyProperty` | Registered for `DataTemplate` |
| `ConfirmationTemplate` | `DataTemplate` | Template for confirmation content |
| `Connect(int, object)` | `void` | **Throws `NotImplementedException`** |

---

#### `NotificationWindow : Window`
WPF window for displaying notifications. Removes the system close button via Win32 API.

| Member | Type | Description |
|--------|------|-------------|
| `NotificationTemplateProperty` | `DependencyProperty` | Registered for `DataTemplate` |
| `NotificationTemplate` | `DataTemplate` | Template for notification content |
| `ImageUriProperty` | `DependencyProperty` | Registered for `Uri` |
| `ImageUri` | `Uri` | URI for notification image |
| `Connect(int, object)` | `void` | Empty implementation |
| `CoppyToClibord_Click(object, RoutedEventArgs)` | `void` | Sets clipboard to hardcoded string |

---

#### `PopupWindowAction : TriggerAction<FrameworkElement>`
Trigger action that displays popup windows in response to `InteractionRequestedEventArgs`.

**Nested Enum:**
```csharp
public enum WindowPositions { CenterOwner, CenterScreen }
```

**Dependency Properties:**

| Property | Type | Default |
|----------|------|---------|
| `WindowContent` | `FrameworkElement` | `null` |
| `ContentTemplate` | `DataTemplate` | `null` |
| `IsModal` | `bool` | `null` (effectively false) |
| `StartupPosition` | `WindowPositions` | `CenterScreen` |
| `CenterOverAssociatedObject` | `bool` | `null` (legacy, unused) |
| `AllowMultipleNotificationWindows` | `bool` | `null` (effectively false) |

**Protected Methods:**
- `Invoke(object parameter)` — Main entry point; creates and displays the window.
- `PrepareContentForWindow(Notification, Window)` — Wires up `IRegionManagerAware` and `IPopupWindowActionAware` on content and its DataContext.
- `GetWindow(Notification)` — Returns either a generic window with `WindowContent` or a specialized window via `CreateWindow`.
- `CreateWindow(Notification)` — Creates `ConfirmationWindow` or `NotificationWindow` based on notification type.
- `GetImageUri(PopupWindowImage)` — Maps enum to pack URI for images.

---

#### `BrowseForFolderDialog`
Win32 `SHBrowseForFolder` wrapper for folder selection.

**Properties:**

| Property | Type | Description |
|----------|------|-------------|
| `SelectedFolder` | `string` | Final selected path (read-only after dialog) |
| `Title` | `string` | Dialog header text |
| `InitialFolder` | `string` | Pre-selected folder path |
| `InitialExpandedFolder` | `string` | Pre-selected and expanded folder (overrides `InitialFolder`) |
| `OKButtonText` | `string` | Custom OK button text |
| `BrowseInfo` | `BROWSEINFOW` | Direct access to Win32 structure |
| `BrowserDialogFlags` | `BrowseInfoFlags` | Flags for dialog behavior |

**Methods:**
- `ShowDialog()` → `Nullable<bool>` — Shows dialog without owner.
- `ShowDialog(Window owner)` → `Nullable<bool>` — Shows dialog with WPF window owner.

**Nested Types:**
- `BrowseCallbackProc` — Delegate for browse event handling.
- `BrowseInfoFlags` — Flags enum (`BIF_NEWDIALOGSTYLE`, `BIF_RETURNONLYFSDIRS`, etc.).
- `BROWSEINFOW` — Win32 structure with `hwndOwner`, `pidlRoot`, `pszDisplayName`, `lpszTitle`, `ulFlags`, `lpfn`, `lParam`, `iImage`.
- `MessageFromBrowser` — Messages received from dialog (`BFFM_INITIALIZED`, `BFFM_SELCHANGED`, etc.).
- `MessageToBrowser` — Messages sent to dialog (`BFFM_SETSELECTIONW`, `BFFM_SETEXPANDED`, `BFFM_SETOKTEXT`, etc.).

---

## 3. Invariants

1. **Window close button removal**: Both `ConfirmationWindow` and `NotificationWindow` always strip the `WS_SYSMENU` style during `SourceInitialized`, removing the system close button.

2. **WindowContent parent check**: `PopupWindowAction.Invoke` returns immediately without action if `WindowContent.Parent != null`.

3. **Notification type requirement**: `PopupWindowAction.CreateWindow` returns `null` if the notification is not a `Confirmation` and `notification.Content` is not castable to `NotificationContentEventArgs`.

4. **Default browse flags**: `BrowseForFolderDialog` always initializes with `BIF_NEWDIALOGSTYLE`.

5. **Scoped RegionManager**: If `WindowContent` lacks a `RegionManager`, `PopupWindowAction` creates a new scoped `RegionManager` and assigns it.

---

## 4. Dependencies

**External Dependencies (from imports):**
- `Microsoft.Practices.Prism.Regions` — `IRegionManager`, `RegionManager`
- `Microsoft.Practices.Prism.Interactivity.InteractionRequest` — `Notification`, `Confirmation`, `InteractionRequestedEventArgs`
- `System.Windows.Interactivity` — `TriggerAction<T>`
- `System.Windows` — WPF core types

**Internal Dependencies (inferred):**
- `DTS.Common.Enums.PopupWindowImage` — Enum for notification image types
- `DTS.Common.Events.NotificationContentEventArgs` — Content type for notifications

**Native Dependencies:**
- `user32.dll` — `SetWindowLong`, `GetWindowLong`, `SendMessageW`
- `shell32.dll` — `SHBrowseForFolderW`, `SHGetPathFromIDList`

---

## 5. Gotchas

1. **`ConfirmationWindow.Connect` throws**: The `Connect` method is implemented but throws `NotImplementedException`. Purpose is unclear from source—may be related to XAML compilation or an interface requirement.

2. **Hardcoded clipboard text**: `NotificationWindow.CoppyToClibord_Click` (note typo in method name) sets clipboard to the literal string `"Hello, clipboard"`. This appears to be debug/test code left in production.

3. **Commented-out timeout functionality**: Both `ConfirmationEx` and `PopupWindowAction` contain commented-out properties and logic for dialog auto-close/timeout (`Timeout`, `TimeoutResult`, `TimeoutInterval`). This feature was partially implemented but disabled.

4. **Legacy `CenterOverAssociatedObject` property**: The `CenterOverAssociatedObjectProperty` is registered but its usage in `Invoke` is commented out. `StartupPosition` is the current mechanism.

5. **Default dependency property values**: `IsModal` and `AllowMultipleNotificationWindows` default to `null` (via `PropertyMetadata(null)`), which boxes to `false` when cast. This is unconventional—typically defaults are explicit `false`.

6. **Image path relies on assembly structure**: `GetImageUri` constructs pack URIs expecting images in an `Images/` folder within the executing assembly. Relocation of image resources will break this.