Windows Phone 8 : Orientation and the PhoneApplicationPage Class (part 1) - OrientationChanged Event

The PhoneApplicationPage class includes two orientation related properties: SupportedOrientations and Orientation.

The SupportedOrientations attribute allows you to restrict the orientation of the page and, if set to either Portrait or Landscape, prevent the orientation from being changed when the device is rotated. If the page is designed to support both portrait and landscape, set SupportedOrientation to PortraitOrLandscape, which allows the orientation to be switched automatically when the device is rotated.

The Orientation property indicates the actual orientation of the page and can be set only at design time.

When you create a new PhoneApplicationPage within Visual Studio, both SupportedOrientations and Orientation are set, by default, to Portrait in XAML.

1. OrientationChanged Event

Both the PhoneApplicationFrame and PhoneApplicationPage include an OrientationChanged event that allows you to detect when the orientation of the page changes. In addition, the PhoneApplicationPage includes an OnOrientationChanged virtual method. When the page orientation changes, the method is called, allowing you to update the UI, trigger animations, and so forth. See the following excerpt:

protected override void OnOrientationChanged(
                            OrientationChangedEventArgs e)
{
    base.OnOrientationChanged(e);
    /* Update UI, trigger animations etc. */
}

The OnOrientationChanged method is called before other OrientationChanged event handlers.

By using the Dispatcher to invoke layout changes, the correct height and width of the page can be determined after the OrientationChanged event has been handled, as shown in the following excerpt:

protected override void OnOrientationChanged(OrientationChangedEventArgs e)
{
    Debug.WriteLine("Orientation changed to " + e.Orientation.ToString("G"));

    Dispatcher.BeginInvoke(
        delegate
        {
            Debug.WriteLine(string.Format(
                "Using dispatcher: ActualWidth: {0}, ActualHeight: {1}",
                ActualWidth, ActualHeight));
        });

    Debug.WriteLine(string.Format(
        "Without dispatcher: ActualWidth: {0}, ActualHeight: {1}",
        ActualWidth, ActualHeight));

    base.OnOrientationChanged(e);
}

The following is the output when switching orientations:

Orientation changed to LandscapeLeft
Without dispatcher: ActualWidth: 0, ActualHeight: 0
Using dispatcher: ActualWidth: 800, ActualHeight: 480
Orientation changed to PortraitUp
Without dispatcher: ActualWidth: 800, ActualHeight: 480
Using dispatcher: ActualWidth: 480, ActualHeight: 800

The OrientionChanged event is always raised before the page is loaded. This explains the zero values for the ActualWidth and ActualHeight in the previous output. The Dispatcher allows the correct width and height values to be obtained because by the time each value is read, the page has already loaded and the properties are populated with the correct values.

The OrientationChangedEventArgs class contains an Orientation property, which is an enum of type PageOrientation, indicating the new page orientation. PageOrientation has the following values:

- Landscape

- LandscapeLeft

- LandscapeRight

- None

- Portrait

- PortraitDown

- PortraitUp

The only values you will ever see in the OrientationChangedEventArgs are, however, LandscapeLeft, LandscapeRight, and PortraitUp. These values indicate the location of the display in relation to the phone hardware buttons (see Figure 1).

FIGURE 1 Valid device orientations.

Although PortraitDown exists as an enum value, at the time of writing, no device supports this orientation, nor does the emulator.

To determine whether the OrientationChangedEventArgs.Orientation value is either landscape or portrait, the value can be ANDed with the PageOrientation.Landscape or PageOrientation.Portrait values, respectively. The PageOrientationExtensions class in the downloadable sample code includes two extension methods for performing this directly on a PageOrientation value (see Listing 1).

LISTING 1. PageOrientationExtensions Class

public static class PageOrientationExtensions
{
    public static bool IsLandscape(this PageOrientation pageOrientation)
    {
        return (pageOrientation & PageOrientation.Landscape) != 0;
    }

    public static bool IsPortrait(this PageOrientation pageOrientation)
    {
        return (pageOrientation & PageOrientation.Portrait) != 0;
    }
}