Skip to content

MtPage

Jump to bottom
Rico Suter edited this page Jul 8, 2015 · 3 revisions
  • Package: MyToolkit.Extended
  • Platforms: WinRT, UWP

Improved page class.

Go to paging for information on how to use the paging classes.

Additional features

New features:

  • Complex types can be used as navigation parameter (serialized using DataContractSerializer)
  • 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 ViewModelHelper
  • 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.

Usage

Page caching

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 MtPage class. This can be changed using the NavigationCacheMode property. The page caching can also be disabled globally in the MtFrame 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 OnSaveState() and OnLoadState() of the page class:

protected override void OnSaveState(MtSaveStateEventArgs pageState)
{
    pageState.Set("MyTest", myTextBox.Text);
}

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 ScrollViewer 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 IStateHandlingViewModel in your view model and register the view model in the constructor of your page:

public MyPage()
{
    InitializeComponent();
    RegisterViewModel(Model, true);
}

Now the OnSaveState() and OnLoadState() 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() method.

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;

    await Messenger.SendAsync(msg);

    if (msg.Result == TextMessage.MessageResult.Yes)
        await SaveDocumentAsync();
    else
        e.Cancel = msg.Result == TextMessage.MessageResult.Cancel;
}

Notes

  • In the TopAppBar and BottomAppBar properties, 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.
Clone this wiki locally