152 lines
9.0 KiB
Markdown
152 lines
9.0 KiB
Markdown
---
|
|
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<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`**
|
|
```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<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. |