Merge branch 'release/v25.1.0' into main

Author: billhenn

.github/workflows/integration-build.yml

@@ -18,7 +18,7 @@ jobs:
 
     env:
       SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
-      LICENSEKEY: ${{ secrets.ACTIPRO_CONTROLS_WPF_V24_1_LICENSEKEY }}
+      LICENSEKEY: ${{ secrets.ACTIPRO_CONTROLS_WPF_V25_1_LICENSEKEY }}
 
     steps:
     - name: Cancel duplicate runs

Documentation/docfx.json

@@ -56,7 +56,7 @@
 			"_docsCopyrightYears": "1999-2025",
 			"_docsProductHref": "https://www.actiprosoftware.com/products/controls/wpf",
 			"_docsProductName": "WPF Controls",
-			"_docsProductVersion": "24.1",
+			"_docsProductVersion": "25.1",
 			"_disableContribution": true,
 			"_enableNewTab": true,
 			"_gitContribute": {

Documentation/topics/bars/configuration.md

@@ -22,6 +22,13 @@ XAML is familiar to most @@PlatformTitle developers and popular IDEs like Visual
 
 Some controls are used in multiple locations, and using XAML will typically require controls to be redefined everywhere they are used. For instance, a button that appears on a ribbon tab, a quick access toolbar, and a context menu might have to be defined three times.  Care must be taken to ensure the same `Key` value is used for each control instance and common UI-centric properties like labels, tooltips, and icons will need to be repeated and synchronized between each control instance.
 
+@if (avalonia) {
+> [!WARNING]
+> Some ribbon and toolbar functionality requires cloning a control from one context (like a Ribbon group) to another (like the Quick Access Toolbar). When objects are defined in XAML, every effort is made to create a new object and copy relevant properties to the copy, but the process is not guaranteed to fully clone the control.  This process also requires the use of reflection and may encounter issues if trimming is enabled.  Properties assigned with bindings will typically only clone the current value of the `Binding` (not the `Binding` itself), so clones may not be notified when the value of a `Binding` changes.  Additionally, event handlers (like `Click` events on buttons) will not be cloned.
+>
+> MVVM does not have this issue since cloned objects can share the same view model.
+}
+
 ## MVVM Configuration
 
 MVVM is an extremely popular pattern used for @@PlatformTitle and one that is fully supported by Bars controls.

Documentation/topics/bars/controls/button.md

@@ -32,7 +32,7 @@ If the button should be checkable, use the [BarToggleButton](xref:@ActiproUIRoot
 | Base class | Native `Button`. |
 | Has key | Yes, via the [Key](xref:@ActiproUIRoot.Controls.Bars.BarButton.Key) property. |
 | Has label | Yes, via the [Label](xref:@ActiproUIRoot.Controls.Bars.BarButton.Label) property.  Auto-generated from the `Key` value if not specified. |
-| Has image | Yes, via the [SmallImageSource](xref:@ActiproUIRoot.Controls.Bars.BarButton.SmallImageSource), [MediumImageSource](xref:@ActiproUIRoot.Controls.Bars.BarButton.MediumImageSource), and [LargeImageSource](xref:@ActiproUIRoot.Controls.Bars.BarButton.LargeImageSource) properties. |
+| Has image | Yes, via the [SmallIcon](xref:@ActiproUIRoot.Controls.Bars.BarButton.SmallIcon), [MediumIcon](xref:@ActiproUIRoot.Controls.Bars.BarButton.MediumIcon), and [LargeIcon](xref:@ActiproUIRoot.Controls.Bars.BarButton.LargeIcon) properties. |
 | Has popup | No. |
 | Is checkable | Yes, but only when using [BarToggleButton](xref:@ActiproUIRoot.Controls.Bars.BarToggleButton). |
 | Variant sizes | `Small` (image only), `Medium` (image and label), `Large` (tall size, image and multi-line label). |
@@ -67,7 +67,7 @@ xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui"
 	<actipro:BarButton
 		Key="Undo"
 		KeyTipText="AZ"
-		SmallImageSource="/Images/Undo16.png"
+		SmallIcon="{StaticResource UndoIcon}"
 		Command="{Binding UndoCommand}"
 		/>
 	...
@@ -105,7 +105,7 @@ Use the [BarMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem) control to
 | Base class | Native `MenuItem`. |
 | Has key | Yes, via the [Key](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.Key) property. |
 | Has label | Yes, via the [Label](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.Label) property.  Auto-generated from the `Key` value if not specified. |
-| Has image | Yes, via the [SmallImageSource](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.SmallImageSource) and [LargeImageSource](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.LargeImageSource) properties. |
+| Has image | Yes, via the [SmallIcon](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.SmallIcon) and [LargeIcon](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.LargeIcon) properties. |
 | Has popup | Not when a button concept is desired. |
 | Is checkable | Yes, when the `ToggleType` property is set to `CheckBox` or `Radio`. |
 | Variant sizes | None, but has a [UseLargeSize](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.UseLargeSize) property that triggers a large height and displays an extended [Description](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.Description). |
@@ -135,16 +135,16 @@ Use the [BarMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem) control to
 ```xaml
 xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui"
 ...
-<actipro:BarContextMenu>
+<actipro:BarMenuFlyout>
 	<!-- Label is auto-generated from Key, but we want to override the auto-generated KeyTipText -->
 	<actipro:BarMenuItem
 		Key="Undo"
 		KeyTipText="AZ"
-		SmallImageSource="/Images/Undo16.png"
+		SmallIcon="{StaticResource UndoIcon}"
 		Command="{Binding UndoCommand}"
 		/>
 	...
-</actipro:BarContextMenu>
+</actipro:BarMenuFlyout>
 ```
 }
 @if (wpf) {
@@ -197,12 +197,21 @@ The [BarMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem).[Label](xref:@A
 
 The controls can display images that help identify their function.
 
-All [BarButton](xref:@ActiproUIRoot.Controls.Bars.BarButton) instances should set a [SmallImageSource](xref:@ActiproUIRoot.Controls.Bars.BarButton.SmallImageSource) at a minimum, which is generally used for `Small` and `Medium` variants, as well as in the [Ribbon Quick Access Toolbar](../ribbon-features/quick-access-toolbar.md) and if the control overflows to a menu.  If the button supports a `Large` variant size, it should also define a [LargeImageSource](xref:@ActiproUIRoot.Controls.Bars.BarButton.LargeImageSource).  @if (avalonia) { When the button is located on a ribbon with `Simplified` layout mode, }@if (wpf) { When the button has a `Spacious` UI density,} it will try to use [MediumImageSource](xref:@ActiproUIRoot.Controls.Bars.BarButton.MediumImageSource).
+@if (avalonia) {
+All [BarButton](xref:@ActiproUIRoot.Controls.Bars.BarButton) instances should set a [SmallIcon](xref:@ActiproUIRoot.Controls.Bars.BarButton.SmallIcon) at a minimum, which is generally used for `Small` and `Medium` variants, as well as in the [Ribbon Quick Access Toolbar](../ribbon-features/quick-access-toolbar.md) and if the control overflows to a menu.  If the button supports a `Large` variant size, it should also define a [LargeIcon](xref:@ActiproUIRoot.Controls.Bars.BarButton.LargeIcon).  When the button is located on a ribbon with `Simplified` layout mode, it will try to use [MediumIcon](xref:@ActiproUIRoot.Controls.Bars.BarButton.MediumIcon).
+
+> [!TIP]
+> See the [Control Basics](control-basics.md) topic for more detail on the fallback logic and custom data templates for button icons.
+
+[BarMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem) instances can optionally define a [SmallIcon](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.SmallIcon) that appears in the menu's icon column.  When [UseLargeSize](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.UseLargeSize) is set to create a large menu item, the [LargeIcon](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.LargeIcon) property is used instead.  When the menu item is checked, a highlight box will appear around the image.  If no image is specified, a standard check glyph will be used in place of the image.}
+@if (wpf) {
+All [BarButton](xref:@ActiproUIRoot.Controls.Bars.BarButton) instances should set a [SmallImageSource](xref:@ActiproUIRoot.Controls.Bars.BarButton.SmallImageSource) at a minimum, which is generally used for `Small` and `Medium` variants, as well as in the [Ribbon Quick Access Toolbar](../ribbon-features/quick-access-toolbar.md) and if the control overflows to a menu.  If the button supports a `Large` variant size, it should also define a [LargeImageSource](xref:@ActiproUIRoot.Controls.Bars.BarButton.LargeImageSource).  When the button has a `Spacious` UI density, it will try to use [MediumImageSource](xref:@ActiproUIRoot.Controls.Bars.BarButton.MediumImageSource).
 
 > [!TIP]
 > See the [Control Basics](control-basics.md) topic for more detail on the fallback logic for button images.
 
-[BarMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem) instances can optionally define a [SmallImageSource](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.SmallImageSource) that appears in the menu's icon column.  When [UseLargeSize](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.UseLargeSize) is set to create a large menu item, the [LargeImageSource](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.LargeImageSource) property is used instead.  When the menu item is checked, a highlight box will appear  around the image.  If no image is specified, a standard check glyph will be used in place of the image.
+[BarMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem) instances can optionally define a [SmallImageSource](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.SmallImageSource) that appears in the menu's icon column.  When [UseLargeSize](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.UseLargeSize) is set to create a large menu item, the [LargeImageSource](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.LargeImageSource) property is used instead.  When the menu item is checked, a highlight box will appear around the image.  If no image is specified, a standard check glyph will be used in place of the image.
+}
 
 ### Description (BarMenuItem only)
 

Documentation/topics/bars/controls/checkbox.md

@@ -97,7 +97,7 @@ Use the [BarMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem) control to
 | Base class | Native `MenuItem`. |
 | Has key | Yes, via the [Key](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.Key) property. |
 | Has label | Yes, via the [Label](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.Label) property.  Auto-generated from the `Key` value if not specified. |
-| Has image | Yes, via the [SmallImageSource](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.SmallImageSource) and [LargeImageSource](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.LargeImageSource) properties. |
+| Has image | Yes, via the [SmallIcon](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.SmallIcon) and [LargeIcon](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.LargeIcon) properties. |
 | Has popup | Not when a checkbox concept is desired. |
 | Is checkable | Yes, when the `ToggleType` property is set to `CheckBox` or `Radio`. |
 | Variant sizes | None, but has a [UseLargeSize](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.UseLargeSize) property that triggers a large height and displays an extended [Description](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.Description). |
@@ -127,15 +127,15 @@ Use the [BarMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem) control to
 ```xaml
 xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui"
 ...
-<actipro:BarContextMenu>
+<actipro:BarMenuFlyout>
 	<!-- Label is auto-generated from Key -->
 	<actipro:BarMenuItem
 		Key="ShowWhitespace"
 		ToggleType="CheckBox"
 		Command="{Binding UndoCommand}"
 		/>
 	...
-</actipro:BarContextMenu>
+</actipro:BarMenuFlyout>
 ```
 }
 @if (wpf) {
@@ -172,7 +172,12 @@ The [BarMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem).[Label](xref:@A
 
 [BarCheckBox](xref:@ActiproUIRoot.Controls.Bars.BarCheckBox) instances do not display any images.
 
+@if (avalonia) {
+[BarMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem) instances can optionally define a [SmallIcon](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.SmallIcon) that appears in the menu's icon column.  When [UseLargeSize](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.UseLargeSize) is set to create a large menu item, the [LargeIcon](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.LargeIcon) property is used instead.  When the menu item is checked, a highlight box will appear  around the image.  If no image is specified, a standard check glyph will be used in place of the image.
+}
+@if (wpf) {
 [BarMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem) instances can optionally define a [SmallImageSource](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.SmallImageSource) that appears in the menu's icon column.  When [UseLargeSize](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.UseLargeSize) is set to create a large menu item, the [LargeImageSource](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.LargeImageSource) property is used instead.  When the menu item is checked, a highlight box will appear  around the image.  If no image is specified, a standard check glyph will be used in place of the image.
+}
 
 ### Description (BarMenuItem only)
 

Documentation/topics/bars/controls/combobox.md

@@ -32,7 +32,7 @@ In summary, a [BarMenuGallery](xref:@ActiproUIRoot.Controls.Bars.BarMenuGallery)
 | Base class | [BarMenuGalleryHostBase](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarMenuGalleryHostBase), which indirectly inherits native `Selector`. |
 | Has key | Yes, via the [Key](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarGalleryBase.Key) property. |
 | Has label | Yes, via the [Label](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarGalleryBase.Label) property.  Auto-generated from the `Key` value if not specified. |
-| Has image | Yes, inline via the [InlineImageSourcePath](xref:@ActiproUIRoot.Controls.Bars.BarComboBox.InlineImageSourcePath) property or externally via the [SmallImageSource](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarGalleryBase.SmallImageSource) property. |
+| Has image | Yes, inline via the [InlineIconMemberBinding](xref:@ActiproUIRoot.Controls.Bars.BarComboBox.InlineIconMemberBinding) property or externally via the [SmallIcon](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarGalleryBase.SmallIcon) property. |
 | Has popup | Yes, which shows a [BarMenuGallery](xref:@ActiproUIRoot.Controls.Bars.BarMenuGallery) with the same items, and optionally additional menu items. |
 | Is checkable | No. |
 | Variant sizes | None. |
@@ -66,7 +66,7 @@ xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui"
 	<!-- Label is auto-generated from Key -->
 	<actipro:BarComboBox
 		Key="Employee"
-		TextPath="Name"
+		TextMemberBinding="{Binding Name, x:DataType=local:Employee}"
 		IsEditable="True"
 		Command="{Binding EmployeeSelectedCommand}"
 		UnmatchedTextCommand="{Binding EmployeeUnmatchedTextCommand}"
@@ -131,7 +131,12 @@ There are several appearance-related properties that determine how the controls
 
 The [Text](xref:@ActiproUIRoot.Controls.Bars.BarComboBox.Text) property gets or sets the text that is displayed within the combobox.
 
+@if (avalonia) {
+The [TextMemberBinding](xref:@ActiproUIRoot.Controls.Bars.BarComboBox.TextMemberBinding) property specifies the `IBinding` to a string-based property off the view model gallery item class to display in the combobox when a gallery item is selected.
+}
+@if (wpf) {
 The [TextPath](xref:@ActiproUIRoot.Controls.Bars.BarComboBox.TextPath) property specifies the path to a string-based property off the view model gallery item class to display in the combobox when a gallery item is selected.
+}
 
 ### Label
 
@@ -145,9 +150,18 @@ The `Label` can be auto-generated based on the control's `Key` property.  For in
 
 ### Images
 
-An image from the selected gallery item can be displayed inline within the control, before the combobox text.  This image will update when the combobox's selection is changed.  The [InlineImageSourcePath](xref:@ActiproUIRoot.Controls.Bars.BarComboBox.InlineImageSourcePath) property specifies the path to an `ImageSource`-based property off the view model gallery item class to display in the combobox when a gallery item is selected.
+An image from the selected gallery item can be displayed inline within the control, before the combobox text.  This image will update when the combobox's selection is changed.
+
+@if (avalonia) {
+The [InlineIconMemberBinding](xref:@ActiproUIRoot.Controls.Bars.BarComboBox.InlineIconMemberBinding) property specifies an `IBinding` to an `object`-based property off the view model gallery item class to display in the combobox when a gallery item is selected.
+
+Alternatively, the control can display a static image via [SmallIcon](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarGalleryBase.SmallIcon) that helps identify its function.  The image is not tied to the selected item and is not rendered by the control itself, but can show externally (such as when in a [RibbonControlGroup](xref:@ActiproUIRoot.Controls.Bars.RibbonControlGroup)), or in customization UI.
+}
+@if (wpf) {
+The [InlineImageSourcePath](xref:@ActiproUIRoot.Controls.Bars.BarComboBox.InlineImageSourcePath) property specifies the path to an `ImageSource`-based property off the view model gallery item class to display in the combobox when a gallery item is selected.
 
 Alternatively, the control can display a static image via [SmallImageSource](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarGalleryBase.SmallImageSource) that helps identify its function.  The image is not tied to the selected item and is not rendered by the control itself, but can show externally (such as when in a [RibbonControlGroup](xref:@ActiproUIRoot.Controls.Bars.RibbonControlGroup)), or in customization UI.
+}
 
 ### Title
 
@@ -205,7 +219,16 @@ See the [Key Tips](../ribbon-features/key-tips.md) topic for more information on
 
 ## Commands and Events
 
-A commit is attempted by an editable [BarComboBox](xref:@ActiproUIRoot.Controls.Bars.BarComboBox) when <kbd>Enter</kbd> is pressed while the control is focused, or the control's text changes and then focus is lost.  As long as the `IsTextSearchEnabled` property is `true`, the commit logic will examine the gallery items and will look for an item that matches the typed text.  `IsTextSearchCaseSensitive` determines whether a case-sensitive text search is made.  The attached `TextSearch.Text` property value from the gallery item (if it is a `DependencyObject`) will be examined first when looking for matches.  If no match is made on that, and the [TextPath](xref:@ActiproUIRoot.Controls.Bars.BarComboBox.TextPath) property specifies a property name on the item to examine, that property on the item will be looked at next for a match.
+A commit is attempted by an editable [BarComboBox](xref:@ActiproUIRoot.Controls.Bars.BarComboBox) when <kbd>Enter</kbd> is pressed while the control is focused, or the control's text changes and then focus is lost.  As long as the `IsTextSearchEnabled` property is `true`, the commit logic will examine the gallery items and will look for an item that matches the typed text.  `IsTextSearchCaseSensitive` determines whether a case-sensitive text search is made.
+
+The attached `TextSearch.Text` property value from the gallery item (if it is a `DependencyObject`) will be examined first when looking for matches.
+
+@if (avalonia) {
+If no match is made on that, and the [TextMemberBinding](xref:@ActiproUIRoot.Controls.Bars.BarComboBox.TextMemberBinding) property specifies an `IBinding` to a property on the item to examine, that property on the item will be looked at next for a match.
+}
+@if (wpf) {
+If no match is made on that, and the [TextPath](xref:@ActiproUIRoot.Controls.Bars.BarComboBox.TextPath) property specifies a property name on the item to examine, that property on the item will be looked at next for a match.
+}
 
 If a matching gallery item is located, the [Command](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarGalleryBase.Command) is executed and is passed the matching gallery item as a command parameter.