WP7 Navigation in depth | Navigation Framework

In the "WP7 Navigation in depth" series of two articles I am going to talk about the different Windows Phone 7 page navigation scenarios in depth.

"WP7 Navigation in depth | Navigation Framework" - I will explain the basic usage and all about the available public API in depth.

"WP7 Navigation in depth | Navigation controls" - I will talk about  using different  navigation controls.

In this article I will explain in details all you need to know about the WP7 Navigation framework. To begin with lets first define a sample WP7 App project and add some pages: MainPage.xaml, Pahe1.xaml and Page2.xaml. I will use these pages in order to demonstrate different ways of page navigation.

Windows Phone applications are based on a Silverlight page model where users can navigate forward through different screens of content. Also, you can move backward using the Windows Phone "back" hardware button. This model enables developers to:

• Easily create view-based applications that fit naturally into the Windows Phone navigation model

• Provide default transitions that match the Windows Phone look and feel

Generally the windows phone 7 navigation  is based on a frame/page model:

 

Note: You must use the PhoneApplicationFrame and PhoneApplicationPage types when developing your application and not the standard Silverlight Frame and Page types.

 

 

 

 

 

PhoneApplicationFrame

Only a single frame is available to the application with no exceptions. It contains the Page control and another elements like system tray and application bar. A frame includes the following characteristics:

• Exposes properties from a hosted page such as screen orientation

• Exposes a client area where pages are rendered

• Reserves space for the system tray and application bar

PhoneApplicationPage

A page fills the entire content region of the frame. It includes the following characteristics:

• Optionally surfaces its own application bar

There are three main ways to navigate between pages in your app:

• Using the PhoneApplicationPage virtual methods for handling the result of navigation.
• HyperlinkButton -   it provides NavigateUri property  which can be used to navigate to a page Uri.
  
• NavigationService - it provides methods, properties, and events to support navigation within a wp7 application.

Note: The PhoneApplicationPage class supports OnNavigatedTo, OnNavigatedFrom and OnNavigatingFrom  virtual methods for handling the result of navigation:

1 2 3 4 5 6

protected override void OnNavigatedFrom(NavigationEventArgs e) {   base.OnNavigatedFrom(e);           // some code here }

Note: Make sure that the Root of your application is set to the PhoneApplicationFrame(this is set by default to every wp7 app project). The code is usually placed in the App.xaml.cs and the code looks like:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16

private void InitializePhoneApplication() {     if (phoneApplicationInitialized)         return;       // Create the frame but don't set it as RootVisual yet; this allows the splash     // screen to remain active until the application is ready to render.     RootFrame = new PhoneApplicationFrame();     RootFrame.Navigated += CompleteInitializePhoneApplication;       // Handle navigation failures     RootFrame.NavigationFailed += RootFrame_NavigationFailed;       // Ensure we don't initialize again     phoneApplicationInitialized = true; }

Once your frame is created, the runtime navigates to a startup page. In WP7 the situation is a little bit different than in Silverlight. Instead of setting the startup page in  App.xaml.cs  the WP7 uses WMAppManifest.xaml file which contains the so called tasks.  Just go to Properties folder and select WMAppManifest.xaml as shown in the sample screen shot. The task section looks like:

1 2 3

<Tasks>   <DefaultTask  Name ="_default" NavigationPage="MainPage.xaml"/> Tasks>

Here is the place where you can change the start up page using the  NavigationPage property.

HyperlinkButton

This is the easiest way to set up navigation. All you need to do is just to create a hyperlink button on one page and set the NavigateUri property to the name of the page that you want to navigate to. Lets make a page called Page1.xaml  in the main root of the project.  The code for accomplishing this is as follows:

1	<HyperlinkButton Content="HyperlinkButton" NavigateUri="/Page1.xaml"/>

Note: HyperlinkButton only navigates between pages. You can use WebBrowserTask to navigate to web uris .

NavigationService

If you need a more flexible way of navigation then use the NavigationService class. This class contains a number of methods, events and properties to help you make your navigation.The NavigationService exists on the Application and Page classes.

Key Methods

• GoBack() -   Navigates to the most recent entry in the back navigation history, or throws an exception if no entry exists in back navigation.
• GoForward() -    Navigates to the most recent entry in the forward navigation history, or throws an exception if no entry exists in forward navigation.
• Navigate(Uri) -    Navigates to the content specified by the uniform resource identifier (URI).

Note:Although the GoBack()  method was utilized in this example, the hardware back key would also have the effect of returning to the previous page.

Key Properties

• CanGoBack    - Gets a value that indicates whether there is at least one entry in the back navigation history.
• CanGoForward  -   Gets a value that indicates whether there is at least one entry in the forward navigation history.
• CurrentSource -    Gets the uniform resource identifier (URI) of the content that is currently displayed.
• Source -    Gets or sets the uniform resource identifier (URI) of the current content or the content that is being navigated to.

Note:For Windows Phone GoForward() will always throw an exception because there is no forward navigation stack.

Key Events

• FragmentNavigation   -  Occurs when navigation to a content fragment begins.
• Navigated  -   Occurs when the content that is being navigated to has been found and is available.
• Navigating    - Occurs when a new navigation is requested.

Lets say that we  want to navigate to Page1.xaml  when clicking on a button and after that return back to MainPage.xaml using the NavigationServoce API. The code for accomplishing this is as follows:

1	MainPage.cs

1 2 3 4

private void btnPage1_Click(object sender, RoutedEventArgs e) {     NavigationService.Navigate(new Uri("/Page1.xaml", UriKind.Relative)); }

1

Page1.cs

1 2 3 4 5 6 7

private void btnBack_Click(object sender, RoutedEventArgs e) {     if (this.NavigationService.CanGoBack)     {         NavigationService.GoBack();     } }

Passing Data between Pages

When we want to pass some data between pages we have to :

• form a query string
• use the NavigationContext.

The NavigationContext exists on the Application and Page classes.  The purpose of this class is to expose the query string of the navigation URI so that we can use it to pass parameters between pages while navigating in an easy way.

The code is as follows:

1	MainPage.cs

1 2	string parameter = "Passing Parameter Test"; NavigationService.Navigate(new Uri(string.Format("/Page2.xaml?parameter={0}", parameter), UriKind.Relative));

In this case we have a string parameter in MainPage and want to pass it to Page2.  When we reach the navigated page the NavigationContext is used  to retrieve the specific information about the passing parameter. The code is as follows:

1

Page2.cs

1 2 3 4 5 6

protected override void OnNavigatedTo(System.Windows.Navigation.NavigationEventArgs e) {     base.OnNavigatedTo(e);     string newparameter = this.NavigationContext.QueryString["parameter"];     this.textLabel.Text = newparameter; }

Note: It is important to override the OnNavigatedTo and after that you can use the NavigationContext.

Another popular syntax is :

1 2 3 4 5

string parameter = string.Empty; if (NavigationContext.QueryString.TryGetValue("parameter", out parameter)) {     this.textLabel.Text = parameter; }

That was all about the navigation framework and the end of "WP7 Navigation in depth | Navigation Framework" article. In the next post "WP7 Navigation in depth | Navigation controls" I will talk about using different  navigation controls.

I hope that the article was helpful. The full source code is available here: