65 lines
5.4 KiB
Markdown
65 lines
5.4 KiB
Markdown
|
---
|
|||
|
|
source_files:
|
|||
|
|
- Common/DTS.CommonCore/RegionManager/RegionAdapters/StackPanelRegionAdapter.cs
|
|||
|
|
- Common/DTS.CommonCore/RegionManager/RegionAdapters/ViewerStackPanelRegionAdapter.cs
|
|||
|
|
generated_at: "2026-04-16T02:50:38.403475+00:00"
|
|||
|
|
model: "Qwen/Qwen3-Coder-Next-FP8"
|
|||
|
|
schema_version: 1
|
|||
|
|
sha256: "01eecd59b616feb7"
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# RegionAdapters
|
|||
|
|
|
|||
|
|
## 1. Purpose
|
|||
|
|
This module provides custom Prism region adapters for integrating WPF `StackPanel` controls into the Prism region management system. Specifically, it enables views to be dynamically added to and removed from a `StackPanel` via Prism’s region abstraction, maintaining synchronization between the region’s view collection and the `StackPanel`’s `Children` collection. Two adapters exist: `StackPanelRegionAdapter` (general-purpose) and `ViewerStackPanelRegionAdapter` (likely intended for specialized viewer scenarios), both implementing identical adaptation logic but registered as distinct types—suggesting potential future divergence or explicit separation of concerns in the system’s region management strategy.
|
|||
|
|
|
|||
|
|
## 2. Public Interface
|
|||
|
|
|
|||
|
|
### `StackPanelRegionAdapter`
|
|||
|
|
- **Constructor**:
|
|||
|
|
`public StackPanelRegionAdapter(IRegionBehaviorFactory regionBehaviorFactory)`
|
|||
|
|
Initializes a new instance, passing the behavior factory to the base `RegionAdapterBase<StackPanel>` constructor.
|
|||
|
|
|
|||
|
|
- **`Adapt` method** (override):
|
|||
|
|
`protected override void Adapt(IRegion region, StackPanel regionTarget)`
|
|||
|
|
Subscribes to the `CollectionChanged` event of `region.Views`. On `Add`, appends new `UIElement` instances to `regionTarget.Children`; on `Remove`, removes matching elements from `regionTarget.Children` (if present). Does nothing if `region` is `null`.
|
|||
|
|
|
|||
|
|
- **`CreateRegion` method** (override):
|
|||
|
|
`protected override IRegion CreateRegion()`
|
|||
|
|
Returns a new `AllActiveRegion` instance, meaning all views in the region are kept active (not deactivated/destroyed on removal).
|
|||
|
|
|
|||
|
|
### `ViewerStackPanelRegionAdapter`
|
|||
|
|
- **Constructor**:
|
|||
|
|
`public ViewerStackPanelRegionAdapter(IRegionBehaviorFactory regionBehaviorFactory)`
|
|||
|
|
Identical to `StackPanelRegionAdapter`; passes `regionBehaviorFactory` to the base constructor.
|
|||
|
|
|
|||
|
|
- **`Adapt` method** (override):
|
|||
|
|
`protected override void Adapt(IRegion region, StackPanel regionTarget)`
|
|||
|
|
Identical behavior to `StackPanelRegionAdapter.Adapt`.
|
|||
|
|
|
|||
|
|
- **`CreateRegion` method** (override):
|
|||
|
|
`protected override IRegion CreateRegion()`
|
|||
|
|
Identical behavior to `StackPanelRegionAdapter.CreateRegion`; returns `AllActiveRegion`.
|
|||
|
|
|
|||
|
|
## 3. Invariants
|
|||
|
|
- `regionTarget` (the `StackPanel`) must be non-null when `Adapt` is called (though `region` may be `null`, in which case the method exits early).
|
|||
|
|
- Views added to the region are appended to the *end* of `StackPanel.Children` in the order they appear in `e.NewItems`.
|
|||
|
|
- Views removed from the region are removed from `StackPanel.Children` *only if* they are currently present in the collection (no exception thrown if missing).
|
|||
|
|
- The `AllActiveRegion` returned by `CreateRegion()` ensures all views remain active; no view deactivation occurs on removal—only visual removal from the `StackPanel`.
|
|||
|
|
- The `CollectionChanged` event handler is attached exactly once per `Adapt` call (no duplicate subscriptions are prevented).
|
|||
|
|
|
|||
|
|
## 4. Dependencies
|
|||
|
|
- **Depends on**:
|
|||
|
|
- `Microsoft.Practices.Prism.Regions` (Prism library), specifically `RegionAdapterBase<T>`, `IRegion`, `IRegionBehaviorFactory`, and `AllActiveRegion`.
|
|||
|
|
- `System.Windows` and `System.Windows.Controls` (WPF), for `StackPanel`, `UIElement`, and `CollectionChanged` event handling.
|
|||
|
|
- **Used by**:
|
|||
|
|
- Prism’s region management system (via `RegionAdapterMappings` or similar registration), where `StackPanel` targets are mapped to these adapters.
|
|||
|
|
- Likely consumed by UI modules that use `StackPanel` as a layout container for dynamic view injection (e.g., tool windows, viewer panes).
|
|||
|
|
- `ViewerStackPanelRegionAdapter` suggests a dedicated path for viewer-related regions (e.g., medical imaging, CAD, or data visualization contexts), though its usage is not explicit in the source.
|
|||
|
|
|
|||
|
|
## 5. Gotchas
|
|||
|
|
- **No deduplication or ordering guarantees**: If the same view is added multiple times to the region (e.g., via duplicate `Add` notifications), it will be added multiple times to `StackPanel.Children`.
|
|||
|
|
- **No cleanup on adapter disposal**: The `CollectionChanged` event handler is attached but never detached. If `Adapt` is called multiple times on the same `StackPanel` instance (e.g., due to region recreation), multiple handlers will accumulate, causing duplicate additions/removals per event.
|
|||
|
|
- **`AllActiveRegion` behavior may be unexpected**: Views removed from the region remain in memory (as `AllActiveRegion` does not deactivate them), but they are only visually removed from the `StackPanel`. This could lead to memory leaks if views hold unmanaged resources.
|
|||
|
|
- **Identical implementations**: The near-identical code in `StackPanelRegionAdapter` and `ViewerStackPanelRegionAdapter` suggests possible technical debt or incomplete refactoring. Without additional context (e.g., future plans for divergent behavior), the duplication is unjustified.
|
|||
|
|
- **No handling for `Replace` or `Reset` actions**: Only `Add` and `Remove` actions are handled; `NotifyCollectionChangedAction.Replace` or `Reset` will be silently ignored, potentially leaving the `StackPanel` out of sync with the region.
|