Improved page class.
for information on how to use the paging classes.
- Complex types can be used as navigation parameter (serialized using
- Navigate back on back key press and navigate back on alt-left and forward on alt-right
- These navigation triggers are disabled if a popup is visible
- On Windows Phone the back navigation is automatically triggered by the back button
- RegisterViewModel and BindViewModelToStatusBarProgress methods: See
- AnimationContext property: Specifies which FrameworkElement is used for page transition animation (see
MtFrame.PageAnimation property). If this is null, the page's root element is used as animation context.
Overloadable methods for page state handling ("thombstoning"):
- OnSaveState: Saves the page state when the app has been suspended.
- OnLoadState: Loads the page state when the app is resumed.
- IsSuspendable property: Defines if a page can be suspended (default: true). If this property is set to true, the page needs the ability to completely rebuild itself in
LoadState method using the state (set in SaveState) and the navigation parameter. On suspension, all pages after the first non-suspendable page are removed from the page stack, the current page is set to the last suspendable page in the page stack
and the states of all suspendable pages are saved using the
MtSuspensionManager. When resuming the app, these saved states are loaded and all the suspendable pages are recreated.
Overloadable methods for navigation handling:
- OnNavigatedTo: Called after navigated to the page.
- OnNavigatingFrom: Called before navigating from the page.
- OnNavigatingFromAsync method which can be used to show animations while navigating from a page or show a modal dialog (e.g. "Save changes?" dialog) and wait until the user closes the popup and cancel the navigation if necessary. The actual
navigating away from the page is triggered after awaiting for the task.
- OnNavigatedFrom: Called after navigating from the page.
The original WinRT page class is by default not cached after navigating away from it. This means that when you navigate away, you have to completely save its state, even the scroll positions and other details. Because most developers are not doing that correctly,
we improved the page cache handling tremendously and enabled page caching by default for the
class. This can be changed using the NavigationCacheMode
property. The page caching can also be disabled globally in the
class using the DisableCache
property to better test the saving and loading of page state described in the next section.
Save and load page state
A windows store app and windows phone app has to save and load page state when it is suspended and resumed. To handle these events, you have to override
of the page class:
protected override void OnSaveState(MtSaveStateEventArgs pageState)
protected override void OnLoadState(MtLoadStateEventArgs pageState)
myTextBox.Text = pageState.Get<string>("MyTest");
The main problem here is that this is not really MVVM friendly as most of the state - except for example the
position - is stored in the view model. This is why we should implement these methods on the view model. To make it very simple, just implement the interface
in your view model and register the view model in the constructor of your page:
Now the OnSaveState
methods of the view model are automatically called by the page object.
Running task in OnNavigatingFrom
Sometimes it is necessary to run asynchronous code in the OnNavigatingFrom
event handler and decide with its result whether to navigate away from the page or not. This was not possible with the original page class because it was called synchronously.
With the MtPage
class, you can simply override the OnNavigatingFromAsync
The following code shows a Yes/No-dialog when navigating from the page and only navigates when the user clicked yes:
protected override async Task OnNavigatingFromAsync(MtNavigatingCancelEventArgs e)
var msg = new TextMessage("Save changes?");
msg.Button = TextMessage.MessageButton.YesNoCancel;
if (msg.Result == TextMessage.MessageResult.Yes)
e.Cancel = msg.Result == TextMessage.MessageResult.Cancel;
- In the TopAppBar and BottomAppBar you can use the resources defined in the page object. However all resources which inherit from
DependencyObject are not copied to the app bars and are not available.
- Please do not add an async back key handler on a Windows Phone starting page, because it will not be possible to close the page with key back press.
Please help me solve this problem.
- This page class supports the Transitions property. However when used in Windows Phone Universal app the NavigationThemeTransition transition is not supported.
- A new transition animation system has been implemented. Check out the PageAnimation property on the
MtFrame class for more details.