WinUI 3 Layout System

Introduction to Layout

The WinUI 3 layout system provides powerful and flexible tools for arranging UI elements in your application. It enables you to create responsive and visually appealing user interfaces that adapt to different screen sizes and orientations. Understanding layout concepts is crucial for building modern Windows applications with WinUI 3.

Key layout panels include Grid, StackPanel, RelativePanel, and Canvas. Each offers unique ways to position and size child elements.

Grid Layout

The Grid panel is one of the most versatile layout containers in WinUI. It allows you to arrange elements in rows and columns, similar to a table. You can define the size of rows and columns using absolute values, percentages, or the Auto or Star sizing options.

Defining Rows and Columns

Example of defining rows and columns in XAML:
<Grid>
    <Grid.RowDefinitions>
        <RowDefinition Height="Auto"/>
        <RowDefinition Height="*"/>
        <RowDefinition Height="100"/>
    </Grid.RowDefinitions>
    <Grid.ColumnDefinitions>
        <ColumnDefinition Width="1*"/>
        <ColumnDefinition Width="2*"/>
    </Grid.ColumnDefinitions>

    <!-- Content for row 0, column 0 -->
    <TextBlock Grid.Row="0" Grid.Column="0" Text="Header" />

    <!-- Content for row 1, spanning columns 0 and 1 -->
    <Border Grid.Row="1" Grid.ColumnSpan="2" Background="LightGray" />

    <!-- Content for row 2, column 1 -->
    <Button Grid.Row="2" Grid.Column="1" Content="Click Me" />
</Grid>

Grid Layout Visualization

Row 0, Col 0
Row 0, Col 1
Row 1, Spans Cols
Row 2, Col 0
Row 2, Col 1

StackPanel

The StackPanel arranges child elements in a single line, either horizontally or vertically. It's useful for creating simple lists or toolbars.

Vertical and Horizontal Stacking

Example of a vertical StackPanel:
Item 1
Item 2
Item 3
Example of a horizontal StackPanel (using Orientation="Horizontal"):
Item A
Item B
Item C
XAML for StackPanel:
<StackPanel Orientation="Vertical" Spacing="10">
    <Button Content="Button 1"/>
    <TextBlock Text="Some Text"/>
    <Image Source="ms-appx:///Assets/icon.png"/>
</StackPanel>

RelativePanel

RelativePanel allows you to position elements relative to each other or the panel itself. This is powerful for creating adaptive layouts where elements align based on anchors.

Anchoring Elements

Example of RelativePanel usage:
Top Left
Top Right
Bottom Left
Bottom Right
Center
XAML for RelativePanel:
<RelativePanel Background="Azure">
    <Button Content="Save" RelativePanel.AlignLeftWithPanel="True" RelativePanel.AlignBottomWithPanel="True"/>
    <Button Content="Cancel" RelativePanel.AlignRightWithPanel="True" RelativePanel.AlignBottomWithPanel="True"/>
    <TextBlock Text="Title" RelativePanel.AlignHorizontalCenterWithPanel="True" RelativePanel.AlignTopWithPanel="True"/>
</RelativePanel>

Canvas

The Canvas panel provides absolute positioning for its children. Each child's position is specified using attached properties like Canvas.Left and Canvas.Top. While simple, it offers less flexibility for responsive design compared to other panels.

XAML for Canvas:
<Canvas Background="LightGreen" Height="200" Width="300">
    <Rectangle Canvas.Left="20" Canvas.Top="20" Width="100" Height="50" Fill="Red" />
    <Ellipse Canvas.Left="150" Canvas.Top="80" Width="80" Height="80" Fill="Blue" />
</Canvas>

Variable Sizing (Star and Auto)

WinUI 3 layout panels heavily utilize Star and Auto sizing for dynamic and responsive layouts.

  • Auto: The row or column takes up only the space required by its content.
  • Star (*): The row or column takes up a proportional amount of the remaining space. For example, 1*, 2*, etc.
Visual example of Star sizing in a Grid:
1*
2*
1*

Padding and Margin

Padding is the space within the border of an element, between the element's content and its border. Margin is the space outside the element's border, separating it from other elements.

These properties are fundamental for creating visual spacing and readability in your UI, regardless of the layout panel used.

Example with padding and margin:
This element has 20px padding inside and 15px margin outside.