DP44/enriched-partialglm/Common/DTS.CommonCore/RibbonControl.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.CommonCore/RibbonControl/RibbonControlSelectionChanged.cs Common/DTS.CommonCore/RibbonControl/RibbonControlOperation.cs Common/DTS.CommonCore/RibbonControl/RibbonControlSelectionEventArgs.cs Common/DTS.CommonCore/RibbonControl/RibbonControlSelectionChangeBehavior.cs Common/DTS.CommonCore/RibbonControl/RibbonRegionAdapter.cs	2026-04-16T12:05:40.425898+00:00	zai-org/GLM-5-FP8	1	c0e1c8bd7f1a18f4

RibbonControl Module Documentation

1. Purpose

This module provides Prism region adapter infrastructure for integrating WPF Ribbon controls with the Prism navigation and region system. It enables dynamic addition and removal of RibbonTab and RibbonApplicationMenu items, synchronizes tab selection between document/workspace views and the Ribbon, and publishes selection change events through the Prism event aggregator for loose coupling between UI components.

---

2. Public Interface

RibbonControlSelectionChanged

Kind: Event class
Signature: public class RibbonControlSelectionChanged : CompositePresentationEvent<RibbonControlSelectionEventArgs>
Behavior: A Prism event used to broadcast when a Ribbon's selection has changed. Carries RibbonControlSelectionEventArgs payload indicating whether an item was added or removed.

---

RibbonControlOperation

Kind: Enumeration
Values:

• AddedItem — Indicates an item was added to the control
• RemovedItem — Indicates an item was removed from the control

Behavior: Used within RibbonControlSelectionEventArgs to describe the type of selection operation.

---

RibbonControlSelectionEventArgs

Kind: Event arguments class
Constructor: public RibbonControlSelectionEventArgs(RibbonControlOperation operation, object item)

Properties:

Property	Type	Access
Operation	RibbonControlOperation	get; (set via constructor)
Item	object	get; (set via constructor)

Behavior: Immutable payload carrying the operation type and the affected item for ribbon selection changes.

---

RibbonControlSelectionChangeBehavior

Kind: WPF Behavior (System.Windows.Interactivity.Behavior<Ribbon>)
Attached Property: public static readonly DependencyProperty TargetRibbonProperty

Properties:

Property	Type	Access
TargetRibbonControl	Ribbon	get; set;

Methods:

• protected override void OnAttached() — Subscribes to AssociatedObject.SelectionChanged; resolves IEventAggregator via ServiceLocator.Current
• protected override void OnDetaching() — Unsubscribes from AssociatedObject.SelectionChanged
• void Ribbon_SelectionChanged(object sender, SelectionChangedEventArgs e) — Publishes RibbonControlSelectionChanged events for each added/removed item

Behavior: When attached to a Ribbon, intercepts selection changes and publishes RibbonControlSelectionChanged events. Publishes separate events for added items (first item from AddedItems) and removed items (first item from RemovedItems).

---

RibbonRegionAdapter

Kind: Prism RegionAdapter (RegionAdapterBase<Ribbon>, IDisposable)
Constructor: public RibbonRegionAdapter(IRegionBehaviorFactory regionBehaviorFactory, IRegionManager regionManager, IEventAggregator eventAggregator)

Methods:

Method	Visibility	Description
Adapt(IRegion region, Ribbon regionTarget)	protected override	Wires up ActiveViews.CollectionChanged to add/remove RibbonTab and RibbonApplicationMenu items
CreateRegion()	protected override	Returns new AllActiveRegion instance
OnTabControlSelectionChanged(TabControlSelectionEventArgs e)	private	Handles TabControlSelectionChanged events to sync Ribbon tab selection
Dispose()	public	Unsubscribes from TabControlSelectionChanged event

Behavior: Adapts a Ribbon control to a Prism region. Handles RibbonTab additions (with auto-generated Uid, TabIndex sorting, and optional default selection via config), RibbonApplicationMenu additions, and RibbonTab removals. Listens to TabControlSelectionChanged events to activate corresponding Ribbon tabs when views implementing IRibbonTabInfoProvider are activated.

---

3. Invariants

1. Null Region Target: Adapt() throws ArgumentNullException if regionTarget is null.
2. Region Type: CreateRegion() always returns a new AllActiveRegion instance.
3. Uid Generation: If a RibbonTab or RibbonApplicationMenu has a null or empty Uid, one is auto-generated using Guid.NewGuid().GetHashCode().ToString(CultureInfo.InvariantCulture).
4. Tab Sorting: All RibbonTab items added to the region are sorted by TabIndex in ascending order.
5. Single Item Publication: RibbonControlSelectionChangeBehavior.Ribbon_SelectionChanged publishes at most one event for added items (index 0) and one for removed items (index 0), regardless of how many items are in the collections.
6. Event Subscription Lifecycle: RibbonRegionAdapter unsubscribes from TabControlSelectionChanged on disposal.

---

4. Dependencies

This module depends on:

• Microsoft.Practices.Prism.Events — CompositePresentationEvent, IEventAggregator
• Microsoft.Practices.Prism.Regions — RegionAdapterBase<T>, IRegion, IRegionBehaviorFactory, IRegionManager, AllActiveRegion
• Microsoft.Practices.ServiceLocation — ServiceLocator
• Microsoft.Windows.Controls.Ribbon — Ribbon, RibbonTab, RibbonApplicationMenu
• System.Windows.Interactivity — Behavior<T>
• System.Configuration — ConfigurationManager
• DTS.Common.Classes — IRibbonTabInfoProvider (referenced but not in source)
• DTS.Common.Enums — TabControlOperation (referenced but not in source)
• DTS.Common.Events — TabControlSelectionChanged event class (referenced but not in source)
• DTS.Common.Base — IBaseView interface (referenced but not in source)

What depends on this module:

• Cannot be determined from source alone; consumers would reference RibbonRegionAdapter in Prism bootstrapping/configuration and use RibbonControlSelectionChanged event for cross-component communication.

---

5. Gotchas

1. Naming Inconsistency: The XML documentation comment in RibbonControlSelectionEventArgs.cs references "TabControlSelectionChanged" while the actual class is RibbonControlSelectionChanged. This may cause confusion.

2. ServiceLocator vs Constructor Injection: RibbonControlSelectionChangeBehavior resolves IEventAggregator via ServiceLocator.Current.GetInstance<IEventAggregator>() (service locator pattern), while RibbonRegionAdapter receives it via constructor injection. This inconsistency may cause issues in testing or if service locator is not configured.

3. Partial Lock Coverage: AddRibbonTabToRegion() uses a lock object for thread safety when modifying regionTarget.Items, but RemoveRibbonTabFromRibbonRegion() does not. This could lead to race conditions in multi-threaded scenarios.

4. Case-Insensitive Comparison via ToLower(): The DefaultRibbonTab configuration comparison uses ToLower() on both sides rather than using StringComparison.OrdinalIgnoreCase, which is the preferred .NET idiom.

5. Only First Item Published: The behavior only publishes events for e.AddedItems[0] and e.RemovedItems[0]. If multiple items are added/removed in a single selection change, subsequent items are silently ignored.

6. External Interface Dependencies: RibbonRegionAdapter.OnTabControlSelectionChanged() depends on IRibbonTabInfoProvider, IBaseView, TabControlSelectionChanged, and TabControlOperation which are not included in the provided source files. Their contracts are inferred but not documented here.