How to handle orientation changes on Windows Phone

[This documentation is preliminary and is subject to change.]

July 25, 2012

Applies to: Windows Phone 8 Developer Preview | Windows Phone OS 7.1

This topic provides information about how to work with orientation changes in Windows Phone to provide organized, structured UI content in your app. There are three possible orientations available on a Windows Phone, portrait and landscape (left or right). Portrait is a vertical positioning of the page content, and landscape is a horizontal representation of the page content. Users can simply rotate the device to initiate a change from one orientation to another and vice versa. For an app to provide orientation support, you must configure the SupportedOrientations property to PortraitOrLandscape either in the XAML or in the code. The following sections provide examples of two mechanisms for displaying content in either the portrait or landscape orientation:

  • Auto-sizing and scrolling – This example uses a StackPanel control working in conjunction with a ScrollViewer control to support both orientations. This is a good, simple method to use if content appears in a list or if different controls appear one after another on the page.

  • Grid Layout – This example places controls into a grid and moves element positioning within the grid cells based on the selected orientation.

Note

This topic is based on C# development; however, Visual Basic code is also provided.

This topic contains the following sections.

  • Using auto-sizing and scrolling
  • Using a grid layout

Using auto-sizing and scrolling

In this section, you enable both portrait and landscape mode in the SupportedOrientations property, and place a group of controls within the ScrollViewer and StackPanel controls.

To auto-size and scroll contents in both orientations

  1. Create a new project by selecting the File | New Project menu command.

  2. The New Project window is displayed. Expand the Visual C# templates, and then select the Windows Phone templates.

  3. Select the Windows Phone Application template. Fill in the project name as desired.

  4. On MainPage.xaml, in the XAML code, ensure that the SupportedOrientations property is set to portrait and landscape orientation under phone:PhoneApplicationPage. If it is not, modify it to the following:

    SupportedOrientations=”PortraitOrLandscape”
    

    Note

    By setting the SupportedOrientations property to both portrait and landscape, your app will support both modes. You can also set this property in the designer when selecting the PhoneApplicationPage control. To select the PhoneApplicationPage control, click the white space area outside of the emulator window.

  5. In this step, you embed a StackPanel control within a ScrollViewer control. A StackPanel control allows you to order controls one after another in your app, and the ScrollViewer control allows you to scroll through the StackPanel contents if the UI elements fall off the screen. This is the case when you switch to the landscape orientation in the emulator or on a device. On MainPage.xaml, add the following code to the XAML code under the Content Panel section toward the bottom of the page. The comment in the front of the section is “<!--ContentPanel - place additional content here-->.” Remove the opening and closing Grid tags that already populate that section.

            <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 sample that will wrap in portrait mode but not landscape.” TextWrapping="Wrap"  />
                    <CheckBox Content="A CheckBox" />
                    <RadioButton Content="A RadioButton" />
                </StackPanel>
            </ScrollViewer>
    
  6. Run the app by selecting the Debug | Start Debugging menu command. This opens the emulator window and launches the app. When the app is running, you can switch the screen orientation from portrait to landscape by clicking the orientation left or right button on the emulator toolbar. Each button has a curved arrow over a box. The final result is a portrait rendering of ordered UI elements that does not require scrolling followed by a landscape representation that does require scrolling.

 

AP_Con_Orien_Scroll1

Using a grid layout

In this example, you create a grid to support UI elements, and then have your app reposition those elements within the grid based on an orientation change. This exercise involves creating a 2 x 2 grid to support an image and a collection of buttons. Next, you create an OrientationChanged event handler and supply code that reorganizes these UI elements within the grid when you switch from portrait to landscape mode or vice versa.

To use a grid layout for orientation changes

  1. Create a new project by selecting the File | New Project menu command.

  2. The New Project window is displayed. Expand the Visual C# templates, and then select the Windows Phone templates.

  3. Select the Windows Phone Application template. Fill in the project name as desired.

  4. On MainPage.xaml, in the XAML code, ensure that the SupportedOrientations property is set to portrait and landscape orientation under phone:PhoneApplicationPage. If it is not, then modify it to the following:

    SupportedOrientations=”PortraitOrLandscape”
    
  5. Next, you add the code to create the 2 x 2 grid, add an image to the grid, and add a StackPanel control containing buttons to the grid. On MainPage.xaml, add the following code to the XAML under the ContentPanel section toward the bottom of the page. The comment in front of the section is “<!--ContentPanel - place additional content here-->.”Add the code between the Grid tags that already populate that section.

                <!--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 that 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="TestImage.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>
    

    Note

    In this exercise, you can use any image. The example TestImage.jpg must be replaced with a valid image name and source path. Also, you can use any name for the button controls.

  6. On MainPage.xaml, in the XAML code, add the following code to the top of the page under phone:PhoneApplicationPage.

    OrientationChanged="PhoneApplicationPage_OrientationChanged"
    

    Note

    When typing OrientationChanged, you have the ability to create a “<New Event Handler>” through IntelliSense. If you select this option, it creates the handler for you with the default name of "PhoneApplicationPage_OrientationChanged."

  7. Go to MainPage.xaml.cs and find the event handler. The following code switches the position of the button list in the grid based on an orientation change.

    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 the portrait mode, move buttonList content to a 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 the portrait mode, move buttonList content to a visible row and column.
    
            Else
                Grid.SetRow(buttonList, 0)
                Grid.SetColumn(buttonList, 1)
    
            End If
    
        End Sub
    
    Important noteImportant Note:

    If you do not add this code to the app, the button content and the image remain stacked as opposed to being side-by-side in a landscape orientation. The buttons would be only partially visible or not visible at all.

  8. Run the app by selecting the Debug | Start Debugging menu command. This opens the emulator window and launches the app. When the app is running, you can switch the screen orientation from portrait to landscape by clicking the orientation left or right buttons on the emulator toolbar. Each button has a curved arrow over a box. You should see the buttons reoriented from the bottom part of the screen to the right side of the screen.

 

AP_Con_Orientation(Port)