Namespaces

Variants
Actions

Please note that as of October 24, 2014, the Nokia Developer Wiki will no longer be accepting user contributions, including new entries, edits and comments, as we begin transitioning to our new home, in the Windows Phone Development Wiki. We plan to move over the majority of the existing entries over the next few weeks. Thanks for all your past and future contributions.

(Difference between revisions)

Tombstoning helper for Windows Phone 7

From Wiki
Jump to: navigation, search
riussi (Talk | contribs)
(Riussi -)
hamishwillee (Talk | contribs)
m (Hamishwillee - Fix categories)
 
(11 intermediate revisions by 2 users not shown)
Line 1: Line 1:
[[Category:Windows Phone]][[Category:Code Snippet]][[Category:Files/Data]]
+
[[Category:Files/Data on Windows Phone]][[Category:Application Framework on Windows Phone]][[Category:Code Snippet]][[Category:XAML]][[Category:Windows Phone 7.5]]
{{Abstract|This article explains how to use tombstone helper to persist your pages data between navigation }}
+
{{Abstract|This article explains how to use [http://tombstonehelper.codeplex.com/ TombstoneHelper], a small library which makes it easy to persist page data during navigation.}}
 
+
{{SeeAlso|
 +
* [http://tombstonehelper.codeplex.com/ Home Page] (CodePlex)
 +
* [http://tombstonehelper.codeplex.com/documentation Documentation] (CodePlex)
 +
}}
 
{{ArticleMetaData <!-- v1.2 -->
 
{{ArticleMetaData <!-- v1.2 -->
 
|sourcecode= <!-- Link to example source code e.g. [[Media:The Code Example ZIP.zip]] -->
 
|sourcecode= <!-- Link to example source code e.g. [[Media:The Code Example ZIP.zip]] -->
 
|installfile= <!-- Link to installation file (e.g. [[Media:The Installation File.sis]]) -->
 
|installfile= <!-- Link to installation file (e.g. [[Media:The Installation File.sis]]) -->
|devices= <!-- Devices tested against - e.g. ''devices=Nokia 6131 NFC, Nokia C7-00'') -->
+
|devices= Lumia 800
|sdk= <!-- SDK(s) built and tested against (e.g. [http://linktosdkdownload/ Qt SDK 1.1.4]) -->
+
|sdk= Windows Phone 7.1 SDK
|platform= Windows Phone 7
+
|platform= Windows Phone 7.5 (Mango)
 
|devicecompatability= <!-- Compatible devices e.g.: All* (must have internal GPS) -->
 
|devicecompatability= <!-- Compatible devices e.g.: All* (must have internal GPS) -->
|dependencies= <!-- Any other/external dependencies e.g.: Google Maps Api v1.0 -->  
+
|dependencies= <!-- Any other/external dependencies e.g.: Google Maps Api v1.0 -->
|signing=<!-- Signing requirements - empty or one of: Self-Signed, DevCert, Manufacturer -->
+
|signing= <!-- Signing requirements - empty or one of: Self-Signed, DevCert, Manufacturer -->
 
|capabilities= <!-- Capabilities required by the article/code example (e.g. Location, NetworkServices. -->
 
|capabilities= <!-- Capabilities required by the article/code example (e.g. Location, NetworkServices. -->
|keywords= tombstoning, wp7
+
|keywords= Tombstoning, OnNavigatingFrom, OnNavigatingTo
 
|language= <!-- Language category code for non-English topics - e.g. Lang-Chinese -->
 
|language= <!-- Language category code for non-English topics - e.g. Lang-Chinese -->
 
|translated-by= <!-- [[User:XXXX]] -->
 
|translated-by= <!-- [[User:XXXX]] -->
|translated-from-title= <!-- Title only -->  
+
|translated-from-title= <!-- Title only -->
 
|translated-from-id= <!-- Id of translated revision -->
 
|translated-from-id= <!-- Id of translated revision -->
|review-by=<!-- After re-review: [[User:username]] -->
+
|review-by= <!-- After re-review: [[User:username]] -->
 
|review-timestamp= <!-- After re-review: YYYYMMDD -->
 
|review-timestamp= <!-- After re-review: YYYYMMDD -->
 
|update-by= <!-- After significant update: [[User:username]]-->
 
|update-by= <!-- After significant update: [[User:username]]-->
Line 27: Line 30:
 
== Introduction ==
 
== Introduction ==
  
[http://tombstonehelper.codeplex.com/ Tombstone helper] is a small helper to ease your life in persisting your pages' data when tombstoning occurs in Windows Phone 7.
+
Windows Phone 7 does not in general allow the execution of background apps. Instead an app that is navigated away from (but not closed) is first moved into a "dormant" state, where no processing occurs, and may later be "tombstoned" (removed from phone memory). Apps are given the opportunity to save their page state when navigated from, and also to restore it when recovered from tombstoning (see the [http://msdn.microsoft.com/en-us/library/ff817008%28VS.92%29.aspx Windows Phone Execution Model] for more information).
 +
 
 +
[http://tombstonehelper.codeplex.com/ TombstoneHelper] is a small helper which handles most of the work of saving/restoring the app state when tombstoning occurs in Windows Phone 7.  {{Icode|TombstoneHelper}} saves the contents, checked state and scroll positions of {{Icode|TextBoxes}}, {{Icode|PasswordBoxes}}, {{Icode|CheckBoxes}}, {{Icode|RadioButtons}}, {{Icode|Sliders}}, {{Icode|ListBox}} and {{Icode|ScrollViewer}}s ''that you have named'' (using the {{Icode|Name}} attribute).
 +
 
 +
This article provides an overview of how the helper is used (more can be found in the official [http://tombstonehelper.codeplex.com/documentation documentation]), along with an overview of using it with a base page class.
  
 
== Setup ==
 
== Setup ==
  
# Download the TombstoneHelper.dll from CodePlex
+
# [http://tombstonehelper.codeplex.com/releases/view/74032 Download] the '''TombstoneHelper.dll''' from CodePlex
 
# Add a reference to it in your project
 
# Add a reference to it in your project
  
Line 37: Line 44:
 
== Usage ==
 
== Usage ==
 
   
 
   
Using TombstoneHelper is dead simple. All you have to do is add a using statement and override your page's OnNavigatingFrom and OnNavigatingTo -methods
+
Using {{Icode|TombstoneHelper}} is simple. All you have to do is add a using statement and override your page's {{Icode|OnNavigatingFrom()}} and {{Icode|OnNavigatingTo()}} methods:
  
<code>
+
<code csharp>
 
using TombstoneHelper;
 
using TombstoneHelper;
  
Line 57: Line 64:
 
</code>
 
</code>
  
TombstoneHelper saves the '''''contents, checked state and scroll positions of TextBoxes, PasswordBoxes, CheckBoxes, RadioButtons, Sliders, Listboxes and ScrollViewers that you have given a name with the Name-attribute.'''''
+
For greater efficiency you can also specify just those components that the page uses. For example:
 +
<code csharp>this.SaveState(typeof(TextBox), typeof(PasswordBox), typeof(CheckBox));</code>
 +
 
 +
The API can also be extended to support other UI component types: this is also covered in the API [http://tombstonehelper.codeplex.com/documentation documentation].
 +
 
 +
== Using a base class ==
  
 
I usually create a base class that handles all the saving and then derive all my application pages from that:
 
I usually create a base class that handles all the saving and then derive all my application pages from that:
  
'''Base-class:'''
+
'''Base-class:''' Handles the save and restore.
Handle the save and restore.
+
<code csharp>
<code>
+
 
namespace Foo.Pages
 
namespace Foo.Pages
 
{
 
{
Line 89: Line 100:
 
'''Page's codebehind:'''
 
'''Page's codebehind:'''
 
Inherit the base-class
 
Inherit the base-class
<code>
+
<code csharp>
 
namespace Foo.Pages
 
namespace Foo.Pages
 
{
 
{
Line 103: Line 114:
  
 
'''Page's XAML:'''
 
'''Page's XAML:'''
<code>
+
<code xml>
 
<local:FooPageBase x:Class="Foo.Pages.ListsPage"
 
<local:FooPageBase x:Class="Foo.Pages.ListsPage"
                            xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
+
                xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
                            xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+
                xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
                            xmlns:phone="clr-namespace:Microsoft.Phone.Controls;assembly=Microsoft.Phone"
+
                xmlns:phone="clr-namespace:Microsoft.Phone.Controls;assembly=Microsoft.Phone"
                            xmlns:shell="clr-namespace:Microsoft.Phone.Shell;assembly=Microsoft.Phone"
+
                xmlns:shell="clr-namespace:Microsoft.Phone.Shell;assembly=Microsoft.Phone"
                            xmlns:local="clr-namespace:Foo.Pages"
+
                xmlns:local="clr-namespace:Foo.Pages"
                            xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
+
                xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
                            xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
+
                xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
                            mc:Ignorable="d"
+
                mc:Ignorable="d"
                            d:DesignWidth="480"
+
                d:DesignWidth="480"
                            d:DesignHeight="696"
+
                d:DesignHeight="696"
                            FontFamily="{StaticResource PhoneFontFamilyNormal}"
+
                FontFamily="{StaticResource PhoneFontFamilyNormal}"
                            FontSize="{StaticResource PhoneFontSizeNormal}"
+
                FontSize="{StaticResource PhoneFontSizeNormal}"
                            Foreground="{StaticResource PhoneForegroundBrush}"
+
                Foreground="{StaticResource PhoneForegroundBrush}"
                            SupportedOrientations="Portrait"
+
                SupportedOrientations="Portrait"
                            Orientation="Portrait"
+
                Orientation="Portrait"
                            shell:SystemTray.IsVisible="True"
+
                shell:SystemTray.IsVisible="True"
                            DataContext="{Binding ListPage, Source={StaticResource Locator}}">
+
                DataContext="{Binding ListPage, Source={StaticResource Locator}}">
 
</code>
 
</code>

Latest revision as of 10:49, 17 July 2013

This article explains how to use TombstoneHelper, a small library which makes it easy to persist page data during navigation.

See Also

WP Metro Icon File.png
SignpostIcon XAML 40.png
SignpostIcon WP7 70px.png
Article Metadata
Tested with
SDK: Windows Phone 7.1 SDK
Devices(s): Lumia 800
Compatibility
Platform(s): Windows Phone 7.5 (Mango)
Windows Phone 7.5
Article
Keywords: Tombstoning, OnNavigatingFrom, OnNavigatingTo
Created: riussi (11 Aug 2012)
Last edited: hamishwillee (17 Jul 2013)

Contents

[edit] Introduction

Windows Phone 7 does not in general allow the execution of background apps. Instead an app that is navigated away from (but not closed) is first moved into a "dormant" state, where no processing occurs, and may later be "tombstoned" (removed from phone memory). Apps are given the opportunity to save their page state when navigated from, and also to restore it when recovered from tombstoning (see the Windows Phone Execution Model for more information).

TombstoneHelper is a small helper which handles most of the work of saving/restoring the app state when tombstoning occurs in Windows Phone 7. TombstoneHelper saves the contents, checked state and scroll positions of TextBoxes, PasswordBoxes, CheckBoxes, RadioButtons, Sliders, ListBox and ScrollViewers that you have named (using the Name attribute).

This article provides an overview of how the helper is used (more can be found in the official documentation), along with an overview of using it with a base page class.

[edit] Setup

  1. Download the TombstoneHelper.dll from CodePlex
  2. Add a reference to it in your project


[edit] Usage

Using TombstoneHelper is simple. All you have to do is add a using statement and override your page's OnNavigatingFrom() and OnNavigatingTo() methods:

using TombstoneHelper;
 
protected override void OnNavigatingFrom(NavigatingCancelEventArgs e)
{
base.OnNavigatingFrom(e);
// Save the state
this.SaveState(e);
}
 
protected override void OnNavigatedTo(NavigationEventArgs e)
{
base.OnNavigatedTo(e);
// Restore the saved state
this.RestoreState();
}

For greater efficiency you can also specify just those components that the page uses. For example:

this.SaveState(typeof(TextBox), typeof(PasswordBox), typeof(CheckBox));

The API can also be extended to support other UI component types: this is also covered in the API documentation.

[edit] Using a base class

I usually create a base class that handles all the saving and then derive all my application pages from that:

Base-class: Handles the save and restore.

namespace Foo.Pages
{
public class FooPageBase : AutoTombstonePage
{
public FooPageBase()
{
}
 
protected override void OnNavigatingFrom(NavigatingCancelEventArgs e)
{
base.OnNavigatingFrom(e);
this.SaveState(e);
}
 
protected override void OnNavigatedTo(NavigationEventArgs e)
{
base.OnNavigatedTo(e);
this.RestoreState();
}
}
}

Page's codebehind: Inherit the base-class

namespace Foo.Pages
{
public partial class ListsPage : FooPageBase
{
public ListsPage()
{
InitializeComponent();
}
}
}

Page's XAML:

<local:FooPageBase x:Class="Foo.Pages.ListsPage"
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
xmlns:phone="clr-namespace:Microsoft.Phone.Controls;assembly=Microsoft.Phone"
xmlns:shell="clr-namespace:Microsoft.Phone.Shell;assembly=Microsoft.Phone"
xmlns:local="clr-namespace:Foo.Pages"
xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
mc:Ignorable="d"
d:DesignWidth="480"
d:DesignHeight="696"
FontFamily="{StaticResource PhoneFontFamilyNormal}"
FontSize="{StaticResource PhoneFontSizeNormal}"
Foreground="{StaticResource PhoneForegroundBrush}"
SupportedOrientations="Portrait"
Orientation="Portrait"
shell:SystemTray.IsVisible="True"
DataContext="{Binding ListPage, Source={StaticResource Locator}}">
This page was last modified on 17 July 2013, at 10:49.
156 page views in the last 30 days.

Was this page helpful?

Your feedback about this content is important. Let us know what you think.

 

Thank you!

We appreciate your feedback.

×