Working with Gradients

Overview

Grial comes with support for linear and radial gradients. They can be applied as background for any VisualElement directly in Xaml through a platform effect.

The gradient structure is defined by a collection of GradientColors that represent the color-stops.

LinearGradient Properties

Property	Type	Description
Angle	double	Renders the gradient with the supplied angle. Default value is 0 which means bottom-up vertical direction (first color is at the bottom and last at the top). It rotates clockwise until 360 that is the same as 0.

RadialGradient Properties

Property	Type	Description
Radius	double?	The radius of the gradient in both directions. It’s value is used when a specific radius is null. If this property itself is null the gradient behaves as if it were 0.5 when RadiusType == Proportional and half width/height when RadiusType == Absolute.
RadiusX	double?	The horizontal radius of the gradient. When null defaults to Radius.
RadiusY	double?	The vertical radius of the gradient. When null defaults to Radius.
RadiusType	Absolute, Proportional	Defines the meaning of the radius. When absolute the radius value is interpreted as device-independent pixels and when proportional it’s a fraction of the rendered area dimension (0.5 means half width/height).
CenterX	double	Horizontal center position. 0 means top, 1 means bottom. Default value is 0.5.
CenterY	double	Vertical center position. 0 means left, 1 means right. Default value is 0.5.

ColorGradient Properties

Property	Type	Description
Color	Color	This can be an inline color, a static resource color or can be set through a binding.
Position	double?	This is the position of the color-stop inside the gradient.
Opacity	double	A Solid color can be made translucid through this property. Its value goes from 0.0 to 1.0. This is a convenient property, the Color itself can have a alpha channel which will be honored too.

Linear Gradients

Check below XAML sample showing a LinearGradient applied on a BoxView element, and using:

<BoxView>
    <grial:Effects.BackgroundGradient>
        <grial:LinearGradient>
            <grial:GradientColor 
                Color="Yellow"
            />
            <grial:GradientColor 
                Color="Green"
            />
        </grial:LinearGradient>
    </grial:Effects.BackgroundGradient>
</BoxView>

..and here is the result:

The default value for the Angle is 0, so the gradient is rendered vertically, from bottom to top.

Let’s see the Angle property in action:

<BoxView>
    <grial:Effects.BackgroundGradient>
        <grial:LinearGradient Angle="45">
            <grial:GradientColor 
                Color="Yellow"
            />
            <grial:GradientColor 
                Color="Green"
            />
        </grial:LinearGradient>
    </grial:Effects.BackgroundGradient>
</BoxView>

…and its result:

Let’s change the Angle to be 180 degrees:

<BoxView>
    <grial:Effects.BackgroundGradient>
        <grial:LinearGradient Angle="180">
            <grial:GradientColor 
                Color="Yellow"
            />
            <grial:GradientColor 
                Color="Green"
            />
        </grial:LinearGradient>
    </grial:Effects.BackgroundGradient>
</BoxView>

Radial Gradients

Let’s create a simple radial gradient:

<BoxView>
    <grial:Effects.BackgroundGradient>
        <grial:RadialGradient>
            <grial:GradientColor 
                Color="Yellow"
            />
            <grial:GradientColor 
                Color="OrangeRed"
            />
        </grial:RadialGradient>
    </grial:Effects.BackgroundGradient>
</BoxView>

As you can see, the radial gradient uses the whole area as the radius by default. When radius type is proportional, this means a 0.5 radius (the radius is half the area hence the circle covers the whole area). If you use 0.25 it would cover half of the area for instance.

You can also specify an absolute value for the radius by setting radius type to absolute. In this case, if you set a specific radius it will be interpreted as device-independent pixels.

Let’s see the following example:

<BoxView HeightRequest="150" WidthRequest="100">
    <grial:Effects.BackgroundGradient>
        <grial:RadialGradient RadiusType="Absolute" Radius="50">
            <grial:GradientColor 
                Color="Yellow"
            />
            <grial:GradientColor 
                Color="OrangeRed"
            />
        </grial:RadialGradient>
    </grial:Effects.BackgroundGradient>
</BoxView>

The radial gradient is now fixed to an specific value and also the origin of the gradient is by default set to 50% vertical and horizontal respectively.

Let’s see how to change it in the next example. We are going to move the center to the top left corner:

<BoxView HeightRequest="150" WidthRequest="100">
    <grial:Effects.BackgroundGradient>
        <grial:RadialGradient RadiusType="Absolute" Radius="50" CenterX="0" CenterY="0">
            <grial:GradientColor 
                Color="Yellow"
            />
            <grial:GradientColor 
                Color="OrangeRed"
            />
        </grial:RadialGradient>
    </grial:Effects.BackgroundGradient>
</BoxView>

…and now let’s move it to the right top corner:

<BoxView HeightRequest="150" WidthRequest="100">
    <grial:Effects.BackgroundGradient>
        <grial:RadialGradient RadiusType="Absolute" Radius="50" CenterX="1" CenterY="0">
            <grial:GradientColor 
                Color="Yellow"
            />
            <grial:GradientColor 
                Color="OrangeRed"
            />
        </grial:RadialGradient>
    </grial:Effects.BackgroundGradient>
</BoxView>

Finally, let’s move it to the center bottom:

<BoxView>
    <grial:Effects.BackgroundGradient>
        <grial:RadialGradient RadiusType="Absolute" Radius="320" CenterX="0.5" CenterY="1">
            <grial:GradientColor 
                Color="Yellow"
            />
            <grial:GradientColor 
                Color="OrangeRed"
            />
        </grial:RadialGradient>
    </grial:Effects.BackgroundGradient>
</BoxView>

Gradient Colors

By default, gradient colors are rendered equidistant from each other. The more colors you include, the less distance between them.

Check the sample below where 4 colors were added:

<BoxView>
    <grial:Effects.BackgroundGradient>
        <grial:LinearGradient>
            <grial:GradientColor 
                Color="Blue"
            />
            <grial:GradientColor 
                Color="Red"
            />
            <grial:GradientColor 
                Color="Yellow"
            />
            <grial:GradientColor 
                Color="Orange"
            />
        </grial:LinearGradient>
    </grial:Effects.BackgroundGradient>
</BoxView>

Each color gets a 25% of the total area.

Position

The color can have a specific coordinate inside the gradient. This is achieved through the Position property. In the following sample we will change the first color position from the initial position:

<BoxView>
    <grial:Effects.BackgroundGradient>
        <grial:LinearGradient Angle="135">
            <grial:GradientColor 
                Color="Blue"
                Position="0"
            />
            <grial:GradientColor 
                Color="Yellow"
            />
        </grial:LinearGradient>
    </grial:Effects.BackgroundGradient>
</BoxView>

…to a relative value. In this case it will be 50%:

<BoxView>
    <grial:Effects.BackgroundGradient>
        <grial:LinearGradient Angle="135">
            <grial:GradientColor 
                Color="Blue"
                Position="0.5"
            />
            <grial:GradientColor 
                Color="Yellow"
            />
        </grial:LinearGradient>
    </grial:Effects.BackgroundGradient>
</BoxView>

Let’s make it differently. Now we will move both color stops:

<BoxView>
    <grial:Effects.BackgroundGradient>
        <grial:LinearGradient Angle="135">
            <grial:GradientColor 
                Color="Blue"
                Position="0.25"
            />
            <grial:GradientColor 
                Color="Yellow"
                Position="0.75"
            />
        </grial:LinearGradient>
    </grial:Effects.BackgroundGradient>
</BoxView>

tip

Positions must increment from color to color and always be between 0 and 1. If color1.Position > color2.Position (while color1 comes before color2) then all positions are ignored and colors occupy the same area.

Opacity

The color stops can be translucid by themselves or if you are using an opaque color it can be turned into a translucid one through the Opacity property. This is very handy when you are working with themes or when you receive the colors as data using Bindings.

Let’s see a concrete example. We will turn a solid (opaque) red color:

<BoxView>
    <grial:Effects.BackgroundGradient>
        <grial:LinearGradient Angle="90">
            <grial:GradientColor 
                Color="Red"
            />
            <grial:GradientColor 
                Color="Black"
            />
        </grial:LinearGradient>
    </grial:Effects.BackgroundGradient>
</BoxView>

…into a translucid red:

<BoxView>
    <grial:Effects.BackgroundGradient>
        <grial:LinearGradient Angle="90">
            <grial:GradientColor 
                Color="Red"
                Opacity="0.5"
            />
            <grial:GradientColor 
                Color="Black"
            />
        </grial:LinearGradient>
    </grial:Effects.BackgroundGradient>
</BoxView>

Now let’s make it totally transparent:

<BoxView>
    <grial:Effects.BackgroundGradient>
        <grial:LinearGradient Angle="90">
            <grial:GradientColor 
                Color="Red"
                Opacity="0"
            />
            <grial:GradientColor 
                Color="Black"
            />
        </grial:LinearGradient>
    </grial:Effects.BackgroundGradient>
</BoxView>