Enhancing Object Power with Extensions

Some of the features discussed in the previous chapters are empowered by new extension methods implemented by the.NET MAUI Community Toolkit. Such extension methods can also be used outside of the objects provided by the Toolkit and leveraged in your own scenarios. More specifically, you can animate and convert colors, and you can make the MAUI engine properly handle your views. These possibilities are all covered in this chapter.

Summarizing extensions

Among others, the .NET MAUI Community Toolkit exposes three classes that define specific extension methods. These classes are referred to as extensions, and Table 7 summarizes them.

Table 7: Reusable Extensions

The next sections describe all the extension methods with suggestions about their use cases.

Working with colors

Two classes allow for working with colors: ColorAnimationExtensions and ColorConversionExtensions. These are described in the next sections.

Animating colors

The ColorAnimationExtensions class exposes two extension methods:

·     BackgroundColorTo: This method animates the BackgroundColor property of those views where it is available, such as (but not limited to) Grid and Button.

·     TextColorTo: This method animates the TextColor property of those views where it is available, such as Entry and Label.

Both methods require at least one argument, which is the target color for the animation. However, they share a full list of parameters described in Table 8.

Table 8: Common Method Parameters

Before using these methods, you need the following using directive.

using CommunityToolkit.Maui.Extensions;

For example, you could animate the background of a Label as follows.

var label = new Label { BackgroundColor = Colors.White };

await label.BackgroundColorTo(Colors.Red);

This code will animate the background color with the default values described in Table 8. You could then further customize the animation like in the following example.

await label.BackgroundColorTo(Colors.Red, 10, 180, Easing.Linear);

With this code, the time between frames is 10 milliseconds, the animation duration is 180 milliseconds, and the type of animation is the Linear one from the Easing collection. The sample project provides the ColorAnimationExtensionsPage.xaml file under the Pages\Extensions folder. If you run the example and start the animations, you will get a result similar to Figure 37.

Figure 37: Animating Colors

These methods are very useful when you need to capture the user’s attention, or when you simply want to provide a nice behavior to your user interface.

Converting colors

In Chapter 4, “Saving Time with Reusable Converters,” you saw how to convert one color to another color or one color to another type via value converters with data-binding scenarios. However, converting colors can also be useful outside of data binding. The value converters you saw in Chapter 4 all rely on separate methods that perform the actual conversions and are all defined inside the static ColorConversionExtensions class, located inside the ColorConversionExtensions.shared.cs file of the Toolkit. For example, if you want to convert a Color into a string that contains the RGB representation of the color, you can invoke an extension method called ToRgbString, as follows.

string resultString = Colors.Green.ToRgbString();

The extension method definition is:

public static string ToRgbString(this Color color)

{

    ArgumentNullException.ThrowIfNull(color);

    return $"RGB({color.GetByteRed()},{color.GetByteGreen()},{color.

    GetByteBlue()})";

}

Tip: The this keyword in the parameter list identifies the definition of an extension method, together with the static modifier.

The GetByteRed, GetByteGreen, and GetByteBlue methods are defined in the same file and their purpose is to retrieve the color’s components. Their definition is:

public static byte GetByteRed(this Color color)

{

    ArgumentNullException.ThrowIfNull(color);

    return ToByte(color.Red * 255);

}

public static byte GetByteGreen(this Color color)

{

    ArgumentNullException.ThrowIfNull(color);

    return ToByte(color.Green * 255);

}

public static byte GetByteBlue(this Color color)

{

    ArgumentNullException.ThrowIfNull(color);

    return ToByte(color.Blue * 255);

}

The ToByte method, invoked by several conversion methods, is defined as follows.

static byte ToByte(float input)

{

   var clampedInput = Math.Clamp(input, 0, 255);

   return (byte)Math.Round(clampedInput);

}

The Math.Clamp method returns a value clamped to the original value including the specified minimum and maximum ranges. The result is rounded via Math.Round and then converted into a byte value.

Tip: In order to use conversion methods, you need the following directive: using CommunityToolkit.Maui.Core.Extensions;

The list of available methods is very long, so a good idea is grouping methods by return type and purpose. Table 9 summarizes methods that return another Color as the result of the conversion or bool as the result of a color check.

Table 9: Methods for Conversion to Color

All the methods in Table 9 (except for IsDark and IsDarkForTheEye) work in the same way: they are invoked over a color instance, and they return another Color object. For example, you can easily retrieve the inverse color for the specified Color object as follows.

Color newColor = Colors.Red.ToInverseColor();

In this example, newColor receives zero for red, 1 for green, 1 for blue, and 1 for alpha. Another set of methods is used to retrieve individual components from a color. These methods are summarized in Table 10.

Table 10: Methods that Return Components of a Color

Tip: For methods that return byte, the minimum and maximum values are between 0 and 255, which is the range for the byte type.

In the following line of code, you can see how to return a component from a color.

byte blue = Colors.Maroon.GetByteBlue();

The other methods work the same, obviously with their specific return type. Another group of methods returns formatted string objects with color components, as represented in Table 11.

Table 11: Methods for Retrieving Formatted Strings

Methods in this group also work in the same way. For example, you can retrieve the RGB with alpha components as follows.

Console.WriteLine(Colors.Azure.ToRgbaString());

The result of the invocation is the following.

> RGBA(240,255,255,1)

Tip: Remember that invoking Console.WriteLine in a .NET MAUI project will print the output in the Output window.

The last group of extension methods allow for generating a new Color from an existing one, to which a different component is applied. Table 12 summarizes these methods.

Table 12: Methods for Color Conversion

For example, the following code adds the maximum value for the yellow component and creates a derived color.

Color newColor = Colors.PaleVioletRed.WithYellow(1);

Methods for color conversion can be very useful in a variety of scenarios, and the library of methods provided by the .NET MAUI Community Toolkit will cover most of your needs.

Working with MAUI services

The .NET MAUI Community Toolkit also provides interesting extensions to methods that you can use if you work with the dependency injection and inversion of control patterns. Such methods simplify the way you register views and their associated viewmodels within the .NET MAUI IServiceCollection, a type handled by the MauiApp class that registers the services that will be used across the app.

For a better understanding, consider the AddScoped<TView>, AddSingleton<TView>, and AddTransient<TView> methods. These are already part of the MAUI codebase, and they respectively allow for adding a scoped view, a singleton view, and a transient view to the collection of services. However, with the Toolkit extension, you now have the option to also register a viewmodel along with its view, as follows.

builder.Services.AddScoped<HomePage, HomePageViewModel>();

builder.Services.AddSingleton<HomePage, HomePageViewModel>();

builder.Services.AddTransient<HomePage, HomePageViewModel>();

Similarly, there are methods in MAUI that allow for registering a view so that the Shell can navigate to the view via the specified route. These methods are AddScopedWithShellRoute<TView>, AddSingletonWithShellRoute<TView>, and AddTransientWithShellRoute<TView>, and they have the same purpose as the previously mentioned methods, but with the possibility to specify a shell route. With the Community Toolkit, you can now associate a viewmodel as follows.

builder.Services.AddScopedWithShellRoute<HomePage, HomePageViewModel>();

builder.Services.AddSingletonWithShellRoute<HomePage, HomePageViewModel>();

builder.Services.AddTransientWithShellRoute<HomePage, HomePageViewModel>();

Though these extension methods become very useful only with dependency injection and inversion of control scenarios, it is worth mentioning that many MVVM third-party frameworks rely on both patterns. Syncfusion has a very interesting article about dependency injection in MAUI that is a nice supplement to this section.

Chapter summary

The .NET MAUI Community Toolkit enhances your development experience with a library of extension methods defined in three public classes. Methods exposed by the ColorAnimationExtensions class allow for animating objects of type Color. Methods exposed by the ColorConversionExtensions class allow for converting Color objects into other colors or other types, depending on the value they retrieve. Methods exposed by the ServiceCollectionExtensions class enhance the way you associate viewmodels with views in a dependency injection scenario. As you have seen, this chapter is mostly based on C# code rather than XAML and this is what you will also see in the next chapter, where you will learn how to leverage fluent C# APIs to define the user interface of your apps.