.NET MAUI Cookbook

Crafting the Page Layout

Great applications start with a good idea and a vision of what users will see on the screen. I won’t be able to come up with an idea for your app, but I can help you avoid expending your energy when you get around to creating the user interface. While crafting the page layout may seem like a basic topic, many professional developers waste considerable time during this step or create views with performance/UX issues.

In this chapter, we’ll create the main layout types you’ll mostly need in .NET MAUI applications, learn how to avoid pitfalls, and delve into details of the algorithm for arranging UI elements.

By the end of this chapter, you will be able to create simple, advanced layouts with your custom arranging mechanism. We will create adaptive views for both desktop and mobile devices. You will get a deep understanding of how the .NET MAUI layout mechanism works, which will help you always make the right choice on what panel works best in your specific scenario.

In this chapter, we’ll be covering the following recipes:

Creating horizontal/vertical layouts
Creating grid layouts
Creating scrollable layouts
Implementing device-specific layouts
Implementing layouts with dynamic orientation
Building a layout dynamically based on a collection
Implementing a custom arranging algorithm

Creating horizontal/vertical layouts

User experience experts constantly emphasize that simplicity is key to a well-designed application. Horizontally or vertically arranged elements are essential for creating clean and clear views. Mastering these layout techniques is crucial to avoid unexpected issues on a user’s device.

Though this topic might seem straightforward, many developers run into issues due to the specific nuances of elements such as HorizontalStackLayout/VerticalStackLayout.

Let’s create several horizontal/vertical layout types to get a basic understanding of how the .NET MAUI layout system works and how to avoid potential issues.

Getting ready

To follow the steps described in this recipe, we just need to create a blank .NET MAUI application. The default template includes sample code in the MainPage.xaml and MainPage.xaml.cs files, but you can remove this code and leave only a blank ContentPage in XAML and a constructor with the InitializeComponent method in the page class. When copying code snippets with namespaces, don’t forget to replace them with the namespaces in your project.

The code for this recipe is available at https://github.com/PacktPublishing/.NET-MAUI-Cookbook/tree/main/Chapter01/c1-HorizontalAndVerticalLayouts.

How to do it…

We’ll create four linear layouts with buttons using the following panels:

HorizontalStackLayout
VerticalStackLayout
Grid
FlexLayout

Figure 1.1 – Linear layouts

Add HorizontalStackLayout with four buttons to arrange elements horizontally:

MainPage.xaml

<ContentPage
xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
x:Class="c1_HorizontalAndVerticalLayouts.MainPage">
    <HorizontalStackLayout Spacing="50">
            <Button Text="B 1"/>
            <Button Text="B 2"/>
            <Button Text="B 3"/>
            <Button Text="B 4"/>
    </HorizontalStackLayout>
</ContentPage>

If you run the project, you should see the result shown on the left-hand side of Figure 1.1.

Replace HorizontalStackLayout with VerticalStackLayout:

<VerticalStackLayout Spacing="50">
    <Button Text="B 1"/>
    <Button Text="B 2"/>
    <Button Text="B 3"/>
    <Button Text="B 4"/>
</VerticalStackLayout >

Run the project to see the result.

Do the same as we did in the previous step, but now, replace VerticalStackLayout with Grid, with four rows. Assign the Grid.Row attached property to each button:

<Grid RowDefinitions="*,*,*,*" RowSpacing="50">
    <Button Text="B 1"/>
    <Button Text="B 2" Grid.Row="1"/>
    <Button Text="B 3" Grid.Row="2"/>
    <Button Text="B 4" Grid.Row="3"/>
</Grid>

Run the project to see the result.

Do the same as we did in the previous step, but now, replace Grid with FlexLayout. Add one more button to the panel:

<FlexLayout Wrap="Wrap">
    <Button Text="B 1" Margin="25"/>
    <Button Text="B 2" Margin="25"/>
    <Button Text="B 3" Margin="25"/>
    <Button Text="B 4" Margin="25"/>
    <Button Text="B 5" Margin="25"/>
</FlexLayout>

Run the project to see the result.

How it works…

All panels in .NET MAUI use the same algorithm to arrange elements. Here’s a broad overview of how it works:

The panel asks its child elements how much space they need to display their content by calling the Measure method. This process is called measuring. During this, the panel informs the child elements about the available space, allowing them to return their optimal size based on these constraints. In other words, the panel communicates the size limits to its elements.
Based on the measurements from the first step, the panel then calls Arrange for each child to position them. This process is called arranging. While the panel considers each element’s desired size, it doesn’t always give them as much space as they request. If all the child elements demand more space than the panel has available, the panel may reduce some of its children.

For a simple linear arrangement task, we used four panel types available in the standard .NET MAUI suite, and all of them have a unique measuring and arranging logic:

HorizontalStackLayout: When measuring its children, the HorizontalStackLayout does so without any horizontal constraints. Essentially, it asks each child, “How wide would you like to be if you had infinite width available?” The height constraint, however, is determined by a panel’s height. In the scenario from the first step, buttons return the width needed to display their text. The panel then arranges the buttons horizontally in a single row, giving each button as much space as requested. Each button is separated by the distance specified in the Spacing property. If the panel doesn’t have enough space to display an element, that element gets cut off (as seen in Figure 1.1, where the fourth button is not displayed in the first layout).

Key point

HorizontalStackLayout provides its child elements with as much width as they require to display all content.

VerticalStackLayout: This panel works exactly like HorizontalStackLayout, but all the logic is rotated by 90 degrees.

Key point

VerticalStackLayout provides its child elements with as much height as they require to display all content.

Grid: The grid panel has a more complex measuring/arranging logic since it may have multiple rows and columns, but in the scenario demonstrated in step 3 in the How to do it section, it does the following:
- All the space available for the grid is divided into four equal parts because we defined four rows.
- When measuring the children, the grid provides each child with as much height as available in a corresponding row. Their width is limited by the width of the grid itself.
- When arranging, each element is placed in its row.
FlexLayout: While this panel also has a complicated measuring/arranging logic because of various settings, in the configuration demonstrated previously, the panel moves elements to the next line when they don’t fit the current row.

There’s more…

What could go wrong in such straightforward scenarios? It might not be obvious at first, but let’s consider the following code example, where CollectionView, displaying items vertically, is added to VerticalStackLayout:

<VerticalStackLayout>
    <CollectionView>
        <CollectionView.ItemsSource>
            <x:Array Type="{x:Type x:String}">
                <x:String>Item1</x:String>
                <x:String>Item2</x:String>
                <x:String>Item3</x:String>
                <!--...-->
                <x:String>Item100</x:String>
            </x:Array>
        </CollectionView.ItemsSource>
    </CollectionView>
    <Button Text="Some Button"/>
</VerticalStackLayout>

Many developers would expect to get the result demonstrated on the left of the following figure, but instead, they would get the output illustrated on the right:

Figure 1.2 – An issue with CollectionView in VerticalStackLayout

The reason for this is that VerticalStackLayout provides infinite height to CollectionView during the measuring cycle and CollectionView arranges its elements based on the size required to display all items. Since CollectionView has 100 items, it returns a larger desired size than VerticalStackLayout has. But since VerticalStackLayout doesn’t constrain its children, the button element is shifted by CollectionView beyond the screen. Besides this layout issue, this results in performance problems because CollectionView creates its elements even if they are not visible on the screen.

To achieve the result demonstrated on the left-hand side of Figure 1.2, use the Grid panel with two rows:

<Grid RowDefinitions="*,Auto">
    <CollectionView>
        <CollectionView.ItemsSource>
            <x:Array Type="{x:Type x:String}">
                <x:String>Item1</x:String>
                <x:String>Item2</x:String>
                <x:String>Item3</x:String>
                <!--more items here-->
                <x:String>Item100</x:String>
            </x:Array>
        </CollectionView.ItemsSource>
    </CollectionView>
    <Button Grid.Row="1" Text="Some Button"/>
</Grid>

Note that RowDefinitions is set to "*, Auto", which means that the second row gets as much space as required by the button and the first row gets all the remaining space.

Creating grid layouts

Linear layouts address most scenarios, but what if you need to create something more complex? For example, what if we want to create a simple editing form with labels and editors, where the first column is resized based on the longest label in all rows?

We can use Grid, which is an extremely powerful panel with a simple concept, but as with any other control, it may pose unexpected challenges for those who don’t fully understand its specifics.

Let’s look at some common grid-related layouts/techniques and potential pitfalls you may encounter.

Getting ready

To follow the steps described in this recipe, we just need to create a blank .NET MAUI application. The default template includes sample code in the MainPage.xaml and MainPage.xaml.cs files, but you can remove it and leave only a blank ContentPage in XAML and a constructor with the InitializeComponent method in CS.

The code for this recipe is available at https://github.com/PacktPublishing/.NET-MAUI-Cookbook/tree/main/Chapter01/c1-GridLayouts.

How to do it…

In this recipe, we will create two simple layouts using the Grid panel, allowing us to use most of Grid’s capabilities, which we will discuss in later sections on this topic:

Figure 1.3 – Grid row spanning and alignment

I used a non-transparent background for child elements in the Grid to demonstrate the space occupied by the elements in grid cells.

Create a two-column layout where the first column is increased based on the largest element. To automatically adjust the size of the first column based on its content, set the first column’s width to Auto using the ColumnDefinitions property:
MainPage.xaml
```
<Grid RowDefinitions="40,80"
      ColumnDefinitions="Auto, *">
    <Label Text="Title"/>
    <Label Text="Description"
           Grid.Row="1"/>
    <Editor Grid.Column="1"/>
    <Editor Grid.Row="1"
            Grid.Column="1"/>
</Grid>
```
If you run the project, you should see the result shown on the left-hand side of Figure 1.3.

Now, let’s create a layout with two columns and stretch a label in the second column across two rows. To do this, define two columns and two rows, and set Grid.RowSpan to span multiple lines with the label:

<Grid RowDefinitions="40,40"
      ColumnDefinitions="*, 60">
    <Label Text="Headline"/>
    <Label Text="Supporting text"
           TextColor="DarkGray"
           Grid.Row="1" />
    <Label Text="100+"
           VerticalOptions="Center"
           HorizontalOptions="End"
           Grid.RowSpan="2"
           Grid.Column="1" />
</Grid>

Run the project to see the result.

How it works…

As you may know, the Grid panel uses the RowDefinitions and ColumnDefinitions properties to specify rows and columns, respectively. Both properties accept a collection of RowDefinitions and ColumnDefinitions classes that can be automatically converted to XAML from the following values:

Double: A constant value
Auto: The space required to display a child element without trimming
* (star): All the remaining space after other rows or columns

Sometimes, developers are confused by * and Auto because both values calculate the width/height automatically, but there is a key difference between them:

When a row definition is set to Auto, Grid provides elements in the row with as much space as they need. In this mode, content in a row is measured similarly to elements in VerticalStackLayout. For example, if you add three rows with the Auto value, you will get the same output as with VerticalStackLayout. For example, the following two layouts will have the same output:

<Grid RowDefinitions="Auto,Auto,Auto">
    <Button Text="Button1"/>
    <Button Text="Button2" Grid.Row="1"/>
    <Button Text="Button3" Grid.Row="2"/>
</Grid>
<VerticalStackLayout>
    <Button Text="Button1"/>
    <Button Text="Button2"/>
    <Button Text="Button3"/>
</VerticalStackLayout>

Of course, if you have only Auto rows, it’s better to choose VerticalStackLayout for performance and code simplicity reasons.

Key point

Multiple Auto rows in Grid work the same way as VerticalStackLayout. Multiple Auto columns work like HorizontalStackLayout.

Rows whose definition is set to * proportionally divide all the space left after other rows. If you need to change the proportion between * rows, you can use numeric multipliers. For example, in the following code snippet, we add three rows – the first row will have a height of X, the second will have a height of 2X, and the third will have a height of 3X:
```
<Grid RowDefinitions="*,2*,3*">
    <Button Text="Button1"/>
    <Button Text="Button2" Grid.Row="1"/>
    <Button Text="Button3" Grid.Row="2"/>
</Grid>
```

There’s more…

Choosing the right row/column type may be challenging, due to performance and device scaling issues. Let me demonstrate to you a few common issues in grid-based layouts:

Cropped elements because of fixed sizes: In cross-platform applications, screen dimensions, resolution, DPI, and font scale may vary, depending on the device and user settings. This may pose a challenge because elements that appear correctly on a developer machine may get cropped on a user device. For example, let’s define grid columns and rows in the following manner:
```
<Grid ColumnDefinitions="80,*" RowDefinitions="30">
    <Label Text="First Name"
        BackgroundColor="LightGreen"/>
    <Editor Grid.Column="1"/>
</Grid>
```
With that, you may get the following output:

Figure 1.4 – The issue with a fixed size and different device font settings

To fix this, you can use Auto for the first column. However, before using it, pay attention to the next point in this list.

Performance issues because of too many Auto rows/columns: Auto rows/columns may lead to performance issues, as a grid may require multiple layout calculation cycles when several child elements are arranged based on their preferred size. Of course, you are unlikely to notice significant delays even on mobile devices if your root or a few nested grids contain Auto rows, but if you have a collection whose ItemTemplate includes many Auto values, you may consider other techniques:
- Use fixed double values, applied based on the device type/settings:
```
<Grid>
    <Grid.RowDefinitions>
        <RowDefinition
            Height="{OnIdiom Desktop=200, Phone=*}"/>
    </Grid.RowDefinitions>
</Grid>
```
We will delve into the details of this technique in the next recipe (Implementing device-specific layouts).
- Create your own panel with custom measure/arrange logic. This technique will be covered in the Implementing a custom arranging algorithm recipe of this chapter. Typically, you will need this technique only when you have a complex layout and many elements on the screen.
Lists added to Auto rows: In the How it works… section, we learned that to measure child elements, a grid’s Auto rows use a basic rule similar to the one used in Vertical/HorizontalStackLayout – it provides the children as much space as they want. Lists, such as CollectionView, usually request the space required to display all their items. As a result, you may face the same issue with the collection infinite height as described in the Creating horizontal/Vertical layouts recipe:
```
<Grid RowDefinitions="Auto, 50">
    <CollectionView>
        <CollectionView.ItemsSource>
            <x:Array Type="{x:Type x:String}">
                <x:String>Item1</x:String>
                <x:String>Item2</x:String>
                <x:String>Item3</x:String>
                
                <x:String>Item100</x:String>
            </x:Array>
        </CollectionView.ItemsSource>
    </CollectionView>
    <Button Grid.Row="1" Text="Some Button"/>
</Grid>
```
Refer to the right-hand side of Figure 1.2 to see the layout produced by this code snippet.
The fix depends on your layout requirements, but typically, you would need to replace Auto with a * value:
```
<Grid RowDefinitions="*, 50">
    
</Grid>
```
Alternatively, you would replace Auto with a fixed size:
```
<Grid RowDefinitions="300, 50">
    
</Grid>
```
The second option is applicable when you need to create a collection with a fixed size instead of stretching it.

Creating scrollable layouts

One of the obvious techniques to add more elements to a screen such that they fit within it is to create a scrollable layout, using the ScrollView element. As always, even basic elements can cause issues when misused. To help you avoid pitfalls, we will create vertical and horizontal scrollable layouts and discuss their specifics in the How it works… and There’s more… sections.

Getting ready

To follow the steps described in this recipe, we just need to create a blank .NET MAUI application. The default template includes sample code in the MainPage.xaml and MainPage.xaml.cs files, but you can remove it and leave only a blank ContentPage in XAML and a constructor with the InitializeComponent method in CS.

The code for this recipe is available at https://github.com/PacktPublishing/.NET-MAUI-Cookbook/tree/main/Chapter01/c1-ScrollableLayout.

How to do it…

To learn how to use scrollable layouts most efficiently and avoid issues, let’s create simple vertical and horizontal layouts and discuss them in further sections:

To create a vertical scrollable layout, it’s sufficient to wrap the part you would like to scroll in the ScrollView element:

MainPage.xaml

<ScrollView>
    <VerticalStackLayout>
        <Button Text="Tall Button 1"
            HeightRequest="500"/>
        <Button Text="Tall Button 2"
            HeightRequest="500"/>
    </VerticalStackLayout>
</ScrollView>

Run the project to see the result.

To enable horizontal scrolling, set ScrollView.Orientation to "Horizontal". Replace VerticalStackLayout with HorizontalStackLayout to arrange elements horizontally:

<ScrollView Orientation="Horizontal">
    <HorizontalStackLayout>
        <Button Text="Tall Button 1"
            WidthRequest="500"/>
        <Button Text="Tall Button 2"
        WidthRequest="500"/>
    </HorizontalStackLayout>
</ScrollView>

Run the project to see the result.

How it works…

Similar to VerticalStackLayout and HorizontalStackLayout, the ScrollView element lets its child element occupy as much space as it requests. As such, it measures it by infinite height or width (depending on the orientation). When the desired size of a child element is greater than the space available in ScrollView, scrolling functionality is activated.

Setting ScrollView.Orientation to Horizontal or Vertical determines the direction of scrolling. You can also set Orientation to Both, to scroll in both directions.

There’s more…

This is probably the most useful section in this recipe, since adding scrolling is straightforward, but ScrollView has its specifics, which should be taken into account to avoid issues. Let’s take a look at a few patterns that you should avoid when working with ScrollView:

Adding ScrollView with an undefined height to VerticalStackLayout:

<VerticalStackLayout>
    <ScrollView>
        <VerticalStackLayout>
           <Button Text="Tall Button 1"
                   HeightRequest="500"/>
           <Button Text="Tall Button 2"
                   HeightRequest="500"/>
           <Button Text="Tall Button 3"
                   HeightRequest="500"/>
           <Button Text="Tall Button 4"
                   HeightRequest="500"/>
        </VerticalStackLayout>
    </ScrollView>
</VerticalStackLayout>

You won’t be able to scroll your view with this layout because, as we know from the Creating horizontal/vertical layouts recipe, VerticalStackLayout provides its children with infinite height. As a result, ScrollView thinks that it has infinite height, and ScrollView doesn’t need to activate scrolling because its children can fit the parent panel.

Adding CollectionView with an undefined height to ScrollView:
```
<ScrollView>
    <CollectionView>
        
    </CollectionView>
</ScrollView>
```
Here, you will encounter the same infinite height issue as with CollectionView in VerticalStackLayout or Grid, whose row is set to Auto. In all these scenarios, parent containers measure CollectionView by an infinite height. As a result, CollectionView is virtually increased to fit all its items.

Implementing device-specific layouts

Desktop and mobile devices have fundamental differences in the user experience. Here are just a few examples:

A small versus a large screen
A mouse versus a touchscreen
A physical versus a virtual keyboard
A single window versus multiple windows

There are even more differences, and all of them affect the UI – you can rarely craft a screen that will be convenient for both mobile and desktop devices without explicit adaptive logic.

While .NET MAUI gives you the power to use a single code base for multiple device types, it won’t automatically adapt your layout to a specific device. However, the OnIdiom and OnPlatform markup extensions will help you implement local customization, or even replace the entire view, based on the device type or operating system. We will use both the OnIdiom and OnPlatform extensions in this recipe to see how they differ from each other.

Getting ready

To follow the steps described in this recipe, we just need to create a blank .NET MAUI application. The default template includes sample code in the MainPage.xaml and MainPage.xaml.cs files, but you can remove it and leave only a blank ContentPage in XAML and a constructor with the InitializeComponent method in CS. When copying code snippets with namespaces, don’t forget to replace them with the namespaces in your project.

The code for this recipe is available at https://github.com/PacktPublishing/.NET-MAUI-Cookbook/tree/main/Chapter01/c1-DeviceSpecificLayout.

How to do it…

Let’s use OnIdiom to specify a single property, specify multiple properties, and replace the entire view. Each of these techniques may be the most suitable, based on your scenario. After that, we will use OnPlatform to show a button on Android and hide it on iOS:

Use the OnIdiom markup extension to set a local property value based on the device type (desktop, phone, tablet, TV, or watch). To adjust the layout using OnIdiom, define a grid with two rows and set the first row’s height using OnIdiom, as follows:
MainPage.xaml
```
<Grid>
    <Grid.RowDefinitions>
        <RowDefinition
            Height="{OnIdiom Desktop=200, Phone=*}"/>
        <RowDefinition Height="*"/>
    </Grid.RowDefinitions>
    <Border BackgroundColor="Coral"/>
    <Border Grid.Row="1" BackgroundColor="DarkRed"/>
</Grid>
```
As you may have noticed, we used an expanded RowDefinition syntax here to adjust each RowDefinition height separately (instead of RowDefinitions="200, *"). Run the project on a desktop and phone to see the result.

Figure 1.5 – Idiom-specific settings

To adjust a bunch of properties using one OnIdiom condition, define a style for each device type:

<ContentPage.Resources>
    <Style TargetType="Grid" x:Key="winUiBorderStyle">
        <Setter Property="Padding" Value="20"/>
        <Setter Property="Margin" Value="20"/>
    </Style>
    <Style TargetType="Grid"
           x:Key="androidBorderStyle">
        <Setter Property="Padding"
                Value="10,0,10,10"/>
        <Setter Property="Margin" Value="10"/>
    </Style>
</ContentPage.Resources>
<Border Style="{OnIdiom Desktop={StaticResource
        winUiBorderStyle}, Phone={StaticResource
        androidBorderStyle}}" BackgroundColor="Coral">
    <Border BackgroundColor="DarkRed"/>
</Border>

Run the project to see the result.

To switch the entire view based on the device type, define separate views for each device and set the ContentPage.Content property using an expanded OnIdiom tag. If you haven’t created ContentView before, right-click on the project, and then select Add | New Item | ContentView. Name one view PhoneView and the other DesktopView:

PhoneView.xaml (for Android/iOS)

<ContentView
xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    x:Class="c1_DeviceSpecificLayout.PhoneView">
    <Border>
        <Label Text="Phone View"/>
    </Border>
</ContentView>

DesktopView (for Windows/macOS/Linux)

<ContentView xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    x:Class="c1_DeviceSpecificLayout.DesktopView">
    <Border>
        <Label Text="Desktop View"/>
    </Border>
</ContentView>

MainPage.xaml

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    xmlns:local="clr-namespace: c1_DeviceSpecificLayout"
    x:Class="c1_DeviceSpecificLayout.MainPage">
    <ContentPage.Content>
        <OnIdiom x:TypeArguments="View">
            <OnIdiom.Phone>
                <local:PhoneView />
            </OnIdiom.Phone>
            <OnIdiom.Desktop>
                <local:DesktopView />
            </OnIdiom.Desktop>
        </OnIdiom>
    </ContentPage.Content>
</ContentPage>

Note that the TypeArguments attribute of OnIdiom should be set to View. Don’t forget to add a namespace definition to MainPage to be able to reference PhoneView and DesktopView.

This technique is useful when there are significant differences between the mobile and desktop views and customizing separate controls is problematic.

Use the OnPlatform markup extension to specify properties that depend on an operating system:
```
<Button IsVisible="{OnPlatform Android=True,
        iOS=False}"/>
```
This code sets Button.IsVisible to True on Android and to False on iOS devices, showing or hiding the button, respectively, based on the operating system. You can also specify different values for other platforms supported in MAUI – MacCatalyst, Tizen, and WinUI.

How it works…

Under the hood, OnIdiom checks the current device information using the DeviceInfo class and returns a value you specified in XAML:

Here is a simplified code snippet illustrating the idea:

public class OnIdiomExtension : IMarkupExtension {
    public object Default { get; set; }
    public object Phone { get; set; }
    public object Desktop { get; set; }
    //...
    public object ProvideValue(IServiceProvider serviceProvider) {
        //...
        if (DeviceInfo.Idiom == DeviceIdiom.Phone)
            return Phone ?? Default;
        if (DeviceInfo.Idiom == DeviceIdiom.Desktop)
            return Desktop ?? Default;
        //...
        return Default;
}

The OnPlatform extension works in the same way, but it uses the DeviceInfo.Platform property to get the currently running platform and return the value you specified in XAML.

There’s more…

If you need to implement more complex logic, you can specify device-specific settings in C#. For example, the following code sets a grid’s height based on the idiom value:

public MainPage() {
    InitializeComponent();
    if (DeviceInfo.Current.Idiom == DeviceIdiom.Desktop) {
        grid1.Height = CalculateDesktopHeight();
    }
    else if (DeviceInfo.Current.Idiom == DeviceIdiom.Phone)
    {
        grid1.Height = CalculateMobileHeight();
    }
}

The CalculateDesktopHeight and CalculateMobileHeight methods are supposed to contain custom calculation logic that cannot be easily implemented in XAML.

You can implement similar customization logic based on the DeviceInfo.Current.Platform property for each operating system. Alternatively, you can use conditional compilation and platform-specific code, as we will demonstrate in Chapter 7, Understanding Platform-Specific APIs and Custom Handlers.

Implementing layouts with dynamic orientation

Users can rotate mobile devices, and it’s important to adapt your UI according to the current orientation. The .NET MAUI platform doesn’t have a built-in class to set orientation-specific settings in XAML; however, it provides a visual state mechanism. Alternatively, you can set orientation-based properties in C#. In this recipe, we’ll implement both techniques.

Getting ready

To follow the steps described in this recipe, we just need to create a blank .NET MAUI application. The default template includes sample code in the MainPage.xaml and MainPage.xaml.cs files, but you can remove it and leave only a blank ContentPage in XAML and a constructor with the InitializeComponent method in CS. When copying code snippets with namespaces, don’t forget to replace them with the namespaces in your project.

The code for this recipe is available at https://github.com/PacktPublishing/.NET-MAUI-Cookbook/tree/main/Chapter01/c1-OrientationSpecificSettings.

How to do it…

Let’s use two different techniques to specify layout settings based on the orientation – set settings in XAML using visual states and set settings in C# by subscribing to the MainDisplayInfoChanged event, which is raised when the orientation is changed:

To specify orientation-based settings in XAML, define VisualStateGroup with Portrait and Landscape visual states. In visual state setters, reference the elements you would like to customize by their names. Note that it’s necessary to explicitly specify the parent property class in each setter:

MainPage.xaml

<VisualStateManager.VisualStateGroups>
    <VisualStateGroupList>
        <VisualStateGroup>
            <VisualState x:Name="Portrait">
                <VisualState.StateTriggers>
                    <OrientationStateTrigger
                           Orientation="Portrait" />
                </VisualState.StateTriggers>
                <VisualState.Setters>
                    <Setter TargetName="rootGrid"
                        Property="Grid.RowDefinitions"
                            Value="*,*" />
                    <Setter TargetName="border2"
                            Property="Grid.Row"
                            Value="1"/>
                </VisualState.Setters>
            </VisualState>
            <VisualState x:Name="Landscape">
                <VisualState.StateTriggers>
                    <OrientationStateTrigger
                        Orientation="Landscape" />
                </VisualState.StateTriggers>
                <VisualState.Setters>
                    <Setter TargetName="rootGrid"
                       Property="Grid.RowDefinitions"
                            Value="*,*" />
                    <Setter TargetName="border2"
                            Property="Grid.Row"
                            Value="1"/>
                </VisualState.Setters>
            </VisualState>
        </VisualStateGroup>
    </VisualStateGroupList>
</VisualStateManager.VisualStateGroups>
<Grid x:Name="rootGrid">
    <Border x:Name="border1" BackgroundColor="Coral"/>
    <Border x:Name="border2" Background="DarkRed"/>
</Grid>

In the preceding code snippet, we set Grid.RowDefinitions and Grid.Row for the grid and border elements, referenced using the TargetName property. The VisualStateManager.VisualStateGroups property is defined at the page/view level, which allows you to set all orientation-based settings in one place instead of creating visual states in each element. You will see the following result if you run the project and try to rotate a device:

Figure 1.6 – Landscape layout customization

To specify orientation-based settings in C#, subscribe to the DeviceDisplay.MainDisplayInfoChanged event and modify all required settings in the event handler:

MainPage.xaml.cs

protected override void OnNavigatedTo(NavigatedToEventArgs args) {
    base.OnNavigatedTo(args);
    SetOrientationSpecificSettings();
    DeviceDisplay.MainDisplayInfoChanged +=
      OnMainDisplayInfoChanged;
}
protected override void OnNavigatedFrom(NavigatedFromEventArgs args) {
    base.OnNavigatedFrom(args);
    DeviceDisplay.MainDisplayInfoChanged -= 
      OnMainDisplayInfoChanged;
}
private void OnMainDisplayInfoChanged(object? sender, 
  DisplayInfoChangedEventArgs e) {
    SetOrientationSpecificSettings();
}
void SetOrientationSpecificSettings() {
    if (DeviceDisplay.MainDisplayInfo.Orientation == 
      DisplayOrientation.Landscape)
        border1.BackgroundColor = Colors.Red;
    else
        border1.BackgroundColor = Colors.Green;
}

Don’t forget to unsubscribe from the MainDisplayInfoChanged event; otherwise, DeviceDisplay will always hold a reference of the view, and it will never be released, causing a memory leak.

How it works…

As you may know, .NET MAUI includes the visual state mechanism. Elements can have different predefined visual statues, which are not limited by Portrait and Landscape. For example, there are states such as Normal, Disabled, and Focused.

In C#, you can change the state using the VisualStateManager.GoToState method:

VisualStateManager.GoToState(someVisualElement, "<stateName>");

You can use any name for your custom state.

In XAML, you can go to a state using a state trigger. The platform provides a built-in OrientationStateTrigger trigger, so when the orientation is changed, this trigger is invoked, and a corresponding state is activated.

When a state is activated, it executes the setters:

<VisualState x:Name="Portrait">
    <VisualState.StateTriggers>
        <OrientationStateTrigger Orientation="Portrait" />
    </VisualState.StateTriggers>
    <VisualState.Setters>
        <Setter TargetName="rootGrid" Property="Grid.RowDefinitions" 
          Value="*,*" />
        <Setter TargetName="border2" Property="Grid.Row" Value="1"/>
    </VisualState.Setters>
</VisualState>

Each setter can be applied to a specific element on a page using the TargetName property. Since we define visual states at the ContentPage level, it’s necessary to explicitly set the name of the parent class in the property setter ("Grid.RowDefinitions").

As for the DeviceDisplay class, it includes basic information about your display, such as orientation, height, width, and density. So, if you need to fine-tune your layout based on these settings, you can use the DeviceDisplay.Current.MainDisplayInfo property:

double screenWidth = DeviceDisplay.Current.MainDisplayInfo.Width;
double screenHeight = DeviceDisplay.Current.MainDisplayInfo.Height;
double screenDensity = DeviceDisplay.Current.MainDisplayInfo.Density

There’s more…

While the bare .NET MAUI platform doesn’t include XAML extensions (similar to OnIdiom/OnPlatform) to set orientation-specific settings, you can use third-party suites, such as DevExpress, which include additional extensions that enable you to perform this task:

    <dx:DXButton Content="Click" Padding="{dx:OnOrientation 
      Portrait='8,4', Landscape='12,8'}"/>

You can learn more about this functionality in DevExpress’s documentation: https://docs.devexpress.com/MAUI/404287/common-concepts/specify-device-specific-settings#xaml-use-the-onorientation-extension.

Building a layout dynamically based on a collection

A bindable layout is a technique that allows you to generate similar UI elements without repeating XAML code blocks. Let’s imagine you need to display a list of actions, and this list is dynamically retrieved from a web API service. A possible solution for this task is to add buttons to your view in C#, but .NET MAUI provides a more convenient way with the BindableLayout.ItemsSource property. Let’s see how to utilize it.

Getting ready

To follow the steps described in this recipe, we just need to create a blank .NET MAUI application. The default template includes sample code in the MainPage.xaml and MainPage.xaml.cs files, but you can remove it and leave only a blank ContentPage in XAML and a constructor with the InitializeComponent method in CS. When copying code snippets with namespaces, don’t forget to replace them with the namespaces in your project.

The code for this recipe is available at https://github.com/PacktPublishing/.NET-MAUI-Cookbook/tree/main/Chapter01/c1-BindableLayout.

How to do it…

Let’s generate buttons with a predefined template, using VerticalStackLayout and the BindableLayout class. We will generate buttons from a collection of custom non-visual objects. Let’s name the class containing information about these objects ActionInfo:

Create a MyViewModel class and define a collection of items that will store information about your buttons:

MyViewModel.cs

public class MyViewModel {
    public ObservableCollection<ActionInfo> DynamicActions { 
      get; set; }
    public MyViewModel() {
        DynamicActions = new ObservableCollection<ActionInfo> {
            new ActionInfo() { Caption = "Action1" },
            new ActionInfo() { Caption = "Action2" },
            new ActionInfo() { Caption = "Action3" }
        };
    }
}
public class ActionInfo {
    public string Caption { get; set; }
}

Assign the view model to the page’s BindableContext:

<ContentPage.BindingContext>
    <local:MyViewModel/>
</ContentPage.BindingContext>

Set the BindableLayout.ItemsSource and BindableLayout.ItemTemplate properties at the VerticalStackLayout level:

<VerticalStackLayout BindableLayout.ItemsSource="{Binding DynamicActions}" Spacing="5">
    <BindableLayout.ItemTemplate>
        <DataTemplate x:DataType="{x:Type local:ActionInfo}">
            <Button Text="{Binding Caption}"/>
        </DataTemplate>
    </BindableLayout.ItemTemplate>
</VerticalStackLayout>

Once you run the code, you should see the following output:

Figure 1.7 – A bindable layout

How it works…

BindableLayout generates elements from a collection and adds them to the panel to which it’s attached. It can work with all elements that implement the IBindableLayout interface. This interface is implemented in the layout abstract class, which is a base class for all layouts – StackLayout, HorizontalStackLayout, Grid, FlexLayout, and AbsoluteLayout.

BindableLayout takes each item in the ItemsSource collection and generates the UI for it, which is defined in ItemTemplate. To allow you to easily bind to properties in your model, BindableLayout assigns your model to BindingContext of ItemTemplate. That’s why you can bind the button’s Text property to Caption, defined in the ActionInfo class.

Here is a code snippet that demonstrates how BindableLayout generates items:

View CreateItemView(object item, DataTemplate dataTemplate)
{
    if (dataTemplate != null)
    {
        var view = (View)dataTemplate.CreateContent();
        view.BindingContext = item;
        return view;
    }
    else
    {
        return new Label
        {
            Text = item?.ToString(),
            HorizontalTextAlignment = TextAlignment.Center
        };
    }
}

As you can see, if DataTemplate is not defined, it simply creates a label with a string representation of your object.

There’s more…

Here are a couple of additional tips you may find useful when using BindableLayout:

Define the BindableLayout.EmptyViewTemplate template to show a message to a user when the source collection is empty:

<BindableLayout.EmptyViewTemplate>
    <DataTemplate>
        <Label Text="There are no actions"/>
    </DataTemplate>
</BindableLayout.EmptyViewTemplate>

When generated elements exceed the space available on the screen, these elements will be cut. As such, if you need to enable scrolling, you need to wrap a panel that is used with BindableLayout within ScrollView. Typically, an even better solution is to use CollectionView. When you need to customize the way items are arranged in it, you can use the ItemsLayout property. For example, to generate items and show them in two columns, use GridItemsLayout as follows:
```
 <CollectionView ItemsSource="{Binding Tiles}">
    <CollectionView.ItemsLayout>
       <GridItemsLayout Orientation="Vertical"
                        Span="2" />
    </CollectionView.ItemsLayout>
</CollectionView>
```
CollectionView uses a virtualization mechanism, which means that it reuses visual elements as you scroll. This prevents performance issues when dealing with a long list of items.

Implementing a custom arranging algorithm

Built-in layout panels help you solve the most common tasks in your app. However, sometimes, you may need to achieve a unique layout, which would be difficult to implement with the default .NET MAUI panels (Grid, VerticalStackLayout, etc.). Fortunately, you can easily implement your custom layout logic, where children are measured and arranged according to your rules.

Getting ready

To follow the steps described in this recipe, we just need to create a blank .NET MAUI application. The default template includes sample code in the MainPage.xaml and MainPage.xaml.cs files, but you can remove it and leave only a blank ContentPage in XAML and a constructor with the InitializeComponent method in CS. When copying code snippets with namespaces, don’t forget to replace them with the namespaces in your project.

The code for this recipe is available at https://github.com/PacktPublishing/.NET-MAUI-Cookbook/tree/main/Chapter01/c1-CustomLayout.

How to do it…

Let’s create a panel that arranges its children in a circle with a specified radius, as demonstrated in the following figure:

Figure 1.8 – A custom circular layout

Create a class inherited from Layout and override CreateLayoutManager. In CreateLayoutManager, return an instance of a class that will measure and arrange children in your panel:

MainWindow.xaml.cs

public class CircularLayout : Layout {
    protected override ILayoutManager CreateLayoutManager() {
        return new CircularLayoutManager(this);
    }
    public double Radius {
        get { return (double)GetValue(RadiusProperty); }
        set { SetValue(RadiusProperty, value); }
    }
    public static readonly BindableProperty RadiusProperty =
        BindableProperty.Create("Radius", typeof(double), 
          typeof(CircularLayout));
}

The Radius dependency property will help us arrange elements according to a specified radius.

Create a class that implements ILayoutManager:

public class CircularLayoutManager : ILayoutManager {
    readonly CircularLayout parentLayout;
    public CircularLayoutManager(CircularLayout layout) {
        this.parentLayout = layout;
    }
    public Size Measure(double widthConstraint, double 
      heightConstraint) {
       throw new NotImplementedException();
    }
    public Size ArrangeChildren(Rect bounds) {
        throw new NotImplementedException();
    }
}

Implement the ILayoutManager.Measure method. In the method, iterate through all children of the panel and call Measure for each of them (this is required to update the desired size of the child items):

public class CircularLayoutManager : ILayoutManager {
    //…
    public Size Measure(double widthConstraint, double 
      heightConstraint) {
        double radius = parentLayout.Radius;
        for (int n = 0; n < parentLayout.Count; n++) {
            var child = parentLayout[n];
            if (child.Visibility == Visibility.Collapsed) {
                continue;
            }
            child.Measure(double.PositiveInfinity, double.
              PositiveInfinity);
        }
        return new Size(parentLayout.WidthRequest, parentLayout.
          HeightRequest);
    }
}

The returned value determines what desired size the panel will have.

Implement the ILayoutManager.ArrangeChildren method. For each child in the parent layout panel (CircularLayout), call Arrange. Pass a rectangle to this method, indicating what exact position and bounds a child should have:

public class CircularLayoutManager : ILayoutManager {
//...
    public Size ArrangeChildren(Rect bounds) {
        double radius = parentLayout.Radius;
        double angleStep = Math.PI * 2 / parentLayout.Count;
        for (int i = 0; i < parentLayout.Count; i++) {
            var child = parentLayout[i];
            if (child.Visibility == Visibility.Collapsed) {
                continue;
            }
            child.Arrange(new Rect(
                radius * Math.Cos(angleStep * i) + radius,
                radius * Math.Sin(angleStep * i) + radius,
                child.DesiredSize.Width,
                child.DesiredSize.Height));
        }
        return new Size(parentLayout.WidthRequest, parentLayout.
          HeightRequest);
    }
}

We use the sin and cos functions to calculate the points of the top-left point of each child. We have intentionally avoided taking into account properties such as Padding and VerticalOptions/HorizontalOptions to simplify the logic.

That’s it! Now, you can use CircularLayout in XAML:

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/
                    maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/
                      xaml"
             x:Class="c1_CustomLayout.MainPage" 
             xmlns:local="clr-namespace:c1_CustomLayout"
             Title="CustomLayoutPage">
    <local:CircularLayout WidthRequest="300"
                          HeightRequest="300"
                          BackgroundColor="There are no actions"
                          Radius="100"
                          VerticalOptions=Start
                          HorizontalOptions="Start">
        <Button Text="Button1"/>
        <Button Text="Button2"/>
        <Button Text="Button3"/>
        <Button Text="Button4"/>
        <Button Text="Button5"/>
        <Button Text="Button6"/>
        <Button Text="Button7"/>
        <Button Text="Button8"/>
    </local:CircularLayout>
</ContentPage>

CircularLayout is intentionally colored so that you can see its bounds and how child elements are distributed in the panel. The panel’s children don’t occupy all available space. Instead, they are arranged according to the specified radius.

Now, you can run the project to see the result.

How it works…

The platform automatically calls the layout manager’s Measure method when it needs to update the layout. The layout manager, in turn, calls Measure for each of its child elements (in the preceding example, CircularLayoutManager calls Measure for each button added to CircularLayout). Once a child’s Measure is called, the child calculates what size it wants to have to properly fit all its content – this size is called DesiredSize. The layout manager can use the DesiredSize property of its children to calculate its own DesiredSize and return this value in its ILayoutManager.Measure method. In the preceding example, we return the size based on the specified radius, without taking into account the panel’s children.

In the ArrangeChildren method, we again iterate through all the child elements and call the Arrange method. This method accepts the rectangle in which a child element should be located. So, here, we specify the position and size of each element.

In .NET MAUI, layouts are created in a two-step process – measuring and arranging. Here is a simplified diagram illustrating the algorithm:

Figure 1.9 – A .NET MAUI layout algorithm

There’s more…

In step 3 of the How to do it… section, we measured all the child elements of our custom panel and returned a value that doesn’t depend on the panel’s children:

public class CircularLayoutManager : ILayoutManager {
    //…
    public Size Measure(double widthConstraint, double 
      heightConstraint) {
        //…
        for (int n = 0; n < parentLayout.Count; n++) {
            //…
            child.Measure(double.PositiveInfinity, 
              double.PositiveInfinity);
        }
        return new Size(parentLayout.WidthRequest, 
          parentLayout.HeightRequest);
    }
}

You may ask, why measure children if we don’t take their desired size into account? The answer is that if you don’t call Measure for a child element, this element won’t calculate its desired size and, as a result, won’t be rendered.

Key point

Always call the Measure element for all panel children, even if you don’t take into account their desired size during the measuring cycle.