Improve the usage experience with CompareConverter in XAML

[bijington]

Description of Change

The aim of this PR is to simplify the usage of the CompareConverter through better control of implementation when inheriting form CompareConverter.

The current usage of the converter is as follows:

<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="{StaticResource ComparingValue}"
    ComparisonOperator="Greater"
    TrueObject="{StaticResource LightGreen}"
    FalseObject="{StaticResource PaleVioletRed}" />

If a developer tries to write ComparingValue="0.5" they will receive a compilation error stating:

No property, BindableProperty, or event found for "ComparingValue", or mismatching type between value and property

This is down to the fact that ComparingValue is of type IComparable and there is no implicit conversion that can be determined between the value 0.5 (which is a string) to IComparable.

This PR makes it possible to define what type ComparingValue should be when inheriting from the converter. Therefore usage becomes:

Converter definition

public sealed class CompareDoubleToColorConverter : CompareConverter<double, Color>
{
}

XAML usage

<converters:CompareDoubleToColorConverter
    x:Key="isLargerThanOneConverter"
    ComparingValue="1"
    ComparisonOperator="Greater"
    TrueObject="LightGreen"
    FalseObject="PaleVioletRed" />

It might feel like a small improvement but I believe it will make quite a difference, especially when using the markup extension to define it inside the binding. The definitions become a lot more concise.

Question

Should we go a step further and make ComparingValue a BindableProperty and allow developers to make the value dynamic through the use of bindings? I think yes but I would like to see what others think.

Linked Issues

• Fixes [BUG] CompareConverter - No property, BindableProperty, or event found for "ComparingValue", or mismatching type between value and property #1437

PR Checklist

• Has a linked Issue, and the Issue has been approved(bug) or Championed (feature/proposal)
• Has tests (if omitted, state reason in description)
• Has samples (if omitted, state reason in description)
• Rebased on top of main at time of PR
• Changes adhere to coding standard
• Documentation created or updated: Add example of how to sub-class the converter and simplify XAML MicrosoftDocs/CommunityToolkit#415

Additional information

[brminnick]

I like it! Should we update the docs to demonstrate this as the recommended way going forward to use CompareConverter?

[bijington]

Yes I'll update the docs to reflect this 👍

[brminnick]

Right on! I've added the approved This Proposal has been approved and is ready to be added to the Toolkit and pending documentation This feature requires documentation labels for now.

It looks like there's a missing XML comment somewhere causing the build to fail, but once that's fixed (and the docs are generated) I'm happy to approve + merge 🙌

[bijington]

Awesome thanks @brminnick. Technically this change is breaking because CompareConverter now takes 2 type arguments.

It went from

public abstract class CompareConverter<TReturnObject> : BaseConverterOneWay<IComparable, object>

to

public abstract class CompareConverter<TValue, TReturnObject> : BaseConverterOneWay<TValue, object> where TValue : IComparable

If we want to avoid a major version now and breaking developers straightaway we could add in the following and mark it as [Obsolete]

[Obsolete]
public abstract class CompareConverter<TReturnObject> : CompareConverter <IComparable, TReturnObject>

This would provide a more gentle break for those that are already using CompareConverter and not having an issue. What do you think?

[brminnick]

Good catch! I've added the breaking change This label is used for PRs that include a breaking change label too.

Nah, don't worry about it. We recently merged another breaking change in #1839, so our next release will be a major version bump anyways.

We'll both just want to double check the Release Notes to ensure these PRs with the breaking change This label is used for PRs that include a breaking change are called out 💯

[bijington]

Docs are at: MicrosoftDocs/CommunityToolkit#415