×
Namespaces

Variants
Actions
(Difference between revisions)

Tombstoning helper for Windows Phone 7

From Nokia Developer Wiki
Jump to: navigation, search
hamishwillee (Talk | contribs)
m (moved Autotombstone helper to Tombstoning helper for Windows Phone 7: It is useful to include the software platform or development environment in the title.)
hamishwillee (Talk | contribs)
m (Hamishwillee - Subedit)
Line 1: Line 1:
[[Category:Windows Phone]][[Category:Code Snippet]][[Category:Files/Data]]
+
[[Category:Windows Phone]][[Category:Code Snippet]][[Category:Files/Data]][[Category:Silverlight]]
{{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]] -->
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"

Revision as of 05:23, 13 August 2012

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
Compatibility
Platform(s): Windows Phone 7
Windows Phone 7.5
Article
Keywords: tombstoning, wp7
Created: riussi (11 Aug 2012)
Last edited: hamishwillee (13 Aug 2012)

Contents

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.

Setup

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


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.

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}}">
150 page views in the last 30 days.
×