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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.Common/RegionManager/RegionAdapters/StackPanelRegionAdapter.cs Common/DTS.Common/RegionManager/RegionAdapters/ViewerStackPanelRegionAdapter.cs	2026-04-16T03:27:23.682098+00:00	Qwen/Qwen3-Coder-Next-FP8	1	46a3e6b99bc63fd1

RegionAdapters

Documentation: StackPanelRegionAdapter and ViewerStackPanelRegionAdapter

---

1. Purpose

This module provides two Prism region adapters—StackPanelRegionAdapter and ViewerStackPanelRegionAdapter—that enable Prism region management (view registration, activation, and removal) to work with WPF StackPanel controls. Both adapters synchronize the Views collection of a Prism IRegion with the Children collection of a StackPanel, enabling declarative region usage in XAML (e.g., <prism:RegionManager.RegionName>...</prism:RegionManager.RegionName> attached to a StackPanel). They are used to host dynamic, stack-ordered UI content in Prism-based views, with ViewerStackPanelRegionAdapter likely reserved for specialized viewer scenarios (e.g., document/image viewers), though its behavior is currently identical to StackPanelRegionAdapter.

---

2. Public Interface

Both classes are public and inherit from Prism.Regions.RegionAdapterBase<StackPanel>. They expose only the base constructor and the two overridden abstract methods.

StackPanelRegionAdapter

• Constructor

  public StackPanelRegionAdapter(IRegionBehaviorFactory regionBehaviorFactory)
  

  Initializes a new instance of StackPanelRegionAdapter, passing regionBehaviorFactory to the base class.

• Adapt (protected override)

  protected override void Adapt(IRegion region, StackPanel regionTarget)
  

  Attaches a CollectionChanged handler to region.Views. On Add, appends each new UIElement in e.NewItems to regionTarget.Children. On Remove, removes each UIElement in e.OldItems from regionTarget.Children if present. Does nothing if region is null.

• CreateRegion (protected override)

  protected override IRegion CreateRegion()
  

  Returns a new instance of AllActiveRegion, meaning all views added to the region are active simultaneously (no activation/deactivation semantics).

ViewerStackPanelRegionAdapter

• Constructor

  public ViewerStackPanelRegionAdapter(IRegionBehaviorFactory regionBehaviorFactory)
  

  Identical to StackPanelRegionAdapter constructor.

• Adapt (protected override)

  protected override void Adapt(IRegion region, StackPanel regionTarget)
  

  Behaviorally identical to StackPanelRegionAdapter.Adapt.

• CreateRegion (protected override)

  protected override IRegion CreateRegion()
  

  Behaviorally identical to StackPanelRegionAdapter.CreateRegion.

Note

: No additional public methods, properties, or events are defined in either class.

---

3. Invariants

• Null Safety: Adapt exits early if region == null; no exception is thrown.
• Child Management:
  • Views are always added to the end of StackPanel.Children (order preserved by Add).
  • Views are only removed if regionTarget.Children.Contains(element) returns true; silent no-op otherwise.
  • No deduplication or uniqueness enforcement: adding the same UIElement instance multiple times (e.g., via multiple Add actions) will result in multiple children.
• Region Type: All regions created via CreateRegion() are AllActiveRegion instances, meaning:
  • All views in the region are considered active.
  • No view activation/deactivation lifecycle is enforced by the region itself.
• Event Subscription: The CollectionChanged handler is attached once per Adapt call and is never detached. Repeated calls to Adapt on the same StackPanel (e.g., due to re-adapter registration) will result in multiple handlers and duplicate operations.

---

4. Dependencies

Dependencies of this module:

• Prism Framework: Specifically Prism.Regions.RegionAdapterBase<T> and Prism.Regions.IRegionBehaviorFactory, IRegion, AllActiveRegion.
• WPF: System.Windows.Controls.StackPanel, System.Windows.UIElement.
• .NET Collections: System.Collections.Specialized.NotifyCollectionChangedAction, NotifyCollectionChangedEventArgs.

Dependencies on this module:

• Likely consumed by Prism region registration logic (e.g., RegionAdapterMappings) to map StackPanel targets to these adapters.
• ViewerStackPanelRegionAdapter suggests a domain-specific usage (e.g., in viewer modules), but no explicit consumers are visible in the source.

---

5. Gotchas

• Duplicate Event Handlers: Since Adapt does not detach previous handlers, re-adapter registration (e.g., due to module reload or re-initialization) will cause CollectionChanged events to be processed multiple times per change, leading to duplicate additions/removals or exceptions (e.g., ArgumentException if Children.Remove is called on a non-child). This is a critical risk if the adapter is registered multiple times.
• No Cleanup: No IDisposable implementation or handler unsubscription occurs. Long-lived StackPanels with short-lived regions may leak memory if the region is garbage-collected but the handler remains attached.
• Redundant Variable Assignment: In Remove handling, var element = elementLoopVariable; is unnecessary (no closure or loop-scope issue in C# 5+), suggesting legacy or defensive coding.
• Identical Implementations: StackPanelRegionAdapter and ViewerStackPanelRegionAdapter have identical logic. Unless future divergence is intended, this duplication is technical debt. The naming implies a semantic distinction (e.g., viewer-specific behavior), but none is implemented.
• No Exception Handling: If Children.Add or Children.Remove throws (e.g., due to cross-thread access or invalid element), the exception propagates unhandled.
• Assumes StackPanel.Children is Mutable: Relies on StackPanel.Children being a standard UIElementCollection. Custom or mocked StackPanel subclasses with non-standard children collections may behave unexpectedly.

None identified from source alone for other non-obvious behavior beyond the above.