Brushes (#256)

* Brushes.

* Switch off border.

* Removed trailing spaces.

docs/TOC.yml

@@ -23,6 +23,20 @@
           href: fundamentals/single-project.md
     - name: User interface
       items:
+        - name: Brushes
+          items:
+            - name: Overview
+              href: user-interface/brushes/index.md
+            - name: Solid colors
+              href: user-interface/brushes/solidcolor.md
+            - name: Gradients
+              items:
+                - name: Overview
+                  href: user-interface/brushes/gradient.md
+                - name: Linear gradients
+                  href: user-interface/brushes/lineargradient.md
+                - name: Radial gradients
+                  href: user-interface/brushes/radialgradient.md                                    
         - name: Controls
           items:
             - name: BlazorWebView
@@ -62,7 +76,7 @@
             - name: FlexLayout
               href: user-interface/layouts/flexlayout.md
             - name: GridLayout
-              href: user-interface/layouts/gridlayout.md              
+              href: user-interface/layouts/gridlayout.md
             - name: HorizontalStackLayout
               href: user-interface/layouts/horizontalstacklayout.md
             - name: StackLayout

docs/index.yml

@@ -48,6 +48,8 @@ landingContent:
             url: user-interface/controls/blazorwebview.md
           - text: Border
             url: user-interface/controls/border.md
+          - text: Brushes
+            url: user-interface/brushes/index.md
           - text: Customize controls
             url: user-interface/handlers/customize.md
           - text: GraphicsView

docs/user-interface/brushes/gradient.md

@@ -0,0 +1,57 @@
+---
+title: "Gradients"
+description: "The .NET MAUI GradientBrush class is an abstract class that describes a gradient, composed of gradient stops."
+ms.date: 01/11/2022
+---
+
+# Gradients
+
+The .NET Multi-platform App UI (.NET MAUI) `GradientBrush` class derives from the `Brush` class, and is an abstract class that describes a gradient, which is composed of gradient stops. A gradient brush paints an area with multiple colors that blend into each other along an axis.
+
+[!INCLUDE [docs under construction](~/includes/preview-note.md)]
+
+Classes that derive from `GradientBrush` describe different ways of interpreting gradient stops, and .NET MAUI provides the following gradient brushes:
+
+- `LinearGradientBrush`, which paints an area with a linear gradient. For more information, see [Linear gradient brushes](lineargradient.md).
+- `RadialGradientBrush`, which paints an area with a radial gradient. For more information, see [Radial gradient brushes](radialgradient.md).
+
+The `GradientBrush` class defines the `GradientStops` property, of type `GradientStopsCollection`, which represents the brush's gradient stops, each of which specifies a color and an offset along the brush's gradient axis. A `GradientStopsCollection` is an `ObservableCollection` of `GradientStop` objects. The `GradientStops` property is backed by a `BindableProperty` object, which means that it can be the target of data bindings, and styled.
+
+> [!NOTE]
+> The `GradientStops` property is the `ContentProperty` of the `GradientBrush` class, and so does not need to be explicitly set from XAML.
+
+## Gradient stops
+
+Gradient stops are the building blocks of a gradient brush, and specify the colors in the gradient and their location along the gradient axis. Gradient stops are specified using `GradientStop` objects.
+
+The `GradientStop` class defines the following properties:
+
+- `Color`, of type `Color`, which represents the color of the gradient stop.
+- `Offset`, of type `float`, which represents the location of the gradient stop within the gradient vector. The default value of this property is 0, and valid values are in the range 0.0-1.0. The closer this value is to 0, the closer the color is to the start of the gradient. Similarly, the closer this value is to 1, the closer the color is to the end of the gradient.
+
+These properties are backed by `BindableProperty` objects, which means that they can be targets of data bindings, and styled.
+
+> [!IMPORTANT]
+> The coordinate system used by gradients is relative to a bounding box for the output area. 0 indicates 0 percent of the bounding box, and 1 indicates 100 percent of the bounding box. Therefore, (0.5,0.5) describes a point in the middle of the bounding box, and (1,1) describes a point at the bottom right of the bounding box.
+
+The following XAML example creates a diagonal `LinearGradientBrush` with four colors:
+
+```xaml
+<LinearGradientBrush StartPoint="0,0"
+                     EndPoint="1,1">
+    <GradientStop Color="Yellow"
+                  Offset="0.0" />
+    <GradientStop Color="Red"
+                  Offset="0.25" />
+    <GradientStop Color="Blue"
+                  Offset="0.75" />             
+    <GradientStop Color="LimeGreen"
+                  Offset="1.0" />
+</LinearGradientBrush>                                                       
+```
+
+The color of each point between gradient stops is interpolated as a combination of the color specified by the two bounding gradient stops. The following diagram shows the gradient stops from the previous example:
+
+:::image type="content" source="media/gradient/gradient-stops.png" alt-text="Screenshot of a Frame painted with a diagonal LinearGradientBrush." border="false":::
+
+In this diagram, the circles mark the position of gradient stops, and the dashed line shows the gradient axis. The first gradient stop specifies the color yellow at an offset of 0.0. The second gradient stop specifies the color red at an offset of 0.25. The points between these two gradient stops gradually change from yellow to red as you move from left to right along the gradient axis. The third gradient stop specifies the color blue at an offset of 0.75. The points between the second and third gradient stops gradually change from red to blue. The fourth gradient stop specifies the color lime green at at offset of 1.0. The points between the third and fourth gradient stops gradually change from blue to lime green.

docs/user-interface/brushes/index.md

@@ -0,0 +1,24 @@
+---
+title: "Brushes"
+description: "The .NET MAUI Brush class is an abstract class that paints an area with its output."
+ms.date: 01/11/2022
+---
+
+# Brushes
+
+A .NET Multi-platform App UI (.NET MAUI) brush enables you to paint an area, such as the background of a control, using different approaches.
+
+[!INCLUDE [docs under construction](~/includes/preview-note.md)]
+
+The `Brush` class is an abstract class that paints an area with its output. Classes that derive from `Brush` describe different ways of painting an area. The following list describes the different brush types available in .NET MAUI:
+
+- `SolidColorBrush`, which paints an area with a solid color. For more information, see [Solid color brushes](solidcolor.md).
+- `LinearGradientBrush`, which paints an area with a linear gradient. For more information, see [Linear gradient brushes](lineargradient.md).
+- `RadialGradientBrush`, which paints an area with a radial gradient. For more information, see [Radial gradient brushes](radialgradient.md).
+
+Instances of these brush types can be assigned to the `Stroke` and `Fill` properties of a `Shape`, the `Stoke` property of a `Border`, the `Brush` property of a `Shadow`, and the `Background` property of a `VisualElement`.
+
+> [!NOTE]
+> The `VisualElement.Background` property enables brushes to be used as the background in any control.
+
+The `Brush` class also has an `IsNullOrEmpty` method that returns a `bool` that represents whether the brush is defined or not.

docs/user-interface/brushes/lineargradient.md

@@ -0,0 +1,118 @@
+---
+title: "Linear gradient brushes"
+description: "The .NET MAUI LinearGradientBrush class paints an area with a linear gradient."
+ms.date: 01/11/2022
+---
+
+# Linear gradient brushes
+
+The .NET Multi-platform App UI (.NET MAUI)  `LinearGradientBrush` class derives from the `GradientBrush` class, and paints an area with a linear gradient, which blends two or more colors along a line known as the gradient axis. `GradientStop` objects are used to specify the colors in the gradient and their positions. For more information about `GradientStop` objects, see [Gradients](gradient.md).
+
+[!INCLUDE [docs under construction](~/includes/preview-note.md)]
+
+The `LinearGradientBrush` class defines the following properties:
+
+- `StartPoint`, of type `Point`, which represents the starting two-dimensional coordinates of the linear gradient. The default value of this property is (0,0).
+- `EndPoint`, of type `Point`, which represents the ending two-dimensional coordinates of the linear gradient. The default value of this property is (1,1).
+
+These properties are backed by `BindableProperty` objects, which means that they can be targets of data bindings, and styled.
+
+The `LinearGradientBrush` class also as an `IsEmpty` method that returns a `bool` that represents whether the brush has been assigned any `GradientStop` objects.
+
+> [!NOTE]
+> Linear gradients can also be created with the `linear-gradient()` CSS function.
+
+## Create a LinearGradientBrush
+
+A linear gradient brush's gradient stops are positioned along the gradient axis. The orientation and size of the gradient axis can be changed using the brush's `StartPoint` and `EndPoint` properties. By manipulating these properties, you can create horizontal, vertical, and diagonal gradients, reverse the gradient direction, condense the gradient spread, and more.
+
+The `StartPoint` and `EndPoint` properties are relative to the area being painted. (0,0) represents the top-left corner of the area being painted, and (1,1) represents the bottom-right corner of the area being painted. The following diagram shows the gradient axis for a diagonal linear gradient brush:
+
+:::image type="content" source="media/lineargradient/gradient-axis.png" alt-text="Frame with a diagonal gradient axis." border="false":::
+
+In this diagram, the dashed line shows the gradient axis, which highlights the interpolation path of the gradient from the start point to the end point.
+
+### Create a horizontal linear gradient
+
+To create a horizontal linear gradient, create a `LinearGradientBrush` object and set its `StartPoint` to (0,0) and its `EndPoint` to (1,0). Then, add two or more `GradientStop` objects to the `LinearGradientBrush.GradientStops` collection, that specify the colors in the gradient and their positions.
+
+The following XAML example shows a horizontal `LinearGradientBrush` that's set as the `Background` of a `Frame`:
+
+```xaml
+<Frame BorderColor="LightGray"
+       HasShadow="True"
+       CornerRadius="12"
+       HeightRequest="120"
+       WidthRequest="120">
+    <Frame.Background>
+        <!-- StartPoint defaults to (0,0) -->
+        <LinearGradientBrush EndPoint="1,0">
+            <GradientStop Color="Yellow"
+                          Offset="0.1" />
+            <GradientStop Color="Green"
+                          Offset="1.0" />
+        </LinearGradientBrush>
+    </Frame.Background>
+</Frame>  
+```
+
+In this example, the background of the `Frame` is painted with a `LinearGradientBrush` that interpolates from yellow to green horizontally:
+
+:::image type="content" source="media/lineargradient/horizontal.png" alt-text="Screenshot of a Frame painted with a horizontal LinearGradientBrush.":::
+
+### Create a vertical linear gradient
+
+To create a vertical linear gradient, create a `LinearGradientBrush` object and set its `StartPoint` to (0,0) and its `EndPoint` to (0,1). Then, add two or more `GradientStop` objects to the `LinearGradientBrush.GradientStops` collection, that specify the colors in the gradient and their positions.
+
+The following XAML example shows a vertical `LinearGradientBrush` that's set as the `Background` of a `Frame`:
+
+```xaml
+<Frame BorderColor="LightGray"
+       HasShadow="True"
+       CornerRadius="12"
+       HeightRequest="120"
+       WidthRequest="120">
+    <Frame.Background>
+        <!-- StartPoint defaults to (0,0) -->    
+        <LinearGradientBrush EndPoint="0,1">
+            <GradientStop Color="Yellow"
+                          Offset="0.1" />
+            <GradientStop Color="Green"
+                          Offset="1.0" />
+        </LinearGradientBrush>
+    </Frame.Background>
+</Frame>
+```
+
+In this example, the background of the `Frame` is painted with a `LinearGradientBrush` that interpolates from yellow to green vertically:
+
+:::image type="content" source="media/lineargradient/vertical.png" alt-text="Screenshot of a Frame painted with a vertical LinearGradientBrush.":::
+
+### Create a diagonal linear gradient
+
+To create a diagonal linear gradient, create a `LinearGradientBrush` object and set its `StartPoint` to (0,0) and its `EndPoint` to (1,1). Then, add two or more `GradientStop` objects to the `LinearGradientBrush.GradientStops` collection, that specify the colors in the gradient and their positions.
+
+The following XAML example shows a diagonal `LinearGradientBrush` that's set as the `Background` of a `Frame`:
+
+```xaml
+<Frame BorderColor="LightGray"
+       HasShadow="True"
+       CornerRadius="12"
+       HeightRequest="120"
+       WidthRequest="120">
+    <Frame.Background>
+        <!-- StartPoint defaults to (0,0)      
+             Endpoint defaults to (1,1) -->
+        <LinearGradientBrush>
+            <GradientStop Color="Yellow"
+                          Offset="0.1" />
+            <GradientStop Color="Green"
+                          Offset="1.0" />
+        </LinearGradientBrush>
+    </Frame.Background>
+</Frame>
+```
+
+In this example, the background of the `Frame` is painted with a `LinearGradientBrush` that interpolates from yellow to green diagonally:
+
+:::image type="content" source="media/lineargradient/diagonal.png" alt-text="Screenshot of a Frame painted with a diagonal LinearGradientBrush.":::

docs/user-interface/brushes/radialgradient.md

@@ -0,0 +1,86 @@
+---
+title: "Radial gradient brushes"
+description: "The .NET MAUI RadialGradientBrush class paints an area with a radial gradient."
+ms.date: 01/11/2022
+---
+
+# Radial gradient brushes
+
+The .NET Multi-platform App UI (.NET MAUI) `RadialGradientBrush` class derives from the `GradientBrush` class, and paints an area with a radial gradient, which blends two or more colors across a circle. `GradientStop` objects are used to specify the colors in the gradient and their positions. For more information about `GradientStop` objects, see [Gradients](gradient.md).
+
+[!INCLUDE [docs under construction](~/includes/preview-note.md)]
+
+The `RadialGradientBrush` class defines the following properties:
+
+- `Center`, of type `Point`, which represents the center point of the circle for the radial gradient. The default value of this property is (0.5,0.5).
+- `Radius`, of type `double`, which represents the radius of the circle for the radial gradient. The default value of this property is 0.5.
+
+These properties are backed by `BindableProperty` objects, which means that they can be targets of data bindings, and styled.
+
+The `RadialGradientBrush` class also has an `IsEmpty` method that returns a `bool` that represents whether the brush has been assigned any `GradientStop` objects.
+
+> [!NOTE]
+> Radial gradients can also be created with the `radial-gradient()` CSS function.
+
+## Create a RadialGradientBrush
+
+A radial gradient brush's gradient stops are positioned along a gradient axis defined by a circle. The gradient axis radiates from the center of the circle to its circumference. The position and size of the circle can be changed using the brush's `Center` and `Radius` properties. The circle defines the end point of the gradient. Therefore, a gradient stop at 1.0 defines the color at the circle's circumference. A gradient stop at 0.0 defines the color at the center of the circle.
+
+To create a radial gradient, create a `RadialGradientBrush` object and set its `Center` and `Radius` properties. Then, add two or more `GradientStop` objects to the `RadialGradientBrush.GradientStops` collection, that specify the colors in the gradient and their positions.
+
+The following XAML example shows a `RadialGradientBrush` that's set as the `Background` of a `Frame`:
+
+```xaml
+<Frame BorderColor="LightGray"
+       HasShadow="True"
+       CornerRadius="12"
+       HeightRequest="120"
+       WidthRequest="120">
+    <Frame.Background>
+        <!-- Center defaults to (0.5,0.5)
+             Radius defaults to (0.5) -->
+        <RadialGradientBrush>
+            <GradientStop Color="Red"
+                          Offset="0.1" />
+            <GradientStop Color="DarkBlue"
+                          Offset="1.0" />
+        </RadialGradientBrush>
+    </Frame.Background>
+</Frame>
+```
+
+In this example, the background of the `Frame` is painted with a `RadialGradientBrush` that interpolates from red to dark blue. The center of the radial gradient is positioned in the center of the `Frame`:
+
+:::image type="content" source="media/radialgradient/center.png" alt-text="Screenshot of a Frame painted with a centered RadialGradientBrush.":::
+
+The following XAML example moves the center of the radial gradient to the top-left corner of the `Frame`:
+
+```xaml
+<!-- Radius defaults to (0.5) -->
+<RadialGradientBrush Center="0.0,0.0">
+    <GradientStop Color="Red"
+                  Offset="0.1" />
+    <GradientStop Color="DarkBlue"
+                  Offset="1.0" />
+</RadialGradientBrush>
+```
+
+In this example, the background of the `Frame` is painted with a `RadialGradientBrush` that interpolates from red to dark blue. The center of the radial gradient is positioned in the top-left of the `Frame`:
+
+:::image type="content" source="media/radialgradient/top-left.png" alt-text="Screenshot of a Frame painted with a top-left RadialGradientBrush.":::
+
+The following XAML example moves the center of the radial gradient to the bottom-right corner of the `Frame`:
+
+```xaml
+<!-- Radius defaults to (0.5) -->
+<RadialGradientBrush Center="1.0,1.0">
+    <GradientStop Color="Red"
+                  Offset="0.1" />
+    <GradientStop Color="DarkBlue"
+                  Offset="1.0" />
+</RadialGradientBrush>            
+```
+
+In this example, the background of the `Frame` is painted with a `RadialGradientBrush` that interpolates from red to dark blue. The center of the radial gradient is positioned in the bottom-right of the `Frame`:
+
+:::image type="content" source="media/radialgradient/bottom-right.png" alt-text="Screenshot of a Frame painted with a bottom-right RadialGradientBrush.":::

docs/user-interface/brushes/solidcolor.md

@@ -0,0 +1,115 @@
+---
+title: "Solid color brushes"
+description: "The .NET MAUI SolidColorBrush class paints an area with a solid color."
+ms.date: 01/11/2022
+---
+
+# Solid color brushes
+
+The .NET Multi-platform App UI (.NET MAUI) `SolidColorBrush` class derives from the `Brush` class, and is used to paint an area with a solid color. There are a variety of approaches to specifying the color of a `SolidColorBrush`. For example, you can specify its color with a `Color` value or by using one of the predefined `SolidColorBrush` objects provided by the `Brush` class.
+
+[!INCLUDE [docs under construction](~/includes/preview-note.md)]
+
+The `SolidColorBrush` class defines the `Color` property, of type `Color`, which represents the color of the brush. This property is backed by a `BindableProperty` object, which means that it can be the target of data bindings, and styled.
+
+The `SolidColorBrush` class also has an `IsEmpty` method that returns a `bool` that represents whether the brush has been assigned a color.
+
+## Create a SolidColorBrush
+
+There are three main techniques for creating a `SolidColorBrush`. You can create a `SolidColorBrush` from a `Color`, use a predefined brush, or create a `SolidColorBrush` using hexadecimal notation.
+
+### Use a predefined Color
+
+.NET MAUI includes a type converter that creates a `SolidColorBrush` from a `Color` value. In XAML, this enables a `SolidColorBrush` to be created from a predefined `Color` value:
+
+```xaml
+<Frame Background="DarkBlue"
+       BorderColor="LightGray"
+       HasShadow="True"
+       CornerRadius="12"
+       HeightRequest="120"
+       WidthRequest="120" />
+```
+
+In this example, the background of the `Frame` is painted with a dark blue `SolidColorBrush`:
+
+:::image type="content" source="media/solidcolor/predefined-color.png" alt-text="Screenshot of a Frame painted with a predefined color.":::
+
+Alternatively, the `Color` value can be specified using property tag syntax:
+
+```xaml
+<Frame BorderColor="LightGray"
+       HasShadow="True"
+       CornerRadius="12"
+       HeightRequest="120"
+       WidthRequest="120">
+       <Frame.Background>
+           <SolidColorBrush Color="DarkBlue" />
+       </Frame.Background>
+</Frame>
+```
+
+In this example, the background of the `Frame` is painted with a `SolidColorBrush` whose color is specified by setting the `SolidColorBrush.Color` property.
+
+### Use a predefined Brush
+
+The `Brush` class defines a set of commonly used `SolidColorBrush` objects. The following example uses one of these predefined `SolidColorBrush` objects:
+
+```xaml
+<Frame Background="{x:Static Brush.Indigo}"
+       BorderColor="LightGray"
+       HasShadow="True"
+       CornerRadius="12"
+       HeightRequest="120"
+       WidthRequest="120" />       
+```
+
+The equivalent C# code is:
+
+```csharp
+Frame frame = new Frame
+{
+    Background = Brush.Indigo,
+    BorderColor = Color.LightGray,
+    // ...
+};
+```
+
+In this example, the background of the `Frame` is painted with an indigo `SolidColorBrush`:
+
+:::image type="content" source="media/solidcolor/predefined-brush.png" alt-text="Screenshot of a Frame painted with a predefined SolidColorBrush.":::
+
+For a list of predefined `SolidColorBrush` objects provided by the `Brush` class, see [Solid color brushes](#solid-color-brushes).
+
+### Use hexadecimal notation
+
+`SolidColorBrush` objects can also be created using hexadecimal notation. With this approach, a color is specified in terms of the amount of red, green, and blue to combine into a single color. The main format for specifying a color using hexadecimal notation is `#rrggbb`, where:
+
+- `rr` is a two-digit hexadecimal number specifying the relative amount of red.
+- `gg` is a two-digit hexadecimal number specifying the relative amount of green.
+- `bb` is a two-digit hexadecimal number specifying the relative amount of blue.
+
+In addition, a color can be specified as `#aarrggbb` where `aa` specifies the alpha value, or transparency, of the color. This approach enables you to create colors that are partially transparent.
+
+The following example sets the color value of a `SolidColorBrush` using hexadecimal notation:
+
+```xaml
+<Frame Background="#FF9988"
+       BorderColor="LightGray"
+       HasShadow="True"
+       CornerRadius="12"
+       HeightRequest="120"
+       WidthRequest="120" />
+```
+
+In this example, the background of the `Frame` is painted with a salmon-colored `SolidColorBrush`:
+
+:::image type="content" source="media/solidcolor/hex.png" alt-text="Screenshot of a Frame painted with a SolidColorBrush created with hexadecimal notation.":::
+
+For other ways of describing color, see [Colors](~/user-interface/graphics/colors.md).
+
+## Solid color brushes
+
+For convenience, the `Brush` class provides a set of commonly used `SolidColorBrush` objects, such as `AliceBlue` and `YellowGreen`. The following image shows the color of each predefined brush, its name, and its hexadecimal value:
+
+:::image type="content" source="media/solidcolor/solidcolorbrushes.png" alt-text="Color table including a color swatch, color name, and hexadecimal value." lightbox="media/solidcolor/solidcolorbrushes-large.png" border="false":::