diff --git a/docs/TOC.yml b/docs/TOC.yml index fb05cff46..36b7755eb 100644 --- a/docs/TOC.yml +++ b/docs/TOC.yml @@ -55,6 +55,12 @@ items: - name: Splash screen href: user-interface/images/splashscreen.md + - name: Layouts + items: + - name: HorizontalStackLayout + href: user-interface/layouts/horizontalstacklayout.md + - name: VerticalStackLayout + href: user-interface/layouts/verticalstacklayout.md - name: Shadows href: user-interface/shadow.md - name: Platform integration diff --git a/docs/user-interface/layouts/horizontalstacklayout.md b/docs/user-interface/layouts/horizontalstacklayout.md new file mode 100644 index 000000000..e6368beee --- /dev/null +++ b/docs/user-interface/layouts/horizontalstacklayout.md @@ -0,0 +1,161 @@ +--- +title: ".NET MAUI HorizontalStackLayout" +description: "Learn how the .NET MAUI HorizontalStackLayout organizes child views in a one-dimensional horizontal stack." +ms.date: 12/06/2021 +--- + +# HorizontalStackLayout + +A `HorizontalStackLayout` organizes child views in a one-dimensional horizontal stack, and is a more performant alternative to a `StackLayout`. In addition, a `HorizontalStackLayout` can be used as a parent layout that contains other child layouts. + +The `HorizontalStackLayout` defines the following properties: + +- `Spacing`, of type `double`, indicates the amount of space between each child view. The default value of this property is 0. + +This property is backed by a `BindableProperty` object, which means that it can be the target of data bindings and styled. + + + +The following XAML shows how to create a `HorizontalStackLayout` that contains different child views: + +```xaml + + + + + +``` + +This example creates a `HorizontalStackLayout` containing a `Rectangle` and a `Label` object. By default, there is no space between the child views: + +:::image type="content" source="media/horizontalstacklayout/basic.png" alt-text="HorizontalStackLayout displaying two views screenshot."::: + +> [!NOTE] +> The value of the `Margin` property represents the distance between an element and its adjacent elements. + +## Space between child views + +The spacing between child views in a `HorizontalStackLayout` can be changed by setting the `Spacing` property to a `double` value: + +```xaml + + + + + +``` + +This example creates a `HorizontalStackLayout` containing a `Rectangle` and a `Label` object, that have ten device-independent units of space between them: + +:::image type="content" source="media/horizontalstacklayout/spacing.png" alt-text="HorizontalStackLayout displaying two spaced views screenshot."::: + +> [!TIP] +> The `Spacing` property can be set to negative values to make child views overlap. + +## Position and size child views + +The size and position of child views within a `HorizontalStackLayout` depends upon the values of the child views' `HeightRequest` and `WidthRequest` properties, and the values of their `VerticalOptions` properties. In a `HorizontalStackLayout`, child views expand to fill the available height when their size isn't explicitly set. + +The `VerticalOptions` properties of a `HorizontalStackLayout`, and its child views, can be set to fields from the `LayoutOptions` struct, which encapsulates an *alignment* layout preference. This layout preference determines the position and size of a child view within its parent layout. + +The following XAML example sets alignment preferences on each child view in the `HorizontalStackLayout`: + +```xaml + + + + +``` + +In this example, alignment preferences are set on the `Label` objects to control their position within the `HorizontalStackLayout`. The `Start`, `Center`, `End`, and `Fill` fields are used to define the alignment of the `Label` objects within the parent `HorizontalStackLayout`: + +:::image type="content" source="media/horizontalstacklayout/alignment.png" alt-text="HorizontalStackLayout displaying aligned views screenshot."::: + +A `HorizontalStackLayout` only respects the alignment preferences on child views that are in the opposite direction to the orientation of the layout. Therefore, the `Label` child views within the `HorizontalStackLayout` set their `VerticalOptions` properties to one of the alignment fields: + +- `Start`, which positions the `Label` at the start of the `HorizontalStackLayout`. +- `Center`, which vertically centers the `Label` in the `HorizontalStackLayout`. +- `End`, which positions the `Label` at the end of the `HorizontalStackLayout`. +- `Fill`, which ensures that the `Label` fills the height of the `HorizontalStackLayout`. + + + +## Nest HorizontalStackLayout objects + +A `HorizontalStackLayout` can be used as a parent layout that contains other nested child layouts. + +The following XAML shows an example of nesting `VerticalStackLayout` objects in a `HorizontalStackLayout`: + +```xaml + + + + +``` + +In this example, the parent `HorizontalStackLayout` contains two nested `HorizontalStackLayout` objects: + +:::image type="content" source="media/horizontalstacklayout/nested.png" alt-text="HorizontalStackLayout displaying two nested HorizontalStackLayout objects screenshot."::: + +> [!IMPORTANT] +> The deeper you nest layout objects, the more the nested layouts will impact performance. diff --git a/docs/user-interface/layouts/media/horizontalstacklayout/alignment.png b/docs/user-interface/layouts/media/horizontalstacklayout/alignment.png new file mode 100644 index 000000000..ed06d8910 Binary files /dev/null and b/docs/user-interface/layouts/media/horizontalstacklayout/alignment.png differ diff --git a/docs/user-interface/layouts/media/horizontalstacklayout/basic.png b/docs/user-interface/layouts/media/horizontalstacklayout/basic.png new file mode 100644 index 000000000..4938260c8 Binary files /dev/null and b/docs/user-interface/layouts/media/horizontalstacklayout/basic.png differ diff --git a/docs/user-interface/layouts/media/horizontalstacklayout/nested.png b/docs/user-interface/layouts/media/horizontalstacklayout/nested.png new file mode 100644 index 000000000..5da77829c Binary files /dev/null and b/docs/user-interface/layouts/media/horizontalstacklayout/nested.png differ diff --git a/docs/user-interface/layouts/media/horizontalstacklayout/spacing.png b/docs/user-interface/layouts/media/horizontalstacklayout/spacing.png new file mode 100644 index 000000000..9bacfe725 Binary files /dev/null and b/docs/user-interface/layouts/media/horizontalstacklayout/spacing.png differ diff --git a/docs/user-interface/layouts/media/verticalstacklayout/alignment.png b/docs/user-interface/layouts/media/verticalstacklayout/alignment.png new file mode 100644 index 000000000..45a6c1dfb Binary files /dev/null and b/docs/user-interface/layouts/media/verticalstacklayout/alignment.png differ diff --git a/docs/user-interface/layouts/media/verticalstacklayout/basic.png b/docs/user-interface/layouts/media/verticalstacklayout/basic.png new file mode 100644 index 000000000..fb81b8729 Binary files /dev/null and b/docs/user-interface/layouts/media/verticalstacklayout/basic.png differ diff --git a/docs/user-interface/layouts/media/verticalstacklayout/nested.png b/docs/user-interface/layouts/media/verticalstacklayout/nested.png new file mode 100644 index 000000000..d6bc16f62 Binary files /dev/null and b/docs/user-interface/layouts/media/verticalstacklayout/nested.png differ diff --git a/docs/user-interface/layouts/media/verticalstacklayout/spacing.png b/docs/user-interface/layouts/media/verticalstacklayout/spacing.png new file mode 100644 index 000000000..f9db24c57 Binary files /dev/null and b/docs/user-interface/layouts/media/verticalstacklayout/spacing.png differ diff --git a/docs/user-interface/layouts/verticalstacklayout.md b/docs/user-interface/layouts/verticalstacklayout.md new file mode 100644 index 000000000..7befbc280 --- /dev/null +++ b/docs/user-interface/layouts/verticalstacklayout.md @@ -0,0 +1,201 @@ +--- +title: "VerticalStackLayout" +description: "Learn how the .NET MAUI VerticalStackLayout organizes child views in a one-dimensional vertical stack." +ms.date: 12/06/2021 +--- + +# VerticalStackLayout + +A `VerticalStackLayout` organizes child views in a one-dimensional vertical stack, and is a more performant alternative to a `StackLayout`. In addition, a `VerticalStackLayout` can be used as a parent layout that contains other child layouts. + +The `VerticalStackLayout` defines the following properties: + +- `Spacing`, of type `double`, indicates the amount of space between each child view. The default value of this property is 0. + +This property is backed by a `BindableProperty` object, which means that it can be the target of data bindings and styled. + + + +The following XAML shows how to create a `VerticalStackLayout` that contains different child views: + +```xaml + + + + +``` + +This example creates a `VerticalStackLayout` containing `Label` and `Rectangle` objects. By default, there is no space between the child views: + +:::image type="content" source="media/verticalstacklayout/basic.png" alt-text="VerticalStackLayout displaying different child views screenshot."::: + +> [!NOTE] +> The value of the `Margin` property represents the distance between an element and its adjacent elements. + +## Space between child views + +The spacing between child views in a `VerticalStackLayout` can be changed by setting the `Spacing` property to a `double` value: + +```xaml + + + + +``` + +This example creates a `VerticalStackLayout` containing `Label` and `Rectangle` objects that have ten device-independent units of space between the child views: + +:::image type="content" source="media/verticalstacklayout/spacing.png" alt-text="VerticalStackLayout displaying different child views with spacing screenshot."::: + +> [!TIP] +> The `Spacing` property can be set to negative values to make child views overlap. + +## Position and size child views + +The size and position of child views within a `VerticalStackLayout` depends upon the values of the child views' `HeightRequest` and `WidthRequest` properties, and the values of their `HorizontalOptions` properties. In a `VerticalStackLayout`, child views expand to fill the available width when their size isn't explicitly set. + +The `HorizontalOptions` properties of a `VerticalStackLayout`, and its child views, can be set to fields from the `LayoutOptions` struct, which encapsulates an *alignment* layout preference. This layout preference determines the position and size of a child view within its parent layout. + +> [!TIP] +> Don't set the `HorizontalOptions` property of a `VerticalStackLayout` unless you need to. The default value of `LayoutOptions.Fill` allows for the best layout optimization. Changing this property has a cost and consumes memory, even when setting it back to its default value. + +The following XAML example sets alignment preferences on each child view in the `VerticalStackLayout`: + +```xaml + + + + +``` + +In this example, alignment preferences are set on the `Label` objects to control their position within the `VerticalStackLayout`. The `Start`, `Center`, `End`, and `Fill` fields are used to define the alignment of the `Label` objects within the parent `VerticalStackLayout`: + +:::image type="content" source="media/verticalstacklayout/alignment.png" alt-text="VerticalStackLayout displaying aligned child views screenshot."::: + +A `VerticalStackLayout` only respects the alignment preferences on child views that are in the opposite direction to the orientation of the layout. Therefore, the `Label` child views within the `VerticalStackLayout` set their `HorizontalOptions` properties to one of the alignment fields: + +- `Start`, which positions the `Label` on the left-hand side of the `VerticalStackLayout`. +- `Center`, which centers the `Label` in the `VerticalStackLayout`. +- `End`, which positions the `Label` on the right-hand side of the `VerticalStackLayout`. +- `Fill`, which ensures that the `Label` fills the width of the `VerticalStackLayout`. + + + +## Nest VerticalStackLayout objects + +A `VerticalStackLayout` can be used as a parent layout that contains other nested child layouts. + +The following XAML shows an example of nesting `HorizontalStackLayout` objects in a `VerticalStackLayout`: + +```xaml + + + + +``` + +In this example, the parent `VerticalStackLayout` contains nested `HorizontalStackLayout` objects inside `Frame` objects: + +:::image type="content" source="media/verticalstacklayout/nested.png" alt-text="VerticalStackLayout displaying nested HorizontalStackLayout objects screenshot."::: + +> [!IMPORTANT] +> The deeper you nest layout objects, the more the nested layouts will impact performance.