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

---
source_files:
  - 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
generated_at: "2026-04-16T02:16:32.989533+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "c0e1c8bd7f1a18f4"
---

# RibbonControl

## Documentation: `DTS.Common.RibbonControl` Module

---

### 1. Purpose

This module provides infrastructure for integrating the Microsoft Ribbon control (from the *RibbonControlsLibrary*) into a Prism-based WPF application, specifically enabling Prism region management and event-driven tab selection coordination for `Ribbon` and `RibbonTab` elements. It defines event types for tab selection changes, a behavior to bridge `Ribbon.SelectionChanged` to Prism events, and a region adapter to manage `RibbonTab` and `RibbonApplicationMenu` views within the `RibbonRegion`. Its role is to decouple view navigation logic from UI controls while preserving Prism’s region-based architecture and enabling reactive tab selection behavior based on view model metadata.

---

### 2. Public Interface

#### `RibbonControlSelectionChanged`
- **Type**: `class` (inherits `CompositePresentationEvent<RibbonControlSelectionEventArgs>`)
- **Purpose**: Prism event used to publish tab selection changes (add/remove operations) on the `Ribbon`.
- **Usage**: Subscribers listen for tab operations via `IEventAggregator.GetEvent<RibbonControlSelectionChanged>().Subscribe(...)`.
- **Payload**: `RibbonControlSelectionEventArgs`

#### `RibbonControlOperation`
- **Type**: `enum`
- **Values**:
  - `AddedItem`: Indicates a tab was added to the `Ribbon`.
  - `RemovedItem`: Indicates a tab was removed from the `Ribbon`.

#### `RibbonControlSelectionEventArgs`
- **Type**: `class`
- **Properties**:
  - `Operation`: `RibbonControlOperation` — the type of operation (`AddedItem` or `RemovedItem`).
  - `Item`: `object` — the `RibbonTab` (or other item) involved in the operation.
- **Constructor**:  
  `RibbonControlSelectionEventArgs(RibbonControlOperation operation, object item)`  
  Initializes the event args with the operation and item.

#### `RibbonControlSelectionChangeBehavior`
- **Type**: `class` (inherits `Behavior<Ribbon>`)
- **Properties**:
  - `TargetRibbonControl`: `Ribbon` (dependency property) — *Note: Property name mismatch in XAML usage; registered as `"TargetRibbonControl"` but exposed as `TargetRibbonControl`.*
- **Behavior**:
  - Attaches to `Ribbon.SelectionChanged` event.
  - On selection change, publishes **two** events (one for `AddedItem`, one for `RemovedItem`) via `RibbonControlSelectionChanged`, using the first item in `e.AddedItems` and `e.RemovedItems` respectively.
  - Uses `ServiceLocator.Current.GetInstance<IEventAggregator>()` to publish events.

#### `RibbonRegionAdapter`
- **Type**: `class` (inherits `RegionAdapterBase<Ribbon>`, implements `IDisposable`)
- **Constructor**:
  ```csharp
  RibbonRegionAdapter(IRegionBehaviorFactory regionBehaviorFactory, IRegionManager regionManager, IEventAggregator eventAggregator)
  ```
  - Registers for `RibbonControlSelectionChanged` events via `_eventAggregator.GetEvent<TabControlSelectionChanged>().Subscribe(OnTabControlSelectionChanged)`.  
    ⚠️ **Note**: Event name mismatch — uses `TabControlSelectionChanged` (see *Gotchas*).
- **Methods**:
  - `Adapt(IRegion region, Ribbon regionTarget)`:  
    Subscribes to `region.ActiveViews.CollectionChanged`, handling `RibbonTab` and `RibbonApplicationMenu` additions/removals:
    - Adds `RibbonTab` to `regionTarget.Items`, assigns a `Uid` if missing, sorts by `TabIndex`.
    - Adds `RibbonApplicationMenu` to `regionTarget.ApplicationMenu`.
    - Sets `IsSelected = true` on the first added tab if `App.config` contains `<add key="DefaultRibbonTab" value="TabHeaderName"/>`.
  - `AddRibbonTabToRegion(RibbonTab, Ribbon)`: Internal helper.
  - `AddApplicationMenuToRegion(RibbonApplicationMenu, Ribbon)`: Internal helper.
  - `RemoveRibbonTabFromRibbonRegion(RibbonTab, Ribbon)`: Removes tab from `Ribbon.Items`.
  - `OnTabControlSelectionChanged(TabControlSelectionEventArgs)`:  
    Reacts to tab selection changes:
    - Ignores `RemovedItem` operations.
    - Extracts `IBaseView` → `IRibbonTabInfoProvider` from view’s `DataContext`.
    - Uses `RibbonTabUid` to programmatically select the corresponding `RibbonTab` in the region.
  - `CreateRegion()`: Returns `new AllActiveRegion()` (all views remain active).
- **IDisposable**:
  - Unsubscribes from `RibbonControlSelectionChanged` in `Dispose(bool)`.

---

### 3. Invariants

- **Event naming consistency**:  
  `RibbonControlSelectionChanged` (defined in `RibbonControlSelectionChanged.cs`) is *not* the same as `TabControlSelectionChanged` (used in `RibbonRegionAdapter.cs`). This is a critical mismatch (see *Gotchas*).
- **Item identity**:  
  `RibbonControlSelectionEventArgs.Item` is always the *first* item in `AddedItems` or `RemovedItems` — only single-item operations are handled.
- **Tab selection logic**:  
  `RibbonRegionAdapter.OnTabControlSelectionChanged` only acts on `AddedItem` operations and only if:
  - `e.Item` is an `IBaseView`,
  - its `DataContext` implements `IRibbonTabInfoProvider`,
  - `IRibbonTabInfoProvider.RibbonTabUid` is non-null/non-empty,
  - and the `RibbonTab` with matching `Uid` exists in the region.
- **UID assignment**:  
  `RibbonTab.Uid` and `RibbonApplicationMenu.Uid` are auto-generated (via `Guid`) if missing during `Adapt()`.

---

### 4. Dependencies

#### Dependencies *of* this module:
- **Prism libraries**:  
  `Microsoft.Practices.Prism.Events`, `Microsoft.Practices.Prism.Regions`, `Microsoft.Practices.ServiceLocation`.
- **WPF & Ribbon**:  
  `System.Windows`, `System.Windows.Controls`, `Microsoft.Windows.Controls.Ribbon` (from *RibbonControlsLibrary*).
- **Custom types**:
  - `DTS.Common.Classes.IBaseView`
  - `DTS.Common.Enums.IRibbonTabInfoProvider`
  - `DTS.Common.Events.TabControlSelectionChanged` *(note: event name mismatch)*
  - `DTS.Common.Base.RegionNames.RibbonRegion`

#### Dependencies *on* this module:
- Application code that uses Prism regions (`RegionNames.RibbonRegion`) to host `Ribbon` controls.
- View models implementing `IRibbonTabInfoProvider` to enable programmatic tab selection.
- Behaviors or services that subscribe to `RibbonControlSelectionChanged` for tab lifecycle monitoring.

---

### 5. Gotchas

- **Event name mismatch**:  
  `RibbonRegionAdapter` subscribes to `TabControlSelectionChanged`, but the event defined in this module is `RibbonControlSelectionChanged`. This will cause `OnTabControlSelectionChanged` to *never fire*, breaking tab selection coordination.  
  → **Fix required**: Change `TabControlSelectionChanged` to `RibbonControlSelectionChanged` in `RibbonRegionAdapter` constructor and `Dispose`.

- **Behavior uses `ServiceLocator`**:  
  `RibbonControlSelectionChangeBehavior` uses `ServiceLocator.Current.GetInstance<IEventAggregator>()` instead of constructor injection. This violates DI best practices and makes testing harder.

- **Single-item assumption**:  
  Only the *first* added/removed item is used (`e.AddedItems[0]`, `e.RemovedItems[0]`). Multi-select scenarios (if supported by `Ribbon`) will be silently ignored.

- **Property name mismatch**:  
  The dependency property is registered as `"TargetRibbonControl"` but exposed as `TargetRibbonControl`. While syntactically valid, this may cause confusion in XAML binding (e.g., `TargetRibbonControl="{Binding ...}"` is required — not `TargetRibbon`).

- **Hardcoded config key**:  
  `DefaultRibbonTab` is read from `App.config` without validation or fallback. If the header string doesn’t match exactly (case-insensitive), selection won’t occur.

- **No null safety for `Item`**:  
  `RibbonControlSelectionEventArgs.Item` is `object`, but downstream logic (e.g., `OnTabControlSelectionChanged`) assumes it is an `IBaseView`. Casting failures will be silent (via `as` operator).

- **Thread-safety via `lock`**:  
  `AddRibbonTabToRegion` uses a `static readonly lock`, but `RibbonRegionAdapter` is instantiated per region (via DI), so the lock is shared across *all* ribbon regions — potentially causing contention or deadlocks if multiple regions are initialized concurrently.

- **Missing `RibbonControlOperation` usage**:  
  `RibbonControlOperation` is defined but only used in `RibbonControlSelectionEventArgs`. No other code references it directly.

--- 

*Documentation generated from provided source files. No external behavior or APIs inferred.*