Windows Phone 8 : Orientation and the PhoneApplicationPage Class (part 2) - PhoneApplicationPage Orientation Property

PhoneApplicationPage Orientation Property

The PhoneApplicationPage includes an Orientation dependency property, which is shown in the following excerpt (take note of the set accessor):

public PageOrientation Orientation
{
    get
    {
        return (PageOrientation)base.GetValue(OrientationProperty);
    }
    [EditorBrowsable(EditorBrowsableState.Never)]
    set
    {
        if (Frame.IsInDesignMode())
        {
            base.SetValue(OrientationProperty, value);
        }
    }
}

You see that changing the page orientation at runtime is not as straightforward as it might first appear. The Orientation property’s set accessor has an effect only at design time and not at runtime. At runtime, the Orientation property indicates the physical orientation of the device, or the orientation of the emulator window. Setting the dependency property directly is also futile and has no effect on runtime page orientation either.

The Orientation property can be used in data binding expressions and allows you to adjust the layout depending on the availability of space. You can maximize space utilization by hiding or revealing content when the orientation changes. For example, when changing to a landscape orientation where horizontal space is more abundant, a TextBlock can be shown in the title section of an application. Conversely, in portrait mode, the TextBlock can be hidden to conserve space, as demonstrated by the following example:

<TextBlock Text="Application Title"
            Visibility="{Binding ElementName=Page, Path=Orientation,
            Converter={StaticResource PageOrientationToVisibilityConverter},
            ConverterParameter=Landscape}" />

You can see that the Orientation property of the PhoneApplicationPage is used to set the Visibility property of the TextBlock using a custom IValueConverter called PageOrientationToVisibilityConverter (see Listing 2), which is located in the WPUnleashed project in the downloadable sample code.

The converter’s ConvertTo method translates the PageOrientation enum value to a System.Windows.Visibility enum value. The ConverterParameter from the previous excerpt indicates when to show the UIElement. If the PageOrientation value is a portrait orientation, for example, and the ConverterParameter is equal to Portrait, then Visibility.Visible will be returned.

LISTING 2. PageOrientationToVisibilityConverter Class

public class PageOrientationToVisibilityConverter : IValueConverter
{
    public object Convert(object value, Type targetType,
        object parameter, CultureInfo culture)
    {
        var orientation = (PageOrientation)value;
        string showWhenOrientation
            = ArgumentValidator.AssertNotNullAndOfType<string>(
                parameter, "parameter").ToLower();

        if (showWhenOrientation != "portrait"
            && showWhenOrientation != "landscape")
        {
            throw new ArgumentException(
                "ConverterParameter must be either Portrait or Landscape.");
        }

        bool show;
        switch (orientation)
        {
            case PageOrientation.Portrait:
            case PageOrientation.PortraitDown:
            case PageOrientation.PortraitUp:
                show = showWhenOrientation == "portrait";
                break;
            case PageOrientation.Landscape:
            case PageOrientation.LandscapeLeft:
            case PageOrientation.LandscapeRight:
                show = showWhenOrientation == "landscape";
                break;
            default:
                throw new ArgumentException("Unknown orientation: "
                    + orientation);
        }

        return show ? Visibility.Visible : Visibility.Collapsed;
    }

    public object ConvertBack(object value, Type targetType,
        object parameter, CultureInfo culture)
    {
        throw new NotImplementedException();
    }
}