Merge branch 'release/v24.1.3' into main

Author: billhenn

Documentation/topics/barcode/symbologies/qr-code.md

@@ -13,7 +13,7 @@ It is readable by most mobile devices with cameras and can be used to display te
 
 *A sample of this symbology*
 
-This symbology can encode up to 7,089 numeric characters, 4,296 alpha numeric characters, or 2,953 bytes.  Encoding modes are automatically switched when it is most efficient to do so.  This symbology implementation also auto-calculates the QR Code symbol version and inserts error correction codewords.
+This symbology can encode up to 7,089 numeric characters, 4,296 alpha numeric characters, or 2,953 bytes.  Extended Channel Interpretation (ECI) support also allows all UTF-8 characters to be encoded.  Encoding modes are automatically switched when it is most efficient to do so.  This symbology implementation also auto-calculates the QR Code symbol version and inserts error correction codewords.
 
 > [!IMPORTANT]
 > When using larger version numbers (i.e., version 25 and up), it may be necessary to lower the default cell size in order for QR code readers to properly read the value.
@@ -94,6 +94,19 @@ Gets or sets the `Brush` to use for rendering the background.
 <tr>
 <td>
 
+[EciMode](xref:@ActiproUIRoot.Controls.BarCode.QrCodeSymbology.EciMode) Property
+
+</td>
+<td>
+
+Gets or sets the Extended Channel Interpretation (ECI) mode used to encode the specified value, when the `EncodingMode` resolves to `QrEncodingMode.Binary`.  The default value is `null`, which indicates the ECI mode will be auto-selected based on the specified value.
+
+</td>
+</tr>
+
+<tr>
+<td>
+
 [EncodingMode](xref:@ActiproUIRoot.Controls.BarCode.QrCodeSymbology.EncodingMode) Property
 
 </td>

Documentation/topics/bars/controls/combobox.md

@@ -31,7 +31,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, via the [SmallImageSource](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarGalleryBase.SmallImageSource) property. |
+| 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 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. |
@@ -88,7 +88,7 @@ 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.
 
-The [TextPath](xref:@ActiproUIRoot.Controls.Bars.BarComboBox.TextPath) property specifies the path to a property off the view model gallery item class to display in the combobox when a gallery item is selected.
+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
 
@@ -102,7 +102,9 @@ The `Label` can be auto-generated based on the control's `Key` property.  For in
 
 ### Images
 
-The control can display an image via [SmallImageSource](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarGalleryBase.SmallImageSource) that helps identify its function.  The image 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.
+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.
+
+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
 
@@ -200,5 +202,6 @@ Since the [BarComboBox](xref:@ActiproUIRoot.Controls.Bars.BarComboBox) control i
 The [BarComboBox](xref:@ActiproUIRoot.Controls.Bars.BarComboBox) control changes the default value of the following inherited gallery property to a common setting for a combobox drop-down appearance:
 
 - [MaxMenuColumnCount](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarMenuGalleryHostBase.MaxMenuColumnCount) = `1` - Uses a single column for gallery items.
+- [MenuResizeMode](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarMenuGalleryHostBase.MenuResizeMode) = `Vertical` - Allows vertical gallery resizing and properly supports virtualization of gallery items, which aids in performance with large galleries.
 
 See the [Gallery](gallery.md) topic for more information on galleries.

Documentation/topics/bars/controls/gallery.md

@@ -219,6 +219,9 @@ Menu galleries that contain many items displayed in multiple columns generally u
 
 The [RibbonGallery](xref:@ActiproUIRoot.Controls.Bars.RibbonGallery).[MenuResizeMode](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarMenuGalleryHostBase.MenuResizeMode) and [BarMenuGallery](xref:@ActiproUIRoot.Controls.Bars.BarMenuGallery).[ResizeMode](xref:@ActiproUIRoot.Controls.Bars.BarMenuGallery.ResizeMode) properties set the resize mode for the containing menu to use.
 
+> [!TIP]
+> For performance reasons in properly supporting virtualization, it is recommended that galleries that can grow vertically to more than a handful of rows should be set to either `Vertical` or `Both` resize mode, per the advice above.
+
 ### Surrounding Separators on Menu
 
 Menu galleries will automatically render a separator between them and surrounding menu items.  In some scenarios, this may be undesired.

Documentation/topics/bars/ribbon-features/quick-access-toolbar.md

@@ -123,7 +123,7 @@ Several Actipro themes require the use of white monochrome images in specific po
 
 When one of the Office Colorful themes is used, such as [OfficeColorfulIndigo](xref:@ActiproUIRoot.Themes.ThemeNames.OfficeColorfulIndigo) above, any button images in the Quick Access Toolbar must be switched over to monochrome variations.  Ribbon has logic in it to automatically perform this conversion on a ribbon button with a supplied normal image.
 
-See the [Themes' Getting Started](../../themes/getting-started.md) page for a complete list of themes.
+See the [Themes' Getting Started](../../themes/getting-started.md) topic for a complete list of themes.
 
 ### Optimal Image Design
 
@@ -140,4 +140,10 @@ In some cases, such as for a vector icon that has a portion showing a selected c
 
 This can be achieved by setting the attached [ImageProvider](xref:@ActiproUIRoot.Media.ImageProvider).`CanAdapt` property to `false` on the portion for the selected color.  That will tell the converter to skip over converting colors within that portion of the image.
 
-See the [Image Provider](../../themes/image-provider.md) topic for more details on working with image adaptation.
+See the [Image Provider](../../themes/image-provider.md) topic for more details on working with image adaptation.
+
+## Key Tips
+
+Key tips for controls in the quick access toolbar are auto-generated, beginning with numbers.  In some cases, the numbers might conflict with a ribbon tab that also uses a key tip beginning with a number.  In this scenario, the [KeyTipTextPrefix](xref:@ActiproUIRoot.Controls.Bars.RibbonQuickAccessToolBar.KeyTipTextPrefix) property can be set to an unused character like `'Q'`, which will prefix the auto-generated key tip text, thereby removing the conflict.
+
+See the [Key Tips](key-tips.md) topic for additional details on key tips in general.

Documentation/topics/bars/ribbon-features/tabs-groups-controlgroups.md

@@ -76,6 +76,13 @@ Most ribbon tabs are always visible, but some tabs are only relevant when the ap
 
 See the [Contextual Tabs](contextual-tabs.md) topic for more details on that feature.
 
+### Hiding Tabs
+
+Some applications with only one ribbon tab may wish to hide the tab row entirely, so that a minimal ribbon is presented.  This appearance can be achieved by setting these [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon) properties:
+- [AreTabsVisible](xref:@ActiproUIRoot.Controls.Bars.Ribbon.AreTabsVisible) = `false`
+- [ApplicationButton](xref:@ActiproUIRoot.Controls.Ribbon.Controls.Primitives.ApplicationButton) = `null`
+- [TabRowToolBarContent](xref:@ActiproUIRoot.Controls.Bars.Ribbon.TabRowToolBarContent) = `null`
+
 ## Groups
 
 Groups are used to organize related controls within a tab and can have a different effect based on the ribbon's layout mode.
@@ -88,7 +95,6 @@ See the [Resizing and Variants](resizing.md) topic for more details on how group
 
 See the [Layout Modes and Density](layout-and-density.md) topic for more details on `Classic` modde.
 
-
 ### Simplified Layout Mode
 
 In the `Simplified` layout mode, controls still visible in the ribbon will render a separator between groups. Any controls that have moved to the **Tab Overflow** menu will be organized under a header based on the containing group's label.  Groups can optionally be configured to overflow to their own menu instead of the common **Tab Overflow** menu.
@@ -105,6 +111,10 @@ The [Label](xref:@ActiproUIRoot.Controls.Bars.RibbonGroup.Label) can be auto-gen
 
 See the [Label and Key Tip Generation](../controls/auto-generation.md) topic for more information on auto-generated labels.
 
+### Label Mode
+
+Group labels only show by default on the ribbon when in `Classic` layout mode.  In scenarios where a ribbon in `Simplified` layout mode should also show group labels, set the [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon).[GroupLabelMode](xref:@ActiproUIRoot.Controls.Bars.Ribbon.GroupLabelMode) property to [Always](xref:@ActiproUIRoot.Controls.Bars.RibbonGroupLabelMode.Always) instead of its default value of [Default](xref:@ActiproUIRoot.Controls.Bars.RibbonGroupLabelMode.Default).
+
 ### Collapsed Button Key Tip (Classic layout mode only)
 
 When a group in the `Classic` layout mode is collapsed to a button, the collapsed button supports key tips.  When the key tip of a group's collapsed button is accessed, the content of the group is displayed in a popup.

Documentation/topics/conversion/converting-to-v24-1.md

@@ -252,6 +252,10 @@ The affected controls grouped by product are:
 - Shared Library - `UserPromptControl`.
 - Views - `Book`, `TaskBoard`, and related controls.
 
+## Context Menu Access Key Updates
+
+Built-in context menus for the Docking and Grids products now support access keys.  An access key is designated by placing an underscore (`_`) character before the desired letter of a menu header.  Previously, all underscore characters in context menus were escaped.  Since the text of a context menu is a [customizable string resource](../customizing-string-resources.md) and underscores are no longer escaped, any custom strings that wish to display an underscore character without it being used as an access key must escape the character by using two underscores (e.g., `"Escaped __Underscore"` will display as `"Escaped _Underscore"`).
+
 ## Removed XBAP Support
 
 XBAP (WPF Browser Application) support has been removed since this feature is no longer supported by .NET or modern browsers.

Documentation/topics/docking/docking-window-features/floating-dock-hosts.md

@@ -124,10 +124,69 @@ To ensure that a portion of the hosted floating windows are always visible to th
 
 ## Determining Which Floating Windows Show in the Windows TaskBar
 
-The [DockSite](xref:@ActiproUIRoot.Controls.Docking.DockSite).[FloatingWindowShowInTaskBarMode](xref:@ActiproUIRoot.Controls.Docking.DockSite.FloatingWindowShowInTaskBarMode) property can be used to determine which kinds of non-hosted floating windows are displayed in the Windows taskbar.  The default behavior is for any floating window that contains a "workspace" (such as a floating tabbed MDI document) to show up in the taskbar and not be "owned" by the main window.  This means that the floating window can appear behind the main window when the main window is activated, but it is ok since the floating window can be accessed via the taskbar.
+The [DockSite](xref:@ActiproUIRoot.Controls.Docking.DockSite).[FloatingWindowShowInTaskBarMode](xref:@ActiproUIRoot.Controls.Docking.DockSite.FloatingWindowShowInTaskBarMode) property can be used to determine which kinds of non-hosted floating windows are displayed in the Windows taskbar.  The default behavior is for any floating window that contains a "workspace" (such as a floating tabbed MDI document) to show up in the taskbar and not be "owned" by the main window.  This means that the floating window can appear behind the main window when the main window is activated, but it is ok since the floating window can be accessed via the taskbar.  Note that the [DockSite](xref:@ActiproUIRoot.Controls.Docking.DockSite).[FloatingWindowOwnerMode](xref:@ActiproUIRoot.Controls.Docking.DockSite.FloatingWindowOwnerMode) property can alter the default owner behavior.
 
 Change the property to `FloatingWindowShowInTaskBarMode.Never` to prevent all floating windows from showing in the taskbar.  In this scenario, all floating windows will be "owned" by the main window so that they remain accessible.
 
-Change the property to `FloatingWindowShowInTaskBarMode.Always` to force all floating windows to show in the taskbar.  In this scenario, no floating windows will be "owned" by the main window and they all will be able to appear behind it when the main window is activated.
+Change the property to `FloatingWindowShowInTaskBarMode.Always` to force all floating windows to show in the taskbar.  In this scenario, no floating windows will be "owned" by the main window and they all will be able to appear behind it when the main window is activated, unless this behavior is altered by the [DockSite](xref:@ActiproUIRoot.Controls.Docking.DockSite).[FloatingWindowOwnerMode](xref:@ActiproUIRoot.Controls.Docking.DockSite.FloatingWindowOwnerMode) property.
 
 }
+
+## Use With Ribbons or ToolBars on the Main Window
+
+WPF will move focus to the last-focused control within a `Window` when the `Window` is activated.  This can be a problem when working with floating docking windows and wanting to use a main `Window`'s ribbon or toolbar to execute commands on the active floating docking window.  As soon as a ribbon or toolbar's button is clicked, the main `Window` is activated, which then can focus another docking window within the main `Window`, causing the button's command to work on it instead of the intended floating docking window.
+
+The Actipro [WindowChrome](../../themes/windowchrome.md) class has a [CanMouseActivateOverToolBar](xref:@ActiproUIRoot.Themes.WindowChrome.CanMouseActivateOverToolBar) property that can be set to `false` to prevent toolbar clicks from activating the `Window`.  A toolbar is considered any control with the `WindowChrome.ElementKind` attached property set to [WindowChromeElementKind.ToolBar](xref:@ActiproUIRoot.Themes.WindowChromeElementKind.ToolBar).  Bars' [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon) and [StandaloneToolBar](xref:@ActiproUIRoot.Controls.Bars.StandaloneToolBar) controls have this attached property set by default.
+
+.NET also has a couple properties that should be applied in app startup that help prevent `Window` activation when working with menus,
+such as a menu that opens when pressing a [BarPopupButton](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton).
+
+When these features are combined, controls on main `Window` ribbons and toolbars can execute commands on active floating document windows.
+
+### Configuring WindowChrome
+
+A regular `Window` can be configured through [WindowChrome](../../themes/windowchrome.md) to prevent mouse activation over any control with the `WindowChrome.ElementKind` attached property set to [WindowChromeElementKind.ToolBar](xref:@ActiproUIRoot.Themes.WindowChromeElementKind.ToolBar):
+
+```xaml
+<Window ...>
+	<themes:WindowChrome.Chrome>
+		<themes:WindowChrome CanMouseActivateOverToolBar="False" />
+	</themes:WindowChrome.Chrome>
+	...
+</Window>
+```
+
+Or if using a Bars [RibbonWindow](../../bars/ribbon-features/ribbon-window.md):
+
+```xaml
+<bars:RibbonWindow ...>
+	<themes:WindowChrome.Chrome>
+		<themes:RibbonWindowChrome CanMouseActivateOverToolBar="False" />
+	</themes:WindowChrome.Chrome>
+	...
+</bars:RibbonWindow>
+```
+
+### Preventing Mouse Activation on a Native ToolBar
+
+If a [WindowChrome](../../themes/windowchrome.md) is applied to the main `Window` as above, an attached property can be set on a `ToolBar` to prevent mouse activation of the ancestor `Window` when the toolbar is clicked.
+
+```xaml
+<ToolBar ... themes:WindowChrome.ElementKind="ToolBar">
+	...
+</ToolBar>
+```
+
+### Additional WPF Properties
+
+Two WPF properties were added in .NET Framework 4.0 to allow Visual Studio to support a toolbar system that functioned with floating docking windows:
+
+- `HwndSource.DefaultAcquireHwndFocusInMenuMode` - Whether a `Window` can acquire Win32 focus for the WPF containing window when the user interacts with menus.
+- `Keyboard.DefaultRestoreFocusMode` - Determines the behavior when WPF restores focus.
+
+When attempting to use main `Window` ribbons or toolbars with floating docking windows, these two properties should be set to the following values in application startup logic:
+
+```csharp
+HwndSource.DefaultAcquireHwndFocusInMenuMode = false;
+Keyboard.DefaultRestoreFocusMode = RestoreFocusMode.None;
+```

Documentation/topics/editors/editboxes/timespaneditbox.md

@@ -83,12 +83,15 @@ Each of the features listed in the table below describe functionality that is co
 
 ## Formats
 
-Standard time formats are supported via the [Format](xref:@ActiproUIRoot.Controls.Editors.TimeSpanEditBox.Format) property and affect the textual value display.  These formats are recommended:
+Standard timespan formats are supported via the [Format](xref:@ActiproUIRoot.Controls.Editors.TimeSpanEditBox.Format) property and affect the textual value display.  These formats are recommended:
 
 - `"c"`
 - `"g"`
 - `"G"`
 
+> [!NOTE]
+> If a custom timespan format is used instead of a standard timespan format, the format should begin with a `+` (plus sign) to indicate that negative timespans are supported.  If a custom timespan format does not begin with a plus sign, then the [Minimum](xref:@ActiproUIRoot.Controls.Editors.TimeSpanEditBox.Minimum) property should be set to a zero or higher timespan value.
+
 ## Minimum and Maximum Values
 
 Minimum and maximum values may be assigned via the [Maximum](xref:@ActiproUIRoot.Controls.Editors.TimeSpanEditBox.Maximum) and [Minimum](xref:@ActiproUIRoot.Controls.Editors.TimeSpanEditBox.Minimum) properties.