Xamarin.Forms-BackgroundKit

🎨 🔨 A powerful Kit for customizing the background of Xamarin.Forms views

📐 Corner Radius | 🎨 Background Gradients | 🍩 Borders | 🌈 Border Gradients | 🙏 Shadows

• Screenshots
• Setup
• Usage
• What was hard
• Break some limitations
• What is Supported
• Ripple Support

ScreenShots

Android

|

iOS (Gifs coming soon...)

Clipping and Shadow Support

|

|

Setup

Xamarin.Android

Initialize the renderer below the Xamarin.Forms.Init

XamarinBackgroundKit.Android.BackgroundKit.Init();

Xamarin.iOS

Initialize the renderer below the Xamarin.Forms.Init

XamarinBackgroundKit.Android.BackgroundKit.Init();

Actual Usage

Everything you need to do is coming from XAML!

Material Card/ContentView

<controls:MaterialContentView HeightRequest="60">

    <controls:MaterialContentView.Background>    

        <!-- Provide the Background Instance -->

        <controls:Background
            Angle="0"
            BorderColor="Brown"
            BorderWidth="4"
            CornerRadius="30"
            IsRippleEnabled="True"
            RippleColor="White">

            <!-- Provide the Background Gradient Brush -->

            <background:Background.GradientBrush>

                <background:LinearGradientBrush Angle="45">

                    <!-- Provide the Background Gradient Stops -->

                    <background:GradientStop Offset="0" Color="DarkBlue" />
                    <background:GradientStop Offset="1" Color="DarkRed" />
                </background:LinearGradientBrush>

            </background:Background.GradientBrush>

            <!-- Provide the Border Gradient Brush -->

            <background:Background.BorderGradientBrush>

                <background:LinearGradientBrush Angle="45">

                    <!-- Provide the Border Gradient Stops -->

                    <background:GradientStop Offset="0" Color="Blue" />
                    <background:GradientStop Offset="1" Color="Red" />
                </background:LinearGradientBrush>

            </background:Background.BorderGradientBrush>

        </controls:Background>

    </controls:MaterialContentView.Background>

    <Label Text="Material ContentView with Gradient and Offsets" />
</controls:MaterialContentView>

New Way by using the Markup extensions

<controls:MaterialContentView 
    HeightRequest="60" 
    Background="{controls:BgProvider Color=White, CornerRadius=8, Elevation=8}" />

Do you need just a color?

<controls:MaterialContentView 
    Background="{controls:BgProvider Color=White}" />

Do you need rounded cornders?

<controls:MaterialContentView 
    Background="{controls:BgProvider CornerRadius='LeftTop, RightTop, RightBottom, LeftBottom'}" />

Do you need shadow?

<controls:MaterialContentView 
    Background="{controls:BgProvider Elevation=8}" />

Do you need ripple?

<controls:MaterialContentView 
    Background="{controls:BgProvider IsRippleEnabled=True, RippleColor=#80000000}" />

Do you need gradient?

<controls:MaterialContentView 
    Background="{controls:BgProvider GradientBrush={controls:LinearGradient Start=Red, End=Green, Angle=70}}" />

Do you need more gradients?

<controls:MaterialContentView 
    Background="{controls:BgProvider GradientBrush={controls:LinearGradient Gradients='Red,Green,Blue', Angle=70}}" />

Do you need border?

<controls:MaterialContentView 
    Background="{controls:BgProvider BorderWidth=4, BorderColor=Red}" />

Do you need dashed border?

<controls:MaterialContentView 
    Background="{controls:BgProvider BorderWidth=4, BorderColor=Red, DashGap=5, DashWidth=10}" />

Do you need gradient border?

<controls:MaterialContentView 
    Background="{controls:BgProvider BorderWidth=4, BorderGradientBrush={controls:LinearGradient Start=Red, End=Green, Angle=70}}" />

Do you need outer border?

<controls:MaterialContentView 
    Background="{controls:BgProvider BorderStyle=Outer}" />

Don't you like MaterialContentView? Feel free to attach it anywhere by

<StackLayout 
    controls:BackgroundEffect.Background="{controls:BgProvider BorderStyle=Outer}" />

Do you need a very complex background? You can achieve it by using only one view!

What was hard

Mixing Gradient on border with gradient on background was a really painful challenge. On Android I had to deal with custom Drawables and CALayers on iOS. Also, on Android, making elevation and clipping work for different radius on each corner was a trial and error pain. An outline provider has been made in order to support cornerRadii. GradientStrokeDrawable extends GradientDrawable and draws a custom paint(to replicate the border) into the shape of the view. On iOS, the GradientStrokeLayer also extends CAGradientLayer and it has a ShadowLayer and another one CAGradientLayer for the border. Clipping on iOS is done through a CAShapeLayer.

Break some limitations

Android

ViewOutlineProvider only supports clipping that can be represented as a rectangle, circle, or round rect. See more at documentation. Setting SetConvexPath() to the outline has no effect on clipping the view, since the CanClip() method returns false.

Clipping SubViews

Clipping subviews (e.g. clip an image inside a stacklayout with rounded corners) is only supported by MaterialContentView and it clips its subviews by clipping the Canvas on DispatchDraw(). Since DispatchDraw must be overwritten in order to make clip to a path happen, clipping on xamarin.forms views is not supported. If there is any other way, i'm glad to accept it as a PR.

Clipping Drawable

On Android, the GradientStrokeDrawable is clipping the outer stroke by Canvas.ClipPath(), and sets the stroke the double value. Although, this seems to work on API <= 27, on API 28, outer stroke was not clipped by the ClipPath() method. To resolve this issue, instead of drawing directly to the canvas, it draws to a bitmap, then clips the canvas by ClipPath() and then DrawBitmap() is called.

iOS

Clipping SubViews

There is a method called InvalidateClipToBounds() inside MaterialVisualElementTracker. This method manually clip each subview of the rendered parent view, using as mask the BezierPath that is calculated by the CornerRadius.

CAGradientLayer vs GradientStrokeLayer

In the old version, when using sublayers to get the job done for the gradient and the border gradient, things went bad and weird flickerings happened.
The new version only extends CALayer and draws manually everything on DrawInContext() method. First of all, it clips the path using the BezierPath provided by the CornerRadius, as explained above, and then draws the Gradient or Color and the Border Gradient or Border Color. Finally, it has only 1 sublayer, the MDCShadowLayer.

By using the GradientStrokeLayer every view's background is identical to Android!

What is used for the Background

BackgroundKit Provides a consistent way for adding Background to your views.
What is supported out of the box:

Native Views (FastRenderers Pattern on Android)

• I used MaterialCardView but there is bug with the RippleEffect and it is not in the codebase yet.

Native Background Managers

What is supported

Xamarin.Forms Layouts

Xamarin.Forms Views

Custom Views from BackgroundKit

PS.: Material Components on Android and iOS are not supporting changing the background, so gradients and gradient borders are not supported when Visual="Material" is used.

Ripple Support

Usage

API Documentation

Background

LinearGradientBrush

GradientStop

Material Content View

Material Card

Same as MaterialContentView

Background Effect

Background Effect has an attached property in order to add background to your views without the need of a custom renderer!