Merge branch 'release/v24.1.0' into main

Documentation/docfx.json

@@ -58,7 +58,7 @@
 			"_docsCopyrightYears": "2021-2024",
 			"_docsProductHref": "https://www.actiprosoftware.com/products/controls/avalonia",
 			"_docsProductName": "Avalonia UI",
-			"_docsProductVersion": "23.1",
+			"_docsProductVersion": "24.1",
 			"_disableContribution": true,
 			"_enableNewTab": true,
 			"_gitContribute": {

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

@@ -1,7 +1,7 @@
 ---
 title: "Converting to v23.1"
 page-title: "Converting to v23.1 - Conversion Notes"
-order: 10
+order: 100
 ---
 # Converting to v23.1
 

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

@@ -0,0 +1,37 @@
+---
+title: "Converting to v24.1"
+page-title: "Converting to v24.1 - Conversion Notes"
+order: 99
+---
+# Converting to v24.1
+
+## Avalonia UI Dependency
+
+Updated the minimum Avalonia UI dependency from v11.0.5 to v11.0.7.
+
+## RingSlice
+
+The [Ring Slice](../shared/shapes/ring-slice.md) shape was added in v23.1 and is a very handy primitive for controls that need to render an arc shape.  When integrating the shape into some other controls, we found that the design needed to be slightly refactored for ease of use and to better support animation.
+
+These API changes were made:
+- The [StartAngle](xref:@ActiproUIRoot.Controls.Shapes.RingSlice.StartAngle) property is now a `Double` instead of an [Angle](xref:ActiproSoftware.Angle).
+- The former `EndAngle` property is now a `Double` instead of an [Angle](xref:ActiproSoftware.Angle) and specified via the [SweepAngle](xref:@ActiproUIRoot.Controls.Shapes.RingSlice.SweepAngle) property instead.  The resolved end angle is now calculated by adding the sweep angle to the start angle.
+
+The end result is that if a ring slice previously specified `StartAngle="90" EndAngle="270"`, the same slice after the updates would be specified `StartAngle="90" SweepAngle="180"`.
+
+## Some Image-Based Identifiers Renamed
+
+Some properties and types related to `IImage` were renamed from "Image" to "ImageSource" as part of a new naming convention.  Some other image-related types were also impacted.  The following breaking changes were made:
+
+- [UserPromptControl](xref:@ActiproUIRoot.Controls.UserPromptControl).`FooterImage` renamed as `FooterImageSource`.
+- [UserPromptControl](xref:@ActiproUIRoot.Controls.UserPromptControl).`StatusImage` renamed as `StatusImageSource`.
+- `ActiproSoftware.UI.Avalonia.Controls.Converters.ImageKeyToImageConverter` type renamed as [ImageKeyToImageSourceConverter](xref:@ActiproUIRoot.Controls.Converters.ImageKeyToImageSourceConverter)
+- `ActiproSoftware.UI.Avalonia.Media.SharedImageKeys` type renamed as [SharedImageSourceKeys](xref:@ActiproUIRoot.Media.SharedImageSourceKeys).
+
+## ButtonCard Theme Removed
+
+Previous builds contained a `ButtonCard` theme (`theme-card` style class name) for native `Button` control instances. With the introduction of the new [Card](../fundamentals/controls/card.md) control, the older `ButtonCard` theme has been removed.  Those who used the old theme can use the [Card](../fundamentals/controls/card.md) control instead.
+
+## Theme Resource Renamed
+
+For naming consistency, the [ThemeResourceKind](xref:@ActiproUIRoot.Themes.ThemeResourceKind) enum value `NotificationBorderBrushInfo` was renamed to `NotificationBorderBrushInformation`.

Documentation/topics/conversion/index.md

@@ -9,4 +9,5 @@ Occasionally during large updates to a product, some breaking changes are necess
 
 Read the following topics that are appropriate for your scenario if you are converting from an older version to the latest version.
 
+- [Converting to v24.1](converting-to-v24-1.md)
 - [Converting to v23.1](converting-to-v23-1.md)

Documentation/topics/customizing-string-resources.md

@@ -81,7 +81,7 @@ xmlns:actiproPropertiesShared="using:ActiproSoftware.Properties.Shared"
 Now lets use the `UITextBoxButtonShowPasswordText` resource's text as a `Button`'s tooltip content:
 
 ```xaml
-<Button ToolTip="{actiproPropertiesShared:SR UITextBoxButtonShowPasswordText}" />
+<Button ToolTip.Tip="{actiproPropertiesShared:SR UITextBoxButtonShowPasswordText}" />
 ```
 
 That's all there is to it!

Documentation/topics/fundamentals/controls/badge.md

@@ -91,7 +91,7 @@ xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui"
 ```xaml
 xmlns:shared="http://schemas.actiprosoftware.com/winfx/xaml/shared"
 ...
-<shared:NumericBadge Count="5"  />
+<shared:NumericBadge Count="5" />
 ```
 }
 
@@ -110,6 +110,26 @@ Use the [OverflowStringFormat](xref:@ActiproUIRoot.Controls.NumericBadge.Overflo
 
 Overflow behavior can be disabled by setting [OverflowCount](xref:@ActiproUIRoot.Controls.NumericBadge.OverflowCount) to `0`.
 
+> [!WARNING]
+> When specifying a custom [OverflowStringFormat](xref:@ActiproUIRoot.Controls.NumericBadge.OverflowStringFormat) value in XAML, prefix the actual value with `{}` to ensure the XAML parser doesn't interpret the open curly braces of the format string as a meaningful XAML delimiter.
+
+The following example demonstrates how to define a [NumericBadge](xref:@ActiproUIRoot.Controls.NumericBadge) that overlows at `9` and uses a custom string format of `"{0}*"`:
+
+@if (avalonia) {
+```xaml
+xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui"
+...
+<actipro:NumericBadge Count="5" OverflowCount="9" OverflowStringFormat="{}{0}*" />
+```
+}
+@if (wpf) {
+```xaml
+xmlns:shared="http://schemas.actiprosoftware.com/winfx/xaml/shared"
+...
+<shared:NumericBadge Count="5" OverflowCount="9" OverflowStringFormat="{}{0}*" />
+```
+}
+
 ## Using as an adornment
 
 A common scenario for a badge is to be used as an adornment to another element. Examples include showing availability status on a user's avatar or a count of unread messages.
@@ -213,11 +233,11 @@ xmlns:shared="http://schemas.actiprosoftware.com/winfx/xaml/shared"
 ### Notes on Avalonia Adorner Issues
 
 > [!WARNING]
-> The Avalonia adorner system may not properly clip adornments.
+> The Avalonia adorner system may not properly clip adornments when the adornment is outside the bounds of the adorned element.
 
-The Avalonia adorner system (last tested on v11.0.7) doesn't properly clip adornments based on the clip regions of ancestors of the adorned element.  This is an issue we are working with the Avalonia team to solve.  A symptom of this issue can sometimes be seen when a badge adornment is used on an adorned element, that adorned element is scrolled out of view within a `ScrollViewer`, and the badge adornment remains visible.
+The Avalonia adorner system (last tested on v11.0.7) may not properly clip adornments based on the clip regions of ancestors of the adorned element.  This is an issue we are working with the Avalonia team to solve.  A symptom of this issue can sometimes be seen when a badge adornment is used on an adorned element, that adorned element is scrolled out of view within a `ScrollViewer`, and the badge adornment remains visible.
 
-If this scenario is encountered, a workaround is to not use [BadgeService](xref:@ActiproUIRoot.Controls.BadgeService), thereby avoiding use of the Avalonia adorner system.  Place the adorned element and the badge element in a `Panel` instead and apply the `HorizontalAlignment`, `VerticalAlignment`, and `RenderTransform` properties on the badge to position it.
+We believe our badge implementation has worked around this issue in most scenarios.  If this scenario is still encountered, one workaround is to position the adornment within the bounds of the adorned element so clipping can be enabled.  Another option is to not use [BadgeService](xref:@ActiproUIRoot.Controls.BadgeService), thereby avoiding use of the Avalonia adorner system.  Place the adorned element and the badge element in a `Panel` instead and apply the `HorizontalAlignment`, `VerticalAlignment`, and `RenderTransform` properties on the badge to position it.
 
 ```xaml
 <Panel>
@@ -341,4 +361,6 @@ The following theme resources are available for customizing the appearance of th
 | [BadgeDotLength](xref:@ActiproUIRoot.Themes.ThemeResourceKind.BadgeDotLength) | The default [DotLength](xref:@ActiproUIRoot.Controls.Badge.DotLength) for when the badge is displayed as a "dot". |
 | [BadgeStringContentPadding](xref:@ActiproUIRoot.Themes.ThemeResourceKind.BadgeStringContentPadding) | The default `Padding` applied to `String`-based content. |
 
+See the [Theme Assets](../../themes/theme-assets.md) topic for more details on working with theme resources.
+
 }