Stuck on an issue?

Lightrun Answers was designed to reduce the constant googling that comes with debugging 3rd party libraries. It collects links to all the places you might be looking at while hunting down a tough bug.

And, if you’re still stuck at the end, we’re happy to hop on a call to see how we can help out.

[Proposal] Drop the Effects API and migrate all Effects to be Behaviors

See original GitHub issue

[Drop the usage of Effects API]

Proposed
Prototype: Started
Implementation: Not Started
- iOS Support
- Android Support
- macOS Support
- Windows Support
Unit Tests: Not Started
Sample: Started
Documentation: Not Started

Summary

Currently Effects don’t get wired into Handlers. The need for effects in XF came from the need to be able to register something that was smaller than a renderer. The usefulness of an effect inside MAUI is debatable because inside MAUI users can just subscribe to AttachedHandler/DetachedHandler and achieve basically the same thing. You could even just use a behavior at this point.

With that quote, I would suggest migrating our Effects to use the Behaviors API.

Motivation

From my understanding. The .NET MAUI team left some tips in issues and PR comment that devs should not use the Effects API and that was added into .NET MAUI just to avoid a hard break change with Forms. That said since we are supporting MAUI Handlers we should move all our Effects to use a better approach.

Detailed Design

The API for the BasePlatformBehavior is the following:

public abstract partial class BasePlatformBehavior<TView, TNativeView> : BaseBehavior<TView>
	where TView : VisualElement
#if !NET6_0 || IOS || ANDROID || WINDOWS
		where TNativeView : NativeView
#else
		where TNativeView : class
#endif
{
	protected TNativeView? NativeView => View?.Handler?.NativeView as TNativeView;

	protected override void OnAttachedTo(BindableObject bindable)
	{
		base.OnAttachedTo(bindable);
	}

	protected override void OnDetachingFrom(BindableObject bindable)
	{
		base.OnDetachingFrom(bindable);
	}

	protected override void OnAttachedTo(TView bindable)
	{
		base.OnAttachedTo(bindable);
		OnPlatformAttachedBehavior(bindable);
	}

	protected override void OnDetachingFrom(TView bindable)
	{
		base.OnDetachingFrom(bindable);
		OnPlatformDeattachedBehavior(bindable);
	}

	protected abstract void OnPlatformAttachedBehavior(TView view);
	protected abstract void OnPlatformDeattachedBehavior(TView view);
}

From the old Effect API we have the Element property that’s a Forms control and we have a Control property that is the PlatformControl.

On this implementation, the property View inside the BaseBehavior is a MAUI control, and the NativeView inside the BasePlatformBehavior is the PlatformControl.

I override all AttachedTo and OnDeataching methods to avoid the implementor changing its behavior, and I expose - as abstract methods - OnPlatformAttachedBehavior and OnPlatformDeattachedBehavior methods, which will implement that feature per platform. In other words, this is the TemplatedMethod Pattern and this API was inspired on how .NET MAUI implements the ViewHandler.

This should be a partial class to make it easy for devs and us to extend this class to implement any platform-specific code when needed.

POC PR #231

Usage Syntax

In this sample, I keep the Effect suffix, but we should drop it as well.

XAML Usage

<Image>
    <Image.Behaviors>
        <xct:IconTintColorEffect
            TintColor="Green"
        />
    </Image.Behaviors>
</Image>

C# Usage

// using the traditional way
var img = new Image();
img.Behaviors.Add(new xct::IconTintColorEffect
{
            TintColor = Colors.Green
});

// maybe using the AppedingBehavior

Image.ControlsViewMapper.AppendToMapping(nameof(IView.Background), (h, v) => 
{
        var behavior = new xct::IconTintColorEffect { TintColor=Colors.Green };
        h.Do(behavior);
});

For more info about AppendToMapping API check this PR