Windows Phone 7 (Mango) Tutorial - 3 - Know more about PhoneApplicationPage

In our last post of the series, we learned about the base class "Page" and Here in this post we will learn about "PhoneApplicationPage" which is root of any Windows Phone 7 page. Before jumping to the core in depth, a beginner must know all these things. As I am also exploring these for the first time, sharing the same knowledge with you.

I hope that, these series of posts will be helpful to a beginner. If you want to know more about PhoneApplicationPage class, read this post to learn about it.

Index - Windows Phone 7 (Mango) Tutorial

What is PhoneApplicationPage?

PhoneApplicationPage is the root of any Windows Phone 7 XAML page. If you already worked on Silverlight, you must be aware of that by default "UserControl" is the root of any Silverlight XAML page. Similarly, Phone 7 XAML has the root named "PhoneApplicationPage". As we described in our last post, every PhoneApplicationPage derives from "Page" which again derives from "UserControl". Hence, it is also nothing but a UserControl which has some additional features for Phone 7 application.

<phone:PhoneApplicationPage 

    x:Class="HelloWorldDemo.MainPage"

    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"

    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"

    xmlns:phone="clr-namespace:Microsoft.Phone.Controls;assembly=Microsoft.Phone"

    xmlns:shell="clr-namespace:Microsoft.Phone.Shell;assembly=Microsoft.Phone"

    SupportedOrientations="Portrait" Orientation="Portrait" shell:SystemTray.IsVisible="True">

PhoneApplicationPage derives from Page class and can be found in Microsoft.Phone.Controls namespace. It has three Dependency Properties called "SupportedOrientations", "Orientation" and "ApplicationBar".

Have a look into the class meta data here:

namespace Microsoft.Phone.Controls

{

    public class PhoneApplicationPage : Page

    {

        public static readonly DependencyProperty SupportedOrientationsProperty;

        public static readonly DependencyProperty OrientationProperty;

        public static readonly DependencyProperty ApplicationBarProperty;

        public PhoneApplicationPage();

        public SupportedPageOrientation SupportedOrientations { get; set; }

        public PageOrientation Orientation { get; [EditorBrowsable(EditorBrowsableState.Never)]

        set; }

        public IApplicationBar ApplicationBar { get; set; }

        public IDictionary<string, object> State { get; }

        ~PhoneApplicationPage();

        protected virtual void OnOrientationChanged(OrientationChangedEventArgs e);

        protected virtual void OnBackKeyPress(CancelEventArgs e);

        protected virtual void OnRemovedFromJournal(JournalEntryRemovedEventArgs e);

        public event EventHandler<OrientationChangedEventArgs> BeginLayoutChanged;

        public event EventHandler<OrientationChangedEventArgs> OrientationChanged;

        public event EventHandler<CancelEventArgs> BackKeyPress;

    }

}

Let's discuss about the three properties available in PhoneApplicationPage.

What is SupportedPageOrientation?

SupportedPageOrientations is a Dependency Property of enum type SupportedPageOrientation, present in the Microsoft.Phone.Controls namespace and contains three enum values called "Portrait", "Landscape" and "PortraitOrLandscape". It defines the property value to define the orientation supported by the application. If you define Portrait orientation your application will support only Portrait view, if declared as Landscape your application will support both left and right landscape view. The third property value defines that your application will support both Portrait and Landscape views.

namespace Microsoft.Phone.Controls

{

    public enum SupportedPageOrientation

    {

        Portrait = 1,

        Landscape = 2,

        PortraitOrLandscape = 3,

    }

}

What is PageOrientation?

PageOrientation is also a dependency property present in the Microsoft.Phone.Controls namespace. It defines the possible orientation of a Windows Phone 7 page.

namespace Microsoft.Phone.Controls

{

    public enum PageOrientation

    {

        None = 0,

        Portrait = 1,

        Landscape = 2,

        PortraitUp = 5,

        PortraitDown = 9,

        LandscapeLeft = 18,

        LandscapeRight = 34,

    }

}

From the meta data of the PageOrientation enum, you can easily understand about the property values. Use Portrait or Landscape property value to check the orientation of your application. According to the MSDN Documentation, if you want to check LandscapeLeft or LandscapeRight for Landscape orientation, check both of them and never check only left or right.

What is ApplicationBar?

This is a dependency property of type IApplicationBar which derives by the ApplicationBar class. It allows developers to create and display an application bar with 1-4 buttons and a set of text menu items for your Windows Phone application. IApplicationBar interface is part of Microsoft.Phone.Shell namespace and defines few properties as mentioned below:

namespace Microsoft.Phone.Shell

{

    public interface IApplicationBar

    {

        bool IsVisible { get; set; }

        double Opacity { get; set; }

        bool IsMenuEnabled { get; set; }

        Color BackgroundColor { get; set; }

        Color ForegroundColor { get; set; }

        IList Buttons { get; }

        IList MenuItems { get; }

        event EventHandler<ApplicationBarStateChangedEventArgs> StateChanged;

    }

}

Hope, this information helped you to learn about the PhoneApplicationPage. We will see the implementation of it in our next post. Till then  enjoy coding.