Improve the usage experience with CompareConverter in XAML (#1841)

* Add additional generic type definition to allow for the ComparingValue to be defined

* Update the sample application to make use of the ability to simplify XAML usage

* Remove broken cref in xml docs

---------

Co-authored-by: Shaun Lawrence <17139988+bijington@users.noreply.github.com>
Co-authored-by: Brandon Minnick <13558917+brminnick@users.noreply.github.com>

samples/CommunityToolkit.Maui.Sample/Converters/CompareDoubleToColorConverter.cs

@@ -0,0 +1,11 @@
+using CommunityToolkit.Maui.Converters;
+
+namespace CommunityToolkit.Maui.Sample.Converters;
+
+/// <summary>
+/// Compares a double value against the ComparingValue property
+/// and returns a <see cref="Color"/> based on the comparison.
+/// </summary>
+public sealed class CompareDoubleToColorConverter : CompareConverter<double, Color>
+{
+}

samples/CommunityToolkit.Maui.Sample/Pages/Converters/CompareConverterPage.xaml

@@ -2,6 +2,7 @@
              xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
              x:Class="CommunityToolkit.Maui.Sample.Pages.Converters.CompareConverterPage"
              xmlns:vm="clr-namespace:CommunityToolkit.Maui.Sample.ViewModels.Converters"
+             xmlns:converters="clr-namespace:CommunityToolkit.Maui.Sample.Converters"
              xmlns:mct="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
              xmlns:pages="clr-namespace:CommunityToolkit.Maui.Sample.Pages"
              x:TypeArguments="vm:CompareConverterViewModel"
@@ -12,6 +13,13 @@
             <x:Double x:Key="ComparingValue">0.5</x:Double>
             <Color x:Key="LightGreen">LightGreen</Color>
             <Color x:Key="PaleVioletRed">PaleVioletRed</Color>
+
+            <converters:CompareDoubleToColorConverter
+                x:Key="isLargerThanOneConverter"
+                ComparingValue="1"
+                ComparisonOperator="Greater"
+                TrueObject="LightGreen"
+                FalseObject="PaleVioletRed" />
         </ResourceDictionary>
     </pages:BasePage.Resources>
 
@@ -22,14 +30,14 @@
             TextColor="{StaticResource NormalLabelTextColor}"/>
 
         <Slider
-            Maximum="1"
+            Maximum="10"
             Minimum="0"
             Value="{Binding SliderValue, Mode=TwoWay}"
             HorizontalOptions="FillAndExpand"/>
 
         <Label 
-            Text="The background of this label will be green if the value of the slider is greater than or equal to 50%, and red otherwise."
-            BackgroundColor="{Binding SliderValue, Mode=OneWay, Converter={mct:CompareConverter ComparingValue={StaticResource ComparingValue}, ComparisonOperator=GreaterOrEqual, TrueObject={StaticResource LightGreen}, FalseObject={StaticResource PaleVioletRed}}}"
+            Text="The background of this label will be green if the value of the slider is greater than 1, and red otherwise."
+            BackgroundColor="{Binding SliderValue, Mode=OneWay, Converter={StaticResource isLargerThanOneConverter}}"
             TextColor="Black"
             Padding="4, 0"/>
 

src/CommunityToolkit.Maui/Converters/CompareConverter.shared.cs

@@ -7,14 +7,14 @@ namespace CommunityToolkit.Maui.Converters;
 /// <summary>
 /// Converts an object that implements IComparable to an object or a boolean based on a comparison.
 /// </summary>
-public sealed class CompareConverter : CompareConverter<object>
+public sealed class CompareConverter : CompareConverter<IComparable, object>
 {
 }
 
 /// <summary>
 /// Converts an object that implements IComparable to an object or a boolean based on a comparison.
 /// </summary>
-public abstract class CompareConverter<TObject> : BaseConverterOneWay<IComparable, object>
+public abstract class CompareConverter<TValue, TReturnObject> : BaseConverterOneWay<TValue, object> where TValue : IComparable
 {
 	/// <inheritdoc/>
 	public override object DefaultConvertReturnValue { get; set; } = new();
@@ -59,7 +59,7 @@ public enum OperatorType
 	/// <summary>
 	/// The comparing value.
 	/// </summary>
-	public IComparable? ComparingValue { get; set; }
+	public TValue? ComparingValue { get; set; }
 
 	/// <summary>
 	/// The comparison operator.
@@ -69,12 +69,12 @@ public enum OperatorType
 	/// <summary>
 	/// The object that corresponds to True value.
 	/// </summary>
-	public TObject? TrueObject { get; set; }
+	public TReturnObject? TrueObject { get; set; }
 
 	/// <summary>
 	/// The object that corresponds to False value.
 	/// </summary>
-	public TObject? FalseObject { get; set; }
+	public TReturnObject? FalseObject { get; set; }
 
 	/// <summary>
 	/// Converts an object that implements IComparable to a specified object or a boolean based on a comparison result.
@@ -83,7 +83,7 @@ public enum OperatorType
 	/// <param name="culture">The culture to use in the converter.  This is not implemented.</param>
 	/// <returns>The object assigned to <see cref="TrueObject"/> if (value <see cref="ComparisonOperator"/> <see cref="ComparingValue"/>) equals True and <see cref="TrueObject"/> is not null, if <see cref="TrueObject"/> is null it returns true, otherwise the value assigned to <see cref="FalseObject"/>, if no value is assigned then it returns false.</returns>
 	[MemberNotNull(nameof(ComparingValue))]
-	public override object ConvertFrom(IComparable value, CultureInfo? culture = null)
+	public override object ConvertFrom(TValue value, CultureInfo? culture = null)
 	{
 		ArgumentNullException.ThrowIfNull(value);
 		ArgumentNullException.ThrowIfNull(ComparingValue);