Quickstart: Screen orientation 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 supports portrait and landscape screen orientations. This Quickstart describes how to work with orientation changes in Windows Phone.

This topic contains the following sections.

• Orientations
• Scrolling technique
• Grid layout technique
• Related Topics

Orientations

Windows Phone supports the following screen orientations:

• Portrait

• Landscape left

• Landscape right

Users can simply rotate the device to initiate a change from one orientation to another. When you're testing your app in the emulator, you can switch the screen orientation by clicking the buttons in the emulator toolbar. The orientation buttons have rectangles with arrows that indicate the orientation change.

In portrait orientation, the page is oriented vertically so that the height of the page is greater than its width.

In either of the two landscape orientations, the Status Bar and the Application Bar remain on the side of the screen that has the Power and the Start button, respectively. Landscape left has the Status Bar on the left and landscape right has the Status Bar on the right.

Portrait is the default orientation for apps and you must add additional code to support landscape. You can't specify only left or only right landscape orientation. If you support landscape orientation, you must support both left and right. To specify that your app supports portrait and landscape, you must set the SupportedOrientations property to PortraitOrLandscape either in the XAML or in the code.

There are different ways to display content in either portrait or landscape orientation. Two techniques are scrolling and grid layout.

Scrolling technique

The scrolling technique uses a StackPanel control that is placed within a ScrollViewer control. Use this technique if you're displaying content in a list or if you have different controls appearing one after another on the page. The StackPanel enables you to order the child elements one after another in your app and the ScrollViewer control enables you to scroll through the StackPanel if the UI elements don't fit on the screen when you switch from portrait to landscape.

To use the scrolling technique, you typically perform the following steps.

• Change the SupportedOrientations property of the page to PortraitOrLandscape.

• Replace the default Grid in the Content Panel section with a ScrollViewer and a StackPanel.

The following example shows a StackPanel and several controls within a ScrollViewer.

<ScrollViewer x:Name="ContentGrid" Grid.Row="1" VerticalScrollBarVisibility="Auto">
    <!--You must apply a background to the StackPanel control or you
    will be unable to pan the contents.-->
    <StackPanel Background="Transparent" >
        <!--Adding various controls and UI elements.-->
        <Button Content="This is a Button" />
        <Rectangle Width="100" Height="100" Margin="12,0"
            HorizontalAlignment="Left" Fill="{StaticResource PhoneAccentBrush}"/>
        <Rectangle Width="100" Height="100" HorizontalAlignment="Center"
            Fill="{StaticResource PhoneAccentBrush}"/>
        <Rectangle Width="100" Height="100" Margin="12,0"
            HorizontalAlignment="Right" Fill="{StaticResource PhoneAccentBrush}"/>
        <TextBlock Text="This is a line of text that will wrap in portrait
            orientation but not landscape orientation." TextWrapping="Wrap" />
        <CheckBox Content="A CheckBox"/>
        <RadioButton Content="A RadioButton" />
    </StackPanel>
</ScrollViewer> 

The following illustrations show the scrolling behavior for portrait and landscape orientations. The portrait orientation doesn't require scrolling, but the landscape orientation does require scrolling.

Grid layout technique

The grid layout technique positions UI elements in a Grid. When an orientation change occurs, you programmatically reposition elements into different cells of the Grid.

To use the grid layout technique, you typically perform the following steps.

1. Change the SupportedOrientations property of the page to PortraitOrLandscape.

2. Use a Grid for the content panel.

3. Create an OrientationChanged event handler and add code to reposition elements in the Grid.

The following example creates a 2 x 2 Grid to position an image and a collection of buttons. The OrientationChanged event handler repositions the elements within the Grid when the orientation is changed.

<Grid x:Name="ContentPanel" Grid.Row="1" Margin="12,0,12,0">
    <!--Create a 2 x 2 grid to store an image and button layout.-->
    <Grid.RowDefinitions>
        <RowDefinition Height="Auto"/>
        <RowDefinition Height="*"/>
    </Grid.RowDefinitions>
    <Grid.ColumnDefinitions>
        <ColumnDefinition Width="Auto"/>
        <ColumnDefinition Width="*"/>
    </Grid.ColumnDefinitions>
    <!--Add an image to the grid. Ensure the image height and width
        are set to 300 and 500 respectively for this example.-->
    <Image x:Name="Image1" Grid.Row="0" Grid.Column="0"
        Stretch="Fill" HorizontalAlignment="Center" Source="licorice.jpg"
        Height="300" Width="500"/>
    <!--Add a StackPanel with buttons to the row beneath the image.-->
    <StackPanel x:Name="buttonList" Grid.Row="1" Grid.Column="0"
        HorizontalAlignment="Center" >
        <Button Content="Action 1" />
        <Button Content="Action 2" />
        <Button Content="Action 3" />
        <Button Content="Action 4" />
    </StackPanel>
</Grid> 

private void PhoneApplicationPage_OrientationChanged(
object sender, OrientationChangedEventArgs e)
{
    // Switch the placement of the buttons based on an orientation change.
    if ((e.Orientation & PageOrientation.Portrait) == (PageOrientation.Portrait))
    {
        Grid.SetRow(buttonList, 1);
        Grid.SetColumn(buttonList, 0);
    }
    // If not in portrait, move buttonList content to visible row and column.
    else
    {
        Grid.SetRow(buttonList, 0);
        Grid.SetColumn(buttonList, 1);
    }
} 

Private Sub PhoneApplicationPage_OrientationChanged(ByVal sender As Object, ByVal e As OrientationChangedEventArgs)
    ' Switch the placement of the buttons based on an orientation change.
    If ((e.Orientation And PageOrientation.Portrait) _
    = PageOrientation.Portrait) Then
        Grid.SetRow(buttonList, 1)
        Grid.SetColumn(buttonList, 0)

    ' If not in portrait, move buttonList content to visible row and column.
    Else
        Grid.SetRow(buttonList, 0)
        Grid.SetColumn(buttonList, 1)
    End If
End Sub

The following illustrations show the grid layout behavior for portrait and landscape orientations. In the portrait orientation, the buttons are positioned on the bottom. In the landscape orientation, the buttons are positioned on the right.

See Also

Other Resources

Layout for Windows Phone 8

Quickstart: Creating a user interface with XAML for Windows Phone 8

Quickstart: Adding controls and handling events for Windows Phone 8