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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.Common/RibbonControl/Classes/ButtonData.cs Common/DTS.Common/RibbonControl/Classes/SeparatorData.cs Common/DTS.Common/RibbonControl/Classes/GalleryItemData.cs Common/DTS.Common/RibbonControl/Classes/ComboBoxData.cs Common/DTS.Common/RibbonControl/Classes/MenuItemData.cs Common/DTS.Common/RibbonControl/Classes/SplitMenuItemData.cs Common/DTS.Common/RibbonControl/Classes/ApplicationMenuItemData.cs Common/DTS.Common/RibbonControl/Classes/ApplicationSplitMenuItemData.cs Common/DTS.Common/RibbonControl/Classes/TextBoxData.cs Common/DTS.Common/RibbonControl/Classes/CheckBoxData.cs Common/DTS.Common/RibbonControl/Classes/RadioButtonData.cs Common/DTS.Common/RibbonControl/Classes/ToggleButtonData.cs Common/DTS.Common/RibbonControl/Classes/SplitButtonData.cs Common/DTS.Common/RibbonControl/Classes/ContextualTabGroupData.cs Common/DTS.Common/RibbonControl/Classes/ViewModel.cs Common/DTS.Common/RibbonControl/Classes/GalleryCategoryData.cs Common/DTS.Common/RibbonControl/Classes/TabData.cs Common/DTS.Common/RibbonControl/Classes/RibbonData.cs Common/DTS.Common/RibbonControl/Classes/GalleryData.cs Common/DTS.Common/RibbonControl/Classes/ControlData.cs Common/DTS.Common/RibbonControl/Classes/MenuButtonData.cs Common/DTS.Common/RibbonControl/Classes/GroupData.cs	2026-04-16T03:24:01.428865+00:00	Qwen/Qwen3-Coder-Next-FP8	1	1a23dab67957c1ec

RibbonControl Data Model Documentation

1. Purpose

This module defines the data model layer for a ribbon UI control framework. It provides a hierarchy of data classes that represent the structure and state of ribbon UI elements—including tabs, groups, controls, menus, galleries, and context-aware groupings—enabling data binding and declarative UI construction. The classes are designed to support MVVM patterns through INotifyPropertyChanged implementations and command binding, with static default data generation via ViewModelData for design-time and testing scenarios. The module serves as the backend data contract for a WPF-based ribbon control implementation.

2. Public Interface

Core Data Classes

ButtonData

• Inherits from: ControlData
• Description: Represents a standard button control in the ribbon. No additional properties beyond those inherited from ControlData.

SeparatorData

• Inherits from: ControlData
• Description: Represents a visual separator between controls. No additional properties beyond ControlData.

GalleryItemData

• Inherits from: ControlData
• Description: Represents an individual item within a gallery. No additional properties beyond ControlData.

ComboBoxData

• Inherits from: MenuButtonData
• Description: Represents a combo box control. Inherits all properties and behavior from MenuButtonData.

TextBoxData

• Inherits from: ControlData
• Properties:
  • string Text: Gets/sets the text content. Raises PropertyChanged on change.

CheckBoxData

• Inherits from: ControlData
• Properties:
  • bool IsChecked: Gets/sets the checked state. Raises PropertyChanged on change.

RadioButtonData

• Inherits from: ControlData
• Properties:
  • bool IsChecked: Gets/sets the checked state. Raises PropertyChanged on change.

ToggleButtonData

• Inherits from: ControlData
• Properties:
  • bool IsChecked: Gets/sets the checked state. Raises PropertyChanged on change.

SplitButtonData

• Inherits from: MenuButtonData
• Properties:
  • bool IsChecked: Gets/sets the checked state. Raises PropertyChanged on change.
  • bool IsCheckable: Gets/sets whether the button can be toggled. Raises PropertyChanged on change.
  • ButtonData DropDownButtonData: Returns a lazily-initialized ButtonData instance representing the dropdown portion of the split button.

MenuItemData

• Inherits from: SplitButtonData
• Constructors:
  • MenuItemData(): Calls this(false).
  • MenuItemData(bool isApplicationMenu): Calls base constructor with isApplicationMenu.
• Description: Represents a menu item. Inherits all properties from SplitButtonData.

SplitMenuItemData

• Inherits from: MenuItemData
• Constructors:
  • SplitMenuItemData(): Calls this(false).
  • SplitMenuItemData(bool isApplicationMenu): Calls base constructor with isApplicationMenu.
• Description: Represents a split menu item (menu item with dropdown). Inherits all properties from MenuItemData.

ApplicationMenuItemData

• Inherits from: MenuItemData
• Constructors:
  • ApplicationMenuItemData(): Calls this(false).
  • ApplicationMenuItemData(bool isApplicationMenu): Calls base constructor with isApplicationMenu.
• Description: Represents a menu item specifically intended for use in the application menu. Inherits all properties from MenuItemData.

ApplicationSplitMenuItemData

• Inherits from: SplitMenuItemData
• Constructors:
  • ApplicationSplitMenuItemData(): Calls this(false).
  • ApplicationSplitMenuItemData(bool isApplicationMenu): Calls base constructor with isApplicationMenu.
• Description: Represents a split menu item for the application menu. Inherits all properties from SplitMenuItemData.

ControlData

• Base class for all ribbon control data classes.
• Properties:
  • string Label
  • Uri LargeImage
  • Uri SmallImage
  • string ToolTipTitle
  • string ToolTipDescription
  • Uri ToolTipImage
  • string ToolTipFooterTitle
  • string ToolTipFooterDescription
  • Uri ToolTipFooterImage
  • ICommand Command
  • string KeyTip
• All properties raise PropertyChanged on change.

MenuButtonData

• Inherits from: ControlData
• Constructors:
  • MenuButtonData(): Calls this(false).
  • MenuButtonData(bool isApplicationMenu): Initializes with isApplicationMenu flag.
• Properties:
  • bool IsVerticallyResizable
  • bool IsHorizontallyResizable
  • ObservableCollection<ControlData> ControlDataCollection: Lazily-initialized collection containing galleries, menu items, split menu items, and separators (see implementation for exact composition).
• Note: Uses internal _nestingDepth field to limit recursive menu nesting.

GalleryCategoryData

• Inherits from: ControlData
• Properties:
  • ObservableCollection<GalleryItemData> GalleryItemDataCollection: Lazily-initialized collection of 10 GalleryItemData instances with default values (label, images, tooltips, command).
• Generic variant GalleryCategoryData<T> also exists with ObservableCollection<T> GalleryItemDataCollection.

GalleryData

• Inherits from: ControlData
• Properties:
  • ObservableCollection<GalleryCategoryData> CategoryDataCollection: Lazily-initialized collection of 3 GalleryCategoryData instances with default values.
  • GalleryItemData SelectedItem: Gets/sets the selected item. Raises PropertyChanged on change.
  • bool CanUserFilter: Gets/sets whether filtering is enabled. Raises PropertyChanged on change.
• Generic variant GalleryData<T> also exists with ObservableCollection<GalleryCategoryData<T>> CategoryDataCollection and T SelectedItem.

ContextualTabGroupData

• Implements: INotifyPropertyChanged
• Constructors:
  • ContextualTabGroupData(): Calls this(null).
  • ContextualTabGroupData(string header): Initializes with header.
• Properties:
  • string Header
  • bool IsVisible
  • ObservableCollection<TabData> TabDataCollection: Lazily-initialized collection.
• Used to group tabs that appear together under a contextual header.

TabData

• Implements: INotifyPropertyChanged
• Constructors:
  • TabData(): Calls this(null).
  • TabData(string header): Initializes with header.
• Properties:
  • string Header
  • string ContextualTabGroupHeader: Associates tab with a ContextualTabGroupData.
  • bool IsSelected
  • ObservableCollection<GroupData> GroupDataCollection: Lazily-initialized collection of 3 GroupData instances with default values.

GroupData

• Inherits from: ControlData
• Constructors:
  • GroupData(string header): Sets Label to header.
• Properties:
  • ObservableCollection<ControlData> ControlDataCollection: Lazily-initialized collection containing 1 each of Button, ToggleButton, RadioButton, CheckBox, TextBox, MenuButton, SplitButton, and ComboBox instances with default values.

RibbonData

• Implements: INotifyPropertyChanged
• Properties:
  • ObservableCollection<TabData> TabDataCollection: Lazily-initialized collection of 4 TabData instances. First two tabs are associated with contextual tab groups (Grp 0, Grp 1), remaining two are non-contextual.
  • ObservableCollection<ContextualTabGroupData> ContextualTabGroupDataCollection: Lazily-initialized collection of 2 ContextualTabGroupData instances (Grp 0, Grp 1), all visible.
  • MenuButtonData ApplicationMenuData: Lazily-initialized application menu button with default values.

Static Data Provider

ViewModelData

• Namespace: DTS.Common.RibbonControl
• Static Properties:
  • RibbonData RibbonData: Returns a thread-static instance of RibbonData.
  • ICommand DefaultCommand: Returns a DelegateCommand that always returns true for CanExecute and does nothing on Execute.
• Internal Constants: Define default counts for UI elements (e.g., TabCount = 4, ControlCount = 5, etc.).

3. Invariants

• All data classes inherit from ControlData (except ContextualTabGroupData and RibbonData), ensuring consistent property set (Label, Command, SmallImage, etc.) across all controls.
• ControlData properties follow a strict pattern: change detection via reference equality (==) before raising PropertyChanged.
• ControlDataCollection properties in MenuButtonData, GroupData, GalleryCategoryData, and GalleryData are lazily initialized and populated only once per instance (no re-initialization on subsequent access).
• RibbonData.TabDataCollection and ContextualTabGroupDataCollection are lazily initialized and populated exactly once per instance.
• ViewModelData.RibbonData uses [ThreadStatic], meaning each thread gets its own independent RibbonData instance.
• Menu nesting depth is limited to ViewModelData.MenuItemNestingCount (value 2) in MenuButtonData.ControlDataCollection via internal _nestingDepth tracking.
• IsCheckable is explicitly set to true only for SplitButtonData and SplitMenuItemData instances in GroupData and MenuButtonData respectively.
• IsApplicationMenu flag is propagated through constructors to MenuButtonData and its subclasses (MenuItemData, SplitMenuItemData, etc.) to influence initialization behavior.

4. Dependencies

Internal Dependencies (within module)

• All classes reside in DTS.Common.RibbonControl namespace.
• ControlData is the base class for most data classes.
• MenuButtonData is a base class for SplitButtonData, ComboBoxData, and MenuItemData hierarchy.
• SplitButtonData is a base class for SplitMenuItemData and ApplicationSplitMenuItemData.
• MenuItemData is a base class for SplitMenuItemData and ApplicationMenuItemData.
• ApplicationMenuItemData and ApplicationSplitMenuItemData extend MenuItemData and SplitMenuItemData respectively with application-menu-specific semantics.

External Dependencies

• System.ComponentModel (INotifyPropertyChanged, PropertyChangedEventArgs, DesignerSerializationVisibilityAttribute)
• System.Windows.Input (ICommand, DelegateCommand)
• System.Collections.ObjectModel (ObservableCollection<T>)
• Prism.Commands (DelegateCommand) — used in ViewModelData.DefaultCommand
• WPF-specific types: Uri (for image paths), DesignerSerializationVisibility

What depends on this module

• UI rendering layer (not included in source) — consumes these data classes to bind to WPF controls.
• Test or design-time code — uses ViewModelData to generate sample data.

5. Gotchas

• Thread-Safe Data Isolation: ViewModelData.RibbonData uses [ThreadStatic], meaning each thread gets its own RibbonData instance. This may cause unexpected behavior if data is expected to be shared across threads.
• Hardcoded Default Values: Many collections (GroupData.ControlDataCollection, GalleryCategoryData.GalleryItemDataCollection, etc.) are populated with hardcoded default values (e.g., "Paste_16x16.png", "ToolTip Title"). These are not configurable via public API.
• One-Time Initialization: Collections like TabData.GroupDataCollection and GroupData.ControlDataCollection are initialized only once. Modifying the collection after first access will not trigger re-initialization, but adding/removing items is allowed.
• Nesting Depth Limitation: MenuButtonData.ControlDataCollection stops populating menu items after _nestingDepth reaches ViewModelData.MenuItemNestingCount (2). This limit is internal and not exposed.
• IsCheckable Not Universal: Only SplitButtonData and SplitMenuItemData instances have IsCheckable = true set in their default initialization. Regular ButtonData, ToggleButtonData, etc., do not have this property set (though ToggleButtonData, CheckBoxData, RadioButtonData have IsChecked).
• GalleryData.SelectedItem Type Mismatch: The non-generic GalleryData uses GalleryItemData for SelectedItem, while the generic GalleryData<T> uses T. Ensure type consistency when using the generic variant.
• ContextualTabGroupHeader Not Enforced: TabData.ContextualTabGroupHeader is a string property; there is no validation ensuring it matches an actual ContextualTabGroupData.Header.
• Command Not Used in Default Logic: While Command properties are set to ViewModelData.DefaultCommand in default data, there is no logic in these classes to invoke or validate the command.
• No Public Constructors for Generic Types: Generic classes (GalleryCategoryData<T>, GalleryData<T>) lack custom constructors, limiting initialization flexibility.

None identified from source alone.