Frame, Page, and Navigation Enhancements for Windows Phone

The NavigatingCancelEventArgs class has a Cancel property that can be set to cancel a navigation that has been requested. For certain scenarios, such as 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. This can cause your application to get into an inconsistent state where it believes it has canceled a navigation, but tries to succeed regardless—for example, having a page of content that wants a cancel navigation to show a “Do you want to save changes?” dialog. However, if the navigation cannot be canceled, there must be an alternate way to save these changes.

To determine whether a navigation is truly cancelable, a new Boolean property, IsCancelable, has been added to 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;
                }
            }

        }

In Windows Phone, 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 NavigationEventArgs 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.

An application can detect a navigation to an external application because the URI passed in the navigation events is app://external/. However, in the previous release, there was no direct way to detect that an incoming navigation was from an external source. This information is useful for customizing animations specific for the different types of animations.

To enable this functionality, the Boolean property IsNavigationInitiator has been added to the NavigationEventArgs and NavigationCancelEventArgs 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.

The BackStack property returns a list of entries in the back stack.

The RemoveBackEntry method is used to remove 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 call this method multiple times. This API is synchronous and must be called from the UI thread.

The JournalEntryRemoved event has been added to 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, that is the journal entry of the item being removed.

The PhoneApplicationFrame class gains the same new 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 now exposed in the PhoneApplicationFrame class. The frame can fire the event directly before the active page receives it and it can be canceled.

The following API changes have been made to the PhoneApplicationPage class:

• 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 is for developers to place all of their cleanup code in a single event. You should not use this method to save data, perform animations, or load and save page state; these things should be done in the navigation events. Again, its purpose is to notify the page that it is being removed from the journal so it can release resources, and ensure it is eligible for garbage collection.

• There is a new JournalEntry class that it is available to user code. The Source property is now accessible and read-only.

The system tray now supports opacity and colors similar to the application bar. The following public read/write attached properties can be attached to a PhoneApplicationPage instance:

• BackgroundColor

• ForegroundColor

• Opacity

• ProgressIndicator

Note:
Again, these properties can be set on the page. The ProgressIndicator property is discussed more in the next section.

The progress indicator is used to indicate the progress of an operation. The system tray and progress indicator are in a parent-child relationship. Hiding the system tray hides the progress indicator regardless of the indicator visibility. The following are the 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 – renders the progress indicator as a meter or three flying dots