Xamarin.Forms StackLayout Tutorial

To complete this tutorial you should have Visual Studio 2019 (latest release), with the Mobile development with .NET workload installed. In addition, you will require a paired Mac to build the tutorial application on iOS. For information about installing the Xamarin platform, see Installing Xamarin. For information about connecting Visual Studio 2019 to a Mac build host, see Pair to Mac for Xamarin.iOS development.

1. Launch Visual Studio, and create a new blank Xamarin.Forms app named StackLayoutTutorial.

   Important

   The C# and XAML snippets in this tutorial requires that the solution is named StackLayoutTutorial. Using a different name will result in build errors when you copy code from this tutorial into the solution.

   For more information about the .NET Standard library that gets created, see Anatomy of a Xamarin.Forms application in the Xamarin.Forms Quickstart Deep Dive.

2. In Solution Explorer, in the StackLayoutTutorial project, double-click MainPage.xaml to open it. Then, in MainPage.xaml, remove all of the template code and replace it with the following code:

   <?xml version="1.0" encoding="utf-8"?>
   <ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
                xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
                x:Class="StackLayoutTutorial.MainPage">
       <StackLayout Margin="20,35,20,25">
           <Label Text="The StackLayout has its Margin property set, to control the rendering position of the StackLayout." />
           <Label Text="The Padding property can be set to specify the distance between the StackLayout and its children." />
           <Label Text="The Spacing property can be set to specify the distance between views in the StackLayout." />
       </StackLayout>
   </ContentPage>
   

   This code declaratively defines the user interface for the page, which consists of three Label instances in a StackLayout. The StackLayout positions its child views (the Label instances) in a single line, which is oriented vertically by default. In addition, the Margin property indicates the rendering position of the StackLayout within the ContentPage.

   Note

   In addition to the Margin property, Padding and Spacing properties can also be set on a StackLayout. The Padding property value specifies the distance between views in the StackLayout, and the Spacing property value specifies the amount of space between each child element in the StackLayout. For more information, see Margin and Padding.

3. In the Visual Studio toolbar, press the Start button (the triangular button that resembles a Play button) to launch the application inside your chosen remote iOS simulator or Android emulator:

   

   For more information about the StackLayout, see Xamarin.Forms StackLayout.

To complete this tutorial you should have Visual Studio for Mac (latest release), with iOS and Android platform support installed. In addition, you will also require Xcode (latest release). For more information about installing the Xamarin platform, see Installing Xamarin.

1. Launch Visual Studio for Mac, and create a new blank Xamarin.Forms app named StackLayoutTutorial.

   Important

   The C# and XAML snippets in this tutorial requires that the solution is named StackLayoutTutorial. Using a different name will result in build errors when you copy code from this tutorial into the solution.

   For more information about the .NET Standard library that gets created, see Anatomy of a Xamarin.Forms application in the Xamarin.Forms Quickstart Deep Dive.

2. In Solution Pad, in the StackLayoutTutorial project, double-click MainPage.xaml to open it. Then, in MainPage.xaml, remove all of the template code and replace it with the following code:

   <?xml version="1.0" encoding="utf-8"?>
   <ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
                xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
                x:Class="StackLayoutTutorial.MainPage">
       <StackLayout Margin="20,35,20,25">
           <Label Text="The StackLayout has its Margin property set, to control the rendering position of the StackLayout." />
           <Label Text="The Padding property can be set to specify the distance between the StackLayout and its children." />
           <Label Text="The Spacing property can be set to specify the distance between views in the StackLayout." />
       </StackLayout>
   </ContentPage>
   

   This code declaratively defines the user interface for the page, which consists of three Label instances in a StackLayout. The StackLayout positions its child views (the Label instances) in a single line, which is oriented vertically by default. In addition, the Margin property indicates the rendering position of the StackLayout within the ContentPage.

   Note

   In addition to the Margin property, Padding and Spacing properties can also be set on a StackLayout. The Padding property value specifies the distance between views in the StackLayout, and the Spacing property value specifies the amount of space between each child element in the StackLayout. For more information, see Margin and Padding.

3. In the Visual Studio for Mac toolbar, press the Start button (the triangular button that resembles a Play button) to launch the application inside your chosen iOS simulator or Android emulator:

   

   For more information about the StackLayout, see Xamarin.Forms StackLayout.

1. In MainPage.xaml, modify the StackLayout declaration so it aligns its children horizontally, instead of vertically:

   <StackLayout Margin="20,35,20,25"
                Orientation="Horizontal">
       <Label Text="The StackLayout has its Margin property set, to control the rendering position of the StackLayout." />
       <Label Text="The Padding property can be set to specify the distance between the StackLayout and its children." />
       <Label Text="The Spacing property can be set to specify the distance between views in the StackLayout." />
   </StackLayout>
   

   This code sets the Orientation property to Horizontal.

2. If the application is still running, save the changes to the file and the application user interface will automatically be updated in your simulator or emulator. Otherwise, in the Visual Studio toolbar, press the Start button (the triangular button that resembles a Play button) to launch the application inside your chosen remote iOS simulator or Android emulator:

   

   Note that the Label instances within the StackLayout are now aligned horizontally, instead of vertically.

1. In MainPage.xaml, modify the StackLayout declaration so it aligns its children horizontally, instead of vertically:

   <StackLayout Margin="20,35,20,25"
                Orientation="Horizontal">
       <Label Text="The StackLayout has its Margin property set, to control the rendering position of the StackLayout." />
       <Label Text="The Padding property can be set to specify the distance between the StackLayout and its children." />
       <Label Text="The Spacing property can be set to specify the distance between views in the StackLayout." />
   </StackLayout>
   

   This code sets the Orientation property to Horizontal.

2. If the application is still running, save the changes to the file and the application user interface will automatically be updated in your simulator or emulator. Otherwise, in the Visual Studio for Mac toolbar, press the Start button (the triangular button that resembles a Play button) to launch the application inside your chosen iOS simulator or Android emulator:

   

   Note that the Label instances within the StackLayout are now aligned horizontally, instead of vertically.

1. In MainPage.xaml, modify the StackLayout declaration to set alignment and expansion options for each Label:

   <StackLayout Margin="20,35,20,25">
       <Label Text="Start"
              HorizontalOptions="Start"
              BackgroundColor="Gray" />
       <Label Text="Center"
              HorizontalOptions="Center"
              BackgroundColor="Gray" />
       <Label Text="End"
              HorizontalOptions="End"
              BackgroundColor="Gray" />
       <Label Text="Fill"
              HorizontalOptions="Fill"
              BackgroundColor="Gray" />
       <Label Text="StartAndExpand"
              VerticalOptions="StartAndExpand"
              BackgroundColor="Gray" />
       <Label Text="CenterAndExpand"
              VerticalOptions="CenterAndExpand"
              BackgroundColor="Gray" />
       <Label Text="EndAndExpand"
              VerticalOptions="EndAndExpand"
              BackgroundColor="Gray" />
       <Label Text="FillAndExpand"
              VerticalOptions="FillAndExpand"
              BackgroundColor="Gray" />
   </StackLayout>
   

   This code sets alignment preferences on the first four Label instances, and expansion preferences on the final four Label instances. The Start, Center, End, and Fill fields are used to define the alignment of the Label instances within the parent StackLayout. The StartAndExpand, CenterAndExpand, EndAndExpand, and FillAndExpand fields are used to define the alignment preference, and whether the view will occupy more space if available within the parent StackLayout.

   Note

   The default value of a view's HorizontalOptions and VerticalOptions properties is Fill.

2. If the application is still running, save the changes to the file and the application user interface will automatically be updated in your simulator or emulator. Otherwise, in the Visual Studio toolbar, press the Start button (the triangular button that resembles a Play button) to launch the application inside your chosen remote iOS simulator or Android emulator:

   

   A StackLayout only respects the alignment preferences on child views that are in the opposite direction to the StackLayout orientation. Therefore, the Label child views within the vertically oriented StackLayout set their HorizontalOptions properties to one of the alignment fields:

   • Start, which positions the Label on the left hand side of the StackLayout.
   • Center, which centers the Label in the StackLayout.
   • End, which positions the Label on the right hand side of the StackLayout.
   • Fill, which ensures that the Label fills the width of the StackLayout.

   A StackLayout can only expand child views in the direction of its orientation. Therefore, the vertically oriented StackLayout can expand Label child views that set their VerticalOptions properties to one of the expansion fields. This means that, for vertical alignment, each Label occupies the same amount of space within the StackLayout. However, only the final Label, which sets its VerticalOptions property to FillAndExpand has a different size.

   Important

   When all the space in a StackLayout is used, expansion preferences have no effect.

   In Visual Studio, stop the application.

   For more information about alignment and expansion, see Layout Options in Xamarin.Forms.

1. In MainPage.xaml, modify the StackLayout declaration to set alignment and expansion options for each Label:

   <StackLayout Margin="20,35,20,25">
       <Label Text="Start"
              HorizontalOptions="Start"
              BackgroundColor="Gray" />
       <Label Text="Center"
              HorizontalOptions="Center"
              BackgroundColor="Gray" />
       <Label Text="End"
              HorizontalOptions="End"
              BackgroundColor="Gray" />
       <Label Text="Fill"
              HorizontalOptions="Fill"
              BackgroundColor="Gray" />
       <Label Text="StartAndExpand"
              VerticalOptions="StartAndExpand"
              BackgroundColor="Gray" />
       <Label Text="CenterAndExpand"
              VerticalOptions="CenterAndExpand"
              BackgroundColor="Gray" />
       <Label Text="EndAndExpand"
              VerticalOptions="EndAndExpand"
              BackgroundColor="Gray" />
       <Label Text="FillAndExpand"
              VerticalOptions="FillAndExpand"
              BackgroundColor="Gray" />
   </StackLayout>
   

   This code sets alignment preferences on the first four Label instances, and expansion preferences on the final four Label instances. The Start, Center, End, and Fill fields are used to define the alignment of the Label instances within the parent StackLayout. The StartAndExpand, CenterAndExpand, EndAndExpand, and FillAndExpand fields are used to define the alignment preference, and whether the view will occupy more space if available within the parent StackLayout.

   Note

   The default value of a view's HorizontalOptions and VerticalOptions properties is Fill.

2. If the application is still running, save the changes to the file and the application user interface will automatically be updated in your simulator or emulator. Otherwise, in the Visual Studio for Mac toolbar, press the Start button (the triangular button that resembles a Play button) to launch the application inside your chosen iOS simulator or Android emulator:

   

   A StackLayout only respects the alignment preferences on child views that are in the opposite direction to the StackLayout orientation. Therefore, the Label child views within the vertically oriented StackLayout set their HorizontalOptions properties to one of the alignment fields:

   • Start, which positions the Label on the left hand side of the StackLayout.
   • Center, which centers the Label in the StackLayout.
   • End, which positions the Label on the right hand side of the StackLayout.
   • Fill, which ensures that the Label fills the width of the StackLayout.

   A StackLayout can only expand child views in the direction of its orientation. Therefore, the vertically oriented StackLayout can expand Label child views that set their VerticalOptions properties to one of the expansion fields. This means that, for vertical alignment, each Label occupies the same amount of space within the StackLayout. However, only the final Label, which sets its VerticalOptions property to FillAndExpand has a different size.

   Important

   When all the space in a StackLayout is used, expansion preferences have no effect.

   In Visual Studio for Mac, stop the application.

   For more information about alignment and expansion, see Layout Options in Xamarin.Forms.