Building cross-platform native control implementation in MAUI

Hello everyone, I'm Zhou Hao, a researcher at Microsoft's MVP Lab in this issue. MAUI uses the Handler system to handle the implementation of native controls on different platforms, that is, correspondingly, if we want to create controls, we only need to create Handlers based on different platforms. So the following mainly teaches you how to build your own controls by creating a Handler (event handler).

Below, we will demonstrate how to create a platform control in a MAUI project and use it by creating an example of a progress bar control.

Suppose the control contains three basic functions, the color of the progress bar (Foreground), the current value of the progress bar (Value), and the mode of the progress bar (Indeterminate).

first step

(declare control class)

First, create the MyProgressBar class and define the corresponding dependency properties.

internal class MyProgressBar : View
    {
        public static readonly BindableProperty ForegroundProperty =
            BindableProperty.Create(nameof(Foreground),
                typeof(Color),
                typeof(MyProgressBar),
                Colors.Transparent);

        public static readonly BindableProperty ValueProperty =
           BindableProperty.Create(nameof(Value),
               typeof(double),
               typeof(MyProgressBar),
               0.0);

        public static readonly BindableProperty IndeterminateProperty =
           BindableProperty.Create(nameof(Indeterminate),
               typeof(bool),
               typeof(MyProgressBar),
               false);

        public Color Foreground
        {
            get { return (Color)GetValue(ForegroundProperty); }
            set { SetValue(ForegroundProperty, value); }
        }
         
        public double Value
        {
            get { return (double)GetValue(ValueProperty); }
            set { SetValue(ValueProperty, value); }
        }

        public bool Indeterminate
        {
            get { return (bool)GetValue(IndeterminateProperty); }
            set { SetValue(IndeterminateProperty, value); }
        }
    }

second step

create standard handler
With the standard property definitions for the control, the next step is to define the standard Handler handler, which contains the control property mapper and constructor, as follows:

partial class MyProgressBarHandler
    {
        public static PropertyMapper<MyProgressBar, MyProgressBarHandler> HorizontalProgressBarMapper = new
        (ViewHandler.ViewMapper)
        {
            [nameof(MyProgressBar.Value)] = MapValue,
            [nameof(MyProgressBar.Foreground)] = MapForeground, 
            [nameof(MyProgressBar.Indeterminate)]= MapIndeterminate
        };

        public MyProgressBarHandler(PropertyMapper mapper)
            : base(mapper)
        {

        }

        public MyProgressBarHandler() : base(HorizontalProgressBarMapper)
        {

        }
    }

third step

create platform handler
In the property mapper, we can easily see the event handler corresponding to the three properties, but it is not defined at present, which means that you need to implement the corresponding three event handlers under different platforms. > Android > Controls defines a MyProgressBarHandler as follows:

Then inherit from ViewHandler and associate with native Android ProgressBar.

using Android.Widget;

partial class MyProgressBarHandler :
        ViewHandler<MyProgressBar, ProgressBar>
    { 

    }

Override CreateNativeView (this is where the native controls are created first).

protected override ProgressBar CreateNativeView()
        {
            return new ProgressBar(Context, null,  Android.Resource.Attribute.ProgressBarStyleHorizontal)
            {
                Indeterminate = true,
                Max = 10000,
            }; 
        }

Next, implement three event handler methods, MapValue, MapForeground, MapIndeterminate.

static void MapValue(MyProgressBarHandler handler, MyProgressBar view)
        {
            var nativeView= handler?.NativeView;
            nativeView.Progress = (int)(view.Value * Max);
        }

        static void MapForeground(MyProgressBarHandler handler, MyProgressBar view)
        {
            UpdateForeground(handler?.NativeView, view.Foreground);

            static void UpdateForeground(ProgressBar nativeProgressBar, Color color)
            {
                if (color == null)
                {
                    (nativeProgressBar.Indeterminate ? nativeProgressBar.IndeterminateDrawable :
                        nativeProgressBar.ProgressDrawable)?.ClearColorFilter();
                }
                else
                {
                    var tintList = ColorStateList.ValueOf(color.ToNative());

                    if (nativeProgressBar.Indeterminate)
                        nativeProgressBar.IndeterminateTintList = tintList;
                    else
                        nativeProgressBar.ProgressTintList = tintList;
                }
            }
        }

        static void MapIndeterminate(MyProgressBarHandler handler, MyProgressBar view)
        {
           var nativeView= handler?.NativeView;
            nativeView.Indeterminate = view.Indeterminate;
        }

the fourth step

corresponds to the Handler event handler that implements the iOS platform, which is the same as the previous step, and the processing details of the event correspond to the logic processing of different platforms.

partial class MyProgressBarHandler :
        ViewHandler<MyProgressBar, UIProgressView>
    {
        protected override UIProgressView CreateNativeView()
{
            return new UIProgressView(UIProgressViewStyle.Default);
        }
         
        static void MapValue(MyProgressBarHandler handler, MyProgressBar view)
{
            var nativeView = handler.NativeView;
            nativeView.Progress = (float)view.Value;
        }

        static void MapForeground(MyProgressBarHandler handler, MyProgressBar view)
{
            var nativeView = handler.NativeView;
            nativeView.ProgressTintColor = view.Foreground?.ToNative();
        } 

        static void MapIndeterminate(MyProgressBarHandler handler, MyProgressBar view)
{
            //...
        }
    }

the fifth step

open the MauiProgram file, add AddHandler

public static MauiApp CreateMauiApp()
        {
            var builder = MauiApp.CreateBuilder();
            builder.UseMauiApp<App>()
                .ConfigureFonts(fonts =>
                {
                    fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
                })
                .ConfigureMauiHandlers(handler =>
                {
                  handler.AddHandler(typeof(MyProgressBar), typeof(MyProgressBarHandler));
                });  
            return builder.Build();
        }

Step 6

interface, declare MAUI native controls and custom controls

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="MAUIRender.MainPage"
             xmlns:my="clr-namespace:MAUIRender" 
             xmlns:ctor="clr-namespace:MAUIRender.Controls" 
             BackgroundColor="{DynamicResource SecondaryColor}">
    <Grid>
        <StackLayout>
            <ProgressBar   
                Progress="30" ProgressColor="Red"/>
            
            <ctor:MyProgressBar 
                Indeterminate="True"
                Value="600"  Foreground="Green" />
        </StackLayout>
    </Grid>
</ContentPage>

Running the actual effect:

By using Handler to handle the behavior of controls on different platforms, it is decoupled from the controls themselves and easier to support more platforms.

Microsoft Most Valuable Professional (MVP)

The Microsoft Most Valuable Professional is a global award given to third-party technology professionals by Microsoft Corporation. For 28 years, technology community leaders around the world have received this award for sharing their expertise and experience in technology communities both online and offline.

MVPs are a carefully selected team of experts who represent the most skilled and intelligent people, passionate and helpful experts who are deeply invested in the community. MVP is committed to helping others and maximizing the use of Microsoft technologies by Microsoft technical community users through speeches, forum Q&A, creating websites, writing blogs, sharing videos, open source projects, organizing conferences, etc.
For more details, please visit the official website:
https://mvp.microsoft.com/zh-cn