Frame, page, and navigation features for Windows Phone 8
[ This article is for Windows Phone 8 developers. If you’re developing for Windows 10, see the latest documentation. ]
This topic describes some of the features of the Windows Phone navigation model and the frame and page architecture. These features have been added or enhanced since the original release of Windows Phone.
This topic contains the following sections.
Navigation APIs
Here are some of the features of the navigation APIs.
Determine whether navigation can be canceled
The NavigatingCancelEventArgs class has a Cancel property that can be set to cancel a navigation that has been requested. For certain scenarios, however – for example, when the navigation is initiated by the system rather than by the user - the navigation is not cancelable, and setting the Cancel property has no effect. If your app handles these scenarios incorrectly, the user can lose changes, because it’s not possible to cancel the navigation and stay on the current page. If the navigation cannot be canceled, there must be another way to save the user’s changes.
To determine whether a navigation is truly cancelable, a Boolean property, IsCancelable, is available in the NavigatingCancelEventArgs class. If true, the navigation can be canceled; otherwise, navigation cannot be canceled. The following code illustrates how to check whether a navigation is cancelable and ask the user whether they want to cancel the navigation:
protected override void OnNavigatingFrom(NavigatingCancelEventArgs e)
{
base.OnNavigatingFrom(e);
// If the navigation can be canceled, ask the user if they want to cancel
if (e.IsCancelable)
{
MessageBoxResult result = MessageBox.Show("Do you want to stay here?", "Confirm Navigation from Page", MessageBoxButton.OKCancel);
if (result == MessageBoxResult.OK)
{
// User wants to stay here
e.Cancel = true;
return;
}
}
}
Detect the navigation direction for page transitions
Page transition animations depend on the direction of the navigation, either forward or back. To indicate the type of navigation that is occurring, a read-only NavigationMode property is available on the NavigationMode class along with a constructor overload to provide the value of the property. If the constructor is not used, the default value of NavigationMode is New, which indicates that the user is navigating to new content.
Detect navigation to an external app
An application can detect a navigation to an external application because the URI passed in the navigation events is app://external/. However, in the original release of Windows Phone, there was no direct way to detect that an incoming navigation was from an external source. This information is useful for customizing animations for the different types of navigation.
To enable this functionality, the Boolean property IsNavigationInitiator is available in the NavigationMode and NavigatingCancelEventArgs classes. This property is set to false for all cases where a navigation is either to or from an external application or the Start screen. It is set to true when the navigation is internal to the application. A new constructor overload is also provided to enable setting the value of this property. If it is not set, the default value is true, which indicates that the navigation is internal to the app.
Working with the back stack
The back stack is an application’s navigation history. Each entry in the back stack is a URI that represents a page. There can be multiple entries in the back stack for a page, but each entry refers to a different instance of the page. Here are some of the scenarios supported by the NavigationService API.
To replace the current page with a new page, navigate forward to the new page and then remove the top of the back stack.
To remove all pages up to a given page, which is typically the first page, remove all the intervening pages and navigate back to the first page.
To clear the entire back stack and replace it with the specified page, navigate forward to the new page and then remove all the entries in the back stack.
For more information about working with the back stack, see How to navigate using the back stack for Windows Phone 8.
BackStack property
The BackStack property returns a list of entries in the back stack.
RemoveBackEntry method
The RemoveBackEntry method removes the most recent entry from the back stack, or throws an InvalidOperationException if there are no more entries to remove. If you want to remove more than one item, you have to call this method multiple times. This API is synchronous and must be called from the UI thread.
JournalEntryRemoved event
The JournalEntryRemoved event is available in the NavigationService class. This event is raised during a RemoveBackEntry operation or during a normal back navigation after the Navigated event has been raised.
The JournalEntryRemovedEventArgs class has a single read-only property, Entry, which is the journal entry of the item being removed.
Frame and page features
Here are some of the features of the PhoneApplicationFrame and PhoneApplicationPage classes.
PhoneApplicationFrame
The PhoneApplicationFrame has some of the same members as the NavigationService class. This includes the RemoveBackEntry()()() method, the JournalEntryRemoved event, and the BackStack property. These all work the same as the members in NavigationService.
Also, the BackKeyPress event is available in the PhoneApplicationFrame class. The frame can handle the event directly before the active page receives it and the key press can be canceled.
PhoneApplicationPage
The OnRemovedFromJournal(JournalEntryRemovedEventArgs) method is called on a page after it has been removed from the journal through the RemoveBackEntry()()() method. It is also called after the OnNavigatedFrom(NavigationEventArgs) override in a normal back navigation. The purpose of this event is to notify the page that it is being removed from the journal so it can release resources, and ensure that it’s eligible for garbage collection. This event lets you place all of your cleanup code in a single event. Do not use this event, however, to save data, play animations, or load and save page state; these actions belong in the navigation events.
A JournalEntry class is available. Its Source property is also accessible and read-only.
System tray features
The system tray supports opacity and colors similar to the application bar. The following public read/write attached properties of the system tray can be attached to a PhoneApplicationPage instance:
ProgressIndicator
The ProgressIndicator in the system tray is used to indicate the progress of an operation.
To use the ProgressIndicator without affecting the layout of the page, set the value of the Opacity property of the SystemTray to 0 (zero).
The ProgressIndicator has the following public properties:
IsVisible – determines whether the indicator is active
Text – short text string to show when work is performed
Value – progress value from 0 to 1
IsIndeterminate – when true, renders the progress indicator as several scrolling dots
Hiding the system tray hides the progress indicator regardless of the visibility of the indicator itself.