Quickstart: Navigating between pages (Windows Store apps using C#/VB/C++ and XAML)

This topic discusses basic navigation concepts and demonstrates how to create an app that navigates between two pages.

Roadmap: How does this topic relate to others? See:

• Roadmap for Windows Store apps using C# or Visual Basic
• Roadmap for Windows Store apps using C++

You can create multiple pages for your Windows Store app and support the user navigating between the pages within the app, similar to how you navigate through pages on a single website. Microsoft Visual Studio Express 2012 for Windows 8 has page templates that provide basic navigation support for Windows Store apps using C# or Microsoft Visual Basic. In this topic, we use the page templates to create a simple app that supports navigation.

Note  

When we discuss navigation for Windows Store apps, we mean navigating between pages within an app, not navigating between apps.

Prerequisites

This topic assumes that you can create a basic Windows Store app using C# or Visual Basic. For instructions on creating your first Windows Store app, see Create your first Windows Store app using C# or Visual Basic.

Creating the navigation app

To create a new project

1. Start Visual Studio Express 2012 for Windows 8.
2. Select File > New Project. The New Project dialog box opens.
3. In the Installed pane, expand Visual C# or Visual Basic.
4. Select the Windows Store app template type.
5. In the center pane, select Blank Application.
6. Enter a name for the project. In this topic, we'll call the project NavigationQuickstart.
7. Click OK. Your project files are created.

Next, add two pages to the project. These act as the pages we navigate between. Do the following steps two times to add two pages.

To add a page to an app

1. Select Project > Add New Item. The Add New Item dialog box opens.
2. In the Installed pane, expand Visual C# or Visual Basic.
3. Pick the Windows Store app template type.
4. In the center pane, select Basic Page.
5. Click Add.

After you have done the previous steps two times, the following files should have been added to your project.

• BasicPage1.Xaml
• BasicPage1.Xaml.cs or BasicPage1.Xaml.vb
• BasicPage2.Xaml
• BasicPage2.Xaml.cs or BasicPage2.Xaml.vb

Now we need to use the pages we added in the app. Make the following changes to BasicPage1.xaml.

• Find the TextBlock element named pageTitle and change the Text property to Page 1. The XAML should look like this:

  XAML

  Copy

  
  
  <TextBlock x:Name="pageTitle" Grid.Column="1" Text="Page 1" 
             Style="{StaticResource PageHeaderTextStyle}"/>
  
  

• Add the following XAML as a second child element to the root Grid. The StackPanel element should be a sibling to the Grid that contains the back button and page title.

  XAML

  Copy

  
  <StackPanel Grid.Row="1"
              Margin="120,0,120,60">
      <HyperlinkButton Content="Click to go to page 2" Click="HyperlinkButton_Click_1"/>
  </StackPanel>
  
  
  

Make the following changes to BasicPage2.xaml.

• Find the TextBlock element named pageTitle and change the Text property to Page 2. The XAML should look like this:

  XAML

  Copy

  
  
  <TextBlock x:Name="pageTitle" Grid.Column="1" Text="Page 2" 
             Style="{StaticResource PageHeaderTextStyle}"/>
  
  

• Add the following XAML as a second child element to the root Grid. The StackPanel element should be a sibling to the Grid that contains the back button and page title.

  XAML

  Copy

  
  <StackPanel Grid.Row="1"
              Margin="120,0,120,60">
      <TextBlock HorizontalAlignment="Left" Name="tb1" Text="Hello World!"/>
  </StackPanel>
  
  
  

Add the following code to the BasicPage1 class in BasicPage1.Xaml.cs or BasicPage1.Xaml.vb

private void HyperlinkButton_Click_1(object sender, RoutedEventArgs e)
{
    this.Frame.Navigate(typeof(BasicPage2));
}

Now that we've prepared the new pages, we need to make BasicPage1 the first thing that appears when the app starts. Open app.xaml.cs/vb and change the OnLaunched method to call Frame.Navigate by using BasicPage1 instead of the BlankPage. The entire OnLaunched method should look like the following:

protected override void OnLaunched(LaunchActivatedEventArgs args)
{
    // Create a Frame to act navigation context and navigate to the first page
    var rootFrame = new Frame();
    rootFrame.Navigate(typeof(BasicPage1));

    // Place the frame in the current window and ensure that it is active
    Window.Current.Content = rootFrame;
    Window.Current.Activate();
}

Now you are ready to test the app. Start the app, and click the link that says Click to go to page 2. The second page should appear that says "Page 2" at the top. Notice that there is a back button to the left of the page title. Click the button to return to the first page.

The Frame and Page classes

Before we add more functionality to our app, let's look at how the pages we added provide navigation support for the app. The Frame class is primarily responsible for navigation and implements methods such as Navigate, GoBack, and GoForward. You use the Navigate method to display content in the Frame. In the previous example, the App.OnLaunched method creates a Frame and passes BasicPage1 to the Navigate method. Then the method sets the content of the app's current window to the Frame. The result is that the app's window contains a Frame that contains BasicPage1

BasicPage1 is an indirect subclass of the Page class. The Page class has a Frame property, a read-only property that gets the Frame that contains the Page. When the Click event handler of the HyperlinkButton calls Frame.Navigate(typeof(BasicPage2)), the Frame in the app's window displays the content of BasicPage2.

Navigation support in page templates

When we created the navigation pages, we used the Basic page template. This template, and other templates that support navigation, creates a page that provides a Back button in the top left corner of the page. The button is styled to be visible only when the button is enabled. The button's IsEnabled property is bound to the Frame.CanGoBack property. This is why you don't see the Back button on the first page but you see it on the second page.

The Basic Page template creates a class that inherits from the LayoutAwarePage class, which is a class that is added to your project in Common/LayoutAwarePage.cs or Common/LayoutAwarePage.vb. The LayoutAwarePage class defines the methods GoBack and GoHome. The Back button on the page invokes the LayoutAwarePage.GoBack method and the Home button invokes the LayoutAwarePage.GoHome method.

The following page templates offer this same navigation support.

• Basic page
• Group Detail page
• Grouped Items page
• Item Detail page
• Items page
• Split page

Passing information between pages

Our app navigates between two pages, but it really doesn't do anything interesting yet. Often, when an app has multiple pages, the pages need to share information. Let's pass some information from the first page to the second page.

In BasicPage1.xaml, replace the StackPanel that you added earlier with the following code.

<StackPanel Grid.Row="1"
    Margin="120,0,120,60">
    <TextBlock Text="Enter your name"/>
    <TextBox Width="200" HorizontalAlignment="Left" Name="tb1"/>
    <HyperlinkButton Content="Click to go to page 2" Click="HyperlinkButton_Click_1"/>
</StackPanel>

In BasicPage1.xaml.cs or BasicPage1.xaml.vb, replace the HyperlinkButton_Click_1 event handler with the following code.

private void HyperlinkButton_Click_1(object sender, RoutedEventArgs e)
{
    this.Frame.Navigate(typeof(BasicPage2), tb1.Text);
}

In BasicPage2.xaml.cs or BasicPage2.xaml.vb, replace the empty OnNavigatedTo method with the following code.

protected override void OnNavigatedTo(NavigationEventArgs e)
{
    string name = e.Parameter as string;

    if (!string.IsNullOrWhiteSpace(name))
    {
        tb1.Text = "Hello, " + name;
    }
    else
    {
        tb1.Text = "Name is required.  Go back and enter a name.";
    }
}

Run the app, type your name in the text box, and then click the link that says Click to go to page 2. When you called this.Frame.Navigate(typeof(BasicPage2), tb1.Text); in the Click event of the HyperlinkButton, the tb1.Text property is passed when BasicPage2 loads. Then, the OnNavigatedTo method of BlankPage2 gets the value from the NavigationEventArgs.Parameter property and uses it to display a message.

Caching a page

When you ran the last example, you might have noticed that if you click the Back button on Page 2, the TextBox on Page 1 is empty when it appears. Let's suppose that the user of the app wants to go back and make a change on the previous page after viewing the results of Page 2. If Page 1 had many fields to fill in, the user would not be happy to see all empty fields when the app went back to that page. You can specify that a page be cached by using the NavigationCacheMode property. In the constructor of BasicPage1, set NavigationCacheMode to Enabled.

public BasicPage1()
{
    this.InitializeComponent();

    this.NavigationCacheMode = 
        Windows.UI.Xaml.Navigation.NavigationCacheMode.Enabled;
}

Now when you run the app and navigate from Page 2 back to Page 1, the TextBox on Page 1 retains its value.

Summary

In this topic you learned how to create a simple app that navigates between pages. You learned how to pass information from one page to another and also how to specify that a page's state should be cached.

Related topics

Roadmap for creating apps using C#, C++, or VB

Build date: 11/9/2012