DP44/enriched-qwen3-coder-next/Common/DTS.CommonCore/RegionManager/RegionAdapters.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.CommonCore/RegionManager/RegionAdapters/StackPanelRegionAdapter.cs Common/DTS.CommonCore/RegionManager/RegionAdapters/ViewerStackPanelRegionAdapter.cs	2026-04-16T02:50:38.403475+00:00	Qwen/Qwen3-Coder-Next-FP8	1	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.