Contents
- Installation
- Usage
- Adding support for other types
- Gotchas
Installation
- Download the library
- Add a reference to it in your project
Or use NuGet:
http://www.nuget.org/List/Packages/WP7TombstoneHelper
Usage
Simple usage
Include a reference to the namespace:
In any pages that have something you may want to preserve during tombstoning, simply call
SaveState(e) in the
OnNavigatingFrom handler and
RestoreState() in the
OnNavigatedTo handler.
Note that I'm using OnNavingatingFrom method, rather than OnNavigatedFrom, as it allows us to detect the direction of navigation. This means we don't save state if we know we won't need it again. This can help improve the performance of the app.
protected override void OnNavigatingFrom(System.Windows.Navigation.NavigatingCancelEventArgs e)
{
this.SaveState(e);
}
protected override void OnNavigatedTo(System.Windows.Navigation.NavigationEventArgs e)
{
this.RestoreState();
}
Ensure that every object you want to be preserved has a
Name specified.
The code below is from "TextBoxes.xaml" in the demo project included with the source. It shows three textboxes, the middle of which won't have it's text automatically preserved during tombstoning.
<TextBlock Text="first (has name)" />
<TextBox Name="first" />
<TextBlock Text="second (doesn't have name)" />
<TextBox /><!--This TextBox does not have a name so it's contents won't be automatically saved and restored -->
<TextBlock Text="third (has name)" />
<TextBox Name="third" />
That's it!
Slightly more advanced usage
If you want to improve performance you can specify only the types of the controls which you want to be preserved when calling
SaveState().
eg:
this.SaveState(typeof(TextBox), typeof(PasswordBox), typeof(CheckBox));
or
this.SaveState(typeof(ScrollViewer));
or in a more generic style
this.SaveState<ScrollViewer>();
or
this.SaveState<ListBox, TextBox>();
Not only does this improve performance but it makes it easy to integrate this functionality to save some properties (typically the scroll position of a ListBox or ScrolViewer) where there is already a view model which preserves the data state.
Adding support for other types
- Add a new class to the project which implements ICanTombstone.
- Add the necessary code to implement the functionality. N.B. The key used for saving the state of the object should be a string comprising the name of the type and the name of the object separated by a '^' character.
- Add appropriate entries to AllTombstoneRestorers() and AllSupportedTombstoners() in "PhoneApplicationPageExtensions.cs".
If you are adding support for additional types then reviewing the exising implementations of
ICanTombstone is highly recommended.
Gotchas
You
may experience strange behaviour or unwanted side effects in the following situations
- If you have an event that is triggered upon setting the property that automatically preserved. e.g. If it's a TextBox and you're handling the TextChanged event—it may have too account for it being triggered additional times.
- If you are databinding the property which is has events or actions in response to setting it.
- If you are generating the UI in code at runtime.
- If you are also doing something with the State object yourself then do it after calling SaveState() as it will clear the contents of the state object to ensure it doen't have anything more than it needs in it.
If one of these scenarios does cause a problem then get in touch as there may be a workaround.