ColorToPercentBlackKeyConverter

The ColorToPercentBlackKeyConverter is a one way converter that allows users to convert an incoming Color to the key component as a value between 0 and 1.

The Convert method returns the key component as a value between 0 and 1 from the supplied value.

The ConvertBack method is not supported.

BaseConverter Properties

The following properties are implemented in the base class, public abstract class BaseConverter:

Property	Description
DefaultConvertReturnValue	Default value to return when IValueConverter.Convert(object?, Type, object?, CultureInfo?) throws an Exception. This value is used when CommunityToolkit.Maui.Options.ShouldSuppressExceptionsInConverters is set to true.
DefaultConvertBackReturnValue	Default value to return when IValueConverter.ConvertBack(object?, Type, object?, CultureInfo?) throws an Exception. This value is used when CommunityToolkit.Maui.Options.ShouldSuppressExceptionsInConverters is set to true.

ICommunityToolkitValueConverter Properties

The following properties are implemented in the public interface ICommunityToolkitValueConverter:

Property	Type	Description
DefaultConvertReturnValue	object?	Default value to return when IValueConverter.Convert(object?, Type, object?, CultureInfo?) throws an Exception. This value is used when CommunityToolkit.Maui.Options.ShouldSuppressExceptionsInConverters is set to true.
DefaultConvertBackReturnValue	object?	Default value to return when IValueConverter.ConvertBack(object?, Type, object?, CultureInfo?) throws an Exception. This value is used when CommunityToolkit.Maui.Options.ShouldSuppressExceptionsInConverters is set to true.

Syntax

The following examples will show how to use the ColorToPercentBlackKeyConverter to display the key component of a specific Color.

XAML

Including the XAML namespace

In order to use the toolkit in XAML the following xmlns needs to be added into your page or view:

xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"

Therefore the following:

<ContentPage
    x:Class="CommunityToolkit.Maui.Sample.Pages.MyPage"
    xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml">

</ContentPage>

Would be modified to include the xmlns as follows:

<ContentPage
    x:Class="CommunityToolkit.Maui.Sample.Pages.MyPage"
    xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit">

</ContentPage>

Using the ColorToPercentBlackKeyConverter

The ColorToPercentBlackKeyConverter can be used as follows in XAML:

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
             x:Class="CommunityToolkit.Maui.Sample.Pages.Converters.ColorToPercentBlackKeyConverterPage">

    <ContentPage.Resources>
        <ResourceDictionary>
            <toolkit:ColorToPercentBlackKeyConverter x:Key="ColorToPercentBlackKeyConverter" />
        </ResourceDictionary>
    </ContentPage.Resources>

    <VerticalStackLayout>
         <Label Text="The key component is:" />

         <Label Text="{Binding MyFavoriteColor, Converter={StaticResource ColorToPercentBlackKeyConverter}}" />
     </VerticalStackLayout>

</ContentPage>

C#

The ColorToPercentBlackKeyConverter can be used as follows in C#:

class ColorToPercentBlackKeyConverterPage : ContentPage
{
    public ColorToPercentBlackKeyConverterPage()
    {
        var label = new Label();

 		label.SetBinding(
 			Label.TextProperty,
 			new Binding(
 				nameof(ViewModel.MyFavoriteColor),
 				converter: new ColorToPercentBlackKeyConverter()));

 		Content = new VerticalStackLayout
 		{
 			Children =
 			{
 				new Label { Text = "The key component is:" },
 				label
 			}
 		};
    }
}

C# Markup

Our CommunityToolkit.Maui.Markup package provides a much more concise way to use this converter in C#.

using CommunityToolkit.Maui.Markup;

class ColorToPercentBlackKeyConverterPage : ContentPage
{
    public ColorToPercentBlackKeyConverterPage()
    {
        Content = new VerticalStackLayout
        {
            Children =
            {
                new Label()
                    .Text("The key component is:"),
                new Label()
                    .Bind(
                        Label.TextProperty,
                        static (ViewModel vm) => vm.MyFavoriteColor,
                        converter: new ColorToPercentBlackKeyConverter())
            }
        };
    }
}

Examples

You can find an example of this converter in action in the .NET MAUI Community Toolkit Sample Application.

API

You can find the source code for ColorToPercentBlackKeyConverter over on the .NET MAUI Community Toolkit GitHub repository.