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.iOS.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:

Background	Android	iOS
Elevation	Android.Views.View.Elevation	MDCShadowLayer
Ripple	Android.Graphics.Drawable.RippleDrawable	MDCInkViewController
CornerRadius	GradientStrokeDrawable	GradientStrokeLayer
Gradients	GradientStrokeDrawable	GradientStrokeLayer
Border	GradientStrokeDrawable	GradientStrokeLayer
Gradient Border	GradientStrokeDrawable	GradientStrokeLayer

Native Views (FastRenderers Pattern on Android)

Parent Views	Android	iOS
MaterialContentView	Android.Views.View	UIView
MaterialCard	CardView*	MaterialComponents.Card

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

Native Background Managers

Android	iOS
MaterialVisualElementTracker	MaterialVisualElementTracker

What is supported

Xamarin.Forms Layouts

Xamarin.Forms Layouts	Android	iOS
AbsoluteLayout	Yes	Yes
CarouselView	Yes	Yes
CollectionView	Yes	Yes
ContentView	Yes	Yes
FlexLayout	Yes	Yes
Frame	No, see more at this issue	Yes
Grid	Yes	Yes
ListView	Yes	Yes
RelativeLayout	Yes	Yes
ScrollView	Yes	Yes
StackLayout	Yes	Yes

Xamarin.Forms Views

Xamarin.Forms Views	Android	iOS
ActivityIndicator	Yes	Yes
BoxView	Yes	Yes
Button	Yes	Yes
DatePicker	Yes	Yes
Editor	Yes	Yes
Entry	Yes	Yes
Image	Yes	Yes
ImageButton	Yes	Yes
Label	Yes	Yes
Picker	Yes	Yes
ProgressBar	Yes	Yes
SearchBar	Yes	Yes
Slider	Yes	Yes
Stepper	Yes	Yes
Switch	Yes	Yes
TimePicker	Yes	Yes
WebView	Yes	Yes

Custom Views from BackgroundKit

BackgroundKit View	Android	iOS
MaterialCard	Yes	Yes
MaterialContentView	Yes	Yes

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

BackgroundKit View	Android	iOS
MaterialCard	Yes through RippleDrawable	Yes through RippleDrawable
MaterialContentView	Yes through MDCInkViewController	Yes through MDCInkViewController

Usage

API Documentation

Background

Property	Type	Description	Why do I need it?
Elevation	double	The elevation of the Background	It adds shadow to view that depends on the value of elevation
TranslationZ	double	The translation in Z axis of the background (only affects on Android)	In android you need to overlap views without adding shadows. TranslationZ is what you need!
CornerRadius	CornerRadius	The corner radius of the background	Exactly as Thickness. Sets the radius to each corner
GradientBrush	LinearGradientBrush	The gradient brush that will be used for the background
BorderColor	Color	The border color of the background
BorderWidth	double	The border width of the background
DashGap	double	Adds dashed border to the background. Dash gap specifies the pixels that the gap of the dash will be
DashWidth	double	Adds dashed border to the background. Dash width specifies the pixels that the width of a filled line will be
BorderGradientBrush	LinearGradientBrush	The gradient brush that will be used for the border of the background
IsRippleEnabled	bool	Whether or not the ripple will be enabled
RippleColor	Color	The ripple color of the background
IsClippedToBounds	bool	Whether or not the parent view clips its subviews

LinearGradientBrush

Property	Type	Description	Why do I need it?
Angle	double	The gradient angle of the background	The -360 to 360 angle of the gradient
GradientType	GradientType	The type of gradient of the background	Linear or Radial. Currently Linear is supported only
Gradients	IList<GradientStop>	The gradients that will be used for the background

GradientStop

Property	Type	Description	Why do I need it?
Offset	double	The offset of the gradient stop	Sets where the gradient stop ends
Color	Color	The color of the gradient stop

Material Content View

Property	Type	Description
Background	Background	The background of the view
IsCircle	bool	By using this property you do not have to set the same WidthRequest and HeightRequest and manually add the CornerRadius. It measures all the child views and then becomes a circle
IsCornerRadiusHalfHeight	bool	The corner radius will ALWAYS become the half of the height

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!