70 lines
3.9 KiB
Markdown
70 lines
3.9 KiB
Markdown
---
|
|
source_files:
|
|
- DTS Viewer/DTS.Viewer/RegionAdapters/StackPanelRegionAdapter.cs
|
|
generated_at: "2026-04-16T14:01:11.367542+00:00"
|
|
model: "zai-org/GLM-5-FP8"
|
|
schema_version: 1
|
|
sha256: "d99a52248dae627a"
|
|
---
|
|
|
|
# StackPanelRegionAdapter Documentation
|
|
|
|
## 1. Purpose
|
|
|
|
`StackPanelRegionAdapter` is a Prism region adapter that enables `StackPanel` controls to participate in Prism's region management system. It bridges the gap between Prism's `IRegion` abstraction and WPF's `StackPanel`, allowing views to be dynamically added to and removed from a `StackPanel` through Prism's navigation and view injection mechanisms. This adapter is part of the `DTS.Viewer` namespace and follows the Prism framework's adapter pattern for region management.
|
|
|
|
## 2. Public Interface
|
|
|
|
### Class: `StackPanelRegionAdapter`
|
|
**Inherits from:** `RegionAdapterBase<StackPanel>`
|
|
|
|
#### Constructor
|
|
```csharp
|
|
public StackPanelRegionAdapter(IRegionBehaviorFactory regionBehaviorFactory)
|
|
```
|
|
Initializes a new instance of the adapter with the specified region behavior factory. Delegates to the base class constructor.
|
|
|
|
#### Method: `Adapt`
|
|
```csharp
|
|
protected override void Adapt(IRegion region, StackPanel regionTarget)
|
|
```
|
|
Subscribes to the `CollectionChanged` event on `region.Views` and synchronizes views with the `StackPanel`'s `Children` collection:
|
|
- **Add action:** Iterates through `e.NewItems` and adds each `UIElement` to `regionTarget.Children`
|
|
- **Remove action:** Iterates through `e.OldItems` and removes each `UIElement` from `regionTarget.Children` if present
|
|
- **Null region:** Returns immediately without any action
|
|
|
|
#### Method: `CreateRegion`
|
|
```csharp
|
|
protected override IRegion CreateRegion()
|
|
```
|
|
Creates and returns a new instance of `AllActiveRegion`. This region type considers all contained views as active at all times.
|
|
|
|
## 3. Invariants
|
|
|
|
- The adapter always creates an `AllActiveRegion`; it does not support activation/deactivation semantics
|
|
- The `Adapt` method will not throw if `region` is null; it returns silently
|
|
- Only `UIElement` instances can be added to the `StackPanel` through this adapter (enforced by WPF's `Children` collection)
|
|
- The adapter does not handle `NotifyCollectionChangedAction.Replace`, `Move`, or `Reset` actions—only `Add` and `Remove`
|
|
|
|
## 4. Dependencies
|
|
|
|
### Imports (this module depends on):
|
|
- `System.Collections.Specialized` — `NotifyCollectionChangedAction`, `NotifyCollectionChangedEventArgs`
|
|
- `System.Windows` — `UIElement`
|
|
- `System.Windows.Controls` — `StackPanel`
|
|
- `Microsoft.Practices.Prism.Regions` — `IRegion`, `IRegionBehaviorFactory`, `RegionAdapterBase<T>`, `AllActiveRegion`
|
|
|
|
### Dependents (inferred):
|
|
- This adapter must be registered with Prism's region adapter mappings during application bootstrap for Prism to use it for `StackPanel` regions. The registration code is not present in this file.
|
|
|
|
## 5. Gotchas
|
|
|
|
1. **Incomplete collection change handling:** The `switch` statement in `Adapt` only handles `Add` and `Remove` actions. `Replace`, `Move`, and `Reset` actions fall through without any handling, which could lead to inconsistent state if the region's view collection undergoes those operations.
|
|
|
|
2. **Redundant variable assignment in remove loop:** The code assigns `elementLoopVariable` from the loop, then immediately reassigns it to a local `element` variable. This is unnecessary and adds no value.
|
|
|
|
3. **No null checks on `NewItems`/`OldItems`:** The code assumes `e.NewItems` and `e.OldItems` are non-null. While Prism typically provides these, a malformed `CollectionChanged` event could cause a `NullReferenceException`.
|
|
|
|
4. **Silent failure on null region:** The null check at the start of `Adapt` returns without any logging or exception, which could make debugging difficult if a null region is passed unexpectedly.
|
|
|
|
5. **AllActiveRegion semantics:** Developers expecting fine-grained control over view activation (e.g., single-active regions like tab controls) should be aware that all views in this region are always considered active. |