Layout for Windows Phone 8

[ This article is for Windows Phone 8 developers. If you’re developing for Windows 10, see the latest documentation. ]

Windows Phone provides a flexible layout system that enables you to specify how controls are positioned on the screen. This Quickstart describes how to design a user interface that automatically sizes to various screen resolutions.

This topic contains the following sections.

• Layout overview
• Absolute layout
• Dynamic layout
• Panel controls
• Related Topics

Layout overview

Layout is the process of sizing and positioning objects in your app for Windows Phone. To position visual objects, you must put them in a container control derived from Panel or another container object. Windows Phone provides various Panel controls, such as Canvas, StackPanel, and Grid, that serve as containers and enable you to position and arrange the controls.

The Windows Phone layout system supports both an absolute layout and a dynamic layout. In an absolute layout, controls are positioned using explicit x/y coordinates (for example, by using a Canvas). In a dynamic layout, the user interface automatically sizes to various screen resolutions (for example, by using a StackPanel or a Grid).

Absolute layout

In an absolute layout, you arrange child elements in a layout panel by specifying their exact locations relative to their parent element. Absolute positioning doesn't consider the size of the screen. If the app requires absolute positioning of UI elements, you can design different pages for different screen resolutions or use scaling as an alternative.

Windows Phone provides a Canvas control to support absolute positioning. By default, when you create a new Windows Phone app project, the root layout panel is a Grid to create a layout based on absolute positioning, you must replace the Grid with a Canvas.

To position controls on a Canvas, you set the following attached properties on the control. When you use the designer in Visual Studio, these properties are updated when you drag controls onto the design surface.

• Canvas..::.Left

• Canvas..::.Top

Dynamic layout

In a dynamic layout, the user interface appears correctly on various screen resolutions. You arrange child elements by specifying how they should be arranged and how they should wrap relative to their parent. For example, you can arrange controls on a panel and specify that they should wrap horizontally. To use automatic or proportional sizing, you must assign special values to the Height and Width properties. The following are the recommended settings for a dynamic layout:

• Set the Height and Width of the control or layout to Auto. When these values are used for controls in the Grid layout, the control fills the cell that contains it. Auto sizing is supported for controls and for the Grid and StackPanel layouts.

• For controls that contain text, remove the Height and Width properties, and set the MinWidth or MinHeight properties. This prevents the text from scaling down to a size that's unreadable.

• To set proportional values for the RowDefinition and ColumnDefinition elements in a Grid layout, use relative Height and Width values. For example, to specify that one column is five times wider than another column, use "*" and "5*" for the Width properties in the ColumnDefinition elements.

Auto and Star Sizing

Auto sizing is used to allow controls to fit their content, even if the content changes size. Star sizing is used to distribute available space among the rows and columns of a grid by weighted proportions. In XAML, star values are expressed as * (or n*). For example, if you have a grid with four columns, you could set the widths of the columns to the values shown in the following table.

Column_1	Auto	The column will size to fit its content.
Column_2	*	After the Auto columns are calculated, the column gets part of the remaining width. Column 2 will be one-half as wide as Column 4.
Column_3	Auto	The column will size to fit its content.
Column_4	2*	After the Auto columns are calculated, the column gets part of the remaining width. Column 4 will be two times as wide as Column 2.

For more information about Auto and star sizing, see the GridUnitType enumeration.

Panel controls

The built-in layout panels in Windows Phone are Canvas, StackPanel, and Grid.

Canvas

Canvas defines an area within which you can explicitly position child elements by coordinates relative to the Canvas area. Canvas is useful for scenarios where the UI elements contained within it never move.

You can position the control inside the Canvas by specifying x and y coordinates. The x and y coordinates are specified by using the Canvas..::.Left and Canvas..::.Top attached properties. Canvas..::.Left specifies the object's distance from the left side of the containing Canvas (the x-coordinate), and Canvas..::.Top specifies the object's distance from the top of the containing Canvas (the y-coordinate).

The following XAML shows how to position a rectangle 30 pixels from the left and 200 pixels from the top of a Canvas.

<Canvas Background="Transparent">
    <Rectangle Canvas.Left="30" Canvas.Top="200"
        Fill="red" Width="200" Height="200" />
</Canvas>

The following illustration shows the output if you add the preceding XAML in the LayoutRoot after the StackPanel with the name TitlePanel.

StackPanel

The StackPanel is a simple layout panel that arranges its child elements into a single line that can be oriented horizontally or vertically. You can use the Orientation property to specify the direction of the child elements. The default value for the Orientation property is Vertical. StackPanel is typically used in scenarios where you want to arrange a small subsection of the UI on your page.

The following XAML shows how to create a vertical StackPanel of items.

<StackPanel Margin="20">
    <Rectangle Fill="Red" Width="50" Height="50" Margin="5" />
    <Rectangle Fill="Blue" Width="50" Height="50" Margin="5" />
    <Rectangle Fill="Green" Width="50" Height="50" Margin="5" />
    <Rectangle Fill="Purple" Width="50" Height="50" Margin="5" />
</StackPanel>

The preceding XAML will produce an output similar to that depicted in the following Windows Phone illustration.

Grid

The Grid control is the most flexible layout panel, and supports arranging controls in multi-row and multi-column layouts. You can specify a Grid's Row and Column definitions by using RowDefinitions and ColumnDefinitions properties that are declared immediately within the Grid control. You can position objects in specific cells of the Grid by using the Column and Row attached properties. You can distribute space within a column or a row by using Auto or star sizing. Auto and star sizing were explained earlier in this Quickstart. Content can span across multiple rows and columns by using the RowSpan and ColumnSpan attached properties.

Child elements of a Grid are drawn in the order in which they appear in markup or code. As a result, layered order (also known as z-order) can be achieved when elements share the same coordinates. For more information about z-order, see ZIndex.

The following XAML shows how to create a Grid with three rows and two columns. The height of the first and third rows is just large enough to contain the text. The height of the second row fills up the rest of the available height. The width of the columns is split equally within the available container width.

<Grid ShowGridLines="True" Margin="12,0,12,0">
    <Grid.RowDefinitions>
        <RowDefinition Height="auto" />
        <RowDefinition />
        <RowDefinition Height="auto" />
    </Grid.RowDefinitions>
    <Grid.ColumnDefinitions>
        <ColumnDefinition Width="*" />
        <ColumnDefinition Width="*" />
    </Grid.ColumnDefinitions>
    <TextBox Text="1st row 1st column" TextWrapping="Wrap" Grid.Column="0" Grid.Row="0" />
    <TextBox Text="3rd row 1st column" TextWrapping="Wrap" Grid.Column="0" Grid.Row="2" />
    <Button Content="1st row 2nd column" FontSize="17" Grid.Column="1" Grid.Row="0" />
    <Button Content="3rd row 2nd column" FontSize="17" Grid.Column="1" Grid.Row="2" />
</Grid>

The preceding XAML will produce an output similar to that depicted in the following illustration.

If you're creating a complex layout that isn't easily achieved by using Canvas, StackPanel, or Grid, you can create a custom panel, which allows you to define layout behavior for the panel's children. To do this, derive from Panel and override its MeasureOverride and ArrangeOverride methods.

See Also

Other Resources

Multi-resolution apps for Windows Phone 8

Quickstart: Screen orientation for Windows Phone 8