init

enriched-qwen3-coder-next/DTS Viewer/DTS.Viewer/RegionAdapters.md

@@ -0,0 +1,70 @@
+---
+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.